{
  "doc": {
    "id": "api/commands/wrap",
    "title": "wrap | Cypress Documentation",
    "description": "Yield the object passed into .wrap() in Cypress",
    "section": "api",
    "source_path": "/llm/markdown/api/commands/wrap.md",
    "version": "48b03b5502f7aea1d0454750cce208f775403542",
    "updated_at": "2026-05-20T19:00:20.270Z",
    "headings": [
      {
        "id": "api/commands/wrap#wrap",
        "text": "wrap",
        "level": 1
      },
      {
        "id": "api/commands/wrap#syntax",
        "text": "Syntax",
        "level": 2
      },
      {
        "id": "api/commands/wrap#usage",
        "text": "Usage",
        "level": 3
      },
      {
        "id": "api/commands/wrap#arguments",
        "text": "Arguments",
        "level": 3
      },
      {
        "id": "api/commands/wrap#yields-learn-about-subject-management",
        "text": "Yields Learn about subject management",
        "level": 3
      },
      {
        "id": "api/commands/wrap#examples",
        "text": "Examples",
        "level": 2
      },
      {
        "id": "api/commands/wrap#objects",
        "text": "Objects",
        "level": 3
      },
      {
        "id": "api/commands/wrap#invoke-the-function-on-the-subject-in-wrap-and-return-the-new-value",
        "text": "Invoke the function on the subject in wrap and return the new value",
        "level": 4
      },
      {
        "id": "api/commands/wrap#elements",
        "text": "Elements",
        "level": 3
      },
      {
        "id": "api/commands/wrap#wrap-elements-to-continue-executing-commands",
        "text": "Wrap elements to continue executing commands",
        "level": 4
      },
      {
        "id": "api/commands/wrap#conditionally-wrap-elements",
        "text": "Conditionally wrap elements",
        "level": 4
      },
      {
        "id": "api/commands/wrap#promises",
        "text": "Promises",
        "level": 3
      },
      {
        "id": "api/commands/wrap#simple-example",
        "text": "Simple example",
        "level": 4
      },
      {
        "id": "api/commands/wrap#application-example",
        "text": "Application example[",
        "level": 4
      },
      {
        "id": "api/commands/wrap#rules",
        "text": "Rules",
        "level": 2
      },
      {
        "id": "api/commands/wrap#requirements-learn-about-chaining-commands",
        "text": "Requirements Learn about chaining commands",
        "level": 3
      },
      {
        "id": "api/commands/wrap#assertions-learn-about-assertions",
        "text": "Assertions Learn about assertions",
        "level": 3
      },
      {
        "id": "api/commands/wrap#timeouts-learn-about-timeouts",
        "text": "Timeouts Learn about timeouts",
        "level": 3
      },
      {
        "id": "api/commands/wrap#command-log",
        "text": "Command Log",
        "level": 2
      },
      {
        "id": "api/commands/wrap#history",
        "text": "History",
        "level": 2
      },
      {
        "id": "api/commands/wrap#see-also",
        "text": "See also",
        "level": 2
      }
    ]
  },
  "chunks": [
    {
      "id": "api/commands/wrap#syntax",
      "doc_id": "api/commands/wrap",
      "heading": "Syntax",
      "heading_level": 2,
      "content_markdown": "## Syntax\n\n```\ncy.wrap(subject)cy.wrap(subject, options)\n```\n\n### Usage\n\n**Correct Usage**\n\n```\ncy.wrap({ name: 'Jane Lane' })\n```\n\n### Arguments\n\n**subject _(Object)_**\n\nAn object to be yielded.\n\n**options _(Object)_**\n\nPass in an options object to change the default behavior of `cy.wrap()`.\n\n| Option | Default | Description |\n| --- | --- | --- |\n| `log` | `true` | Displays the command in the [Command log](/llm/markdown/app/core-concepts/open-mode.md#Command-Log) |\n| `timeout` | [`defaultCommandTimeout`](/llm/markdown/app/references/configuration.md#Timeouts) | Time to wait for `cy.wrap()` to resolve before [timing out](#Timeouts) |\n\n### Yields [Learn about subject management](/llm/markdown/app/core-concepts/introduction-to-cypress.md#Subject-Management)\n\n*   `cy.wrap()` yields the object it was called with.\n",
      "section": "api",
      "anchors": [
        "syntax"
      ],
      "path": "/llm/json/chunked/api/commands/wrap.json",
      "token_estimate": 131
    },
    {
      "id": "api/commands/wrap#arguments",
      "doc_id": "api/commands/wrap",
      "heading": "Arguments",
      "heading_level": 3,
      "content_markdown": "### Arguments\n\n**subject _(Object)_**\n\nAn object to be yielded.\n\n**options _(Object)_**\n\nPass in an options object to change the default behavior of `cy.wrap()`.\n\n| Option | Default | Description |\n| --- | --- | --- |\n| `log` | `true` | Displays the command in the [Command log](/llm/markdown/app/core-concepts/open-mode.md#Command-Log) |\n| `timeout` | [`defaultCommandTimeout`](/llm/markdown/app/references/configuration.md#Timeouts) | Time to wait for `cy.wrap()` to resolve before [timing out](#Timeouts) |\n",
      "section": "api",
      "anchors": [
        "arguments"
      ],
      "path": "/llm/json/chunked/api/commands/wrap.json",
      "token_estimate": 88
    },
    {
      "id": "api/commands/wrap#examples",
      "doc_id": "api/commands/wrap",
      "heading": "Examples",
      "heading_level": 2,
      "content_markdown": "## Examples\n\n### Objects\n\n#### Invoke the function on the subject in wrap and return the new value\n\n```\nconst getName = () => {  return 'Jane Lane'}cy.wrap({ name: getName }).invoke('name').should('eq', 'Jane Lane') // true\n```\n\n### Elements\n\n#### Wrap elements to continue executing commands\n\n```\ncy.get('form').within(($form) => {  // ... more commands  cy.wrap($form).should('have.class', 'form-container')})\n```\n\n#### Conditionally wrap elements\n\n```\ncy.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  }})\n```\n\n### Promises\n\nYou 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](/llm/markdown/app/references/recipes.md#Logging-In) recipe for the full example.\n\n#### Simple example\n\n```\nconst myPromise = new Promise((resolve, reject) => {  // we use setTimeout(...) to simulate async code.  setTimeout(() => {    resolve({      type: 'success',      message: 'It worked!',    })  }, 2500)})it('should wait for promises to resolve', () => {  cy.wrap(myPromise).its('message').should('eq', 'It worked!')})\n```\n\n#### Application example[\n\nEnd-to-End Only\n\n](/llm/markdown/app/core-concepts/testing-types.md#What-is-E2E-Testing)\n\n```\n// import application code for logging inimport { userService } from '../../src/_services/user.service'it('can assert against resolved object using .should', () => {  cy.log('user service login')  cy.env(['username', 'password']).then(({ username, 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,        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')})\n```\n\n**Note:** `.wrap()` will not synchronize asynchronous function calls for you. For example, given the following example:\n\n*   You have two async functions `async function foo() {...}` and `async function bar() {...}`\n*   You need to make sure `foo()` has resolved first before invoking `bar()`\n*   `bar()` is also dependent on some data that is created while after calling other Cypress commands.\n\nIf you wrap the asynchronous functions in `cy.wrap()`, then `bar()` may be called prematurely before the required data is available:\n\n```\ncy.wrap(foo())cy.get('some-button').click()cy.get('some-input').type(someValue)cy.get('some-submit-button').click()// this will execute `bar()` immediately without waiting// for other cy.get(...) functions to completecy.wrap(bar()) // DON'T DO THIS\n```\n\nThis behavior is due to the function invocation `foo()` and `bar()`, which call the functions immediately to return a Promise.\n\nIf you want `bar()` to execute after `foo()` and the [cy.get()](/llm/markdown/api/commands/get.md) commands, one solution is to chain off the final command using [.then()](/llm/markdown/api/commands/then.md):\n\n```\ncy.wrap(foo())cy.get('some-button').click()cy.get('some-input').type(someValue)cy.get('some-submit-button')  .click()  .then(() => {    // this will execute `bar()` after the    // other cy.get(...) functions complete    cy.wrap(bar())  })\n```\n",
      "section": "api",
      "anchors": [
        "examples"
      ],
      "path": "/llm/json/chunked/api/commands/wrap.json",
      "token_estimate": 621
    },
    {
      "id": "api/commands/wrap#objects",
      "doc_id": "api/commands/wrap",
      "heading": "Objects",
      "heading_level": 3,
      "content_markdown": "### Objects\n\n#### Invoke the function on the subject in wrap and return the new value\n\n```\nconst getName = () => {  return 'Jane Lane'}cy.wrap({ name: getName }).invoke('name').should('eq', 'Jane Lane') // true\n```\n",
      "section": "api",
      "anchors": [
        "objects"
      ],
      "path": "/llm/json/chunked/api/commands/wrap.json",
      "token_estimate": 45
    },
    {
      "id": "api/commands/wrap#invoke-the-function-on-the-subject-in-wrap-and-return-the-new-value",
      "doc_id": "api/commands/wrap",
      "heading": "Invoke the function on the subject in wrap and return the new value",
      "heading_level": 4,
      "content_markdown": "#### Invoke the function on the subject in wrap and return the new value\n\n```\nconst getName = () => {  return 'Jane Lane'}cy.wrap({ name: getName }).invoke('name').should('eq', 'Jane Lane') // true\n```\n",
      "section": "api",
      "anchors": [
        "invoke-the-function-on-the-subject-in-wrap-and-return-the-new-value"
      ],
      "path": "/llm/json/chunked/api/commands/wrap.json",
      "token_estimate": 43
    },
    {
      "id": "api/commands/wrap#elements",
      "doc_id": "api/commands/wrap",
      "heading": "Elements",
      "heading_level": 3,
      "content_markdown": "### Elements\n\n#### Wrap elements to continue executing commands\n\n```\ncy.get('form').within(($form) => {  // ... more commands  cy.wrap($form).should('have.class', 'form-container')})\n```\n\n#### Conditionally wrap elements\n\n```\ncy.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  }})\n```\n",
      "section": "api",
      "anchors": [
        "elements"
      ],
      "path": "/llm/json/chunked/api/commands/wrap.json",
      "token_estimate": 84
    },
    {
      "id": "api/commands/wrap#conditionally-wrap-elements",
      "doc_id": "api/commands/wrap",
      "heading": "Conditionally wrap elements",
      "heading_level": 4,
      "content_markdown": "#### Conditionally wrap elements\n\n```\ncy.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  }})\n```\n",
      "section": "api",
      "anchors": [
        "conditionally-wrap-elements"
      ],
      "path": "/llm/json/chunked/api/commands/wrap.json",
      "token_estimate": 57
    },
    {
      "id": "api/commands/wrap#promises",
      "doc_id": "api/commands/wrap",
      "heading": "Promises",
      "heading_level": 3,
      "content_markdown": "### Promises\n\nYou 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](/llm/markdown/app/references/recipes.md#Logging-In) recipe for the full example.\n\n#### Simple example\n\n```\nconst myPromise = new Promise((resolve, reject) => {  // we use setTimeout(...) to simulate async code.  setTimeout(() => {    resolve({      type: 'success',      message: 'It worked!',    })  }, 2500)})it('should wait for promises to resolve', () => {  cy.wrap(myPromise).its('message').should('eq', 'It worked!')})\n```\n\n#### Application example[\n\nEnd-to-End Only\n\n](/llm/markdown/app/core-concepts/testing-types.md#What-is-E2E-Testing)\n\n```\n// import application code for logging inimport { userService } from '../../src/_services/user.service'it('can assert against resolved object using .should', () => {  cy.log('user service login')  cy.env(['username', 'password']).then(({ username, 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,        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')})\n```\n\n**Note:** `.wrap()` will not synchronize asynchronous function calls for you. For example, given the following example:\n\n*   You have two async functions `async function foo() {...}` and `async function bar() {...}`\n*   You need to make sure `foo()` has resolved first before invoking `bar()`\n*   `bar()` is also dependent on some data that is created while after calling other Cypress commands.\n\nIf you wrap the asynchronous functions in `cy.wrap()`, then `bar()` may be called prematurely before the required data is available:\n\n```\ncy.wrap(foo())cy.get('some-button').click()cy.get('some-input').type(someValue)cy.get('some-submit-button').click()// this will execute `bar()` immediately without waiting// for other cy.get(...) functions to completecy.wrap(bar()) // DON'T DO THIS\n```\n\nThis behavior is due to the function invocation `foo()` and `bar()`, which call the functions immediately to return a Promise.\n\nIf you want `bar()` to execute after `foo()` and the [cy.get()](/llm/markdown/api/commands/get.md) commands, one solution is to chain off the final command using [.then()](/llm/markdown/api/commands/then.md):\n\n```\ncy.wrap(foo())cy.get('some-button').click()cy.get('some-input').type(someValue)cy.get('some-submit-button')  .click()  .then(() => {    // this will execute `bar()` after the    // other cy.get(...) functions complete    cy.wrap(bar())  })\n```\n",
      "section": "api",
      "anchors": [
        "promises"
      ],
      "path": "/llm/json/chunked/api/commands/wrap.json",
      "token_estimate": 489
    },
    {
      "id": "api/commands/wrap#simple-example",
      "doc_id": "api/commands/wrap",
      "heading": "Simple example",
      "heading_level": 4,
      "content_markdown": "#### Simple example\n\n```\nconst myPromise = new Promise((resolve, reject) => {  // we use setTimeout(...) to simulate async code.  setTimeout(() => {    resolve({      type: 'success',      message: 'It worked!',    })  }, 2500)})it('should wait for promises to resolve', () => {  cy.wrap(myPromise).its('message').should('eq', 'It worked!')})\n```\n",
      "section": "api",
      "anchors": [
        "simple-example"
      ],
      "path": "/llm/json/chunked/api/commands/wrap.json",
      "token_estimate": 59
    },
    {
      "id": "api/commands/wrap#application-example",
      "doc_id": "api/commands/wrap",
      "heading": "Application example[",
      "heading_level": 4,
      "content_markdown": "#### Application example[\n\nEnd-to-End Only\n\n](/llm/markdown/app/core-concepts/testing-types.md#What-is-E2E-Testing)\n\n```\n// import application code for logging inimport { userService } from '../../src/_services/user.service'it('can assert against resolved object using .should', () => {  cy.log('user service login')  cy.env(['username', 'password']).then(({ username, 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,        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')})\n```\n\n**Note:** `.wrap()` will not synchronize asynchronous function calls for you. For example, given the following example:\n\n*   You have two async functions `async function foo() {...}` and `async function bar() {...}`\n*   You need to make sure `foo()` has resolved first before invoking `bar()`\n*   `bar()` is also dependent on some data that is created while after calling other Cypress commands.\n\nIf you wrap the asynchronous functions in `cy.wrap()`, then `bar()` may be called prematurely before the required data is available:\n\n```\ncy.wrap(foo())cy.get('some-button').click()cy.get('some-input').type(someValue)cy.get('some-submit-button').click()// this will execute `bar()` immediately without waiting// for other cy.get(...) functions to completecy.wrap(bar()) // DON'T DO THIS\n```\n\nThis behavior is due to the function invocation `foo()` and `bar()`, which call the functions immediately to return a Promise.\n\nIf you want `bar()` to execute after `foo()` and the [cy.get()](/llm/markdown/api/commands/get.md) commands, one solution is to chain off the final command using [.then()](/llm/markdown/api/commands/then.md):\n\n```\ncy.wrap(foo())cy.get('some-button').click()cy.get('some-input').type(someValue)cy.get('some-submit-button')  .click()  .then(() => {    // this will execute `bar()` after the    // other cy.get(...) functions complete    cy.wrap(bar())  })\n```\n",
      "section": "api",
      "anchors": [
        "application-example"
      ],
      "path": "/llm/json/chunked/api/commands/wrap.json",
      "token_estimate": 371
    },
    {
      "id": "api/commands/wrap#rules",
      "doc_id": "api/commands/wrap",
      "heading": "Rules",
      "heading_level": 2,
      "content_markdown": "## Rules\n\n### Requirements [Learn about chaining commands](/llm/markdown/app/core-concepts/introduction-to-cypress.md#Chains-of-Commands)\n\n*   `cy.wrap()` requires being chained off of `cy`.\n\n### Assertions [Learn about assertions](/llm/markdown/app/core-concepts/introduction-to-cypress.md#Assertions)\n\n*   `cy.wrap()`, when its argument is a promise, will automatically wait until the promise resolves. If the promise is rejected, `cy.wrap()` will fail the test.\n*   `cy.wrap()` will automatically [retry](/llm/markdown/app/core-concepts/retry-ability.md) until all chained assertions have passed.\n\n### Timeouts [Learn about timeouts](/llm/markdown/app/core-concepts/introduction-to-cypress.md#Timeouts)\n\n*   `cy.wrap()` can time out waiting for assertions you've added to pass.\n",
      "section": "api",
      "anchors": [
        "rules"
      ],
      "path": "/llm/json/chunked/api/commands/wrap.json",
      "token_estimate": 99
    },
    {
      "id": "api/commands/wrap#assertions-learn-about-assertions",
      "doc_id": "api/commands/wrap",
      "heading": "Assertions Learn about assertions",
      "heading_level": 3,
      "content_markdown": "### Assertions [Learn about assertions](/llm/markdown/app/core-concepts/introduction-to-cypress.md#Assertions)\n\n*   `cy.wrap()`, when its argument is a promise, will automatically wait until the promise resolves. If the promise is rejected, `cy.wrap()` will fail the test.\n*   `cy.wrap()` will automatically [retry](/llm/markdown/app/core-concepts/retry-ability.md) until all chained assertions have passed.\n",
      "section": "api",
      "anchors": [
        "assertions-learn-about-assertions"
      ],
      "path": "/llm/json/chunked/api/commands/wrap.json",
      "token_estimate": 55
    },
    {
      "id": "api/commands/wrap#command-log",
      "doc_id": "api/commands/wrap",
      "heading": "Command Log",
      "heading_level": 2,
      "content_markdown": "## Command Log\n\n**_Make assertions about object_**\n\n```\ncy.wrap({ amount: 10 }).should('have.property', 'amount').and('eq', 10)\n```\n\nThe commands above will display in the Command Log as:\n\nWhen clicking on the `wrap` command within the command log, the console outputs the following:\n",
      "section": "api",
      "anchors": [
        "command-log"
      ],
      "path": "/llm/json/chunked/api/commands/wrap.json",
      "token_estimate": 53
    },
    {
      "id": "api/commands/wrap#history",
      "doc_id": "api/commands/wrap",
      "heading": "History",
      "heading_level": 2,
      "content_markdown": "## History\n\n| Version | Changes |\n| --- | --- |\n| [3.2.0](/llm/markdown/app/references/changelog.md#3-2-0) | Retry `cy.wrap()` if `undefined` when followed by [.should()](/llm/markdown/api/commands/should.md) |\n| [0.4.5](/llm/markdown/app/references/changelog.md#0-4-5) | `cy.wrap()` command added |\n",
      "section": "api",
      "anchors": [
        "history"
      ],
      "path": "/llm/json/chunked/api/commands/wrap.json",
      "token_estimate": 41
    }
  ]
}