{
  "doc": {
    "id": "api/utilities/promise",
    "title": "Cypress.Promise | Cypress Documentation",
    "description": "Cypress automatically includes Bluebird and exposes it as Cypress.Promise.",
    "section": "api",
    "source_path": "/llm/markdown/api/utilities/promise.md",
    "version": "3cf5b86b3403f604bdf7f3e35025c3bc3865e02c",
    "updated_at": "2026-05-07T17:44:31.931Z",
    "headings": [
      {
        "id": "api/utilities/promise#cypress-promise",
        "text": "Cypress.Promise",
        "level": 1
      },
      {
        "id": "api/utilities/promise#syntax",
        "text": "Syntax",
        "level": 2
      },
      {
        "id": "api/utilities/promise#usage",
        "text": "Usage",
        "level": 3
      },
      {
        "id": "api/utilities/promise#examples",
        "text": "Examples",
        "level": 2
      },
      {
        "id": "api/utilities/promise#basic-promise",
        "text": "Basic Promise",
        "level": 3
      },
      {
        "id": "api/utilities/promise#waiting-for-promises",
        "text": "Waiting for Promises",
        "level": 3
      },
      {
        "id": "api/utilities/promise#notes",
        "text": "Notes",
        "level": 2
      },
      {
        "id": "api/utilities/promise#rejected-test-promises-do-not-fail-tests",
        "text": "Rejected test promises do not fail tests",
        "level": 3
      },
      {
        "id": "api/utilities/promise#see-also",
        "text": "See also",
        "level": 2
      }
    ]
  },
  "content": {
    "type": "root",
    "children": [
      {
        "type": "heading",
        "depth": 1,
        "children": [
          {
            "type": "text",
            "value": "Cypress.Promise"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Cypress automatically includes "
          },
          {
            "type": "link",
            "title": null,
            "url": "https://github.com/petkaantonov/bluebird",
            "children": [
              {
                "type": "text",
                "value": "Bluebird"
              }
            ]
          },
          {
            "type": "text",
            "value": " and exposes it as `Cypress.Promise`."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Instantiate a new bluebird promise."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Syntax"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "new Cypress.Promise(fn)"
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Usage"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Correct Usage"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "new Cypress.Promise((resolve, reject) => { ... })"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Incorrect Usage"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "new cy.Promise(...)  // Errors, cannot be chained off 'cy'"
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Examples"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Use `Cypress.Promise` to create promises. Cypress is promise aware so if you return a promise from inside of commands like "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/api/commands/then.md",
            "children": [
              {
                "type": "text",
                "value": "`.then()`"
              }
            ]
          },
          {
            "type": "text",
            "value": ", Cypress will not continue until those promises resolve."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Basic Promise"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "cy.get('button').then(($button) => {  return new Cypress.Promise((resolve, reject) => {    // do something custom here  })})"
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Waiting for Promises"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "it('waits for promises to resolve', () => {  let waited = false  function waitOneSecond() {    // return a promise that resolves after 1 second    return new Cypress.Promise((resolve, reject) => {      setTimeout(() => {        // set waited to true        waited = true        // resolve with 'foo' string        resolve('foo')      }, 1000)    })  }  cy.wrap(null).then(() => {    // return a promise to cy.then() that    // is awaited until it resolves    return waitOneSecond().then((str) => {      expect(str).to.eq('foo')      expect(waited).to.be.true    })  })})"
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Notes"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Rejected test promises do not fail tests"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "If the test code has an unhandled rejected promise, it does not automatically fail the test. If you do want to fail the test if there is an unhandled rejected promise in the test code you have to do one of two things:"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "If you use `Cypress.Promise` in your test code, register a callback using Bluebird's API"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "Cypress.Promise.onPossiblyUnhandledRejection((error, promise) => {  throw error})"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "If you use native built-in promises in your test code, register an event listener on the test `window` object:"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "window.addEventListener('unhandledrejection', (event) => {  throw event.reason})"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Note: because this is the test `window` object, such listeners are NOT reset before every test. You can register such listeners once using the `before` hook in the spec file."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "See also"
          }
        ]
      },
      {
        "type": "list",
        "ordered": false,
        "start": null,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/references/bundled-libraries.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "Bundled Libraries"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "The recipe "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/references/recipes.md#Fundamentals",
                    "children": [
                      {
                        "type": "text",
                        "value": "Handling errors"
                      }
                    ]
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  },
  "token_estimate": 431
}