In Cypress, when is a Cypress.Commands.overwrite() in the support file worth it?

## What the blast radius actually is `Cypress.Commands.overwrite(name, fn)` replaces the implementation of a built-in command. Put it in `cypress/support/e2e.js` — the only place it is normally put — and Cypress evaluates it before **every spec in the run**. From that moment `.click()` means whatever your function says it means, in every spec, for every author, including the ones who joined last week and have never opened the support file. There is no opt-out at the call site unless you build one, and nothing in a spec hints that a built-in has been redefined. `cy.get('[data-cy=approve-report]').click()` looks exactly the same whether the overwrite exists or not. That is the whole trade: an overwrite is the only mechanism that guarantees a rule holds without anybody remembering it, and it is also the only mechanism that can change what a spec does without touching the spec. ## Orthogonal changes versus semantic ones The distinction that decides most of these calls is whether the overwrite changes *how* a command is configured or *what it means*. | Change | Kind | Verdict | |---|---|---| | Set a default option, e.g. `waitForAnimations: false` on `.click()` | orthogonal | usually defensible | | Mask a sensitive value out of the log for `.type()` | orthogonal | defensible, and hard to enforce any other way | | Add a fixed wait for one page's overlay before `.click()` | semantic | no — it is one page's problem, suite-wide | | Swallow an error so the spec keeps going | semantic | no — it makes every failure less trustworthy | | Change what a command yields to the next command | semantic | no — it breaks every chain silently | Orthogonal overwrites keep the mental model intact: `.click()` still clicks, still fails the same way, still yields the same subject. Semantic ones ask every reader of every spec to hold a private exception in their head, which is exactly the debt this leaf is about. ## The ladder to climb before overwriting Reach for the smallest tool that solves it: 1. **Pass the option at the call site.** If two specs need `{ waitForAnimations: false }`, write it twice. Visible, local, obvious. 2. **Set it in configuration.** Some behaviour is a config key — `defaultCommandTimeout`, `scrollBehavior`, `keystrokeDelay` — and a config key is discoverable in a way an overwrite is not. 3. **Add a new named command.** `cy.clickAndSettle()` makes the divergence visible in the spec. The reader sees a name they do not recognise and can look it up; that is a feature. 4. **Overwrite the built-in.** Only when the rule must hold everywhere, silently, and forgetting it would be a real defect — such as keeping a secret out of the Command Log. Most cases stop at step 1 or step 3. ## Making an overwrite survivable If you do take step 4: - **Always call `originalFn`.** An overwrite that forgets to invoke the original silently turns a command into a no-op, and the spec still passes. - **Change one thing.** A default option, a log detail. Not control flow, not the yielded subject, not error handling. - **Write it where the specs are.** A comment in the support file is not documentation for someone reading a spec. The team convention has to say which built-ins are modified. - **Keep the list short and reviewable.** Two overwrites are a convention; nine are a dialect of Cypress that only this repository speaks, and every onboarding engineer pays for it. - **Expect it to complicate upgrades.** You are wrapping an implementation whose signature and defaults belong to Cypress, not to you. ## What Cypress 16 removed from the option set Some overwrites are no longer available at all. `cy.getCookie()`, `cy.getCookies()`, `cy.getAllCookies()`, `cy.getAllLocalStorage()` and `cy.getAllSessionStorage()` became **queries** in Cypress 16, and `Cypress.Commands.overwrite()` cannot overwrite a query — attempting it throws, and directs you to `Cypress.Commands.overwriteQuery()`, which is a different API with different rules. An older suite that leaned on overwriting a cookie getter has to be rewritten rather than carried forward. That is worth weighing before you add another one: an overwrite is a bet on an implementation detail, and this release just settled a few of those bets against the people who made them. ## The judgement, stated plainly An overwrite is a suite-wide policy with no signature at the point of use. It is the right tool when the alternative is trusting every author to remember something, and the wrong tool for anything a reader would want to see in the spec. If you cannot name the defect that would occur if the rule were forgotten, you do not need the overwrite — you need a named command.