products

Cypress Tips and Tricks

A few tips on getting the most out of E2E testing tool Cypress

We have been successfully using Cypress to verify our websites and web apps for a while. Here are some tips & tricks we have learned.

Even this blog is tested using Cypress :)

Read the docs

Cypress has excellent documentation at https://docs.cypress.io/, including examples, guides, videos and even a busy Gitter chat channel. There is also "Search" box that quickly finds relevant documents. The search is really good and covers the docs, the blog posts and the examples.

Recently common recipes were combined into a single place. If you still have an issue with Cypress, please search through open and closed issues.

You can also read my other blog posts about Cypress under tags/cypress.

Run Cypress on your own CI

As long as the project has a project key, you can run the tests on your own CI boxes. I found running inside Docker to be the easiest, and even built an unofficial Docker image with all dependencies.

Note that cypress ci ... will upload recorded videos and screenshots (if capturing them is enabled) to the Cypress cloud, while cypress run ... will not.

Record success and failure videos

When Cypress team has released the video capture feature in version 0.17.11 it quickly became my favorite. I have configured our GitLab CI to keep artifacts from failed test runs for 1 week, while keeping videos from successful test runs only for a 3 days.

1
2
3
4
5
6
7
8
9
10
11
12
13
artifacts:
  when: on_failure
  expire_in: '1 week'
  untracked: true
  paths:
    - cypress/videos
    - cypress/screenshots
artifacts:
  when: on_success
  expire_in: '3 days'
  untracked: true
  paths:
    - cypress/screenshots

Whenever a test fails, I watch the failure video side by side with the video from the last successful test run. The differences in the subject under test are quickly obvious.

Move common code into utility package

Testing code should be engineered as well as the production code. To avoid duplicating testing helper utilities, we advise to move all common helpers into their own NPM module. For example, we use local CSS styles with randomized class names in our web code.

1
2
3
<div class="table-1b4a2 people-5ee98">
  ...
</div>

This makes the selectors very long since we need to use prefixes.

1
cy.get('[class*=people-]') // UGLY!

By creating a tiny helper function we alleviated the selector head aches.

1
2
3
import {classPrefix} from '@team/cypress-utils/css-names'
// classPrefix('foo') returns "[class*=foo-]"
cy.get(classPrefix('people'))

The test code became a lot more readable.

Separate tests into bundles

Using a single cypress/integration/spec.js file to test a large web application quickly becomes difficult and time consuming. We have separated our code into multiple files. Additionally, we keep the source files in src folder and build the multiple bundles in cypress/integration using kensho/multi-cypress tool.

The multi-cypress tool assumes that Docker and GitLab CI are used to actually run the tests. Each test will be inside its own "test job", thus 10 spec files can be executed at once (assuming at least 10 GitLab CI runners are available).

The command to run a specific spec file is cypress run --spec "spec/filename.js" by the way.

Make JavaScript crashes useful

As I have said before, the true value of a test is not when it passes, but when it fails. Additionally, even a passing test might generate client-side errors that are not crashes and do not fail the test. For example, we often use Sentry exception monitoring service where we forward all client-side errors.

If a client-side error happens while the E2E Cypress test is running, we need this additional context: which test is executing, what steps were already finished before the error was reported, etc.

By loading a small library send-test-info before each test, we can capture the name of the test, its spec filename and even the Cypress test log as breadcrumbs; this information is then sent to Sentry with each crash. For example, the exception below shows the name of the test when the error was reported

Test name

Similarly, the Cypress test steps are logged as breadcrumbs and are sent with the exception allowing any developer to quickly get a sense when the error happens as the test runs.

Test steps

Use test names when creating data

