Using Cypress

Improve this doc
  1. How do I get an element’s text contents?
  2. How do I get an input’s value?
  3. How do I compare the value or state of one thing to another?
  4. How do I get the native DOM reference of an element found using Cypress?
  5. How do I do something different if an element doesn’t exist?
  6. Can I throttle network speeds using Cypress?
  7. Can I use the new ES7 async / await syntax?
  8. How do I select or query for elements if my application uses dynamic classes or dynamic IDs?
  9. Is there a suggested way or best practice for how I should target elements or write element selectors?
  10. Can I prevent Cypress from failing my test when my application throws an uncaught exception error?
  11. Can I override environment variables or create configuration for different environments?
  12. Can I override or change the default user agent the browser uses?
  13. Can I block traffic going to specific domains? I want to block Google Analytics or other providers.
  14. How can I verify that calls to analytics like Google Analytics are being made correct?
  15. I’m trying to test a chat application. Can I run more than one browser at a time with Cypress?
  16. Can I test a chrome extension? How do I load my chrome extension?
  17. How can I modify or pass arguments used to launch the browser?
  18. Can I make cy.request() poll until a condition is met?
  19. Can I use the Page Object pattern?
  20. How can I parallelize my runs?
  21. Can I run a single test or group of tests?
  22. How do I test uploading a file?
  23. What is the projectId for?
  24. What is a Record Key?
  25. How do I check that an email was sent out?
  26. How do I wait for multiple XHR requests to the same url?
  27. How do I seed / reset my database?
  28. How do I test elements inside an iframe?
  29. How do I preserve cookies / localStorage in between my tests?
  30. Some of my elements animate in, how do I work around that?
  31. Can I test anchor links that open in a new tab?
  32. How do I require or import node modules in Cypress?
  33. Is there a way to give a proper SSL certificate to your proxy so the page doesn’t show up as “not secure”?
  34. Is there any way to detect if my app is running under Cypress?
  35. Do you allow before, beforeEach, after, or afterEach hooks?
  36. I tried to install Cypress in my CI, but I get the error: EACCES: permission denied.
  37. Is there a way to test that a file got downloaded? I want to test that a button click triggers a download.
  38. Is it possible to catch the promise chain in Cypress?
  39. Is there a way to modify the screenshots/video resolution?
  40. Does Cypress support ES7?
  41. How does one determine what the latest version of Cypress is?
  42. Is there an ESLint plugin for Cypress or a list of globals?
  43. When I visit my site directly, the certificate is verified, however the browser launched through Cypress is showing it as “Not Secure”. Why?
  44. Is there an option to run Cypress headlessly with DevTools open? We want to track network and console issues.
  45. How do I run the server and tests together and then shutdown the server?
  46. Can I test my Electron app?
  47. I found a bug! What do I do?

How do I get an element’s text contents?

Cypress commands yield jQuery objects, so you can simply call methods on them.

If you’re just trying to assert on an element’s text content:

cy.get('div').should('have.text', 'foobarbaz')

If you’d like to work with the text prior to an assertion:

cy.get('div').should(($div) => {
  const text = $div.text()

  expect(text).to.match(/foo/)
  expect(text).to.include('foo')
  expect(text).not.to.include('bar')
})

If you need to hold a reference or compare values of text:

cy.get('div').invoke('text').then((text1) => {
  // do more work here

  // click the button which changes the div's text
  cy.get('button').click()

  // grab the div again and compare its previous text
  // to the current text
  cy.get('div').invoke('text').should((text2) => {
    expect(text1).not.to.eq(text2)
  })
})

jQuery’s .text() method automatically calls elem.textContent under the hood. If you’d like to instead use innerText you can do the following:

cy.get('div').should(($div) => {
  // access the native DOM element
  expect($div.get(0).innerText).to.eq('foobarbaz')
})

This is the equivalent of Selenium’s getText() method, which returns the innerText of a visible element.

How do I get an input’s value?

