In Cypress, what does cy.wrap() do, and when do you need it?

## The subject is what a chain passes along Every Cypress command hands exactly one value - its **subject** - to whatever is chained after it. `cy.get('[data-cy=book-row]')` yields a jQuery collection of matching rows, `cy.title()` yields a string, `cy.window()` yields the application's `window` object. The next link receives that subject without you naming it, which is why `cy.get('[data-cy=book-row]').first().click()` reads the way it does: `.first()` narrows the subject, `.click()` acts on what `.first()` handed over. `cy.wrap(value)` is how you put something into that pipeline **from outside it**. It is a parent command, so it starts a fresh chain, and its subject is exactly the argument you gave it. From that point on the value is an ordinary Cypress subject: `.its()`, `.invoke()`, `.then()`, `.each()` and retrying `.should()` assertions all work against it, and it gets its own entry in the Command Log. ## The four jobs it actually does - **Assert on a plain value.** A borrow count read out of a fixture is not a DOM node, but `cy.wrap(loan.copiesLeft).should('eq', 2)` still gets a real Cypress assertion, with the Command Log entry and the diffed failure message that comes with it. - **Re-enter the chain from inside a callback.** The `$row` that `.then(($row) => ...)` gives you is a jQuery object, not a chainer. `$row.click()` is **jQuery's** `click()`: it dispatches a DOM event synchronously, right now, outside the queue. `cy.wrap($row).click()` enqueues Cypress's own `.click()` behind the commands already in flight. - **Wait for a promise.** `cy.wrap()` resolves a promise argument before yielding, so `cy.wrap(libraryApi.findBook('B-1204')).its('title').should('eq', 'Dune')` waits for the application's own promise and fails the test if it rejects. - **Give a child command a subject.** `.its()` and `.invoke()` require a previous command; call one straight off `cy` and Cypress answers *"you are trying to call a child command before running a parent command"*. `cy.wrap(loan).its('borrower.name')` is the shortest legal way to read a nested property off an object literal. ## What it changes, and what it leaves alone | you have | you write | the next command sees | |---|---|---| | a plain object or number | `cy.wrap(loan)` | that same value, unchanged | | a jQuery element from a callback | `cy.wrap($row)` | the element, as a Cypress subject | | a promise from application code | `cy.wrap(promise)` | the resolved value | | a rejected promise | `cy.wrap(promise)` | nothing - the command fails the test | `cy.wrap()` does **not** make the wrapped value live. It captures the reference you passed at the moment the command ran; if the application later replaces that object with a new one, the wrapped subject still points at the old one. It also does not turn a plain object into a DOM subject - element-only commands such as `.click()` or `.type()` still error unless the wrapped value really is an element. An assertion chained onto `cy.wrap()` does retry: Cypress re-checks the **same** captured subject until the assertion passes or `defaultCommandTimeout` expires. That is genuinely useful for a value your application mutates in place, such as an array it keeps pushing into, and useless for one it recomputes and reassigns - for that, query the page again instead. ## A library catalogue example, end to end 1. Query the row you care about and hand the jQuery element to a callback: `cy.get('[data-cy=book-row]').contains('Dune').then(($row) => { ... })`. 2. Inside the callback, read whatever you need with jQuery: `$row.attr('data-book-id')`, `$row.find('[data-cy=due-date]').text()`. Reading is safe and synchronous. 3. Re-enter the chain for anything Cypress should own: `cy.wrap($row).find('[data-cy=borrow]').click()`. 4. Assert on the plain value you captured: `cy.wrap($row.attr('data-book-id')).should('match', /^B-\d{4}$/)`. Steps 2 and 3 are the split that trips people. jQuery is fine for **reading** a value you already have in hand; every **action** should go back through a Cypress command so it is queued in order, snapshotted, and visible in the Command Log when the test fails at three in the morning in CI. ## Where it goes wrong - **Calling `.its()` or `.invoke()` off `cy`.** Both are child commands. Start with `cy.wrap()` or any query first. - **Expecting `cy.wrap()` to re-read.** The subject is the reference captured when the command ran, not a live view of application state. - **Wrapping a scraped string instead of querying the page.** If the value is on screen, query it so the assertion retries against the real DOM rather than against a snapshot you took earlier. - **Drowning the Command Log.** Pass `{ log: false }` when the wrapped subject is a large object, and put a readable message in a `cy.log()` call instead.