Repository navigation
docs: add a multi-tab testing guide for @cypress/puppeteer - #7049
Open
jennifer-shehane wants to merge 11 commits into
Open
jennifer-shehane wants to merge 11 commits into
jennifer-shehane wants to merge 11 commits into
Conversation
Multi-tab coverage was scattered across five pages, each a sentence or two that linked out to the plugin README. This adds one guide that covers when a second tab is needed, how the plugin works, browser support, setup, four verified multi-tab flows, CI, and troubleshooting. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016sNZ3z2W8wCcBH61TTgwXn
…t example Trade-offs, the FAQ, both migration guides, and the plugins list each described @cypress/puppeteer in a sentence and linked out to three different places. They now lead readers to the multi-tab testing guide. The Playwright migration example is also corrected: it no longer says Puppeteer must be installed separately (the plugin bundles it), its "After" now clicks Confirm like the "Before" does and closes the tab, and it uses the cypress-config-plugin-example directive. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016sNZ3z2W8wCcBH61TTgwXn
Adds a diagram of how one cy.puppeteer() call moves between the browser and Node.js, a sequence diagram of the popup flow, and Command Log screenshots of a passing and a failing handler, captured from real runs on Cypress 16.1.1. Adds three verified workflows: signing out across tabs, testing two users at once with a separate browser context, and screenshotting other tabs when a test fails, since Cypress screenshots only capture its own tab. Also fixes the tab lookups in readNewTab, allowAccessInPopup, and the Playwright guide's confirmInNewTab to skip the Cypress tab. Its URL contains the spec's file name, so a spec named after the tab it looks for matched the Cypress tab and closed it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016sNZ3z2W8wCcBH61TTgwXn
Puts the new tab or popup to the right of Node.js, so the diagram reads left to right from the spec to the handler to the tab it controls. Drops the numbered steps and legend from the image and explains the call in the page text instead. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016sNZ3z2W8wCcBH61TTgwXn
Drops the gray notes under each box so the diagram shows only the tabs, the handler, and the calls between them. The page text already explains the fresh Puppeteer connection and where the new tab comes from. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016sNZ3z2W8wCcBH61TTgwXn
Drops the sequence diagram from the popup section of the multi-tab guide. The section's markup, handler, and spec already walk through the flow step by step. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016sNZ3z2W8wCcBH61TTgwXn
Returns readNewTab, allowAccessInPopup, and the Playwright guide's confirmInNewTab to a plain URL match. The guide still warns that the Cypress tab's URL contains the spec's file name, so a handler can match it by mistake. Recaptures both Command Log screenshots with the simpler handler. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016sNZ3z2W8wCcBH61TTgwXn
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LaBf5JWCwkJkA3hA1Qz3n2
- Move the diagram's column labels into the page text so the SVG shows only the three boxes and arrows. - Rework the intro for flow and drop the public beta caution. - Rename "Choose how to test links that open a new tab" to say these options fit when the tabs don't interact, and update the FAQ link. - Lead the how-it-works section with the scenarios that need the plugin, and move the explanation under an H3. - Reduce browser support to the Chromium-based requirement and its two limits, without the Cypress version or the browser table. - Click "Allow access" from inside the popup with $eval. popup.click() failed intermittently with "Target closed" because the app closes the popup on click (2 of 200 runs; the fix ran 500 of 500 clean). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LaBf5JWCwkJkA3hA1Qz3n2
…w fixes - Use browser.createBrowserContext(), since puppeteer-core 24 removed createIncognitoBrowserContext(), and update the related notes. - Say that cy.puppeteer() runs its handler once and doesn't retry. - Guard the afterEach hooks so suites still run outside Chromium. - Say that headed Chrome 137+ fails to launch once setup() is registered. - Show the connect.html markup the window.open stub runs against. - Quote the ::-p-text() selector so unbalanced parentheses match. - Drop bold from list lead-ins, trim the description, and remove unused SVG styles. - Make five headings stand on their own, and tighten wording for tense, voice, and tone. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LaBf5JWCwkJkA3hA1Qz3n2
cypress-documentation
 |
||||||||||||||||||||||||||||||||||||||||
| Project |
cypress-documentation
|
| Branch Review |
docs/multi-tab-testing-guide
|
| Run status |
|
| Run duration | 02m 21s |
| Commit |
|
| Committer | Jennifer Shehane |
| View all properties for this run ↗︎ | |
| Test results | |
|---|---|
 |