Cypress yields you jQuery objects, so you can simply call methods on them.

If you’re just trying to assert on an input’s value:

// make an assertion on the value
cy.get('input').should('have.value', 'abc')

If you’d like to massage or work with the text prior to an assertion:

cy.get('input').should(($input) => {
  const val = $input.val()

  expect(val).to.match(/foo/)
  expect(val).to.include('foo')
  expect(val).not.to.include('bar')
})

If you need to hold a reference reference or compare values of text:

cy.get('input').invoke('val').then((val1) => {
  // do more work here

  // click the button which changes the input's value
  cy.get('button').click()

  // grab the input again and compare its previous value
  // to the current value
  cy.get('input').invoke('val').should((val2) => {
    expect(val1).not.to.eq(val2)
  })
})

How do I compare the value or state of one thing to another?

Our Variables and Aliases guide gives you examples of doing exactly that.

How do I get the native DOM reference of an element found using Cypress?

Cypress wraps elements in jQuery so you’d just get the native element from there within a .then() command.

cy.get('button').then(($el) => {
  $el.get(0)
})

How do I do something different if an element doesn’t exist?

What you’re asking about is conditional testing and control flow.

Please read our extensive Conditional Testing Guide which explains this in detail.

Can I throttle network speeds using Cypress?

You can throttle your network connection by accessing your Chrome DevTools Network panel. Additionally, you can add your own custom presets by selecting Custom > Add from the Network Conditions drawer.

We do not currently offer any options to simulate this headlessly.

Can I use the new ES7 async / await syntax?

No. The Command API is not designed in a way that makes this possible. This is not a limitation of Cypress - it is a very conscious and important design decision.

Async / await is sugar around promises and Cypress commands are a mixture of both promises and streams.

If you’re curious please read:

How do I select or query for elements if my application uses dynamic classes or dynamic IDs?

Easy - you don’t use classes or ID’s. You add data-* attributes to your elements and target them that way.

Read more about the best practices for selecting elements here.

Is there a suggested way or best practice for how I should target elements or write element selectors?

Yes. Read more about the best practices for selecting elements here.

Can I prevent Cypress from failing my test when my application throws an uncaught exception error?

Yes.

By default Cypress will automatically fail tests whenever an uncaught exception bubbles up out of your app.

Cypress exposes an event for this (amongst many others) that you can listen for to either:

  • Debug the error instance itself
  • Prevent Cypress from failing the test

This is documented in detail on the Catalog Of Events page.

Can I override environment variables or create configuration for different environments?

Yes, you use your pluginsFile to modify configuration values and environment variables.

We have a whole API document showing you how to do just that.

Can I override or change the default user agent the browser uses?

Yes. You can override this with userAgent in cypress.json.

Can I block traffic going to specific domains? I want to block Google Analytics or other providers.

Yes. You can set this with blacklistHosts in cypress.json.

Also, check out our Google Analytics Recipe.

How can I verify that calls to analytics like Google Analytics are being made correct?

Easy - you stub their functions and then ensure they’re being called.

Check out our Google Analytics Recipe.

I’m trying to test a chat application. Can I run more than one browser at a time with Cypress?

We’ve answered this question in detail here.

Can I test a chrome extension? How do I load my chrome extension?

Yes. You can test your extensions by loading them when we launch the browser..

How can I modify or pass arguments used to launch the browser?

You use the before:browser:launch plugin event.

Can I make cy.request() poll until a condition is met?

Yes. You do it the same way as any other recursive loop.

Can I use the Page Object pattern?

Yes.

The page object pattern isn’t actually anything “special”. If you’re coming from Selenium you may be accustomed to creating instances of classes, but this is completely unnecessary and irrelevant.

The “Page Object Pattern” should really be renamed to: “Using functions and creating custom commands”.

If you’re looking to abstract behavior or roll up a series of actions you can create reusable Custom Commands with our API. You can also just use regular ol’ JavaScript functions without any of the ceremony typical with “Page Objects”.

