feat(web): tabs in the browser fixture, with switch_tab and close_tab agent verbs

Merged
KD
5d ago
+1685-89

Why

A tab the app opened (target="_blank", window.open, an OAuth popup) was out of reach for tests and for the agent: the agent could not finish new-tab-flow (ENG-843).

What changes

  • A tab the app opens joins browser.tabs() in the background. The active tab stays where it was, as Playwright's page does. browser.waitForPopup(trigger) is the opt-in that makes the new tab active:

    await screen.getByRole('link', 'Read the terms').tap();   // screen stays on the opener
    await screen.getByLabel('Name').fill('Ada');
    
    const popup = await browser.waitForPopup(() => screen.getByRole('button', 'Sign in').tap());
    await screen.getByRole('button', 'Authorize').tap();       // closes itself: the opener is active again
    
  • New browser tab calls: tabs(), waitForPopup(trigger), newTab() (same context and cookies), and BrowserTab with url, title, isActive, isClosed, activate, close. When the active tab closes, its nearest open opener is active again, else the tab shown most recently.

  • waitForPopup that times out names the page a tab was still loading: ACTION_FAILED: the tab the app opened did not load <url> within <n>ms. Otherwise no tab opened within <n>ms; the trigger resolved after <m>ms.

  • Engine contract: optional session.switchTab(index) and session.closeTab(index) hooks (session/switchTab, session/closeTab on the wire, both in engine-manifest-v1), and EngineSnapshot.tabs { count, active } when two or more tabs are open.

  • Agent: switch_tab and close_tab verbs on engines that declare the hooks, recorded and replayed by the replay cache. close_tab refuses the last open tab. The agent stays on its tab, and the action that opened one reads:

    Tapped #n6.
    
    The app opened a new tab (tab 2 of 2). The screen still shows tab 1; use switch_tab to see it. Screen unchanged since revision b26 (...)
    
  • Not breaking: both changesets are patches. @e2e-dev/web needs e2e >=0.23.1, since an older runner rejects the new hooks.

sequenceDiagram
  participant T as test / agent
  participant S as AttemptSession
  participant P as Playwright
  T->>P: tap (opens a tab)
  P-->>S: popup reported (first page committed)
  S->>S: join tabs() in the background
  alt waitForPopup is waiting
    S->>S: show the new tab
    S-->>T: resolve with the BrowserTab
  else nobody waits
    S-->>T: next call runs on the same tab
  end

Details in packages/web/src/attempt-session.ts:

  • join adopts a page the app opened once it has a document. A _blank download, mailto:, or 204 never gets one and never joins.
  • orphaned: a tab whose opener closed before it loaded (a window that opens the next one and closes itself) joins when Chromium reports an openerId for it. A page something else opened in the context does not.
  • Each joined tab records its CDP target, so a reconnect remaps it, a tab in the background too.
  • A read (locate, observe) in flight when the app closes the shown tab is a retryable NODE_STALE. A tap whose own tab closes succeeds once the call log shows the input went out.
  • Tabs are numbered in the order they joined, which is when their first page loads. Two tabs one action opens can swap numbers between runs if their pages load in another order; the docs say so.
  • Screencast: one segment per shown tab. A tab that closes itself keeps no segment.

Verified

Ran it locally: yes

  • The review's scenarios through the built CLI on the testbed, against a server that never answers /hang:
    • a _blank tap, then fill on the opener: passes, and browser.title() is the opener's;
    • the call after a hanging popup: 165 ms;
    • the call after a mailto: or a 204 link: under 300 ms;
    • waitForPopup on the hanging popup: ACTION_FAILED: the tab the app opened did not load http://127.0.0.1:4299/hang within 2000ms.
  • Agentic new-tab-flow, live, re-recorded: passes with tap, switch_tab 2, switch_tab 1, type, tap. The model read the background-tab note above and switched on its own. The typed code is a run-time value, so replay hands that step to the model, like async-states.
  • Web benchmark: 93 passed; agent suite with CI=1 --strict-cache: 34 passed, no REPLAY_STALE.
  • Testbed: 588 passed. set-input-files "upload a file after popup" is back to main's version.
  • packages/web/tests/integration/tabs.test.ts: 13 tests, 3 repeats green. The reconnect test for a background tab fails without the fix.
  • A fresh gpt-6.1-sol review of the rework found three issues, all fixed: background tabs dropped by a reconnect, a tab-opening action told it had "no visible effect", and the tab-numbering docs.
  • Earlier rounds, still in: cubic's 17 findings, two earlier gpt-6.1-sol findings, and the Linux-only "Target page closed" tap fix.

Refs ENG-843

🤖 Generated with Claude Code