Playwright Rs Usage

Capabilities worth reaching for

Concept-level pointers; the exact options live on docs.rs.

• Stable / redacted screenshots. ScreenshotOptions carries animations(Disabled) for flake-free shots (freeze CSS animations before capture) and mask/mask_color to overpaint dynamic or sensitive elements. Reach for animations(Disabled) whenever a screenshot races an animation.

• Context-level events. Beyond per-page handlers, BrowserContext observes activity across all its pages — on_download, on_page_load / on_page_close, on_frame_attached / _detached / _navigated — and Browser::on_context fires for each new context. Use these for multi-tab fixtures instead of wiring every page individually.

• HAR network capture. tracing().start_har(path, ..) / stop_har() records all network traffic to a HAR — inspect it in browser devtools or replay it deterministically with route_from_har. A sibling to trace capture.

• Typed page probes. page.evaluate::<R, T>(expr, arg) deserializes the JS return value straight into any serde Deserialize type — define a struct for the shape and skip manual parsing (None::<&()> for the no-argument case). evaluate_value (returns String) is only for one-off scalar probes; if you catch yourself returning delimited strings from JS and splitting them in Rust, switch to evaluate. Runnable walkthroughs: examples/evaluate_typed.rs and examples/canvas_pixels.rs (canvas pixel assertions for wasm/canvas frontends).

• Drags: Locator::drag_to covers everything, including canvas. It drives the real pointerdown → capture → pointermove → pointerup chain (works against setPointerCapture UIs), and DragToOptions::target_position — an offset from the target's top-left — turns it into "drag to a coordinate": pass the containing canvas/stage as the target. Prefer it over held-button Mouse::move_to sequences, which hang on headless Linux. Don't hand-roll synthetic PointerEvent dispatch via evaluate.

• External drag-and-drop. Locator::drop simulates dragging files or data in from outside the page (upload zones), distinct from drag_to, which drags one element onto another within the page.

• File System Access API flows. page.fake_file_system() installs an opt-in fake of showSaveFilePicker/showOpenFilePicker (native dialogs no automation tool can drive): seed opens with set_open_file, assert saves with last_saved_bytes(), control permission state. Don't hand-roll an add_init_script picker shim.

• Accessibility-tree assertions. expect_page(&page) .to_match_aria_snapshot(..) (and the locator form) guard the page's ARIA structure as a regression check; aria_snapshot can emit [box=..] bounding boxes for visual/agent reasoning. aria_snapshot_json returns the same tree as serde_json::Value rather than YAML markup, which is what an agent walking the tree wants; the YAML form is for a human reading a diff.

• Pages behind HTTP auth. BrowserContextOptions::builder() .http_credentials(vec![HttpCredentials::new("user", "pass")]) — do not hand-set an Authorization header. Give an entry an origin when the test talks to more than one host; the first matching entry wins. APIRequestContextOptions takes the same list, and is the only one that honors send(HttpCredentialsSend::Always) — which you need when the server answers 403 rather than 401, leaving nothing to react to.

• Dialogs: wait for the close, not the open. on_dialog hands you the dialog to accept or dismiss; on_dialog_closed fires once it has been answered, which is the point at which the page is interactive again. Both exist on Page and BrowserContext, and context handlers run first.