For those wanting to use page objects, we’ve highlighted the best practices for replicating the page object pattern.

How can I parallelize my runs?

You can read more about parallelization here.

Can I run a single test or group of tests?

You can run a group of tests or a single test by placing an .only on a test suite or specific test.

You can run a single test file headlessly by passing the --spec flag to cypress run.

Currently there is no way to specify a group of test files to run headlessly. You can read more here.

How do I test uploading a file?

It is possible to upload files in your application but it’s different based on how you’ve written your own upload code. You can read more about this here

What is the projectId for?

Once you set up your tests to record, we generate a unique projectId for your project and automatically insert it into your cypress.json file.

The projectId is a 6 character string in your cypress.json:

{
  "projectId": "a7bq2k"
}

This is how we uniquely identify your project. If you manually alter this, Cypress will no longer be able to identify your project or find the recorded tests for it. We recommend that you check your cypress.json, including the projectId, into source control.

What is a Record Key?

Once you’re set up to record test runs, we automatically generate a Record Key for the project.

A record key is a GUID that looks like this:

f4466038-70c2-4688-9ed9-106bf013cd73

You can create multiple Record Keys for a project, or delete existing ones from our Dashboard Service.

You can also find your Record Key inside of the Settings tab in the Test Runner.

Settings Tab of Test Runner

How do I check that an email was sent out?

Anti-Pattern

Don’t try to use your UI to check email. Instead opt to programmatically use 3rd party API’s or talk directly to your server. Read about this best practice here.

How do I wait for multiple XHR requests to the same url?

You should set up an alias (using .as()) to a single cy.route() that matches all of the XHRs. You can then cy.wait() on it multiple times. Cypress keeps track of how many matching XHR requests there are.

cy.server()
cy.route('users').as('getUsers')
cy.wait('@getUsers')  // Wait for first GET to /users/
cy.get('#list>li').should('have.length', 10)
cy.get('#load-more-btn').click()
cy.wait('@getUsers')  // Wait for second GET to /users/
cy.get('#list>li').should('have.length', 20)

How do I seed / reset my database?

You can use either cy.request() or cy.exec() to talk to your backend to seed data.

You could also just stub XHR requests directly using cy.route() which avoids ever even needing to fuss with your database.

How do I test elements inside an iframe?

As of 0.20.0 you can now wrap the elements of an iframe and work with them.

We have an open proposal to expand the API’s to support “switching into” an iframe and then back out of them.

How do I preserve cookies / localStorage in between my tests?

By default, Cypress automatically clears all cookies before each test to prevent state from building up.

You can whitelist specific cookies to be preserved across tests using the Cypress.Cookies api:

// now any cookie with the name 'session_id' will
// not be cleared before each test runs
Cypress.Cookies.defaults({
  whitelist: "session_id"
})

You can not currently preserve localStorage across tests and can read more here.

Some of my elements animate in, how do I work around that?

Oftentimes you can usually account for animation by asserting .should('be.visible') or another assertion on one of the elements you expect to be animated in.

// assuming a click event causes the animation
cy.get('.element').click().should('not.have.class', 'animating')

If the animation is especially long, you could extend the time Cypress waits for the assertion to pass by increasing the timeout of the previous command before the assertion.

cy.get('button', { timeout: 10000 }) // wait up to 10 seconds for this 'button' to exist
  .should('be.visible')              // and to be visible

cy.get('.element').click({ timeout: 10000 }).should('not.have.class', 'animating')
// wait up to 10 seconds for the .element to not have 'animating' class

However, most of the time you don’t even have to worry about animations. Why not? Cypress will automatically wait for elements to stop animating prior to interacting with them via action commands like .click() or .type().

Can I test anchor links that open in a new tab?

Cypress does not and may never have multi-tab support for various reasons.

Luckily there are lots of easy and safe workarounds that enable you to test this behavior in your application.

Read through this recipe to see how to test anchor links.

How do I require or import node modules in Cypress?

