Why can a Cypress .invoke() call the method more than once, and how do you stop it?

## Why the call repeats Cypress splits its steps into two kinds. **Actions** run once and stay run. **Queries** are pure lookups that Cypress is free to run again, and it runs them again whenever something later in the chain is still waiting to pass. As of Cypress 16 `.invoke()` is registered as a query - it sits in the same family as `.its()`, `.find()` and `.first()`. The trouble is that `.invoke()` is the one query whose "lookup" is a **function call**. Re-running `.its('copiesLeft')` re-reads a property, which is harmless. Re-running `.invoke('borrow', 'B-1204')` calls `borrow()` again. Cypress cannot tell a reader from a mutator, so it treats them alike, and the Cypress documentation carries the warning in plain language: *if you chain further commands off of `.invoke()`, it will be called multiple times.* ## What it looks like in a library catalogue suite ```javascript cy.window() .its('catalogue') .invoke('borrow', 'B-1204') .should('have.property', 'copiesLeft', 2) ``` The intent is obvious: borrow one copy, then check two are left. What happens is that the assertion fails on the first attempt (the application has not finished updating), Cypress retries, the whole query chain including `.invoke()` is evaluated again, `borrow()` fires a second time, and now three copies are gone. Either the assertion passes on a number you did not create, or it never passes and you spend an afternoon accusing the application. ## How to spot it - **The Command Log shows one `.invoke()` entry, the application shows two effects.** The log records the command, not the number of evaluations, so the count will not be on screen. - **The failure is timing-shaped.** It appears on the slow CI machine and not on the laptop, because a retry only happens when the first attempt did not pass. - **The numbers are out by exactly the retry count.** Two borrows, three borrows - never a random amount. - **Removing the chained assertion makes the symptom vanish.** That is the cleanest confirmation you will get, and it points straight at the mechanism. - **A spy or stub on the method records more calls than the test made.** If the method is one you already spy on, the call count is the fastest possible proof. None of these show up as a Cypress error. The test either fails with a puzzling number or - worse - passes, because the extra call happened to move the application into the state the assertion wanted. That is why the habit is worth building before you meet it: read every `.invoke()` in a review and ask whether the method name is a verb. ## Making the call happen exactly once 1. **End the chain at `.invoke()`.** Let the call be the last link, then start a new chain with `cy` for whatever you wanted to assert. This is the remedy the Cypress docs name first. 2. **Call the method inside a `.then()` callback instead.** `.then((catalogue) => catalogue.borrow('B-1204'))` invokes it in plain JavaScript, outside the query machinery. Note that chaining `.then()` *after* `.invoke()` does not help - the callback has to replace `.invoke()`, not follow it. 3. **Assert against the page, not against the return value.** In a catalogue suite the honest check is `cy.get('[data-cy=copies-left]').should('have.text', '2')`, which retries a query over the rendered DOM and mutates nothing. ## When repeating is harmless | the call | repeats safely? | why | |---|---|---| | `.invoke('text')` on a jQuery element | yes | re-reads the DOM, which is what a retry is for | | `.invoke('attr', 'data-book-id')` | yes | pure read of an attribute | | `.invoke('val')` on an input | yes | pure read of the current value | | `.invoke('borrow', 'B-1204')` | no | mutates catalogue state on every attempt | | `.invoke('show')` on a hidden panel | usually | idempotent, but it re-fires jQuery's effect each time | The rule of thumb: `.invoke()` is safe as a **getter** and dangerous as a **command**. If the method name is a verb that changes something, sends something, or is being counted by a spy, do not reach `.invoke()` for it. ## The related gotcha next door `.invoke()` also drops the implicit existence check that `.its()` adds. `.its()` keeps retrying until the property is neither `null` nor `undefined`; `.invoke()` has no such requirement, and instead errors when the named property is not callable - *"errored because the property: `length` returned a `number` value instead of a function."* That error is a good sign you wanted `.its()`. The repeated-call problem and the missing existence check are the two things that make `.invoke()` the sharpest edge in the subject-yielding family, and both come from the same fact: it is a query that happens to run your code.