Yield the object passed into .wrap().

Syntax

cy.wrap(subject)
cy.wrap(subject, options)

Usage

Correct Usage

cy.wrap({ name: 'Jane Lane' })

Arguments

subject (Object)

An object to be yielded.

options (Object)

Pass in an options object to change the default behavior of cy.wrap().

Option	Default	Description
`log`	`true`	Displays the command in the Command log
`timeout`	`defaultCommandTimeout`	Time to wait for `cy.wrap()` to resolve before timing out

Yields

cy.wrap() yields the object it was called with.

Examples

Objects

Invoke the function on the subject in wrap and return the new value

const getName = () => {
  return 'Jane Lane'
}

cy.wrap({ name: getName }).invoke('name').should('eq', 'Jane Lane') // true

Elements

Wrap elements to continue executing commands

cy.get('form').within(($form) => {
  // ... more commands

  cy.wrap($form).should('have.class', 'form-container')
})

Conditionally wrap elements

cy
  .get('button')
  .then(($button) => {
    // $button is a wrapped jQuery element
    if ($button.someMethod() === 'something') {
      // wrap this element so we can
      // use cypress commands on it
      cy.wrap($button).click()
    } else {
      // do something else
    }
  })

Promises

You can wrap promises returned by the application code. Cypress commands will automatically wait for the promise to resolve before continuing with the yielded value to the next command or assertion. See the Logging in using application code recipe for the full example.

// import application code for logging in
import { userService } from '../../src/_services/user.service'

it('can assert against resolved object using .should', () => {
  cy.log('user service login')
  const username = Cypress.env('username')
  const password = Cypress.env('password')

  // wrap the promise returned by the application code
  cy.wrap(userService.login(username, password))
    // check the yielded object
    .should('be.an', 'object')
    .and('have.keys', ['firstName', 'lastName', 'username', 'id', 'token'])
    .and('contain', {
      username: 'test',
      firstName: 'Test',
      lastName: 'User'
    })

  // cy.visit command will wait for the promise returned from
  // the "userService.login" to resolve. Then local storage item is set
  // and the visit will immediately be authenticated and logged in
  cy.visit('/')
  // we should be logged in
  cy.contains('Hi Test!').should('be.visible')
})

Rules

Requirements

cy.wrap() requires being chained off of cy.

Assertions

cy.wrap() will automatically retry until assertions you've chained all pass.

Timeouts

cy.wrap() can time out waiting for assertions you've added to pass.

Command Log

Make assertions about object

cy.wrap({ amount: 10 })
  .should('have.property', 'amount')
  .and('eq', 10)

The commands above will display in the Command Log as:

When clicking on the wrap command within the command log, the console outputs the following:

History

Version	Changes
3.2.0	Retry `cy.wrap()` if `undefined` when followed by `.should()`
0.4.5	`cy.wrap()` command added

W3cubDocs

wrap