How far should Cypress specs be allowed to reach into application internals?

## Why the question exists at all Every other kind of browser runner answers this question for you: reaching into the application is expensive, so specs mostly do not. Cypress removes that friction. `cy.window().its('store')` is one line, works first time, and makes a slow, awkward test instantly fast and stable. **A privilege with no friction spreads on its own**, which is why a team adopting or migrating to Cypress needs an answer before the suite is written rather than after thirty specs have adopted a habit. The wrong answers are both easy. "Never reach in" throws away the largest single advantage of the placement and produces long, brittle click-through setup for every test. "Reach in freely" produces a suite that goes green while proving progressively less about the product. ## The line that holds: arrange in, assert out The distinction that survives contact with a real codebase is **which phase of the test is doing the reaching**. - **Arranging through the application is cheap and usually right.** Putting a shipment into the console's feed, flipping a feature flag, forcing an error branch with `cy.stub()`, taking the page's clock with `cy.clock()` -- these replace slow setup with fast setup and change nothing about what the test proves. - **Asserting through the application is where coverage quietly evaporates.** A test that seeds the feed and then asserts the feed has one entry has proved that the setup ran. It will pass with the rendering layer entirely broken. Stated as one rule: **reach in to put the application in a state, assert on what the user would see.** A test written that way still fails when the view breaks, and still passes when someone renames an internal used only in setup. The assertions themselves are ordinary Chai and Chai-jQuery chainers that Cypress bundles -- `should('contain', ...)`, `should('have.length', ...)` -- so the rule costs no extra tooling. ## A standard worth writing down 1. **Prefer a seam that is already a contract.** A documented store action, a feature flag, or a network response shaped with `cy.intercept()` is a name someone has agreed to keep. A private function found by reading the bundle is not. 2. **Declare each reach-in once.** Wrap it in a custom command with `Cypress.Commands.add()` so the application-internal name appears in exactly one file. A rename then costs one edit rather than thirty, and the specs read as intent instead of as internals. 3. **Assert through the rendered interface by default.** Allow an assertion on internal state only where the state *is* the observable contract -- something persisted for the next session, a queued payload -- and say so in the test's name. 4. **Keep a reserved set of journeys that reach in nowhere.** Two or three end-to-end paths that navigate, click and assert on what renders. These are the specs that tell you the suite still describes the product. 5. **Review reach-ins like production coupling**, because that is what they are: dependencies on names no compiler checks and no build breaks on. ## What it costs when the line is not held | Symptom | What actually happened | | --- | --- | | A UI refactor breaks thirty specs that never touched the UI | An internal name was repeated across files instead of being declared once | | The suite stays green through a visibly broken release | Assertions were made on state rather than on what renders | | A migration pilot reports excellent stability, then degrades | The pilot specs reached in everywhere, so they never exercised the fragile parts | | Nobody can say what a failing spec proves | The test asserts on an internal whose meaning is not written down anywhere | ## Setting it across teams At the point where several teams share a suite, this stops being a code-review preference and becomes a standard with an owner. Three things make it stick: - **Make the allowed seams explicit and few**, published as custom commands the teams import rather than as advice in a wiki page. The easiest path has to be the sanctioned one. - **Attach the rule to the evidence, not to style.** The argument is not that reaching in is untidy; it is that a green suite must mean something. Frame every exception as a question about what failure the test would still catch. - **Judge a migration pilot on more than green-rate.** Ask what proportion of the pilot's specs assert on rendered output, and how the suite behaved through one real refactor. A pilot that reached into internals everywhere will look fast and stable and will tell you almost nothing about the suite you are about to own.