← All Posts

How to Do Cypress E2E Tests on Claude Code

You can run and write Cypress end-to-end tests directly inside Claude Code by prompting it in plain English or using /run slash commands to execute your test suite. This workflow works for any developer who wants to stay inside their terminal without switching context to a browser dashboard. The main trade-off: Cypress tests are token-heavy, so long sessions will eat into your usage limit fast. Use Claude Code usage monitoring to avoid a surprise 5-hour lockout mid-PR.

  • Claude Code can scaffold, debug, and run Cypress tests without leaving your terminal
  • Cypress e2e test generation is one of the most token-intensive Claude Code workflows
  • Usagebar shows live usage in your macOS menu bar so you never hit the wall mid-test

What is Cypress and why use it with Claude Code?

Cypress is a JavaScript-based end-to-end testing framework that runs directly in the browser. It's a developer favourite for testing React, Next.js, Vue, and other frontend apps because tests are fast to write and results are easy to read.

Claude Code is Anthropic's terminal-native coding assistant. Combining the two means you can describe a user flow in plain language, have Claude generate the Cypress spec, then run it against your local dev server, all from one terminal session. No context switching, no boilerplate hunting.

How to set up Cypress in a Claude Code project

Before asking Claude to write tests, make sure Cypress is installed. If it isn't, tell Claude and it will handle it:

Install Cypress as a dev dependency and initialise it for this project.

Claude will run npm install cypress --save-dev and set up the cypress.config.js file. If you already have Cypress installed, skip straight to writing tests.

Verify your project structure first

Claude works best when it can see the folder structure. Open your project directory in the terminal where Claude Code is running. A standard Cypress layout looks like:

  • cypress/e2e/ - where spec files live
  • cypress/fixtures/ - static test data (JSON)
  • cypress/support/ - custom commands and setup
  • cypress.config.js - base URL, timeouts, plugins

How to write Cypress e2e tests using Claude Code prompts

The most efficient pattern is to describe the user journey you want covered and let Claude generate the full spec file. Be specific about selectors and assertions to get production-ready output on the first pass.

Example prompts that work well

  • Write a Cypress e2e test for the login flow. The form has #email and #password fields and a [data-cy="submit"] button. After login, the user should land on /dashboard.
  • Add a Cypress test for the checkout flow: add item to cart, proceed to checkout, fill in a dummy address, and assert the order confirmation page shows "Order placed".
  • Generate Cypress tests for the homepage covering: nav links, hero CTA click, and footer email signup form validation.

Using data-cy attributes as selectors is a Cypress best practice because they decouple tests from CSS classes. Tell Claude to use them and it will apply them consistently.

Asking Claude to fix a failing test

Paste the error output directly into Claude Code:

This Cypress test is failing with: "AssertionError: expected '#submit' to exist in the DOM". Here is the spec: [paste spec]. Fix it.

Claude will inspect the selector, suggest the correct attribute, and rewrite the assertion. This tight feedback loop is where Claude Code saves the most time compared to manually debugging.

How to run Cypress tests from Claude Code

Claude Code can execute shell commands directly. You have two options:

Option 1: Ask Claude to run the tests for you

Run the Cypress tests headlessly and show me the results.

Claude will execute npx cypress run and surface the output inline. You can filter by spec:

Run only the login spec: cypress/e2e/login.cy.js

Option 2: Use the /run slash command

Claude Code's /run slash command lets you trigger terminal commands without a natural language wrapper. According to the Claude Code slash commands reference, you can chain commands directly:

/run npx cypress run --spec "cypress/e2e/checkout.cy.js"

This is faster when you know exactly which spec to target and don't need Claude to interpret the request.

Running tests against a live dev server

If your dev server isn't running, start it first:

Start the dev server on port 3000, then run all Cypress e2e tests headlessly.

Claude will spin up the server in the background and execute the tests once the port is ready. Make sure your cypress.config.js has baseUrl: 'http://localhost:3000' set.

How to handle Cypress test output and reporting

By default, cypress run prints a summary table to stdout. Claude reads this and can tell you which tests passed, which failed, and why. For richer output:

  • Ask Claude to install mochawesome for HTML reports
  • Use --reporter json flag to get machine-readable output Claude can parse and summarise
  • Ask Claude to interpret a failing video or screenshot path from cypress/screenshots/

Generating detailed reports from long test runs is token-intensive. If you're wrapping up a feature before a PR merge, this is exactly the moment a usage limit can catch you off guard. See the section below on managing usage.

How to manage Claude Code usage during long Cypress sessions

Cypress test generation is one of the heavier Claude Code tasks. A full e2e suite for a mid-size app can involve dozens of back-and-forth exchanges, spec files, debugging loops, and /run calls. This burns through your usage window faster than simple refactoring work.

Claude Code enforces usage limits tied to a 5-hour rolling window (see when Claude Code usage resets). Hitting that limit mid-session, especially when you're debugging a flaky test before a deadline, means a forced 5-hour pause. You can check your current consumption with the /usage slash command inside Claude Code, or by visiting claude.ai/settings/usage.

A better approach: monitor usage passively in the background so you're never surprised. Usagebar is a macOS menu bar app that shows your live Claude Code usage and fires smart alerts at 50%, 75%, and 90% thresholds. Credentials are stored securely in the macOS Keychain. It's free for students and pay-what-you-want for everyone else. Get Usagebar before your next long Cypress session.

For tips on keeping token counts down during testing workflows, see how to reduce Claude Code token usage.

Key takeaways

  1. Install Cypress first, then describe user flows in plain English to generate spec files
  2. Use data-cy selectors - tell Claude to apply them by default
  3. Run tests with /run npx cypress run or by asking Claude directly
  4. Paste error output back to Claude for fast debugging loops
  5. Monitor usage with Usagebar or /usage to avoid a mid-session lockout
  6. Use --spec flag to target individual files and reduce token overhead

Related guides

Track Your Claude Code Usage

Never hit your usage limits unexpectedly. Usagebar lives in your menu bar and shows your 5-hour and weekly limits at a glance.

Get Usagebar