The code you write in Cypress is executed in the browser, so you can import or require JS modules, but only those that work in a browser.

You can simply require or import them as you’re accustomed to. We preprocess your spec files with babel and browserify.

Cypress doesn’t have direct access to node or your file system. We recommend utilizing cy.exec() or cy.readFile() to execute a shell command or a node script that will do what you need.

Check out this example recipe.

Is there a way to give a proper SSL certificate to your proxy so the page doesn’t show up as “not secure”?

No, Cypress modifies network traffic in real time and therefore must sit between your server and the browser. There is no other way for us to achieve that.

Is there any way to detect if my app is running under Cypress?

You can check for the existence of window.Cypress, in your application code.

Here’s a simple example:

if (window.Cypress) {
  // we are running in Cypress
  // so do something different here
  window.env = 'test'
} else {
  // we are running in a regular ol' browser
}

Do you allow before, beforeEach, after, or afterEach hooks?

Yes. You can read more here.

I tried to install Cypress in my CI, but I get the error: EACCES: permission denied.

First, make sure you have node installed on your system. npm is a node package that is installed globally by default when you install node and is required to install our cypress npm package.

Next, you’d want to check that you have the proper permissions for installing on your system or you may need to run sudo npm install cypress.

Is there a way to test that a file got downloaded? I want to test that a button click triggers a download.

There are a lot of ways to test this, so it depends. You’ll need to be aware of what actually causes the download, then think of a way to test that mechanism.

If your server sends specific disposition headers which cause a browser to prompt for download, you can figure out what URL this request is made to, and use cy.request() to hit that directly. Then you can test that the server send the right response headers.

If it’s just an anchor that initiates the download, you could just test that it has the right href property. As long as you can verify that clicking the button is going to make the right HTTP request, there’s nothing else to test for.

In the end, it’s up to you to know your implementation and to test just enough to cover everything.

Is it possible to catch the promise chain in Cypress?

No. You cannot add a .catch error handler to a failed command. Read more about how the Cypress commands are not Promises

Is there a way to modify the screenshots/video resolution?

Not at the moment. There is an open issue for this.

Does Cypress support ES7?

Yes. You can customize how specs are processed by using one of our preprocessor plugins or by writing your own custom preprocessor.

Typically you’d reuse your existing babel, webpack, typescript configurations.

How does one determine what the latest version of Cypress is?

There are a few ways.

  • The easiest way is probably to check our changelog.
  • You can also check the latest version here.
  • It’s also always in our repo.

Is there an ESLint plugin for Cypress or a list of globals?

Yes! Check out our ESLint plugin. It will set up all the globals you need for running Cypress, including browser globals and Mocha globals.

When I visit my site directly, the certificate is verified, however the browser launched through Cypress is showing it as “Not Secure”. Why?

This is normal. Cypress modifies the traffic between your server and the browser. The browser notices this and displays a certificate warning. However, this is purely cosmetic and does not alter the way your application under test runs in any way, so you can safely ignore this warning.

Is there an option to run Cypress headlessly with DevTools open? We want to track network and console issues.

No. This is definitely the motivation behind this open issue, but there is not a way to run Cypress headlessly with DevTools open.

You may try running the tests locally and select the Electron browser, that’s as close as you’ll get with DevTools open and replicating the environment that was run headlessly.

How do I run the server and tests together and then shutdown the server?

To start the server, run the tests and then shutdown the server we recommend these NPM tools.

Can I test my Electron app?

Testing your Electron app will not ‘just work’, as Cypress is designed to test anything that runs in a browser and Electron is a browser + node.

That being said, we use Cypress to test our own Desktop app’s front end - by stubbing events from Electron. These tests are open source so you can check them out here.

I found a bug! What do I do?

  • Search existing open issues, it may already be reported!
  • Update Cypress. Your issue may have already been fixed.
  • Open an issue. Your best chance of getting a bug looked at quickly is to provide a repository with a reproducible bug that can be cloned and run.