Often as part of the E2E test we create items / users / posts. I like to put the full test title in the created data to easily see what test created which datum. Inside the test we can quickly grab the full title (which includes the full parent's title and the current test name) from the context.

I also like creating random numbers for additional difference

1
2
3
4
5
6
7
8
9
10
11
12
const uuid = () => Cypress._.random(0, 1e6)
describe('foo', () => {
  // note that we need to use "function" and not fat arrow
  // to actually get the right "this" context
  it('bar', function () {
    const id = uuid()
    const testName = this.test.fullTitle()
    const name = `test name: ${testName} - ${id}`
    // name will be "test name: foo bar - <random>"
    makeItem({name}) // use the test name to create unique item
  })
})

Get test status

If you use function () {} as the test's body, or a body of a hook, you can find lots of interesting properties in the this object. For example, you can see the state of the test: passed or failed. To see them all, place the debugger keyword and run the test with DevTools open.

1
2
3
4
afterEach(function () {
  console.log(this)
  debugger
})

There is an object for the entire test, and for the current hook

Information in the test context object

The this.currentTest object contains the status of the entire test

Check if the test has passed or failed

Explore the environment

You can pause the test execution by using debugger keyword. Make sure the DevTools are open!

1
2
3
4
it('bar', function () {
  debugger
  // explore "this" context
})

Run all spec files locally

If you separate Cypress E2E tests into multiple spec files, you soon end up with lots of files. If you need to run the scripts one by one from the command line, I wrote a small utility run-each-cypress-spec.

1
2
3
4
5
6
7
8
npm install -g run-each-cypress-spec
run-specs
...
running cypress/integration/a-spec.js
Started video recording: /Users/gleb/cypress/videos/p259n.mp4
...
running cypress/integration/b-spec.js
Started video recording: /Users/gleb/cypress/videos/62er1.mp4

If you need environment variables (like urls, passwords), you can easily inject them using as-a

1
as-a cy run-specs

Get command log on failure

While videos of the failed tests are useful, sometimes we just want to get a sense of the failure before triaging it. In the headless CI mode, you can get a JSON file for each failed test with the log of all commands. See the JSON file below as an example of a failed test and the file it generated.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "testName": "Website loads the About tab",
  "testError": "Timed out retrying: Expected to find content: 'Join Us' but never did.",
  "testCommands": [
    "visit",
    "new url https://www.company.com/#/",
    "contains a.nav-link, About",
    "click",
    "new url https://www.company.com/#/about",
    "hash",
    "assert expected **#/about** to equal **#/about**",
    "contains Join Us",
    "assert expected **body :not(script):contains(**'Join Us'**),
      [type='submit'][value~='Join Us']** to exist in the DOM"
  ]
}

This is a separate project that just needs to be included from your cypress/support/index.js file. For instructions see cypress-failed-log project.

Wait on the right thing

It is important to wait for the right element. Imagine we have a list of items in the DOM. We expect a new element to appear with text "Hello". We could select first the list, then the element containing "Hello" and check if it becomes visible

1
2
3
cy.get('.list')
  .contains('li', 'Hello')
  .should('be.visible')

But sometimes it does not work. When we cy.get('.list') Cypress saves the DOM element as the "subject" and then tries to wait for a child of that element with text "Hello" to become visible. If we use React for example, the DOM of the list might be recreated from scratch if we push a new item into the list. When that happens Cypress notices that the "subject" DOM it holds a reference to becomes "detached from the DOM" - it becomes an orphan!

A better solution to this problem is to use a composite CSS selector that will grab the list AND the item in a single operation.

1
2
cy.contains('.list li', 'Hello')
  .should('be.visible')

This forces Cypress to wait for the list AND list item element without caching a reference to the DOM element .list.

You can use advanced CSS selectors to get an element in a single command. For example instead of cy.get('.something').first() you could use cy.get('.something:first-child'). Similarly,

1
2
3
4
5
6
7
8
9
// get first element
cy.get('.something').first()
cy.get('.something:first-child')
// get last element
cy.get('.something').last()
cy.get('.something:last-child')
// get second element
cy.get('.something').eq(1)
cy.get('.something:nth-child(2)')

Write and read files

You can write files to disk directly from Cypress using cy.writeFile and read an existing file using cy.readFile. What if you want to read a file that might not exist? cy.readFile will fail the test if file does not exist, thus we need to find a work around.

In my case, the file I would like to load is a JSON of test values useful for Jest-like snapshot testing.

Here is a neat trick. Save the file using cy.writeFile, for example cy.writeFile('spanshots.json') whenever there is something to save. When reading the file, fetch it through the Cypress code proxy using fetch Notice how the test spec itself is served by Cypress from URL which looks like http://localhost:49829/__cypress/tests?p=cypress/integration/spec.js-438. Let us "hack" it to load a file that might not exist.

The code below tries to load snapshots file before each test. If the fetch call fails, the file does not exist.

1
2
3
4
5
6
7
8
9
10
11
12
let snapshots
beforeEach(function loadSnapshots() {
  return fetch('/__cypress/tests?p=./snapshots.json')
    .then(r => r.text())
    .then(function loadedText(text) {
      // ?
    })
    .catch(err => {
      console.error('snapshots file does not exist')
      snapshots = {}
    })
})

If the fetch call succeeds, the returned text will NOT be original JSON! Instead it will be webpacked module :)

For example, here is the saved file

snapshots.json
1
2
3
4
5
6
7
{
  "spec.js": {
    "works": [
      "foo"
    ]
  }
}

Here is how built-in Cypress bundler returns it in response to /__cypress/tests?p=./snapshots.json - I have shortened the webpack boilerplate preamble.