• Visibility is a locator, not a pseudo-class. locator.visible() narrows to the visible matches (Playwright's replacement for :visible), and filter(FilterOptions::default().visible(false)) is the hidden half.

• Frames without naming the iframe. page.frame_locator(None) searches every frame in the subtree, so no iframe selector is needed; Frame::frame_locator takes the same optional argument. The rest of the locator resolves inside one frame, and matching several is an error, so keep the inner selector unique.

• Waiting on arbitrary state: wait_for_function. When there is no selector to wait on — a JS flag, a store, a counter — page.wait_for_function("() => window.app?.ready", None) polls a predicate and resolves to its value as a JSHandle. The locator form binds the matched element as the first argument (locator.wait_for_function("el => el.dataset.state === 'done'", None)) and returns (). Prefer this over poll_until-around-evaluate loops: the driver polls on requestAnimationFrame and enforces the timeout. WaitForFunctionOptions::polling_interval switches to timer polling (page-global form only).

• Calling back into Rust: evaluate_with_callback. Hands the expression a Rust closure as its argument — JS calls it, the arguments come to Rust, and the closure's return value resolves the JS promise. The expression may stash the function for later (event listeners); the binding lives until the page closes, so register once rather than in a loop. For a permanently installed window.fn, use expose_function/expose_binding instead.

• Session save & replay. context.storage_state(None) captures cookies and per-origin storage; StorageStateOptions::default().credentials(true).indexed_db(true).opfs(true) additionally captures WebAuthn passkeys, IndexedDB, and each origin's private file system. set_storage_state(state) restores into any context — a replace, not a merge: the driver clears storage for every visited origin, and restoring a state without credentials disposes an installed virtual authenticator. The fast path for "log in once, reuse everywhere".

• Opting out of auto-scroll. Pointer actions scroll the target into view before acting; ClickOptions::builder().scroll(Scroll::None) makes the action fail instead — the way to assert something is already visible, or to avoid scroll side effects.

• Serving the app from inside the test: route_service (the release 0.18.0 and later). When the frontend under test is served by Rust (an axum Router, or a built wasm bundle in a directory via tower-http's ServeDir), hand the service to page.route_service("https://app.example/**", service) or the BrowserContext form and navigate to that origin. Every matching request is answered by the service in-process: no listener, no port, any origin including https://, works in sandboxes. Prefer it over binding an ephemeral port and spawning axum::serve for a test. Reach for a real listener instead when the app depends on streaming responses, server-sent events, WebSockets (those go through route_web_socket), or connection-level behavior, since route interception delivers whole bodies and has no connection. The Sleeping to wait for a page is wrong anyway, and wronger here: a delay tuned against a real listener can be too short once the bundle crosses the driver channel, which is the one behavior change a consumer hit converting a suite. Wait on what the app renders. The route_service module rustdoc has the full contract and a wasm testing section.

Debugging failures with traces

Rust has no async Drop, so trace cleanup is explicit. The canonical pattern: capture the test result, run cleanup unconditionally, pass the trace path only on failure.

See examples/trace_on_failure.rs for the runnable end-to-end version — it's compiled by cargo check --examples so it can't silently rot.

To view a captured trace: playwright show-trace trace.zip. The viewer is language-agnostic — same UI JS / Python users see. The hosted version is at https://trace.playwright.dev.

Programmatic trace inspection

For CI bots, agent feedback loops, or any code that wants to read what happened in a trace without re-running the test, turn on the trace feature and the parser is playwright_rs::trace, at a version this crate already pins:

playwright-rs = { version = "0.18", features = ["trace"] }

Use trace::open(path) then TraceReader::actions() to walk the reassembled action stream, TraceReader::network() for HTTP traffic, and TraceReader::blob(path) to pull a screencast frame or response body out of the archive. Code that reads traces without driving a browser can depend on playwright-rs-trace alone instead; it needs 0.2 or later to read traces from the current driver, since 0.1 reads only the older trace format and refuses them. The crate's //! rustdoc on https://docs.rs/playwright-rs-trace has a runnable example.

Things that look like playwright-python but aren't quite

• No sync_playwright. Async only; everything awaits on tokio.
• Result, not exceptions. Use ? to propagate.
• No keyword arguments. Options come through Options structs with ..Default::default(), not name=value in method calls.
• No async Drop. Always close browsers / stop tracing explicitly in a cleanup block — don't rely on RAII for I/O.
• Locators are values, not lazy proxies. page.locator(...) returns a Locator you can .clone() and re-use cheaply.
• Functions cannot ride inside evaluate args. Python passes callables directly; here the callback is a dedicated parameter (evaluate_with_callback) since serialized data cannot carry a Rust closure.

Common pitfalls

• Manual sleeps before assertions. Use expect(..) and let it auto-retry.
• Closing the browser before tracing.stop() — traces are written on stop, so order matters: stop tracing first, then close.
• Hardcoding selectors as &str. Switch to locator!() for any selector you write as a literal.

References

• Full API: https://docs.rs/playwright-rs
• Runnable examples: https://github.com/padamson/playwright-rust/tree/main/crates/playwright/examples
• Upstream Playwright docs: https://playwright.dev/docs/api
• Trace format / parser: https://docs.rs/playwright-rs-trace
• locator!() macro: https://docs.rs/playwright-rs-macros