0
|
 |
2
|
 |
0
|
 |
0
|
 |
428
|
| View all changes introduced in this branch ↗︎ | |
UI Coverage
32.73%
|
|
|---|---|
|
|
745
|
|
|
26
|
Accessibility
98.89%
|
|
|---|---|
|
|
2 critical
6 serious
4 moderate
1 minor
|
|
|
150
|
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a Multi-tab testing guide (
/app/guides/multi-tab-testing) that shows how to test links, popups, and windows that open a new browser tab. It covers the@cypress/puppeteerplugin, and the alternatives that keep a test in the Cypress tab. The guide replaces the scattered "Cypress can't do multiple tabs" mentions on five other pages with links to it.Why
Readers kept landing on pages that said multi-tab testing wasn't possible, or that pointed at a plugin with no worked examples. The guide does three things:
target, or stubbingwindow.openis enough, and it runs in every browser.cy.puppeteer()reaches other tabs, with a diagram.It's written for
@cypress/puppeteer1.0 (cypress-io/cypress#35203), which bundlespuppeteer-corev24 and drops the beta label. The examples use v24 APIs, such ascreateBrowserContext()in place ofcreateIncognitoBrowserContext().What changed
docs/app/write-tests/multi-tab-testing.mdxstatic/img/app/multi-tab-testing/:trade-offs.mdxfaq.mdxsrc/data/plugins.jsonNotes for reviewers
Code example verification
Every example ran in the
.example-check/harness, pasted verbatim, with Cypress 16.1.0. The plugin was@cypress/puppeteer0.1.10 withpuppeteer-coreoverridden to 24.43.1. That's the code 1.0 ships: the PR's only source change is the wording of the minimum-version error.window.openreadNewTab, plus the "Failed retrying after 4000ms" troubleshooting exampleallowAccessInPopup)clickInNewTab(theme and sign-out))closeExtraTabsandscreenshotOtherTabssupport-file hookstsconfig.jsontypes entrycypress run --browser chromeCypress.browser.family === 'chromium'The guide's Electron limits each failed with the exact text the guide quotes:
newPage()(Target.createTarget: Not supported), browser contexts (Failed to create browser context), a popup with nowindow.opener, and apage.screenshot()that never finishes. The headed Chrome 137+ launch failure was reproduced by registering Chromium as Chrome 141.Decisions worth knowing
$eval, notpage.click(). The app closes the popup on click, sopage.click()intermittently failed withProtocol error (Input.dispatchMouseEvent): Target closed: 2 of 200 runs on Puppeteer 21 and 8 of 300 on 24.$evalran 800 of 800 clean.cy.puppeteer()doesn't retry. A chained assertion that fails doesn't run the handler again. The guide says so and waits inside handlers withretry(). This was confirmed in the plugin source (Commands.addaround onecy.task()) and with a run./__/and the spec's file name. A spec namedreceipt.cy.jscallingreadNewTab('receipt')closes the Cypress tab and aborts the run. The guide warns about this. Whether to add a/__/filter to the three lookups is still an open question.Generated by Claude Code
Note
Low Risk
Documentation-only: new guide, cross-links, plugin copy, and static assets; no runtime or security-sensitive code paths.
Overview
Summary
Adds
/app/guides/multi-tab-testing—a full guide for testing new tabs, popups, and separate contexts with@cypress/puppeteer, plus when to stay in the Cypress tab (asserthref, striptarget, stubwindow.open). Includes setup, browser limits (Chromium, headed Chrome 137+, Electron caveats), worked examples (read tab, OAuth-style popup, cross-tab storage, second user viacreateBrowserContext, cleanup hooks, failure screenshots), troubleshooting, and a how-it-works diagram.Why
Replaces scattered “no multi-tab” messaging with one source of truth and links from Trade-offs, FAQ (new-tab anchors), Playwright and Selenium migration guides (rewritten multi-tab sections and cheat-sheet row pointing at the guide), and a clearer plugins.json blurb for Puppeteer.
Notes for reviewers
Examples are written for
@cypress/puppeteer1.0 / Puppeteer v24 APIs (createBrowserContext, etc.). Confirm sidebar/nav picks up the new MDX from existing patterns. Large guide and image assets (~863 lines + SVG); spot-check internal links and Command Log image paths.Reviewed by Cursor Bugbot for commit 50cffbe. Bugbot is set up for automated code reviews on this repo. Configure here.