Cypress API

Examples of uses of the Cypress API, for a full reference, go to docs.cypress.ioopen in new window

Cypress.Commands.add()open in new window

To add a command, use Cypress.Commands.add().

    prevSubject: true,
  (subject, method) => {
    method = method || 'log'

    // log the subject to the console
    console[method]('The subject is', subject)
    return subject
// prints the object to the window console
cy.wrap({ life: 42 }).console('info')

To yield a value from a custom command to the next command or assertion

    prevSubject: true,
  (value, method) => {
    return value * 2
cy.wrap(21).double().should('equal', 42)

You can also wrap a value to be returned - Cypress automatically takes the value of the last command.

    prevSubject: true,
  (value, method) => {
    cy.wrap(value * 3)
cy.wrap(21).triple().should('equal', 63)

Note: you cannot both use cy.wrap and return in the same code, since it is ambiguous, watch the video Fix The Cypress Error "You are mixing async and sync code"open in new window.

Calling other custom commands

You can call other custom commands from inside a custom command.

Cypress.Commands.add('name', () => 'Joe')
Cypress.Commands.add('greeting', () =>
  // call the custom command
  // then form the full greeting text and yield it => `Hello, ${n}`),
cy.greeting().should('equal', 'Hello, Joe')

Cypress.Commands.overwrite()open in new window

You can overwrite an existing Cypress command, either completely replacing it or wrapping with extra code. For example, to always repeat the string when typing, let's overwrite the cy.type command:

<input id="type-here" />
Cypress.Commands.overwrite('type', function (type, $el, text) {
  // call the original "type" command twice on the jQuery element
  return type($el, text + text)
  .should('have.value', 'HelloHello')

Rename and replace the cy.then command

See the recipe Replace cy.then command.

Cypress.Cookies.debug()open in new window

To enable or disable cookie debugging, use Cypress.Cookies.debug().

// Cypress will now log in the console when
// cookies are set or removed

cy.setCookie('fakeCookie', '123ABC')
cy.setCookie('fakeCookie', '123ABC')
cy.setCookie('fakeCookie', '123ABC')

Cypress.Cookies.preserveOnce() (deprecated)

Deprecated, use cypress-v10-preserve-cookieopen in new window.

To preserve cookies by its key, use Cypress.Cookies.preserveOnce().


// preserving a cookie will not clear it when
// the next test starts
cy.setCookie('lastCookie', '789XYZ')

Cypress.Cookies.default() (deprecated)

Deprecated, use cypress-v10-preserve-cookieopen in new window.

To set defaults for all cookies, use Cypress.Cookies.default().

  preserve: 'session_id',

Cypress.Server.default() (deprecated)

To change the default configuration for cy.server, use Cypress.Server.defaults().

  delay: 0,
  force404: true,
  ignore: function (xhr) {
    // handle custom logic for ignoring certain requests

Cypress.archopen in new window

To get CPU architecture name of underlying OS, use Cypress.arch.


Cypress.config()open in new window

To get or set configuration options, use Cypress.config(). Note: the config object should be reserved for Cypress settings, like baseUrl and viewportWidth. To store your custom values use the Cypress.env() approach.

const myConfig = Cypress.config()

// the config has a combination of default
// and user values from cypress.json file
expect(myConfig)'defaultCommandTimeout', 4000)
expect(myConfig)'requestTimeout', 5000)
expect(myConfig)'responseTimeout', 30000)
expect(myConfig)'viewportHeight', 1000)
  // previous assertion yields the value
  // now let's assert the value pretending
  // we only know min and max limits
  .within(600, 1000)
expect(myConfig)'pageLoadTimeout', 60000)
expect(myConfig)'waitForAnimations', true)
// we can check if the property is present without checking its value

// setting and getting an individual property

Cypress.config('pageLoadTimeout', 20000)


Cypress.config('pageLoadTimeout', 60000)

Cypress.dom.isHidden()open in new window

To see whether a DOM element is hidden, use Cypress.dom.isHidden().

<div class="dom-p">
  <p class="hidden">I'm hiding!</p>
  <p class="visible">I'm visible!</p>
let hiddenP = Cypress.$('.dom-p p.hidden').get(0)
let visibleP = Cypress.$('.dom-p p.visible').get(0)

// our first paragraph has css class 'hidden'

Tip: elements that are hidden have a special "crossed eye" icon next to them in the Command Log.

cy.get('.dom-p p.hidden').should('')
cy.get('.dom-p p.visible').should('be.visible')

Hidden element with the eye icon

Cypress.env()open in new window

To get or set environment variable, use Cypress.env().

// set multiple environment variables
  host: '',
  api_server: 'http://localhost:8888/v1/',

// get environment variable

// set environment variable
Cypress.env('api_server', 'http://localhost:8888/v2/')

// get all environment variable

Cypress.platformopen in new window

To get name of underlying OS, use Cypress.platform.


Cypress.platformopen in new window

To get name of underlying OS, use Cypress.platform.

// for example "darwin" on Mac

Cypress.versionopen in new window

To get version of Cypress being run, use Cypress.version.


Here is an example of parsing Cypress version and confirming it is at least v9. You can watch the explanation in the short video 📺 Parse Cypress Version String And Confirm The Major Versionopen in new window.

const [major, minor, patch] = Cypress.version
console.log({ major, minor, patch })
expect(major, '>= v9 requires')

Cypress.specopen in new window

Cypress.spec returns you the properties of the spec under test.

// wrap the object so we can inspect it easily by clicking in the command log
cy.wrap(Cypress.spec).should('include.keys', [

Multiple specs

If you are using cypress open to run multiple specs at once, you can detect it by using the Cypress.spec object. The field name will be set to "All Integration Specs" and the fields absolute and relative will be set to "__all".

if (Cypress.spec.absolute === '__all') {
  cy.log('Running several specs together')
} else {
  cy.log(`Running a single spec ${Cypress.spec.relative}`)

Cypress.currentTestopen in new window

Cypress.currentTest is an object representing the currently executing test instance, with properties to access the title of the test.

// wrap the object so we can inspect it easily by clicking in the command log
  .should('include.keys', ['title', 'titlePath'])
  .then((currentTest) => {
      'Get the current test information',
    // get the entire full title, including the parent suite titles
        'Cypress API', // the top suite
        'Cypress.currentTest', // the parent suite
        'Get the current test information', // the test title

Cypress.testingTypeopen in new window

Cypress.testingType returns the current testing type, determined by the Test Runner chosen to run. The Cypress.testingType returns "e2e" for Cypress Test Runner integration tests, or "component" for experimental Component Testingopen in new window.

expect(Cypress.testingType)['e2e', 'component'])
  // in this case, we are running e2e spec'e2e')