In Cypress, why must a `Cypress.Commands.addQuery()` callback return another function?

## Two functions, two lifetimes `Cypress.Commands.addQuery()` looks odd until you see what the shape buys. You pass one callback; Cypress calls it once and keeps what it returns: ```javascript Cypress.Commands.addQuery('expenseRow', function expenseRow(reportId, options = {}) { // outer: runs once, when the test reaches this step this.set('timeout', options.timeout) return (subject) => { // inner: runs on every retry, and again later if the subject is needed return subject.find(`[data-report-id="${reportId}"]`) // jQuery's .find() } }) ``` The outer half is **setup**. It sees the arguments the test wrote, so it is the place to validate them, to create the `Cypress.log()` entry the Command Log will show, and to set the query's timeout. Doing any of that inside the inner half would repeat it on every retry and flood the log. The inner half is **the query itself**: previous subject in, new subject out. Cypress owns its schedule. It calls it until the inner function stops throwing and any chained assertions pass, or until the timeout runs out — and it can call it again afterwards when a later command needs the subject resolved once more. ## The three rules that follow from the shape 1. **Synchronous.** The inner function must return a subject, never a promise, and must not await anything. Cypress has no way to retry something it must wait on. 2. **Retriable.** Failure is signalled by throwing. You do not catch, wait and try again yourself; you throw, and Cypress schedules the next attempt. Any error type works — Cypress catches it and renders it in the Command Log. 3. **Idempotent.** Calling the inner function twenty times must leave the application exactly as one call would. Anything that mutates state — clicking, seeding a report over the network, writing to storage — belongs in a command created with `Cypress.Commands.add()`, not in a query. The third rule is the one that bites in production. A query that quietly performs a side effect works on the happy path, where the first attempt succeeds, and misbehaves only when something is slow enough to trigger retries — which is to say, only in CI, only sometimes, and never on the machine of the person trying to reproduce it. ## What belongs in which half | Work | Outer half (once) | Inner half (every retry) | |---|---|---| | Validating the test's arguments | yes | no | | Creating the `Cypress.log()` entry | yes | no | | `this.set('timeout', options.timeout)` | yes | no | | Reading the DOM or app state | no | yes | | Validating the previous subject | no | yes | | Updating the log with the yielded value | no | yes | ## Validating the subject Cypress performs no validation on what it passes the inner function — the previous subject can be any value at all, including `undefined`. There is no `prevSubject` option on `addQuery()`, so the check is yours to make. `Cypress.ensure` exposes the same helpers the built-ins use, including `Cypress.ensure.isType`, `Cypress.ensure.isElement`, `Cypress.ensure.isWindow`, `Cypress.ensure.isDocument`, `Cypress.ensure.isAttached`, `Cypress.ensure.isVisible` and `Cypress.ensure.isNotDisabled`. Each simply throws when the check fails, which is exactly the retry contract, so calling one at the top of the inner function costs nothing and produces the same error text a built-in would. ## Why an arrow function breaks it The outer callback must be written as `function () {}`. The query API sets a query's timeout through `this`, as in `this.set('timeout', options.timeout)`, and an arrow function has no `this` of its own to bind. Omit the call, or pass `null` or `undefined` to it, and the query falls back to the default timeout — which is why a query that seems to ignore the `timeout` option it was handed is almost always an arrow function in disguise. The same rule explains the calling convention when you extend an existing query with `Cypress.Commands.overwriteQuery()`: reach for `originalFn.call(this, ...)` or `originalFn.apply(this, args)` rather than invoking it bare. ## When a query is the wrong choice The two registration APIs answer different questions, so the choice is usually quick: - **Use `Cypress.Commands.add()`** when the step must be asynchronous, must run exactly once, or changes the application — approving a report, uploading a receipt, seeding a month of expenses over the network. - **Use `Cypress.Commands.addQuery()`** when the step is a way of *locating* something on an expense-report page that the rest of the chain then acts on, and re-locating it later is harmless. - **Use neither** when the logic touches no Cypress state at all: an ordinary JavaScript function imported by the spec needs no registration and no type declaration.