In Cypress, how do you test a link that opens in a new browser tab?

## The ceiling behind the question Cypress drives **one browser and one tab** for the life of a spec. There is no `cy.switchToWindow()`, no tab handle, no window index, and no option on any command that means "follow the tab the browser just opened". When a bank statement page renders a link like ```html <a href="/statements/2026-08.pdf" target="_blank" rel="noopener">August 2026 statement</a> ``` and a Cypress test clicks it, the click genuinely fires and the browser genuinely opens a second tab in front of you. What does **not** change is where Cypress is pointing: the command queue keeps running against the statements page, `cy.url()` still reports `/statements`, and `cy.get()` still queries the original document. As of Cypress 16 this is documented as a *permanent* trade-off, not a gap waiting to be closed. ## Test the handoff, not the destination The useful reframe is that a `target="_blank"` link is a **contract your application renders**, and that contract is the part your suite owns. The bank statement app's job is to hand the browser the right URL with the right opening behaviour. What the third-party PDF viewer then does with that URL is the viewer's job, and driving somebody else's page is explicitly outside what Cypress is built for. So the default step is an attribute assertion: ```js cy.contains('a', 'August 2026 statement') .should('have.attr', 'target', '_blank') .and('have.attr', 'href', '/statements/2026-08.pdf') ``` `cy.contains()` finds the anchor by its text, and the two assertions pin both halves of the handoff. If the href is generated (a signed URL, a statement id), assert the shape rather than the literal — Chai's `match` against a regular expression works through `.should()` the same way. ## Three techniques, and what each actually proves | technique | proves | does not prove | |---|---|---| | `.should('have.attr', 'href', …)` plus `'target', '_blank'` | the app renders the right destination and opening behaviour | that the destination responds, or that a human sees anything | | `cy.request(href)` | the URL resolves and returns the status and content type you expect | that the link is reachable from the UI at all | | `.invoke('removeAttr', 'target')` then `.click()` | the destination page loads and behaves in a tab Cypress controls | that the link opens in a new tab — you just deleted that attribute | The three compose. A common shape for the statements page is: assert the attributes on every row, then `cy.request()` one href to prove the file is really served, and leave the viewer itself to its own coverage. `.invoke('removeAttr', 'target')` deserves a warning. `.invoke()` calls a method on the jQuery-wrapped subject, so this is jQuery's `removeAttr` mutating the real DOM of the application under test. The click that follows navigates the tab Cypress is already in, which is convenient — but you have changed the page before measuring it, and the test no longer says anything about new-tab behaviour. Pair it with a separate attribute assertion if both matter. ## When JavaScript, not markup, opens the tab Plenty of apps do not use an anchor at all; a Download button calls `window.open(url, '_blank')`. Nothing above helps, because there is no attribute to read. The seam is the app's own `window`: - `cy.visit()` accepts an `onBeforeLoad` callback that receives the application's `window` before its scripts run. - Replace the method there with `cy.stub(win, 'open').as('openViewer')`. - Click the button as a user would, then assert on the alias with Sinon's `calledWith`, exposed through Chai as `.should('have.been.calledWith', …)`. - Nothing opens, nothing steals focus, and you have asserted the exact URL the app intended to hand over. This is the highest-fidelity option for the JavaScript case, because it observes the real call site rather than a rendered attribute. ## When you genuinely need the second tab Sometimes the value of the test really does live on the other side — the viewer posts a message back, or a token minted in the first tab must be spent in the second. That is what the `@cypress/puppeteer` plugin exists for: it hands a Node-side handler a Puppeteer `browser` connected to the browser Cypress launched, so the handler can find the extra page and drive it. It is a genuine escape hatch, it runs on Chromium-family browsers only, and the code lives outside your spec. Reach for it when the cheaper seams above cannot reach the behaviour, not as the default answer to "the app opens a tab".