Cypress

Why it matters

A tool’s design decides which tests are easy and which are painful. Cypress retries queries and assertions automatically and shows every command against a snapshot of the page, so many failures are quick to diagnose. The same design sets limits: one tab per test, JavaScript only, and commands that do not behave like ordinary JavaScript. Ignore them and you write fixed sleeps and tests that fail for the wrong reason.

For the product, a Cypress suite on every pull request catches regressions in key journeys before users do. For you, extending an existing Cypress suite is a practical skill on any team with a JavaScript front end.

How Cypress works: inside the browser, through a command queue

Selenium (Java, Python, C#, JavaScript, Ruby) sends W3C WebDriver commands over HTTP to a driver such as chromedriver or safaridriver; you write explicit waits and switch windows by handle. Playwright (TypeScript/JavaScript, Python, Java, .NET) drives Chromium, Firefox and WebKit over its own connection, with auto-waiting actions and retrying assertions, and can use several pages in one test. Both run tests in a separate process. Cypress runs your spec inside the browser, in the application’s run loop; a Node.js process behind it starts the browser and runs the Node tasks, defined in the config file, that a test calls with cy.task(). Cypress also controls the network, which makes cy.intercept() possible.

Commands are queued, not run when their line executes: cy.visit(), cy.get() and .click() join a queue that Cypress runs after the test function returns. They are not promises, so you cannot await them or store their result; chain .then() or .should() instead.

The core idea is retry-ability: queries such as cy.get() and cy.contains() are retried with their chained assertions until the assertions pass or defaultCommandTimeout expires (4 seconds by default). Actions such as .click() run once, after waiting until the element is actionable: visible, enabled and not covered. Assert the state you expect instead of adding cy.wait(5000).

cy.visit('/cart')
cy.get('[data-cy=add-item]').click()   // action: waits until actionable, runs once
cy.get('[data-cy=cart-count]')         // query: retried...
  .should('have.text', '1')            // ...until this passes or the timeout expires

// Wrong: commands are queued, they return no value you can store
// const count = cy.get('[data-cy=cart-count]').text()

// Right: work with the yielded value inside .then()
cy.get('[data-cy=cart-count]').invoke('text').then((text) => {
  cy.log(`The badge shows ${text}`)
})

Install, project layout and the config file

Install Cypress per project with npm install --save-dev cypress; the first npx cypress open starts the Launchpad, where choosing E2E Testing creates the config file and the cypress/ folder. The config file below uses Node’s require() and module.exports (CommonJS), the older equivalent of import and export, because Node loads it; spec, support and page-object files can still use import and export, because Cypress bundles them before running them in the browser.

In the config file, baseUrl points cy.visit("/orders") at an environment; timeouts limit queries, page loads and responses; retries is set separately for cypress run and cypress open; reporter picks the output, such as JUnit XML for CI. The browser is chosen at run time with --browser chrome, edge or firefox; defaultBrowser sets the one used without the flag (otherwise cypress run uses the bundled Electron browser, deprecated since Cypress 16), and the browsers list can be filtered in setupNodeEvents.

• cypress/e2e/: spec files such as orders.cy.js.
• cypress/fixtures/: stub data such as orders.json, and files to upload.
• cypress/support/: e2e.js runs before every spec and imports commands.js, which holds custom commands such as cy.login(); page objects often live beside it.
• cypress/screenshots/ and cypress/downloads/: run output, kept out of version control.

// cypress.config.js
const { defineConfig } = require('cypress')

module.exports = defineConfig({
  e2e: {
    baseUrl: 'http://localhost:3000',        // cy.visit('/orders') opens this host
    specPattern: 'cypress/e2e/**/*.cy.js',
  },
  defaultBrowser: 'chrome',                  // used when --browser is not given
  defaultCommandTimeout: 6000,               // queries and assertions (default 4000)
  pageLoadTimeout: 60000,                    // page loads after cy.visit()
  responseTimeout: 30000,                    // cy.request() and cy.wait() responses
  retries: { runMode: 1, openMode: 0 },      // one rerun in cypress run only
  reporter: 'junit',
  reporterOptions: { mochaFile: 'results/junit-[hash].xml' },
  screenshotOnRunFailure: true,
  video: false,
})

Try it: JavaScript Formatter

Run one test, debug it, and run the suite in CI

While writing, use npx cypress open: pick a browser and a spec, and it reruns on every save. Clicking a command in the Command Log shows the page as it was at that moment (time travel). From the command line and in CI:

• One spec: npx cypress run --spec cypress/e2e/orders.cy.js --browser chrome.
• One test: it.only( while you work; remove it before committing.
• Headed mode: cypress run hides the browser; add --headed to watch.
• Debugging: cy.pause() stops the queue in the open runner, .debug() stops at a breakpoint when DevTools are open, and DEBUG=cypress:* (Linux and macOS syntax) prints Cypress’s own logs when it will not start or launch a browser.
• CI: the official image cypress/browsers has Node.js and browsers (cypress/included adds a fixed Cypress version). The job below runs every spec in Chrome, takes the password from repository secrets and keeps the JUnit results and failure screenshots.

# .github/workflows/e2e.yml
name: e2e
on: [pull_request]

jobs:
  cypress:
    runs-on: ubuntu-latest
    container:
      image: cypress/browsers:latest     # pin an exact tag in a real pipeline
    steps:
      - uses: actions/checkout@v7
      - run: npm ci
      - run: npx cypress run --browser chrome --config baseUrl=https://test.example.com
        env:
          CYPRESS_BUYER_PASSWORD: ${{ secrets.BUYER_PASSWORD }}
      - uses: actions/upload-artifact@v7
        if: always()
        with:
          name: cypress-results
          path: |
            results
            cypress/screenshots

Try it: YAML Formatter

Sessions, network stubs, dialogs, tabs and uploads

Test isolation is on by default: each test starts with a blank page and no cookies or storage, so each test must sign in. cy.session() runs the login once, caches the resulting cookies and storage, and restores them for later tests with the same id; validate checks that a restored session still works. Visit a page afterwards, because the page is blank.

cy.intercept() matches requests by method and URL. Given a static response such as { fixture: "orders.json" } or { statusCode: 500 } it stubs the server, so empty states and errors are reachable on demand; without one it only watches, and cy.wait("@alias") waits for the request so you can assert on it.

• Dialogs: Cypress accepts alert() and confirm() automatically. Pass cy.on("window:alert", …) a stub, a stand-in function that records its calls, and assert on its alias, so the test also fails when no alert appears; a window:confirm stub that returns false chooses Cancel.
• New tabs: Cypress drives one tab. For a target="_blank" link, check href and target, then visit the URL in the same tab or remove target before clicking; the documentation points to the @cypress/puppeteer plugin when a second tab is unavoidable.
• Upload: .selectFile("cypress/fixtures/receipt.pdf") on a file input; add { action: "drag-drop" } for a drop zone.

// cypress/support/commands.js: sign in once per user, reuse the session
Cypress.Commands.add('login', (email) => {
  cy.session(email, () => {
    cy.env(['BUYER_PASSWORD']).then(({ BUYER_PASSWORD }) => {
      cy.request({
        method: 'POST',
        url: '/api/login',
        body: { email, password: BUYER_PASSWORD },
        log: false,                          // keep the password out of the log
      })
    })
  }, {
    validate() {
      cy.request('/api/me').its('status').should('eq', 200)
    },
  })
})

// In a spec: watch a request, check an alert, upload a file
cy.login('buyer@example.com')
cy.intercept('POST', '/api/receipts').as('upload')     // watch only, no stub
cy.on('window:alert', cy.stub().as('alert'))           // record every alert
cy.visit('/account/receipts')
cy.get('[data-cy=receipt-file]').selectFile('cypress/fixtures/receipt.pdf')
cy.get('[data-cy=upload]').click()
cy.wait('@upload').its('response.statusCode').should('eq', 201)
cy.get('@alert').should('have.been.calledOnceWith', 'Receipt uploaded')

Try it: Mock API Response Generator Try it: Mock Error Response Generator

Worked example: order history in four tests with a page object

A first Cypress test often signs in, checks the list, cancels an order and checks an error in one it. When an early step fails, the later checks never run. Split it by behaviour.

Requirement: “The order history page lists the buyer’s orders. With none it shows You have no orders yet; if loading fails it shows Could not load your orders. Cancelling asks for confirmation; choosing Cancel keeps the order.”

The page object holds the selectors and makes no assertions. The fixture orders.json holds three orders; A-1002 has the status Processing. Each test stubs its own data, reuses the cached session and checks one behaviour, so a failing title names what broke.

// cypress/support/pages/ordersPage.js: knows the screen, makes no assertions
export const ordersPage = {
  visit: () => cy.visit('/account/orders'),
  rows: () => cy.get('[data-cy=order-row]'),
  row: (id) => cy.get(`[data-cy=order-row][data-order-id="${id}"]`),
  message: () => cy.get('[data-cy=orders-message]'),
  cancel: (id) => ordersPage.row(id).find('[data-cy=cancel-order]').click(),
}

// cypress/e2e/orders.cy.js: one behaviour per test
import { ordersPage } from '../support/pages/ordersPage'

describe('Order history', () => {
  beforeEach(() => {
    cy.login('buyer@example.com')
  })

  it('lists the orders returned by the API', () => {
    cy.intercept('GET', '/api/orders', { fixture: 'orders.json' }).as('orders')
    ordersPage.visit()
    cy.wait('@orders')
    ordersPage.rows().should('have.length', 3)
  })

  it('shows the empty state when there are no orders', () => {
    cy.intercept('GET', '/api/orders', { body: [] })
    ordersPage.visit()
    ordersPage.message().should('have.text', 'You have no orders yet')
  })

  it('shows an error when the orders cannot be loaded', () => {
    cy.intercept('GET', '/api/orders', { statusCode: 500, body: {} })
    ordersPage.visit()
    ordersPage.message().should('have.text', 'Could not load your orders')
  })

  it('keeps the order when the buyer cancels the confirmation', () => {
    cy.intercept('GET', '/api/orders', { fixture: 'orders.json' })
    cy.on('window:confirm', cy.stub().as('confirm').returns(false))  // choose Cancel
    ordersPage.visit()
    ordersPage.cancel('A-1002')
    cy.get('@confirm').should('have.been.calledOnceWith', 'Cancel order A-1002?')
    ordersPage.row('A-1002').should('contain', 'Processing')
  })
})

Try it: JSON Validator Try it: Mock API Response Generator

Frequently asked questions

References

• Cypress DocumentationCypress.ioOfficial documentation for end-to-end and component testing in the browser with Cypress.
• Best Practices — CypressCypress.ioCypress guidance on selecting elements with dedicated attributes, avoiding fixed waits and keeping tests independent.
• GitHub Actions documentationGitHubHow workflows, jobs, runners and artifacts are defined in GitHub Actions — where automated tests run on each push or pull request.