Navigation

Navigation API

• navigate(url, options?)
• goBack(options?)
• goForward(options?)
• reload(options?)
• waitForDocumentReady(options?)

Page state

• Tracks loading state.
• Tracks title and URL.
• Exposes onNavigated and onNavigationFailed callbacks.

navigate(url, options?)

navigate() returns a promise that resolves when the requested wait target is reached and rejects on timeout or navigation failure.

The same NavigateOptions shape is also supported by:

• goBack(options?)
• goForward(options?)
• reload(options?)

NavigateOptions

Property	Type	Default	Description
timeoutMs	number	30000	Maximum wait duration before navigation rejects.
waitUntil	NavigateWaitUntil	"load"	Navigation milestone to wait for.

NavigateWaitUntil

Value	Best for	What it means	Limitations
"load"	Standard HTML pages	Waits for the browser load event.	May never fire for streaming top-level responses.
"domcontentloaded"	DOM-first automation	Waits for the DOMContentLoaded event.	Still may never fire for unusual streaming documents.
"frameNavigated"	Early navigation commit	Waits for the top-level frame navigation to commit.	Does not guarantee DOM readiness or subresource completion.
"responseReceived"	Network-aware flows	Waits until CDP sees the HTTP response for the navigation.	Does not guarantee any DOM milestone or page interactivity.
"eventSourceMessageReceived"	In-page SSE consumers	Waits for the first EventSource message for the matched request.	Only useful when the page creates an EventSource; not for direct top-level navigation to an SSE endpoint.

Examples

await view.navigate("https://example.com", {
  waitUntil: "domcontentloaded",
  timeoutMs: 10000,
});

await view.navigate("https://example.com/stream", {
  waitUntil: "responseReceived",
  timeoutMs: 5000,
});

Streaming responses

For top-level streaming responses such as text/event-stream:

• frameNavigated usually works because the browser commits the navigation.
• responseReceived usually works because the HTTP response arrives quickly.
• load and domcontentloaded may time out because the document can remain in loading state indefinitely.
• eventSourceMessageReceived usually does not apply unless a normal HTML page creates an EventSource request from script.

Navigation callbacks

Use view.onNavigated and view.onNavigationFailed when you want to observe navigations beyond the explicit navigation promise you are awaiting.

onNavigated includes:

• direct calls to navigate(), reload(), goBack(), and goForward()
• page-triggered navigations such as link clicks
• script-triggered navigations such as location.href = ...
• redirects that commit in the main frame

onNavigationFailed includes:

• failures returned from explicit navigation commands
• main-frame document navigation failures reported by the network layer

These callbacks are useful for logging, host integration, or syncing external state. They do not replace explicit await view.navigate(...) calls when your code needs deterministic wait semantics.