1
2
3
4
5
6
7
8
9
(function e(t,n,r){function ...)({1:[function(require,module,exports){
module.exports={
  "spec.js": {
    "works": [
      "foo"
    ]
  }
}
},{}]},{},[1]);

Notice that our JSON has been placed into module with id '1' (first line expression {1:). The entire bundle registers a stand alone require function. If we want to get into the actual "module" contents we have to do the following in our function loadedText(text) to finish the hack

1
2
3
4
5
6
7
8
function loadedText (text) {
  if (text.includes('BUNDLE_ERROR')) {
    // if the bundler tried to handle missing file
    return Promise.reject(new Error('not found'))
  }
  const req = eval(text)
  snapshots = req('1')
}

Boom, the object snapshots has been loaded from the file snapshots.json which might or might not exist.

Note while I have successfully used the above hack when running Cypress locally, it was always failing when doing cypress run in headless mode.

Read JSON files with retries

Cypress cy.readFile command automatically parses JSON files. It also re-reads the file if the assertions on the returned JSON fail. For example, let's validate the number of items stored by the app in its JSON "database" file:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// note cy.readFile retries reading the file until the should(cb) passes
// https://on.cypress.io/readfile
cy.get('.new-todo')
  .type('todo A{enter}')
  .type('todo B{enter}')
  .type('todo C{enter}')
  .type('todo D{enter}')
cy.readFile('./todomvc/data.json').should(data => {
  expect(data).to.have.property('todos')
  expect(data.todos).to.have.length(4, '4 saved items')
  expect(data.todos[0], 'first item').to.include({
    title: 'todo A',
    completed: false
  })

Even if the application sends the items after a time delay, the cy.readFile(...).should(cb) combination retries and successfully passes when all four items are found.

Test passes after the file has been updated

Conditional logic

Sometimes you might need to interact with a page element that does not always exist. For example there might a modal dialog the first time you use the website. You want to close the modal dialog.

1
2
3
4
5
cy.get('.greeting')
  .contains('Close')
  .click()
cy.get('.greeting')
  .should('not.be.visible')

But the modal is not shown the second time around and the above code will fail. In order to check if an element exists without asserting it, use the proxied jQuery function Cypress.$

1
2
3
4
5
6
7
8
9
const $el = Cypress.$('.greeting')
if ($el.length) {
  cy.log('Closing greeting')
  cy.get('.greeting')
    .contains('Close')
    .click()
}
cy.get('.greeting')
  .should('not.be.visible')

The above check is safe.

Customize Cypress test runner colors

Read Cypress Halloween Theme and check out cypress-dark plugin.

Shorten assertions

For cy.location you can pass the part you are interested in

1
2
3
cy.location().should(location => {
  expect(location.pathname).to.eq('/todos');
});

is the same as

1
cy.location('pathname').should('equal', '/todos')

You can use its to get nested properties easier

1
2
3
cy.get('@login').should(req => {
  expect(localStorage.getItem('token')).to.be.eq(req.response.body.accessToken);
});

is the same as

1
2
cy.get('@login').its('response.body.accessToken')
  .should(accessToken => expect(accessToken).to.equal(localStorage.getItem('token')))

and this could be expressed more clearly in steps

1
2
3
4
5
6
cy.then(() => {
  // by this step, there should the token stored in local storage
  const token = localStorage.getItem('token')
  // and it should come from the response
  cy.get('@login').its('response.body.accessToken').should('equal', token)
})

You can wait for network request to happen and then check something using cy.then

1
2
3
4
5
// notice that we are waiting for @login XHR alias
// before checking that the token is NOT set
cy.get('@login').should(req => {
  expect(localStorage.getItem('token')).to.be.null;
});

Instead we can use .then after waiting for the network request. It is also helpful to print the message when checking for the token, otherwise command log simply says "expect null to equal null".

1
2
3
4
cy.wait('@login')
  .then(() => {
    expect(localStorage.getItem('token'), 'token in local storage').to.be.null;
  });

You don't need to wrap elements just to dynamically use them. For example if you want to test each item from the list

1
2
3
4
5
6
7
8
9
10
11
const inputs = [
  { element: 'username', text: 'foo', error: 'Please enter your username.' },
  { element: 'password', text: 'foo', error: 'Please enter your password.' }
];
cy.wrap(inputs).each(input => {
  const { element, text, error } = input;

  cy.getByTestId(element)
    .type(text)
    .should('have.value', text);
})

Every Cypress command is automatically inserted into the queue, so you can iterate over the items and use Cypress commands, everything will be queued correctly.

1
2
3
4
5
6
7
inputs.forEach(input => {
  const { element, text, error } = input;

  cy.getByTestId(element)
    .type(text)
    .should('have.value', text);
})

I prefer cy.first() to cy.eq(0).

Disable ServiceWorker

ServiceWorkers are great - but they can really affect your end-to-end tests by introducing caching and coupling tests. If you want to disable the service worker caching you need to remove or delete navigator.serviceWorker when visiting the page with cy.visit.

First, here is the way that does not work - simply deleting the property from the navigator object.

1
2
3
4
5
6
7
8
it('disables it', function () {
  cy.visit('index.html', {
    onBeforeLoad (win) {
      delete win.navigator.serviceWorker
      // nope, win.navigator.serviceWorker is still there
    }
  })
})

The reason for this is that we are deleting the property from the wrong object. The serviceWorker is NOT defined on the navigator, it is defined on its prototype. You can confirm this by using Object.getOwnPropertyDescriptor method:

1
2
3
4
Object.getOwnPropertyDescriptor(win.navigator, 'serviceWorker')
// undefined
Object.getOwnPropertyDescriptor(win.navigator.__proto__, 'serviceWorker')
// {set: undefined, enumerable: true, configurable: true, get: ƒ}

After we delete the property from the right object, the application code will no longer think it can register the service worker.

cypress/integration/spec.js
1
2
3
4
5
6
7
it('disables it', function () {
  cy.visit('index.html', {
    onBeforeLoad (win) {
      delete win.navigator.__proto__.serviceWorker
    }
  })
})
index.html
1
2
3
4
5
6
7
8
9
<body>
  <script>
    if ('serviceWorker' in navigator) {
      console.log('registering service worker')
    } else {
      console.log('skipping sw registration')
    }
  </script>
</body>

Service worker is no longer registered

Note: once deleted, the SW stays deleted in the window, even if the application navigates to another URL.

Read also "Stub navigator API in end-to-end tests" for another example.

Control navigator.language

Imagine you have a page that shows different greeting depending on the navigator.language property.

1
2
3
4
5
6
7
8
9
10
11
12
<body>
  <div id="greeting"></div>
  <script>
    const greeting = document.getElementById('greeting')
    if (navigator.language === 'Klingon') {
      // https://www.omniglot.com/language/phrases/klingon.php
      greeting.innerText = 'nuqneH'
    } else {
      greeting.innerText = 'Hi there'
    }
  </script>
</body>

How do we check if the default English greeting is displayed? Easily

1
2
3
4
it('shows default greeting', () => {
  cy.visit('index.html')
  cy.contains('#greeting', 'Hi there').should('be.visible')
})

But how do we force the Klingon greeting to be displayed? Trying to change read-only navigator.language property throws an error.

1
2
3
4
5
6
7
8
9
it('shows Klingon greeting', () => {
  cy.visit('index.html', {
    onBeforeLoad (win) {
      // DOES NOT WORK
      win.navigator.language = 'Klingon'
    }
  })
  cy.contains('#greeting', 'nuqneH').should('be.visible')
})

Error is thrown when trying to directly set `navigator.language`

The navigator.language property is actually set on navigator.__proto__ object:

1
2
3
4
Object.getOwnPropertyDescriptor(navigator, 'language')
//> undefined
Object.getOwnPropertyDescriptor(navigator.__proto__, 'language')
//> {get: ƒ, set: undefined, enumerable: true, configurable: true}

We can create language property on the navigator object instead - thanks, prototypical inheritance! We can specify the property's value:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
it('shows Klingon greeting', () => {
  cy.visit('index.html', {
    onBeforeLoad (win) {
      // DOES NOT WORK
      // Uncaught TypeError: Cannot assign to read only property
      // 'language' of object '[object Navigator]'
      // win.navigator.language = 'Klingon'

      // instead we need to define a property like this
      Object.defineProperty(win.navigator, 'language', {
        value: 'Klingon'
      })
    }
  })
  cy.contains('#greeting', 'nuqneH').should('be.visible')
})

This test shows proper respect to each Klingon warrior browsing the web.

Klingon greeting

How do we ensure that the application actually read navigator.language property when displaying the greeting? Maybe the "nuqneH" is hard-coded! We need to track navigator.language "get" access. We can do this using cy.stub method.

1
2
3
4
5
6
7
8
9
10
11
it('checks if application gets language property', () => {
  cy.visit('index.html', {
    onBeforeLoad (win) {
      Object.defineProperty(win.navigator, 'language', {
        get: cy.stub().returns('Klingon').as('language')
      })
    }
  })
  cy.contains('#greeting', 'nuqneH').should('be.visible')
  cy.get('@language').should('have.been.calledOnce')
})

Now we know for sure how the application behaves.

Language was read by the application

Use fixtures to stub network requests

If your tests are full of stubbed network responses, move the responses into fixtures

before

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
it('does A', () => {
  cy.server()
  cy.route({
    method: 'POST',
    url: '**/api/v1/suggestion_query/query',
    response: {
      ... loooong response object ...
    }
  })
  // UI actions
})

it('does B', () => {
  cy.server()
  cy.route({
    method: 'POST',
    url: '**/api/v1/suggestion_query/query',
    response: {
      ... another loooong response object ...
    }
  })
  // UI actions
})

after 1

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
it('does A', () => {
  cy.server()
  cy.route({
    method: 'POST',
    url: '**/api/v1/suggestion_query/query',
    // loads JSON fixture from cypress/fixtures/first_query_response.json
    response: 'fixture:first_query_response'
  })
  // UI actions
})

it('does B', () => {
  cy.server()
  cy.route({
    method: 'POST',
    url: '**/api/v1/suggestion_query/query',
    // loads JSON fixture from cypress/fixtures/second_query_response.json
    response: 'fixture:second_query_response'
  })
  // UI actions
})

after 2

You can even require the JSON fixtures directly if the second response is just a little bit different from the first response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
const responseFixture = require('../fixtures/first_query_response')
it('does A', () => {
  cy.server()
  cy.route({
    method: 'POST',
    url: '**/api/v1/suggestion_query/query',
    response: responseFixture
  })
  // UI actions
})

it('does B', () => {
  // Lodash is bundled with Cypress https://on.cypress.io/_
  // so use it to avoid changing the shared response object
  const secondResponse = Cypress._.cloneDeep(responseFixture)
  secondResponse.someProperty = 'new value'
  cy.server()
  cy.route({
    method: 'POST',
    url: '**/api/v1/suggestion_query/query',
    response: secondResponse
  })
  // UI actions
})

See cy.route and cy.fixture documentation.

Bonus: read Import Cypress fixtures

Use code coverage

You can instrument your application and use Cypress code coverage plugin to produce combined reports in multiple formats. End-to-end tests are very effective at covering a lot of code in a single test.

Use visual testing

If a test grows to be very long because it checks so many elements on the page, see if it makes sense to test the entire page using Visual Testing.

before

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
it('checks lots of things', () => {
  // perform some actions on the page
  // check results after action
  cy.get('selector1').should('be.visible')
    .find('sub-selector1').should('have.text', 'expected text')
  cy.get('selector2').should('be.visible')
    .find('sub-selector2').should('have.text', 'expected text')
  cy.get('selector3').should('be.visible')
    .find('sub-selector3').should('have.text', 'expected text')
  cy.get('selector4').should('be.visible')
    .find('sub-selector4').should('have.text', 'expected text')
  cy.get('selector5').should('be.visible')
    .find('sub-selector6').should('have.text', 'expected text')
  ...
})

after

1
2
3
4
5
6
7
8
9
10
11
12
13
it('checks lots of things', () => {
  // perform some actions on the page
  // check results after action
  // first, confirm the page has been updated after action
  cy.get('selector1').should('be.visible')
    .find('sub-selector1').should('have.text', 'expected text')

  // but instead of the checking individual elements
  // compare the entire page against expected "gold" image
  // using one of the visual testing plugins
  // https://on.cypress.io/plugins#visual-testing
  cy.takeVisualSnapshot('user action')
})

Bonus: check out bahmutov/sudoku for visual component testing using open source tools, and read Visual testing for React components using open source tools.

Interactive and headed mode

You can find out if the test is currently running using the interactive mode which is when the user calls cypress open.

1
2
3
4
5
if (Cypress.config('isInteractive')) {
  // interactive "cypress open" mode!
} else {
  // "cypress run" mode
}

When you use the interactive mode you always see the browser, thus the browser is always headed. But when using the cypress run command, the browser might be headless or headed. You can find out how the browser is displayed:

1
2
3
4
5
6
7
if (Cypress.browser.isHeaded) {
  // browser is headed
  // might be interactive mode "cypress open"
  // or "cypress run --headed"
} else {
  // browser is running headlessly
}

When using cypress run, Electron is headless by default, while Chrome and Firefox browsers are headed by default. You can control the browser though:

1
npx cypress run --browser chrome --headless

Trying to pass both --headed and --headless CLI parameters raises an error.

Produce high quality video recording

Read the full blog post Generate High-Resolution Videos and Screenshots.

You can find most of the advice below implemented in bahmutov/cypress-movie. To generate better videos from tests

  • set video compression to false
  • set browser window size to larger value, which should work fine when using headless Chrome on CI
1
2
3
4
5
6
7
8
9
// in your plugins file
on('before:browser:launch', (browser = {}, launchOptions) => {
  if (['chrome', 'chromium'].includes(browser.name) && browser.isHeadless) {
    launchOptions.args.push(
      `--window-size=1920,1080`,
    )
  }
  return launchOptions
})
  • hide command log

You can "expand" the application under test iframe to cover the entire window

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
const clearViewport = () => {
  const runnerContainer = window.parent.document.getElementsByClassName(
    'iframes-container',
  )[0]
  runnerContainer.setAttribute(
    'style',
    'left: 0; top: 0; width: 100%; height: 100%;',
  )

  const sizeContainer = window.parent.document.getElementsByClassName(
    'size-container',
  )[0]
  sizeContainer.setAttribute('style', '')

  const sidebar = window.parent.document.getElementsByClassName(
    'reporter-wrap',
  )[0]
  sidebar.setAttribute('style', 'opacity: 0')

  const header = window.parent.document.querySelector(
    '.runner.container header',
  )
  header.setAttribute('style', 'opacity: 0')
}

Call this function before the tests.

  • use native Chrome Debugger Protocol to take full page screenshots. See "cypress-movie" project.

Use the page base url

Sometimes multiple tests visit a different base url. For example, you might usually go to the index page by setting baseUrl in the config file

cypress.json
1
2
3
{
  "baseUrl": "http://localhost:7080"
}

Every test can cy.visit('/') and get to the index page. But imagine that a suite of tests is trying to visit and test the "About" page. It is located at /about.html, so every test has to visit it.

1
2
3
4
5
6
7
8
9
10
11
describe('About', () => {
  it('loads', () => {
    cy.visit('/about.html')
      .contains('h1', 'About')
  })

  it('loads again', () => {
    cy.visit('/about.html')
      .contains('h1', 'About')
  })
})

Visiting the about page from every test

Now, we can refactor the tests to avoid duplication. For example, we could move the cy.visit into beforeEach hook.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
/// <reference types="cypress" />

describe('About', () => {
  beforeEach(() => {
    cy.visit('/about.html')
  })

  it('loads', () => {
    cy.contains('h1', 'About')
  })

  it('loads again', () => {
    cy.contains('h1', 'About')
  })
})

Works.

Or we could create a utility function:

1
2
3
4
5
6
7
8
9
10
11
12
13
describe('About', () => {
  const visit = () => cy.visit('/about.html')

  it('loads', () => {
    visit()
    cy.contains('h1', 'About')
  })

  it('loads again', () => {
    visit()
    cy.contains('h1', 'About')
  })
})

It works too.

Here is one more way to (abuse) test configuration feature introduced in Cypress v5.0.0. We will change the baseUrl in the describe block to apply to just these tests.

1
2
3
4
5
6
7
8
9
10
11
describe('About', { baseUrl: '/about.html' }, () => {
  it('loads', () => {
    cy.visit('')
    cy.contains('h1', 'About')
  })

  it('loads again', () => {
    cy.visit('')
    cy.contains('h1', 'About')
  })
})

Notice the { baseUrl: '/about.html' } parameter in describe call. We can overwrite multiple config values using this parameter. In our case, we overwrite the baseUrl, appending the file name. In the cy.visit('') call we pass an empty string - because we do not want to append / at the end.

But the tests fail.

Extra slash at the end fails the tests

While our visit used an empty string, Cypress requires baseUrl to be a valid base URL and appends / at the end automatically.

Luckily, Cypress v5.4.0 has a fix for baseUrl that has params for issue #2101. If your base url is of the form ...?foo=bar then visiting '' would keep the original full url. Let's change our test by appending ? to the base url:

1
2
- describe('About', { baseUrl: '/about.html' }, () => {
+ describe('About', { baseUrl: '/about.html?' }, () => {

Now the tests pass - and the ?/ at the end of the URL is ignored

The page is visited correctly

Pass the environment variables correctly

Imagine you need to pass database username and password from your test. These values are probably available as environment variables. How would you pass them to cypress run? You might try something like this in the package.json file. It will NOT work:

package.json
1
2
3
4
5
{
  "scripts": {
    "cy:run": "node_modules\\.bin\\cypress run --env db.user='$DB_USERNAME',db.password='$PASSWORD'"
  }
}

First, you do not need the node_modules\\.bin path when calling an NPM alias - they are automatically resolved by the npm run command. Thus always use simply:

package.json
1
2
3
4
5
{
  "scripts": {
    "cy:run": "cypress run --env db.user='$DB_USERNAME',db.password='$PASSWORD'"
  }
}

The above command will NOT work yet. To see why, change the cypress run to cypress open to see the Cypress GUI.

package.json
1
2
3
4
5
6
{
  "scripts": {
    "cy:run": "cypress run --env db.user='$DB_USERNAME',db.password='$PASSWORD'",
    "cy:open": "cypress open --env db.user='$DB_USERNAME',db.password='$PASSWORD'"
  }
}

Select the "Settings" tab and inspect the resolved environment variables.

Resolved environment variables

We have two problems:

  1. Instead of passing the environment variable's value, we got the strings "$DB_USERNAME" and "$PASSWORD". Resolving environment variables inside commands might be tricky and depend on the operating system.
  2. The username and the password are stored under names db.user and db.password, which might be not what you expect. From the dot notation, I would expect these values to create an object db with properties user and password.

But there are other trickier problems here. Let's change our NPM scripts to avoid single quotes around the values. We hope that now the environment variables are resolved correctly.

package.json
1
2
3
4
5
6
{
  "scripts": {
    "cy:run": "cypress run --env db.user=$DB_USERNAME,db.password=$PASSWORD",
    "cy:open": "cypress open --env db.user=$DB_USERNAME,db.password=$PASSWORD"
  }
}

At first, it appears to work

The username and the password were passed correctly

Now, let's try a user name with a space.

The username is incorrect, the password is missing completely

Ummm. The space inside the username value created problems; the cypress open command effectively received ended with --env db.user=joe smith,db.password=123. The part after --env db.user=joe was ignored!

Solution: Cypress can grab the environment variables in multiple ways. The most powerful and flexible way is to grab them from the process.env object using the plugins code.

cypress/plugins/index.js
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
module.exports = (on, config) => {
  const username = process.env.DB_USERNAME
  const password = process.env.PASSWORD

  if (!username) {
    throw new Error(`missing DB_USERNAME environment variable`)
  }

  if (!password) {
    throw new Error(`missing PASSWORD environment variable`)
  }

  // form a very nice object
  // from the spec use Cypress.env('db') to access it
  config.env.db = {
    username, password,
  }

  // make sure to return the updated `config` object
  return config
}

The plugins file runs in Node environment, has access to the process.env object. It can grab the variables, check their values, and place them into a single object db. Now the Settings tab shows the correct values.

The right "db" object with the username and password

Additional reading: the blog post Keep passwords secret in E2E tests and the recipe Environment variables.

Tip: when working locally you can use the utility as-a to conveniently inject environment variables when running any command.

Parse and use URL

Let's take a Next.js application with dynamic routes. We can scaffold one using the provided example.

You can find the complete source code at bahmutov/dynamic-routing-app

The app was initialized using the provided example command

1
$ npx create-next-app --example dynamic-routing dynamic-routing-app

The app contains two dynamic routes:

  1. pages/post/[id]/index.js
    • e.g. matches /post/my-example (/post/:id)
  2. pages/post/[id]/[comment].js
    • e.g. matches /post/my-example/a-comment (/post/:id/:comment)

Let's see how we can parse the above URLs to use them during tests. First we need to install Cypress and start-server-and-test:

1
2
3
4
$ yarn add -D cypress start-server-and-test
info Direct dependencies
├─ [email protected]
└─ [email protected]

I can scaffold the Cypress files with my helper bahmutov/cly

1
$ npx @bahmutov/cly init

We place the base url localhost:3000 in cypress.json file and start the app and Cypress. Our first test can confirm the home page loads:

cypress/integration/spec.js
1
2
3
4
5
6
7
8
9
describe('Dynamic routes', () => {
  it('loads home', () => {
    cy.visit('/')
    cy.contains('li', 'Home')
    cy.contains('li', 'About')
    cy.contains('li', 'First Post')
    cy.contains('li', 'Second Post')
  })
})

Home test

Great, we can make sure the link "About" goes to the "About" page.

1
2
3
4
it('goes to the about page', () => {
  cy.visit('/').contains('li a', 'About').click()
  cy.url().should('match', /\/about$/)
})

The test passes, but with a tiny red flag. Notice little eye crossed icons next to the "contains" command?

The link was invisible when clicked

The Next.js application fetches a static HTML with the markup present but invisible. It is hydrated later - but we want to click on the link like a real user would, after it becomes visible. Let's add an assertion.

1
2
3
4
it('goes to the about page', () => {
  cy.visit('/').contains('li a', 'About').should('be.visible').click()
  cy.url().should('match', /\/about$/)
})

Much better.

The link becomes visible and then is clicked

We assert that we go to the right page by using the expression cy.url().should('match', /\/about$/). It works, but the command cy.url returns the full URL. If you click on the command you will see what it yields:

cy.url yields the full application URL

We are interested only in the relative pathname - the /about part. Thus I suggest using cy.location command that parses the URL and can yield just the interesting part.

Now let's check the first post. We can start with the same test as before

1
2
3
4
it('goes to the first post', () => {
  cy.visit('/').contains('li a', 'First Post').should('be.visible').click()
  cy.location('pathname').should('equal', '/post/first')
})

Testing the first post

Now let's go to the first command. We need to click on the link, but before we do this, let's validate it. Let's grab the current post url and use it somehow in our tests.

1
2
3
4
5
6
7
it('goes to the first comment', () => {
  cy.visit('/').contains('li a', 'First Post').should('be.visible').click()
  cy.location('pathname').should('include', '/post')
    .then(pathname => {
      console.log('pathname is', pathname)
    })
})

After the assertion .should('include', '/post') passes, the value is yielded to the next command where we print it.

Getting the pathname after the page navigation

Now we have all the JavaScript magic we need to parse and slice URL. Let's even change the test and go to the second comment of the first post.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
it('goes to the first post / second comment', () => {
  cy.visit('/').contains('li a', 'First Post').should('be.visible').click()
  cy.location('pathname')
    .should('include', '/post')
    .then(pathname => {
      // pathname is like "/post/[id]"
      // ignore first two items from the split
      const [, , post] = pathname.split('/')
      expect(post, 'first post').to.equal('first')

      // there should be a link to the second post
      const commentUrl = `/post/${post}/second-comment`
      cy.get(`a[href="${commentUrl}"]`).should('be.visible').click()
    })

  // let's validate every part of the URL's pathname
  cy.location('pathname').should(pathname => {
    // pathname is like "/post/[id]/[comment]"
    const [, , post, comment] = pathname.split('/')
    expect(post, 'post id').to.equal('first')
    expect(comment, 'comment id').to.equal('second-comment')
  })
})

We can parse, validate, and use the URL in our test.

Using parsed URL to browse to the second comment

Deal with target=_blank

Imagine a link on the page uses <a href="/about.html" target="_blank">About</a>. Cypress does not work with the second tab, so what can we do?

1
2
3
4
it('loads the about page', () => {
  cy.visit('index.html')
  cy.get('a').click()
})

Test opens the second tab invisible to Cypress

Figure out what you want to test. You can for example verify the link has the expected address and attribute target=_blank and call it a day.

1
2
3
4
5
6
7
it('loads the about page', () => {
  cy.visit('index.html')
  cy.get('a').should($a => {
    expect($a.attr('href'), 'href').to.equal('/about.html')
    expect($a.attr('target'), 'target').to.equal('_blank')
  })
})

Test confirms the anchor link's attributes

We can also change the target attribute before clicking the link (but after confirming it to be blank). Then we can verify the second "tab" loads correctly.

1
2
3
4
5
6
7
8
9
it('loads the about page', () => {
  cy.visit('index.html')
  cy.get('a').should($a => {
    expect($a.attr('href'), 'href').to.equal('/about.html')
    expect($a.attr('target'), 'target').to.equal('_blank')
    $a.attr('target', '_self')
  }).click()
  cy.location('pathname').should('equal', '/about.html')
})

Test opens the target link in the same tab

Deal with window.open

Imagine the application under test uses window.open() to load a new URL in the second tab.

1
2
3
4
5
6
7
<a href="/about.html" target="_blank">About</a>
<script>
  document.querySelector('a').addEventListener('click', (e) => {
    e.preventDefault()
    window.open('/about.html')
  })
</script>

By default the /about.html page opens in a new tab - and we do not want that. Let's stub the window.open method instead.

1
2
3
4
5
6
7
8
it('opens the about page', () => {
  cy.visit('index.html')
  cy.window().then(win => {
    cy.stub(win, 'open').as('open')
  })
  cy.get('a').click()
  cy.get('@open').should('have.been.calledOnceWithExactly', '/about.html')
})

Test stubs the window.open method

If we really want to load the new URL, let's call the original window.open method, passing _self as the second parameter.

Tip: use <method>.wrappedMethod to get to the original method wrapped in Sinon stub.

1
2
3
4
5
6
7
8
9
10
11
it('opens the about page', () => {
  cy.visit('index.html')
  cy.window().then(win => {
    cy.stub(win, 'open').callsFake((url, target) => {
      expect(target).to.be.undefined
      return win.open.wrappedMethod.call(win, url, '_self')
    }).as('open')
  })
  cy.get('a').click()
  cy.get('@open').should('have.been.calledOnceWithExactly', '/about.html')
})

Test redirects `window.open` target

Minimize memory use

Sometimes Cypress can crash during CI run due to running out of memory. Typically it shows a message like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
10:38:58 AM: We detected that the Chromium Renderer process just crashed.
10:38:58 AM:
10:38:58 AM: This is the equivalent to seeing the 'sad face' when Chrome dies.
10:38:58 AM:
10:38:58 AM: This can happen for a number of different reasons:
10:38:58 AM:
10:38:58 AM: - You wrote an endless loop and you must fix your own code
10:38:58 AM: - There is a memory leak in Cypress (unlikely but possible)
10:38:58 AM: - You are running Docker (there is an easy fix for this: see link below)
10:38:58 AM: - You are running lots of tests on a memory intense application
10:38:58 AM: - You are running in a memory starved VM environment
10:38:58 AM: - There are problems with your GPU / GPU drivers
10:38:58 AM: - There are browser bugs in Chromium
10:38:58 AM:
10:38:58 AM: You can learn more including how to fix Docker here:
10:38:58 AM:
10:38:58 AM: https://on.cypress.io/renderer-process-crashed

You can profile memory usage every second with environment variables

1
2
3
export DEBUG=cypress:server:util:process_profiler
export CYPRESS_PROCESS_PROFILER_INTERVAL=1000
cypress run

The things you can do to minimize the amount of memory used:

  • try running tests without extra reporters, plugins, and preprocessors
  • split specs to have fewer tests per spec. Cypress opens and closes the browser for every spec
  • turn the video recording off with video: false using cypress.json or environment variables
  • turn the command log off using the environment variable CYPRESS_NO_COMMAND_LOG=1
  • expose garbage collection and running it after each test. See issue 8525, but in general for Electron browser you want to use an environment variable ELECTRON_EXTRA_LAUNCH_ARGS=--js-flags=--expose_gc and from the test call window.gc() method if available
1
2
3
4
5
6
7
8
9
10
11
12
afterEach(() => {
  cy.window().then(win => {
    if (win.gc) {
      gc();
      gc();
      gc();
      gc();
      gc();
      cy.wait(1000)
    }
  })
})

Tip: if Electron keeps crushing, try running tests using Chrome or Firefox browsers.

Start browser with specific time zone

You can start Cypress (and thus the browser it spawns) with specific time zone to see how the application handles it.

1
2
3
$ <timezone> npx cypress open
# for example
$ TZ=Asia/Tokyo npx cypress open

Typical time zones are America/New_York, Europe/Berlin, Europe/London, Asia/Tokyo.

Tip: an application can obtain its time zone using the following code snippet

1
2
Intl.DateTimeFormat().resolvedOptions().timeZone
// "America/New_York"

For more information, read Testing Time Zones in Parallel

See also