Return the main resource response from goto and reload

[k3dom]

Problem

Page.goto, Frame.goto and Page.reload are typed Effect<void, PlaywrightError> and drop the Response | null that Playwright resolves with. Playwright doesn't reject when the server answers with an error status such as 404 or 500, so the response is the only way to tell whether you got the page you asked for or an error page. Today that takes the escape hatch:

const response = yield* page.use((page) => page.goto(url))

We hit this capturing screenshots of pages from a CMS. Without the status check, a 404 page gets captured as if it were the page.

Page.reload also takes no options, unlike Page.goBack and Page.goForward.

Change

• Page.goto and Frame.goto now return Effect<Option<Playwright.Response>, PlaywrightError>, mapped the same way as Page.goBack and Page.goForward and as the implement-playwright-method skill describes for an async T | null result. None covers the navigations Playwright resolves with null, such as about:blank or a change of the URL hash.
• Page.reload is now a method that takes Playwright's reload options and returns the response in the same way.

The TSDoc says that an error status doesn't fail the navigation, and Page.goto has an example that reads the status.

Changelog

The Unreleased section lists the response from goto and reload under Features, since code that ignores the result keeps working and code that needs Effect<void, PlaywrightError> can pipe Effect.asVoid.

Turning Page.reload from an Effect property into a method is breaking, so it is listed under Breaking Changes. Callers replace yield* page.reload with yield* page.reload(), like the consoleMessages and pageErrors change in 0.5.0.

Tests

• Page.goto returns the response of a route fulfilled with status 404.
• Page.goto returns None for about:blank.
• Frame.goto returns the response through page.mainFrame().
• Page.reload returns the response of the reload rather than of the first load.
• Page.reload fails with a Timeout error when the reload exceeds its timeout option.

The new tests fail when goto and reload go back to the old implementation, and the timeout test fails when the options are not passed on.

pnpm biome ci ., pnpm type-check, pnpm check-doc-examples and pnpm test:playwright pass. I ran the vitest files one at a time with Chromium 154. They all pass except two tests in src/playwright.test.ts, should connect via CDP (confirm browser.close only closes CDP connection) and should fail with timeout 1, which fail in my environment on main as well.

---

Note

Medium Risk
Breaking TypeScript API on a core navigation path; runtime behavior is unchanged when the return value is ignored, but typed consumers must update.

Overview
Breaking change: Page.goto() and Frame.goto() now return Effect<Option<Response>, PlaywrightError> instead of Effect<void, …>, matching goBack/goForward and Playwright’s Response | null. The wrapper maps null to None and wraps responses with makeResponse; navigation still succeeds on HTTP error statuses (404/500), so callers can inspect response.status() without using page.use.

Docs and CHANGELOG (Unreleased) describe the migration (Effect.asVoid if you still want void). New tests cover 404 responses, about:blank → None, and frame goto.

^{Reviewed by Cursor Bugbot for commit 41c3dc2. Bugbot is set up for automated code reviews on this repo. Configure here.}

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/effect-playwright@b427ea6

commit: b427ea6

[fiws]

thanks, looks good in general.

personally i would not mark this as a breaking change, i don't see many cases where it would be - but also fine if we wanna keep it as breaking.

i also think it totally makes sense to change Page.reload the same way.

They all pass except two tests in src/playwright.test.ts (launchPersistentContext and connectCDP), which fail in my environment on main as well.

can you post the output of the failures here? curious what could be the problem.

[k3dom]

Yeah sorry for the clanker slop comments, should be good now and I added Page.reload as well. Regarding the two test failures both aren't issues and where related to my machine, the CDP test failed because I use ungoogled-chromium and the "should fail with timeout 1" test failed because NixOS has no /bin/cat. Don't think this warrants changing anything

[fiws]

thanks for the contribution