Why can't a Cypress cy.origin() callback see variables declared outside it?

## Two instances of Cypress, one test A `cy.origin()` block is not a scoping construct in your spec — it is a **remote procedure call**. When the block runs, Cypress injects a second copy of itself into the origin you named (the docs call this the *spec bridge*), sets up bidirectional communication with it, takes the callback function, converts it to a string, sends the string across, and evaluates it in that other instance. Everything follows from that one fact. The function that eventually runs was rebuilt from source text in a different JavaScript realm. It never had a closure over your spec, so: - a `const` or `let` declared above the block is simply not defined inside it, and you get a `ReferenceError` naming it - an `import` at the top of the spec file is not in scope either - helper functions defined in the spec are invisible, however small - values captured from a `beforeEach` hook or an outer `.then()` are equally gone This fails at **run time**, not at type-check time: the code looks perfectly valid to TypeScript and to your editor, which is why the mistake survives review so often. ## `args` is the only door in The `options` object accepts exactly one key, `args`, and its value is delivered as the callback's first and only argument: ```js const account = { id: 'ACC-88213', month: '2026-08' } cy.origin( 'https://viewer.pdfhost.example', { args: account }, ({ id, month }) => { cy.visit(`/documents/${id}/${month}`) } ) ``` Transport is the web platform's **structured clone algorithm** — the same mechanism used to post a message to a worker — so what can travel is decided by that algorithm, not by Cypress. | What you want to pass | Does it survive? | What to do instead | | --- | --- | --- | | Strings, numbers, booleans, `null` | Yes | — | | Plain objects and arrays, nested | Yes | — | | `Date`, `Map`, `Set`, typed arrays | Yes | — | | A function or an arrow function | No | move the logic into the callback body | | A DOM element or jQuery object from `cy.get()` | No | re-query it inside the block | | A class instance such as a page object | Structure survives, methods do not | import the class inside with `Cypress.require()` | | A `Symbol` | No | pass a string key instead | When something unsupported is passed, the failure is explicit: Cypress reports that the value could not be serialized and names the reason — a function, a symbol, or a property the algorithm does not support. ## The same wall on the way out `cy.origin()` yields whatever the last command inside the callback yielded, and that value has to come back across the same boundary. So this fails: ```js cy.origin('https://viewer.pdfhost.example', () => { cy.get('[data-cy=doc-title]') // yields a jQuery element… }).should('contain', 'ACC-88213') // …which cannot be serialized back ``` There are two clean fixes, and the first is usually better: 1. **Keep the assertion inside the block.** Nothing needs to cross at all, and the failure message stays attached to the origin it came from. 2. **Yield a serializable projection.** `cy.get('[data-cy=doc-title]').invoke('text')` yields a string, which crosses happily and can be asserted on outside. A thrown value obeys the rule too: if a command inside the block throws something the algorithm cannot clone, Cypress reports that it could not serialize the thrown value rather than the original error, which is a confusing failure to debug — so throw `Error` objects and plain values inside the callback. ## Getting code across, not just data Because the callback is extracted from the spec bundle before it is preprocessed, neither CommonJS `require()` nor a dynamic `import()` works inside it. Cypress supplies `Cypress.require()` for this, gated behind the `experimentalOriginDependencies` configuration option. It takes a **static, single-line string** — a variable holding a module name will not resolve — and it may only be called inside a `cy.origin()` callback. That is how a shared page object or an npm package reaches the block: require the module inside the callback and construct it there, and keep using `args` for the data it needs. The execution context also persists between blocks for the **same** origin within a spec, so requiring your custom commands once in a `before` hook makes them available to every later block for that origin.