DEV Community: Cypress

How to connect Claude Code to Cypress

Jennifer Shehane — Thu, 15 Oct 2026 13:52:42 +0000

You ask Claude Code to fix a failing checkout test. It reads the spec, spots a likely timing issue, and suggests a reasonable fix. What it doesn’t know is that the same test has failed on and off in CI all week, or what the page looked like when it failed. A fix that looks right in the editor may not touch what’s really going on.

Sound familiar? That gap usually isn’t about the model. It’s about context. Claude Code can read your spec files and pick up some of your patterns along the way. What it can’t see is your run history: which tests failed in CI, which ones are flaky, and what happened in your last recorded run.

First, some terminology

If you’re new to AI coding tools, the vocabulary piles up fast. Here’s what each term means in this post:

Context: everything Claude Code has in front of it during a session, including your messages, the files it's read, its instructions, and the results of the tools it uses. Claude Code can only work with what’s in its context.
Token: a small chunk of text, often part of a word. AI models measure context and usage in tokens, so a larger context uses more tokens on every turn.
CLI (command-line interface): a tool you run by typing commands in a terminal, like npx cypress run. Claude Code can run CLI commands too, such as the Cypress Cloud CLI, cy-cloud.
Skill: a folder of instructions that teaches Claude Code how to handle a specific kind of task. Claude Code loads a skill only when a task calls for it. Cypress AI Skills cover writing, explaining, running, and debugging Cypress tests.
MCP (Model Context Protocol): an open standard that lets AI tools connect to other systems. An MCP server offers tools that Claude Code can call to get live data. Cloud MCP is our MCP server for Cypress Cloud.
Connector: an MCP server you add to your Claude account at claude.ai, so Claude can use it across Claude apps. If you sign in to Claude Code with your claude.ai account, your connectors are available there automatically. Cypress Cloud is available as a connector in the Claude connectors directory, which gives you a way to use Cloud MCP without running a setup command.
Plugin: a package that installs several pieces into Claude Code at once, such as skills and MCP server settings. You install a plugin from a marketplace, a catalog of plugins that anyone can publish. The Cypress plugin installs all five Cypress AI Skills and sets up Cloud MCP in one step.
CLAUDE.md file: a markdown file of instructions in your project, such as your team’s testing conventions, that Claude Code reads as context.

This post sets up three pieces: Cypress AI Skills, which help Claude Code work the way your team does; Cloud MCP, which gives it your run history; and cypress tap, which lets it check its work in your open Cypress session. You can use any of them on its own.

Skills, CLAUDE.md files, and cypress tap all work with what’s on your machine. Only Cloud MCP and the Cloud CLI reach into Cypress Cloud for your recorded runs.

Which setup do you need?

You want better tests from Claude Code, and you don’t use Cypress Cloud. Install Cypress AI Skills. They’re free and need no account.
You write tests locally and want Claude Code to check its own work. Install the skills and keep a cypress open session running so Claude Code can use cypress tap. This works without Cypress Cloud.
You record runs to Cypress Cloud and spend time investigating flake and failures. Install the skills and connect Cloud MCP or the Cloud CLI. This is where the two work best together.
You’re rolling this out to a team. Commit the skills and your Cypress CLAUDE.md file to your repository, ask an admin to turn on Cloud MCP, and consider a project scope OAuth configuration so everyone starts from the same setup.

Quick start: install the Cypress plugin

The fastest way to set up the skills and Cloud MCP together is the Cypress plugin for Claude Code. It installs all five Cypress AI Skills and configures Cloud MCP in one step. In a Claude Code session, add the Cypress marketplace and install the plugin:

/plugin marketplace add cypress-io/ai-toolkit
/plugin install cypress@cypress

Choose an install scope when Claude Code asks.

User scope gives you the plugin in every project on your machine.
Project scope turns it on for everyone who works in the repository, and each person installs it once.

An organization admin still needs to turn on Cloud MCP in Cypress Cloud, and you sign in the first time Claude Code uses it.

If you’d rather install the pieces one at a time, follow the steps below.

Step 1: Install Cypress AI Skills

Cypress AI Skills live in the open source cypress-io/ai-toolkit repository on GitHub. They don’t require a Cypress Cloud account, a subscription, or have usage limits.

There are five skills:

Skill	What it helps Claude Code do
`cypress-author`	Create, update, and fix end-to-end and component tests. It reads your config, custom commands, and fixtures first, so new tests match the patterns you already use.
`cypress-explain`	Review and explain existing tests. It flags brittle selectors and missing assertions and uses accurate Cypress terminology.
`cypress-tap`	Run and debug tests against a live `cypress open` session from the command line. Claude Code can verify its own work by reading reporter output and inspecting the app where a test fails.
`cypress-cloud-cli`	Investigate recorded runs through the Cypress Cloud CLI, including test attempts and failures reconstructed from Test Replay data.
`cypress-docs`	Route Cypress questions to the official documentation, with awareness of the Cypress version you use.

Install all Cypress skills

From the root of your project, run:

npx skills add cypress-io/ai-toolkit

The skills install at the project level, so you can commit them and give everyone on your team the same Cypress context.

Install one Cypress skill

If you only want one skill, name it:

npx skills add https://github.com/cypress-io/ai-toolkit --skill cypress-author

Prefer the GitHub CLI? This works too:

gh skill install cypress-io/ai-toolkit

You can also copy the skill folders into .claude/skills in your project by hand.

Use a skill

Claude Code picks up the right skill when a task matches it. You can also call one directly with a slash command:

/cypress-author Write an end-to-end test for the guest checkout flow. A guest should be able to add a product to the cart, enter a shipping address, and see the order confirmation page.

If you installed the Cypress plugin, include its prefix: /cypress:cypress-author.

Skills won’t turn a vague request into a precise one. The clearer your acceptance criteria, the closer the first draft will be to what you want.

Step 2: Connect Claude Code to Cypress Cloud

Cloud MCP is free on every Cypress Cloud plan, including Starter. It reads recorded run data, so you need to record your runs to Cypress Cloud to use it.

Claude Code can reach your recorded runs in three ways:

Cypress Cloud connector
Cloud MCP server
Cypress Cloud CLI

All three read recorded run data, so you need to record your runs to Cypress Cloud to use them. Cloud MCP and Cypress Cloud CLI are free on every Cypress Cloud plan, including Starter.

Ask an admin to turn on the Cloud MCP integration

An organization admin turns on Cloud MCP from the Integrations page in your Cypress Cloud organization settings. After that, each person connects their own Claude Code.

Option 1: Add the Cypress Cloud connector

If you sign in to Claude Code with your claude.ai account, the connector is the quickest route. You add it once, and it works in Claude Code and the Claude apps.

Open the Cypress Cloud connector in the Claude connectors directory.
Select Connect to Claude , then sign in to Cypress Cloud when prompted.
In Claude Code, run /mcp to confirm the connector is listed.

Option 2: Add the Cloud MCP server from your terminal

Use this route if you sign in to Claude Code another way, such as with an API key, or if you want to control the scope more precisely. If you already added the connector, you can skip it. If you do both, Claude Code uses the server you added here and hides the connector as a duplicate.

We recommend signing in with OAuth. Run this command in your terminal:

claude mcp add cypress-cloud \
  https://mcp.cypress.io/mcp \
  --transport http \
  --scope user

Then start Claude Code with claude and ask it something about Cypress Cloud. Claude Code opens your browser so you can sign in to Cypress Cloud. Your session lasts 30 days, so you won’t need to rotate tokens, and you can revoke access at any time from your Manage Profile page in Cypress Cloud. To check the connection, run /mcp inside Claude Code.

Choose a scope for the Cloud MCP

The --scope flag decides where the connection is available:

--scope user makes Cloud MCP available in every project on your machine. This is the setting we recommend.
--scope local limits it to the current project.
--scope project saves the configuration to a .mcp.json file in your repository, so teammates who pull the repository get the same setup. Each person still signs in with their own Cypress Cloud account.

Use a personal access token instead of OAuth

If OAuth doesn’t fit your environment, create an MCP personal access token from your Manage Profile page in Cypress Cloud.

Cypress Cloud shows the token once, so copy it right away. Then add it as a header:

claude mcp add cypress-cloud \
  https://mcp.cypress.io/mcp \
  --transport http \
  --scope user \
  --header "Authorization: Bearer YOUR_MCP_TOKEN"

Keep token-based setups at user or local scope. The project scope writes the configuration to a file in your repository, and a token doesn’t belong there.

Option 3: Use the Cypress Cloud CLI

The Cypress Cloud CLI, cy-cloud, reads the same recorded runs as Cloud MCP, from your terminal. The cypress-cloud-cli skill from Step 1 teaches Claude Code how to use it. The CLI can also download Test Replay data, so Claude Code can step through a test’s timeline and inspect the page at the moment it failed.

Before you start, an organization admin needs to turn on the Cloud CLI integration in Cypress Cloud.

Install the CLI and sign in:

npm install --global @cypress/cloud
cy-cloud login

cy-cloud login opens your browser to sign in. In CI or a Claude Code web session, set CYPRESS_CLOUD_TOKEN to a personal access token instead. It signs you in without writing credentials to disk.

Cloud MCP or the Cloud CLI?

Cloud MCP is the quickest to set up. It works in the Claude apps and any MCP client, and it has tools for Cypress Accessibility and UI Coverage reports.
Cloud CLI adds nothing to Claude Code’s context until it runs, and it can dig into Test Replay data in great detail.
You can use both.

Prompts to try with Cypress Cloud MCP

Here are a few prompts to start with:

Find the latest passing run on main in Cypress Cloud and get the duration of every spec, paging through all results. Then suggest how to balance our specs across parallel CI machines.

For latest run on this branch in Cypress Cloud, pull spec durations and tell me which specs are the slowest. Then break the slowest one down by test so I know whether to split it.

List every skipped and pending test in the last run on this branch in Cypress Cloud, grouped by spec.

Run, spec, test, and failure data are available on every plan.

Flaky test data, Cypress Accessibility results, and UI Coverage reports are available for plans that have access to those features, so those tools return data when your plan includes them.

List all flaky tests from the last five runs in Cypress Cloud. Do the error messages share any patterns?

Pull the Cypress Accessibility report for the latest run on this branch. List any critical or serious violations, grouped by rule.

Using Cypress Cloud, pull the UI Coverage report for the latest run on this branch. What is the overall score, and which untested elements are in the riskiest view?

Cloud MCP limits how many tool requests you can make per hour. The Cloud MCP documentation lists the current limit.

Step 3: Let Claude Code check its work with `cypress tap`

Writing a test is only half the job. The other half is watching it run and seeing what went wrong. cypress tap is a command-line interface (CLI) built into the Cypress App that lets Claude Code work with the Cypress App you already have open. It can run a spec, read the results and the Command Log, go back to the snapshot at any command, and inspect the page’s DOM and accessibility tree. That’s the same context you use when you debug a test yourself.

The cypress-tap skill you installed in Step 1 teaches Claude Code how to use these commands well. For example, it makes sure Claude reads the result of the run it just started, not the previous one.

How it differs from `cypress run`

cypress run runs your specs headlessly and exits, which is what you want in CI. cypress tap attaches to a running cypress open session instead, so Claude Code can rerun a spec, look at the app at the moment a test failed, and try again without starting over.

Start a `cypress tap` session

Open Cypress the way you normally would, and leave it running:

npx cypress open --e2e --browser electron

Then start Claude Code from the same project folder. Claude Code finds the open session automatically.

Ask Claude Code to verify a test

Run cypress/e2e/checkout/guest-checkout.cy.ts in my open Cypress session. If a test fails, look at the page at the failing command and fix the selector or assertion.

Here’s what that looks like in practice. Say Claude Code wrote the checkout test with a guessed selector, .submit-btn, and the test fails. Claude Code reads the failing test from the reporter, goes back to the snapshot at the failing command, and inspects the page. It finds that the button is actually [data-cy="checkout-submit"], updates the spec, and runs it again. No guessing, and no copying error messages out of the Cypress app.

You can run the same commands yourself, which is useful when you want to see what Claude Code sees:

npx cypress tap status
npx cypress tap run cypress/e2e/checkout/guest-checkout.cy.ts
npx cypress tap dom --selector "[data-cy=checkout-submit]"

Step 4: give your Cypress tests their own CLAUDE.md

Skills teach Claude Code how Cypress works. A CLAUDE.md file teaches it how your team works. It’s a plain markdown file of instructions that Claude Code reads as context, and you can put one right in your cypress folder so your testing conventions live next to your tests.

Why a separate file? Your root CLAUDE.md probably covers how to build and run the app. Cypress conventions, like which selectors to use or which custom commands exist, matter only when Claude Code works on tests. A separate file keeps the root file short and gives the people who own your test suite a file they can maintain.

The skills already read your config and custom commands. CLAUDE.md is where you put the decisions that aren’t visible in the code, like which of two similar commands your team prefers.

Create a CLAUDE.md file in your `cypress` folder

Add a CLAUDE.md file to your cypress folder. Here’s an example; swap in your own commands, paths, and rules:

# Cypress tests

## Selectors
- Select elements with `data-cy` attributes, for example `cy.get('[data-cy="checkout-submit"]')`.
- Don't select elements by CSS class or position.

## Custom commands
- Use `cy.login(role)` to sign in. Only tests in `cypress/e2e/auth/` drive the login form directly.
- Use `cy.seedCart(products)` to set up cart state through the API.

## Running tests
- Run one spec with `npx cypress run --spec cypress/e2e/checkout/guest-checkout.cy.ts`.
- Reuse fixtures in `cypress/fixtures` before creating new ones.

Keep it short and specific. Anthropic recommends staying under 200 lines per file, because longer files use more context and Claude Code follows them less consistently.

How Claude Code scopes a CLAUDE.md file to the folder

You don’t need any configuration. Claude Code loads a CLAUDE.md file in a subfolder on demand: when it reads, writes, or edits a file inside cypress/, it adds cypress/CLAUDE.md to its context. In a session where you only work on application code, the file doesn’t load.

Scope Cypress rules by file pattern instead

A folder file only covers files inside that folder. If some of your specs live elsewhere, like component tests next to the components they cover, use a path-scoped rule instead. Create .claude/rules/cypress.md at the root of your project and list the paths it applies to:

---
paths:
  - "cypress/**/*"
  - "src/**/*.cy.{js,ts,jsx,tsx}"
---

# Cypress tests

- Select elements with `data-cy` attributes.

Claude Code loads the rule only when it reads, writes, or edits a file that matches one of the patterns.

Share it with your team

Commit cypress/CLAUDE.md or your rule file so everyone gets the same conventions. For personal notes that shouldn’t be shared, like the port your local server runs on, use a CLAUDE.local.md file at the project root and add it to your .gitignore file.

Put them together: from a CI failure to a verified fix

Say a spec fails on your branch in CI. Instead of opening Cypress Cloud, finding the run, copying the error, and pasting it into a chat, you ask:

The checkout spec failed in Cypress Cloud on my branch in CI. Find out why and fix it.

Here’s what Claude Code can do with all the Cypress connections in place:

Find the failure. Through Cloud MCP, it pulls the failed test, the error message, the stack trace, and a Test Replay link for the run.
Understand the test. With cypress-explain, it reads the spec and identifies the likely cause, such as an assertion that runs before an API response arrives.
Write the fix. With cypress-author, it updates the test using your existing custom commands and selector conventions.
Verify the fix. With cypress-tap, it runs the spec against your open Cypress session and reads the results.

You stay in the loop the whole way. Claude Code proposes changes to your local files, and you review them like you’d review a teammate’s pull request. What changes is how much time you spend gathering context before you can make a decision.

What Cypress data Claude Code can and can’t see

Giving an AI assistant access to your test data is a reasonable thing to be careful about, so here’s exactly how Cloud MCP works:

It’s read-only. Cloud MCP can’t change your tests or delete runs in Cypress Cloud.
It follows your permissions. Claude Code sees only the projects your Cypress Cloud account can see, based on your existing role in your organization and team.
We don’t see your conversation. Cypress has no access to your chat history or Claude Code’s context. We receive only the inputs to each tool call, such as a project ID.
Your test data isn’t used for model training.
You control the connection. Cloud MCP works only where you configure it, and you can revoke OAuth access at any time from your Manage Profile page.

AI Skills run locally in your project and don’t send data to Cypress Cloud on their own. The cypress-cloud-cli skill reads Cloud data only through the Cloud CLI you authenticate.

Get started

The setup takes a few minutes: one command for the skills and one for Cloud MCP or the Cloud CLI. The Cypress AI Skills documentation, the Cloud MCP documentation, and the Cloud CLI documentation cover every option in detail, and the Claude Code MCP documentation explains how Claude Code manages servers.

To go deeper on CLAUDE.md files and path-scoped rules, see how Claude Code remembers your project.

Frequently asked questions

Do I need Cypress Cloud to use Claude Code with Cypress?

No. Cypress AI Skills and cypress tap work with your local project and your open Cypress session. You need Cypress Cloud only for Cloud MCP and the Cloud CLI, which read your recorded runs.

Is Cloud MCP free?

Yes. Cloud MCP is included on every Cypress Cloud plan, including Starter. Some tools return data only when your plan includes the related feature, such as flaky test detection, Cypress Accessibility, or UI Coverage. Usage limits are subject to change.

Are Cypress AI Skills free?

Yes. They’re open source, and they don’t require a Cypress Cloud account or subscription.

Can Cypress see my Claude Code conversations?

No. Cypress receives only the inputs to each Cloud MCP tool call, such as a project ID. We have no access to your conversation or Claude Code’s context, and your test data isn’t used for model training. Prompts sent directly to the submit_mcp_feedback tool call are sent to our team, so only call this when you have feedback to share with us.

Does this work with Cursor or GitHub Copilot?

Yes. Cypress AI Skills work with AI coding tools that support skills, including Cursor and GitHub Copilot, and Cloud MCP works with any MCP-compatible client. The setup steps differ by tool. Check the setup steps in our documentation.

Find elements the way your users do with cy.getByRole()

Jennifer Shehane — Wed, 14 Oct 2026 17:54:38 +0000

Starting in Cypress 16.2.0, cy.getByRole() is a built-in query that finds elements by their role and accessible name. The role is what a screen reader announces an element as, such as a button or a link, and the accessible name is the text it announces for it.

This offers a built-in alternative to the .findByRole() selector from the popular Cypress Testing Library plugin. That package no longer has an active maintainer and the previous maintainer suggested Cypress build these queries into Cypress directly.

We agree with that direction. Role-based queries are a core way to write resilient, accessible tests, and they belong in Cypress itself. cy.getByRole() is the first of these built-in queries. We plan to bring more of the Testing Library queries teams depend on into Cypress.

What `cy.getByRole()` does

cy.getByRole() finds every element with a given role, such as button, link, heading, or tab, and can narrow the results to elements whose accessible name matches. Because those are what assistive technology announces, a test written this way finds elements the way assistive technology does. If a control’s role or label changes, the test fails.

describe('account settings', () => {
  it('saves profile changes', () => {
    cy.visit('/settings')
    cy.getByRole('textbox', { name: 'Display name' }).type('Jane Doe')
    cy.getByRole('button', { name: 'Save changes' }).click()
    cy.getByRole('alert').should('have.text', 'Changes saved')
  })
})

A few behaviors on how cy.getByRole() works:

It yields every match. Like cy.get(), cy.getByRole() yields all matching elements in document order. Narrow the name, or chain .first() or .eq(), to act on one.
A string name matches the whole name, case-sensitively. Pass a regular expression to match part of a name or ignore case, or a function for custom logic.
It skips elements hidden from the accessibility tree by default, such as elements with aria-hidden="true" or display: none. Pass hidden: true to include them.
It retries like any Cypress query, so it waits for an element to appear and for chained assertions to pass.
It prefers built-in HTML elements. If a native HTML element exists for a given role, cy.getByRole() matches that element only, unless native: false is passed.

To narrow by state, such as checked, selected, expanded, or heading level, chain .filter():

// The tab that is currently selected
cy.getByRole('tab').filter('[aria-selected="true"]')

// Level 2 headings
cy.getByRole('heading').filter('[aria-level="2"], h2:not([aria-level])')

// A checked native checkbox
cy.getByRole('checkbox').filter(':checked')

// A checked checkbox that gets its role from a role attribute
cy.getByRole('checkbox', { native: false }).filter('[aria-checked="true"]')

// The menu button whose menu is open
cy.getByRole('button').filter('[aria-expanded="true"]')

// A toggle button that is switched on
cy.getByRole('button').filter('[aria-pressed="true"]')

// The link to the page the reader is on
cy.getByRole('link').filter('[aria-current="page"]')

// Every button except disabled ones
cy.getByRole('button').not(':disabled, [aria-disabled="true"]')

The cy.getByRole() API reference covers every option, including shadow DOM, TypeScript, and scoping with .within().

Why native elements are the default in `cy.getByRole()`

For any role that HTML has a native element for, such as button, link, heading, dialog, or checkbox, cy.getByRole() matches only elements whose tag gives them that role. A <div role="button"> does not match cy.getByRole('button') unless you pass native: false.

<button>Save</button>
<div role="button" tabindex="0">Cancel</div>

// Yields and clicks the native <button>
cy.getByRole('button', { name: 'Save' }).click()

// The <div> has the role only through its role attribute, so it's skipped
cy.getByRole('button', { name: 'Cancel' }).should('not.exist')

Why make more strict behavior the default? Because a role-based locator that accepts both elements can cover up accessibility issues that could be easily discovered by your tests. Native controls are the most likely to work well for keyboard-only users, including many people with motor disabilities, or for screen reader users, because the browser handles the behavior automatically and consistently.

On the other hand, custom controls may implement a role attribute in order to satisfy a byRole selector, and often skip the rest of the required behavior. This creates a false impression that something is accessible.

What a `role` attribute does not support natively

Adding role="button" to a <div> changes one thing: assistive technology announces the element as a button. As MDN’s documentation of the button role explains, the role does not add keyboard handling or other button behavior. The application code has to account for all of it.

A native <button> gives you these behaviors built in:

Automatically joins the keyboard tab order.
Activates with both the Enter and Space keys.
Fires a click event for keyboard activation, not only for mouse clicks.
Supports the disabled attribute, which removes the button from the tab order and blocks activation.
Submits the surrounding form.

A <div role="button"> gets none of these. To match a native button, a developer has to add tabindex="0", a keydown handler for both keys, logic to stop Space from scrolling the page, and their own disabled state handling. Each of those is a place for a bug to hide, and a mouse-driven test won’t notice any of them, so if the accessibility-friendly byRole locator is passing, it can be easy to miss the risk.

What people experience when the native element doesn’t match the role

Here’s what that gap looks like for real users of a partially-implemented button, for example a <div role="button"> that only has a click handler:

Keyboard-only users press Tab and skip right past the control. Without tabindex, the browser never puts it in the tab order, so there’s no way to reach it. People who can’t use a mouse, including many people with motor disabilities, are stuck.
Screen reader users may reach the content and hear “Save, button” and do what anyone would: press Enter or Space. Depending on their screen reader and how they’re navigating, nothing may happen, because the page only listens for mouse clicks. They will not know if they successfully operated the button.
Anyone using Space to activate it may watch the page scroll down instead, because Space scrolls the page unless the developer prevents it.
Users who encounter a “disabled” state may still be able to activate it. Setting aria-disabled="true" describes a state to screen readers, but doesn’t block clicks or key presses the way the native disabled attribute does, allowing for unintentional activation.

None of this shows up in a test that clicks the element with a simulated mouse event. That’s exactly why we made native matching the default. If someone replaces a <button> with a <div role="button">, your existing cy.getByRole('button', ...) test fails and points you at the change, and you can decide whether it was intentional and if more tests are needed.

The broader principle comes from web accessibility: The first rule of ARIA advises using a native HTML element whenever one already has the semantics and behavior you need, instead of rebuilding it with an ARIA role attribute. The W3C ARIA Authoring Practices Guide button pattern shows how much work a custom button takes to get right.

When to pass `native: false` to `cy.getByRole()`

In some cases a role attribute is the right call, or at least not yours to change. Pass native: false to also match elements that get their role from a role attribute:

// A dialog rendered by a component library you don't control
cy.getByRole('dialog', { name: 'Delete project', native: false }).should('be.visible')

A few common patterns need native: false even when they follow the ARIA authoring practices, because HTML has a different native element for the role:

An autocomplete <input role="combobox">. The native combobox is a <select> or an <input> with a list attribute.
An icon <svg role="img">. The native image is an <img>.

For widget roles that HTML has no element for, such as tab, menuitem, or switch, a role attribute is the only option, so cy.getByRole() always matches it. You don’t need native: false for those.

If your app is built on a component library that re-implements native elements with role attributes, you don’t have to pass native: false on every call. You can overwrite the query in your support file to make native: false your project’s default. A test can still pass native: true to require a native element.

// cypress/support/commands.js
Cypress.Commands.overwriteQuery(
  'getByRole',
  function (originalFn, role, options = {}) {
    return originalFn.call(this, role, { native: false, ...options })
  }
)

Moving off of Cypress Testing Library

Do you need to migrate `cy.findByRole()` to `cy.getByRole()` right now?

No. Cypress Testing Library still works with Cypress 16.2.0. It registers only findBy* queries, so it doesn’t conflict with cy.getByRole(), and you can migrate one spec at a time.

Most calls translate by renaming the query:

// Before: Cypress Testing Library
cy.findByRole('button', { name: 'Place order' }).click()
cy.findAllByRole('listitem').should('have.length', 3)
cy.findByRole('tab', { selected: true }).should('have.text', 'Shipping')

// After: cy.getByRole()
cy.getByRole('button', { name: 'Place order' }).click()
cy.getByRole('listitem').should('have.length', 3)
cy.getByRole('tab').filter('[aria-selected="true"]').should('have.text', 'Shipping')

There are a few differences that could cause a one-to-one replacement to fail:

Native elements by default. A test that found a <div role="button"> with findByRole() fails after migrating. Decide for each one whether the app should use the native element, or the test should pass native: false. I’d encourage you to treat this list as an accessibility review, not a chore. To keep your current behavior while you migrate, overwrite the query to default to native: false, as shown earlier.
Every match, not one. cy.getByRole() yields every match instead of failing when more than one element matches. Narrow the name or chain .first() to act on one.
State options become .filter(). The checked, selected, pressed, expanded, current, busy, level, and value options move to a chained .filter(). If you pass one of these options, the error tells you which filter to use.

The migration guide in the cy.getByRole() docs has before-and-after examples and a copyable prompt you can give an AI agent to do the migration.

Custom command failing with `cy.getByRole()`

If your project already defines its own getByRole with Cypress.Commands.add() or Cypress.Commands.addQuery(), that call throws an error in Cypress 16.2.0, because getByRole is now a built-in query. Rename your command, or remove it and use the built-in one.

How `cy.getByRole()` and Cypress Accessibility fit together

cy.getByRole() only checks the elements you locate in a test. Cypress Accessibility widens the view. It runs axe-core checks against every unique page state your recorded tests reach, with no changes to your test code, and reports the results in Cypress Cloud. That catches problems like missing labels, low color contrast, and invalid ARIA on parts of the page no test explicitly asserts.

Put together, it looks like this:

cy.getByRole() helps ensure the elements your tests use or assert about have a clear accessibility purpose and name.
Cypress Accessibility audits every state your tests reach, including everything they don’t interact with or make assertions about.

cy.getByRole() is built into the Cypress app and works without Cypress Cloud. Cypress Accessibility runs with Cypress Cloud. You can adopt either one on its own, and each makes the other more useful, because you will get a more detailed axe-core report if your elements have recognizable roles with associated accessibility expectations, and don’t appear to be generic content.

What to do next

If you’re starting a new test, reach for cy.getByRole() first. If you already use Cypress Testing Library, there’s no rush, but migrating gives you a supported query and an accessibility check on every control your tests touch. And if a migrated test fails because of the native default, take that seriously. It may be the first time your test suite noticed something a keyboard user has been running into all along.

Upgrade to Cypress 16.2.0, then read the cy.getByRole() documentation to get started. We’d love to hear how it goes, and which Testing Library queries you’d like to see built in next.

Frequently asked questions

What is `cy.getByRole()` in Cypress?

cy.getByRole() is a built-in Cypress query that finds DOM elements by their role and, optionally, their accessible name. The role is what a screen reader announces an element as, such as a button or a link. It yields every matching element and retries until the elements exist and chained assertions pass.

Which version of Cypress includes `cy.getByRole()`?

Cypress 16.2.0 and later.

What about test IDs?

Test IDs like data-cy and data-test specifically avoid depending on anything about the element, which means they have no opinion about accessibility, HTML, or content. They are useful for maximum stability where those things don’t matter, or for separating different instances of otherwise-similar elements.

When working with cy.getByRole(), you may want to chain .filter('[data-cy="your-test-id"]') to ensure a specific element is matched if there is a chance that more than one might be on the same page.

Do I still need `@testing-library/cypress` to find elements by role?

No. cy.getByRole() replaces findByRole() and findAllByRole() without a plugin. If you use other Testing Library queries, such as findByLabelText(), keep the package for now. The two can run side by side.

Why doesn’t `cy.getByRole()` find my `<div role="button">`?

For roles that have a native HTML element, cy.getByRole() matches only the native element by default. Pass { native: false } to also match elements that get their role from a role attribute, or switch the element to a native <button>, which means keyboard and screen reader users get built-in button behavior and you will not need to pass an option. To make native: false your project’s default, overwrite the query with Cypress.Commands.overwriteQuery().

Why is a native `<button>` more accessible than `role="button"`?

role="button" only changes how assistive technology announces the element. A native <button> is also in the keyboard tab order, activates with Enter and Space, supports the disabled attribute, and submits forms. A custom button has to rebuild each of these by hand, and missing any of them can block keyboard and screen reader users.

How is `cy.getByRole()` different from Testing Library’s `findByRole()`?

cy.getByRole() matches native elements by default, yields every match instead of failing on multiple matches, and uses a chained .filter() for states such as checked and selected instead of options.

How do I find a checked checkbox or a level 2 heading with `cy.getByRole()`?

Chain .filter(). For example, cy.getByRole('checkbox').filter(':checked') or cy.getByRole('heading').filter('[aria-level="2"], h2:not([aria-level])').

Does `cy.getByRole()` work inside shadow DOM?

Yes. Pass includeShadowDom: true, set the includeShadowDom configuration option, or chain cy.getByRole() off .shadow().

Should I use `cy.getByRole()` or `cy.prompt` self-healing to keep tests stable?

They work well together. cy.getByRole() ties a test to roles and accessible names, which rarely change by accident, and fails when a control loses native behavior. cy.prompt heals steps when an element changes and marks each heal so you can review it. Preferring role and aria-label in your ElementSelector priority helps cy.prompt heal less often.

Does Cypress Accessibility replace `cy.getByRole()`?

No. Cypress Accessibility audits every page state your recorded tests reach, including elements no test touches. cy.getByRole() is an explicit technique to conveniently locate elements by their accessible role and get a built-in preference for native browser implementations.

Will Cypress add other Testing Library queries?

Yes, that’s our plan. cy.getByRole() is the first, and we’ll announce others as they’re ready.

Skip tests that pass on the current build: Re-run optimization in Cypress Cloud

Mark Noonan — Thu, 01 Oct 2026 16:35:34 +0000

When Cypress detects a CI rerun, it can now skip the work that already passed and run only what failed, so you get to green faster, burn fewer CI minutes, and record fewer billable test results. Re-runs with few failures can skip 99% or more of the tests that would have re-executed. It works out-of-the-box with common CI providers, and ships with overrides to customize the re-run behavior to your specific needs.

Re-run Optimization is available for all Business plans and higher, and in free trials, as a part of Smart Orchestration.

This post will walk through the highlights for saving time and getting a green build faster.

Why do teams re-execute failed Cypress runs?

We interviewed current Cypress Cloud customers to get this feature right. Most told us they already use tools like flake detection to stay on top of things they can control from the testing side. Generally their test design is not causing flakiness, and in-run, often flake represents real race-condition bugs in the application logic.

Re-runs address instability that’s not at the application layer or the test design layer. A re-run adds information to help you understand the full end-to-end picture, especially if your testing environment itself is not fully stable, which means a single failure could have multiple causes. The re-run helps rule some of those causes out cheaply, before you or your AI systems work on debugging.

For busy teams with large test suites on complicated applications, keeping the test environment stable isn’t always practical, or even necessarily desired. When systems integrate with live devices or depend on third parties, stability itself is part of what a full end-to-end test run is measuring.

Whatever the underlying reason for a failure, if something is blocking a release or an important merge, your priority in that moment is to understand the issue and get unblocked as fast as possible. At those times, re-run optimization makes your re-executions cheaper, faster, and less painful.

How much time is saved with Re-run optimization in Cypress Cloud?

The most time savings come from test-level re-runs, which allows Cypress to cherry-pick individual tests that need to re-run. Based on real production runs from customers who have adopted this technique, the median re-run skips 92% of the original run’s tests, and finishes 9.3 minutes faster than the original run.

The maximum savings we have seen on re-runs are when there are large test suites with small numbers of failures, where 99.8% of the tests that would have re-executed were skipped , and 36 minutes were saved for the test run. This is the pattern you may see if you run long nightly test suites or pre-release tests of live environments that might have deployments or other disruptions during the test execution.

Re-run optimization makes it much faster and more practical to get that extra confidence and confirmation of what’s going on when a build has failed, and avoids the risk of instability leading to the original failures passing on the new run, only for something else to start failing.

Choose spec-level or test-level reruns in Cypress Cloud

You set the granularity once in the Smart Orchestration section of your organization or project settings, and projects can inherit the org default or override it.

When set to run only failed specs , Cypress re-runs every spec that contained a failure on the last run, including the tests in that spec that passed, which is the safer choice if your tests share state inside a spec.

When set to run only failed tests , Cypress re-runs only the tests that didn't pass, plus any that are new or changed since the last run. It requires Cypress 15.21.0 or later (older versions fall back to failed specs). If a test would pass on its own with .only, it will work in a re-run. If not, prefer spec-based retries for your project.

Controlling the re-run behavior in Cypress Cloud

If you re-run before Cloud marks the previous run complete, Cypress plays it safe and runs everything. Keeping your run completion delay short can reduce the window where your CI is ready to rerun a job but Cypress Cloud is still open. But in many cases, you may want to manage the previous run’s status explicitly. Our recently released Run Cancellation API, and Run Completion API give you programmatic control over the run state. Combined with Spec Prioritization and Auto Cancellation.

Turn it on

Re-run optimization is part of Smart Orchestration on Business and Enterprise plans, and it's available during a free trial. Owners and Admins can enable it in organization or project settings. The Re-run optimization docs cover setup for each CI provider.

Build custom workflows with Cypress Cloud Webhooks

Mark Noonan — Tue, 08 Sep 2026 17:17:31 +0000

Webhooks are a new addition to Cypress Cloud, supporting more flexible automation workflows beyond what is built into the platform itself.

Learn why we've added them and how to get started using them in your project.

Integration support in Cypress Cloud

Cypress Cloud supports a wide range of integrations out of the box. If you need a GitHub status check for every group of tests in your test run, we've got you covered. Slack and Teams messages when a run fails? That's there, along with desktop notifications, Jira ticket creation, high-level trend reporting APIs, and more.

Why webhooks?

Using webhooks is a great solution for custom integrations where you want Cypress Cloud to push run results and other data into another system.

A webhook can be the starting point to kick off workflows based on inspecting the outcome of a run, or a way to customize the details you will include in a Slack or Teams message, or send messages to destinations Cypress doesn't support, such as Google Chat.

Webhooks also help you leverage our other recently-released Cypress App and Cypress Cloud updates in ways that work for you. Rather than invoke the Cypress Cloud CLI or MCP at the end of every run, you can set up a URL for Cypress to deliver run results, along with the tags, branch, and commit info that helps you decided if further action is needed.

This lets you be more efficient with AI token usage and reduce rate-limited request you make for routine run analysis. Filter to just the runs you are most interested in based on the webhook payload, then you can dive deeper with scripts using the Cloud AI tools to get Test Replay snapshot data and command logs, or hand off to your LLM using the live Cypress App running locally with cypress tap.

When to use a webhook

In some cases, existing APIs may fully meet your needs, particularly if your runs are small and the existing integrations are well-suited to the content you already want in your messaging platforms.

In other cases, webhooks remove multiple layers of handoffs from your CI environment to other services, removing glue code or even opening up new possibilities, like optionally triggering re-runs of your failed tests in CI based on the tags or commit message you send to Cypress Cloud.

Get started

Available on all paid Cypress Cloud plans, today webhooks can be attached to a run.completed event, which fires when a run has resolved to a finalized state after all results have been recorded.

Admins and owners can add webhooks in your project settings page.

Note: the recently-released Run Completion API may be useful if you have parallel or grouped runs, and you want your webhooks to fire as soon as all expected groups have finished recording.

What's next

We'd love to know how you are using this and what types of events or payloads would be useful for your specific goals. We will continue developing and expanding in this area based on your feedback.

Read the webhooks docs to get your first webhook configured. Don't have a Cypress Cloud account yet? Start your free trial and try it on your own project.

cypress tap: Closing the Loop Between Your Agent and Your Suite

David Ingraham — Fri, 28 Aug 2026 19:03:12 +0000

Your agent can write the test and run the test. Until now, it couldn't see the page.

Test failures will happen. Flake will happen. Writing new tests against a product deadline will happen. We've all been there and will be there again in the future.

Software development is predictable that way, and completely fluid at the same time, which is what makes every day a slightly different problem than the one before it.

As we've all started folding AI into that work, we've learned it's extremely good at producing a lot of code, fast. And one rule has held up better than any other: the better your inputs and the more context the tool has, the better the output. That's the whole reason we encode conventions as Skills, point agents at tickets through MCP, and hand them our patterns instead of hoping they guess right.

But there's a ceiling, and it shows up the moment the agent has to work against a running app.

When it's debugging a broken test or writing a new one, it can't see the DOM. It sees whatever I paste in. No matter how good the Skills are or how well-structured the repo is, the agent is reasoning about a page it has never actually looked at.

That's the gap, and it sits in the middle of a loop we all run every day:

The agent writes the test.
The suite runs it.
Somebody reads what happened.
The agent revises.

Steps 1, 2, and 4 have been handled for a while now.

Step 3 was me, until now.

A Read Interface, Not a Writer

cypress tap is a set of CLI commands that read and drive an open-mode Cypress session from your terminal.

Setup is two terminals. cypress open in one, cypress tap from the same project root in the other. No config, no server, no MCP.

The subcommands split into three jobs:

Find and run: sessions, specs, status, run
Read results: reporter, command
Interrogate the page: pin, dom, aria, inspect

Everything prints readable output by default and machine-readable JSON with --json.

The thing worth noticing is what isn't in that list.

There's no tap write. No tap fix. No tap generate. It takes the context the Cypress app was already showing you on screen and puts it somewhere a terminal, or an agent working in one, can actually reach.

Breaking a Test Purposefully

I have a fake pet adoption site I use for testing out new automation features and for creating workshops against. This exciting new feature was one I hooked up to that repo.

To demo what tap actually does, I needed something red to point at, so I broke it deliberately: I renamed an app-side data-testid from favorite-button-* to favorite-toggle-* and left the spec untouched.

Deliberately simple, too. The point here isn't the puzzle in the break, it's how the agent utilizes cypress tap to get to the solution and how this new approach can be scaled to more complicated, real-life scenarios.

Here's the whole diagnosis, terminal only.

1. Is there a session I can reach? cypress tap drives an already-open Cypress, so first prove one exists using tap sessions.

$ npx cypress tap sessions
SESSIONS (1)
  PID    PROJECT                                         TYPE  BROWSER
  29426  /Users/davidingraham/repos/pet-adoption-portal  e2e   Chrome

2. What can it run? Using tap specs it identifies the open spec from the runner.

$ npx cypress tap specs
SPECS (1)
  cypress/e2e/favorites.cy.js  9 minutes ago

3. Trigger the failure. Next it runs the open spec so it can capture the current output.

$ npx cypress tap run cypress/e2e/favorites.cy.js
▶ cypress/e2e/favorites.cy.js

4. The failure as text. The bare reporter command returns the suite summary. As you can see, I only ran one test and I knew it was going to fail. I imagine when you are actively working on building multiple tests at once, the reporter command will be a great translator between what is happening in the runner and what the agent knows as changes are made.

$ npx cypress tap reporter
cypress/e2e/favorites.cy.js  (started at 7:21:21 PM)
✓ --  ✖ 1  ○ --  00:04

Favorites Feature
   r3  ✖ adds a pet to favorites  4.2s

5. Expand the failing test. The agent can pass in additional flags to expand on what happened at each step, all the way up until the captured failure. Note the test id, r3, which every command from here on scopes to.

$ npx cypress tap reporter --test-id r3
✖ Favorites Feature > adds a pet to favorites  failed

ROUTES (1)
  METHOD  MATCHER             STUBBED  ALIAS        #
  POST    **/api/favorites/*  no       addFavorite  -

BEFORE EACH · h1
   1  request  ● POST 200 http://localhost:3000/api/auth/login
   2  request  ● GET 200 http://localhost:3000/api/favorites
   3  visit    /pets

TEST BODY · r3
   1  get      [data-testid="pets-grid"]
  e1    (xhr) ● GET 200 http://localhost:3000/api/auth/me
  e2    (xhr) ● GET 200 http://localhost:3000/api/auth/me
  e3    (xhr) ● GET 200 http://localhost:3000/api/pets?species=&age=&size=&gender=&search=&sortBy=dateAdded&sortOrder=desc&page=1
  e4    (xhr) ● GET 200 http://localhost:3000/api/favorites
   2  -assert  expected <div.grid.md:grid-cols-2.gap-6> to be visible
   3  get      [data-testid^="favorite-button-"] ✖

✖ AssertionError
  Timed out retrying after 4000ms: Expected to find element: `[data-testid^="favorite-button-"]`, but never found it.

cypress/e2e/favorites.cy.js:29:8
    27 |
    28 |     cy.intercept('POST', '**/api/favorites/*').as('addFavorite');
  > 29 |     cy.get('[data-testid^="favorite-button-"]').first().as('favoriteButton').click();
       |        ^
    30 |     cy.wait('@addFavorite').its('response.statusCode').should('eq', 201);
    31 |
    32 |     cy.get('@favoriteButton').should('contain', '❤️');

6. Pull the failing command as data. Command 3 is the one that failed, so the agent asks for it directly. This is the Command Log row as structured output rather than something you hover in the UI.

$ npx cypress tap command --test-id r3 --command-id 3
TEST BODY · r3
✖  3  get  [data-testid^="favorite-button-"]  failed

CONSOLE PROPS
  Selector  [data-testid^="favorite-button-"]
  Elements  0

7. Put the at-failure DOM back on screen. pin pushes that command's snapshot into the live browser frame, so everything that follows is querying the page exactly as it looked when the test broke.

$ npx cypress tap pin --test-id r3 --command-id 3
⚲ PINNED - (1/1)
TEST BODY · r3
   3  get  [data-testid^="favorite-button-"] ✖

8. Ask the page what's actually there. Next it can read the real ARIA tree from the DOM, which shows twelve favorite buttons rendered and healthy.

$ npx cypress tap aria
navigation
  link  🐾 PawMatch
  ...
main
  heading  Adopt a Pet
  ...
  image  Scout
  button  🤍
  heading  Scout
  button  View Details →
  [...eleven more pet cards...]

9. Inspect the element itself. Finally, tap inspect returns the actual attributes on that button, which is where the answer is sitting.

$ npx cypress tap inspect --selector '.grid button[data-testid]' --at 0
ATTRIBUTES (2)
  data-testid  favorite-toggle-18
  class        absolute top-3 right-3 w-10 h-10 bg-white/90 ...

ACCESSIBILITY
  role  button
  name  🤍

BOX
  x 189   y 564   width 40   height 40

Two lines carry the whole diagnosis.

Step 6 says Elements 0. Step 9 says favorite-toggle-18.

The button was there the entire time. Visible, clickable, exactly where it should be. What changed was its contract with the test.

That's a diagnosis I'd previously have assembled by clicking the red row in the Command Log, hovering the snapshot, opening DevTools on the runner, and squinting at the Elements panel to compare attribute names. Here it's text I can paste straight into the fix commit.

The fix is a one-line selector update, and tap run plus tap reporter confirm it green, without ever touching the GUI.

$ npx cypress tap reporter
cypress/e2e/favorites.cy.js  (started at 7:22:21 PM)
✓ 1  ✖ --  ○ --  310ms

Favorites Feature
   r3  ✓ adds a pet to favorites  302ms

Scale This Up

The demo above was a single renamed attribute. Sure I could have solved it by eye, but think about the front ends most of us are actually testing. Virtualized tables that only render what's in view. Nested modals and portals. Shadow DOM. Component libraries that regenerate class names on every build. Accessibility trees that don't match the visual order. Conditional rendering three states deep, where the element exists in one branch and not the other.

When one of those fails, the hard question is almost never what the error was. The error is right there in the stack trace. The hard question is what was on the page at the moment it broke, and that has always meant a human clicking into the runner and looking.

That's the context that's been missing. Not smarter models, not better prompts. Just a way to ask the page what it looked like and get an answer back as text. tap aria and tap inspect produce that on demand now, which is incredibly powerful and exciting.

On a real application, it's the difference between an agent that can help with triage and one that can only guess at it. I'm looking forward to seeing how many wasted agent cycles disappear now that it has the product context it always needed.

What It Needs to Run

It's a local development tool. tap reads an open-mode session, and cypress open has to be running on the same machine. Sessions register themselves in a shared cache, which is how tap sessions finds them.

There's no headless story, so you can't drop tap into a CI job or a nightly run. This isn't a knock on tap, it's just not how it is designed. CI has no open-mode session in a pipeline for it to read. If you were hoping to hand failure context to an agent triaging a 2am CI failure, that isn't this. At least not yet.

It also means someone has to keep the runner open. Close the session and the agent goes blind mid-task. That's a non-issue when you're sitting there working, but worth knowing if you're multi-tasking or handing work off.

Here's the flip side of that though: because cypress open is up, you're watching. The browser is right there. The agent kicks off the spec and you see the run happen while the terminal narrates it. That's a very different experience from an agent working headless and reporting back a summary. You get the machine-readable context and your own eyes on the same run, at the same time.

Final Thoughts

Back to the loop.

The agent writes the test.
The suite runs it.
Somebody reads what happened.
The agent revises.

Steps 1, 2, and 4 were never the hard part and those solutions have been around for a while. cypress tap hands step 3 over. The Command Log as text. The failing command as data. The DOM and the accessibility tree, on demand, exactly as they were when things broke.

Failures are still going to happen. Flake is still going to happen. The deadlines are definitely not moving. What changes is how fast you find out why, and how much of that you have to type out yourself in the age of AI.

Point your agent at it on the next red test and see if your triage gets shorter.

I'm pretty excited about this one and can't wait to fully implement it.

As always, happy testing.

Building Mocks-First Automated Testing with Cypress and AWS DynamoDB

Sehani Chathurangi — Fri, 14 Aug 2026 10:10:37 +0000

When testing applications that depend on cloud services, manually preparing database records for every test can quickly become time-consuming, repetitive, and error-prone.

A better approach is to automate test-data creation using reusable fixtures, custom Cypress tasks, and the AWS SDK.

In this article, I'll walk through how I built a mocks-first testing approach using Cypress and AWS DynamoDB, where each test can create the data it needs, execute independently, and verify the resulting database state.

Why Mocks-First Testing?

A mocks-first approach allows tests to control their required data and dependencies instead of relying on manually prepared records.

Rather than creating database records before running a test, the test itself prepares the required state during execution.

This provides several benefits:

Faster test execution
Repeatable test scenarios
Reusable test data
Less manual setup
Better test isolation
Easier maintenance
More reliable CI/CD execution

The goal is not to mock every AWS service. Instead, the approach focuses on controlling test data and external dependencies so that tests remain predictable and repeatable.

The Overall Approach

The architecture can be summarized as:

Cypress Test → cy.task() → Node.js → AWS SDK → DynamoDB

The Cypress test is responsible for describing the scenario and assertions, while the Node.js layer handles AWS-specific operations.

This separation keeps the test code clean and prevents AWS database logic from being duplicated across test cases.

Step 1: Create Reusable Mock Data

The first step is to create reusable JSON fixtures.

cypress/
└── fixtures/
    └── test-data.json

The fixture contains the information required to create the database record.

Instead of hardcoding database values inside every test, the fixture becomes the base payload that can be reused across multiple scenarios.

For example:

{
  "id": "test-12345",
  "name": "Sample Test Data",
  "category": "TEST",
  "status": "ACTIVE"
}

Different fixtures can also be created for:

Positive scenarios
Negative scenarios
Boundary conditions
Error scenarios
Different transaction states

This keeps test data separate from test logic.

Step 2: Separate Database Logic

The next step is to keep DynamoDB operations outside the Cypress test itself.

A dedicated helper can be responsible for:

Creating the DynamoDB client
Converting fixture data into database records
Generating partition keys and sort keys
Calculating TTL values
Inserting records
Retrieving records
Deleting test data when required

For example, a helper might expose operations such as:

insertMockData()
getMockData()
deleteMockData()

The important principle is separation of concerns.

The test should describe what data it needs, while the helper handles how that data is stored in DynamoDB.

Step 3: Expose Database Operations Through Cypress Tasks

Cypress provides cy.task() as a bridge between the Cypress test environment and Node.js.

Instead of putting AWS SDK operations directly inside the browser-side test, the test can call a custom task:

cy.task('insertMockData', mockData);

The flow becomes:

Cypress Test
     │
     ▼
 cy.task()
     │
     ▼
 Node.js
     │
     ▼
 AWS SDK
     │
     ▼
 DynamoDB

Typical Cypress tasks can include:

insertMockData
getMockData
deleteMockData

This approach centralizes AWS operations and makes them reusable across the entire test suite.

Step 4: Configure Environment Variables

Cloud configuration should never be hardcoded inside test files.

Environment-specific values can be provided through configuration such as:

AWS Region
AWS credentials
DynamoDB table name
Local DynamoDB endpoint
Other environment-specific settings

This allows the same test suite to run against different environments.

For example:

Local
  ↓
Development
  ↓
QA
  ↓
CI/CD

The test logic remains unchanged while the configuration changes according to the execution environment.

Credentials and secrets should always be managed securely and should never be committed to the repository.

Step 5: Build Flexible Test Data

Creating a separate fixture for every test scenario can eventually lead to duplicated test data.

Instead, a base fixture can be loaded and overridden only where necessary.

For example:

const testData = {
  ...baseFixture,
  id: `test-${Date.now()}`,
  status: 'INACTIVE'
};

The base fixture provides the common structure, while the test customizes only the values relevant to the scenario.

This approach makes it easier to generate unique test records while keeping the fixture maintainable.

It is especially useful when testing:

Multiple transactions
Different statuses
Different merchants
Edge cases
Concurrent processing
Large datasets

Step 6: Verify the Database State

Creating test data is only part of the process.

After the application processes the data, the test should retrieve the relevant DynamoDB record and validate the resulting state.

Typical validations include:

Record exists
Partition key is correct
Sort key is correct
Required attributes are stored
Status is updated correctly
Configuration values match expectations
TTL is generated correctly
Expected processing results are persisted

For example:

Insert test data
       ↓
Application processes data
       ↓
Retrieve DynamoDB record
       ↓
Validate final state

This allows the test to validate not only that data can be written, but also that the application's workflow produces the expected result.

Why This Structure Works

The approach separates the test suite into three main responsibilities:

Fixtures
   ↓
Test Data

Database Helpers
   ↓
AWS / DynamoDB Operations

Cypress Tests
   ↓
Business Scenarios + Assertions

This separation provides a cleaner architecture and makes individual components easier to maintain.

If the DynamoDB implementation changes, the test cases do not necessarily need to change.

If the test scenario changes, the AWS helper does not need to change.

Moving Toward Event-Driven Testing

Directly inserting records into DynamoDB is useful for preparing controlled test states, but it can also bypass parts of the application's normal workflow.

This approach can therefore become the foundation for a more complete event-driven testing strategy.

The current approach might look like:

Fixture
   ↓
Cypress Task
   ↓
DynamoDB
   ↓
Application / Verification

The next evolution could be:

Fixture
   ↓
Event / SNS
   ↓
Application
   ↓
DynamoDB
   ↓
Cypress Verification

Instead of directly creating the database record, the same mock payload can be published as an event.

The application then processes the event through its normal workflow, and Cypress verifies the final database state.

The biggest advantage is that the test-data model can remain reusable.

The injection point changes, but the underlying fixture structure can remain largely the same.

When This Approach Is Useful

This pattern works particularly well for:

Integration testing
Event-driven applications
DynamoDB-backed services
CI/CD pipelines
Repeatable test scenarios
Large-scale automated test suites
Tests requiring controlled database state

However, direct database seeding should be used carefully for end-to-end testing because it can bypass application logic that you may actually want to validate.

A good testing strategy can use both approaches:

Database seeding for controlled setup and targeted integration tests.

Event/API-driven setup for validating the application's complete workflow.

Key Benefits

Using reusable fixtures together with Cypress tasks provides several advantages:

Cleaner test code — AWS logic stays outside the test cases.
Reusable mock data — Fixtures can support many scenarios.
Reduced duplication — Base data can be overridden when needed.
Faster execution — Tests do not depend on manual database preparation.
Better test isolation — Each test can create its own required state.
Centralized AWS logic — DynamoDB operations are maintained in one place.
CI/CD friendly — Test data can be generated automatically.
Easy evolution — The same data model can support future event-driven testing.

Final Thoughts

Automating database setup with reusable fixtures, Cypress tasks, and the AWS SDK can remove a significant amount of repetitive manual work from integration testing.

The key is to keep test data, database operations, and test scenarios separate.

Instead of manually preparing DynamoDB records before every test, the test suite becomes responsible for creating the state it needs and validating the resulting behavior.

More importantly, this approach creates a foundation for moving toward event-driven testing. As the application architecture evolves, the same reusable test data can be injected through events and processed through the application's normal workflow.

The result is a testing architecture that is repeatable, maintainable, scalable, and easier to integrate into CI/CD pipelines.

Teaching an Agent to Triage Flaky Tests — and to Know When Not To

Lyle Smart — Thu, 06 Aug 2026 18:32:22 +0000

Teaching an Agent to Triage Flaky Tests — and to Know When Not To

Every team with a mature Cypress suite eventually meets the same quiet adversary: the flaky test. Not the broken test—the flaky one. It fails, then passes on retry, so nobody files it, so it lingers. Over time, "just re-run it" stops being a workaround and becomes a habit, and that habit costs you the one thing an end-to-end suite is supposed to give you: confidence.

We decided to stop treating flake as background noise and start treating it as a signal worth acting on every single morning. So we built an autonomous agent to do the triage a human never quite finds time for. What we learned building it had less to do with automation than we expected, and a lot to do with judgment.

Turning a Number Nobody Reads into a Decision

The data was already there. Cypress Cloud records a flaky_test_count on every CI run and can tell you precisely which tests flaked—the error name, the message, the failing line of the stack, attempt by attempt. That is a rich signal. It was also, for us, a number that scrolled past unread.

So we gave the agent a way to read it directly. We use the Cypress MCP server to dial into Cypress Cloud. It is the pipe through which the agent pulls recent runs and, for any run that flaked, the per-attempt failure detail behind each one. No scraping dashboards. No exporting CSVs. The agent simply asks Cypress Cloud what happened and gets back structured data, which is exactly what makes the rest of the loop possible.

Each weekday it scans the last fifty completed CI runs, tallies flakiness per test, and applies a deliberately blunt rule: a test is only a candidate if it flaked in three or more distinct runs. One bad night is not a pattern. A test that wobbles across three separate runs is telling you something. That threshold is the difference between a useful beacon and an alarm everyone learns to mute.

From there the loop is end to end, and this is where the second tool earns its place. We use Claude to review and fix the tests. It reads the failure detail surfaced through the Cypress MCP server, opens the actual spec file, groups failures into distinct modes, and writes a concrete, code-level diagnosis. Where a spec change is genuinely the right answer, it proposes the fix itself.

The agent then deduplicates against Jira so the same flake is never filed twice, creates one ticket per flaky test on our QE board, @mentions the appropriate team, posts a summary to Slack, and updates a running tally in Confluence so the trend is visible to anyone who cares to look.

The Most Important Thing It Does Is Refuse

Here is where the project stopped being about automation.

The obvious way to build a test-fixing agent is to let it fix everything. Point it at a red test and let it turn the test green. But a flaky test is often not a test problem at all—it is a product telling you the truth in an inconvenient way.

A backend might return a 500 during a read-after-write race. A page might render late because grading happens server-side. Increase the Cypress timeout and the test goes green, but you have not removed the flake. You have hidden a real bug and taught your suite to lie.

So the single most important rule in the agent is one of restraint.

It proposes a fix only when a spec change genuinely stabilizes the test. When the root cause is application-side or infrastructure-related, it files the ticket, classifies it clearly, and opens no pull request at all.

It is not there to make tests pass.

It is there to tell you why they don't.

When it does propose a fix, that fix stays inside a narrow lane:

Draft pull requests only
Cypress spec files only
Never application source code
Clearly labeled as auto-generated and unverified

The pull request's own CI run is the real verification. The agent's confidence is never mistaken for correctness.

Giving It a Memory—and a Rule About That Memory

Diagnosis is the part of this an agent is most likely to get wrong, so we gave it something to lean on: a committed file of confirmed root-cause patterns.

Each entry pairs a spec family and an error signature with:

The confirmed root cause
The correct classification
The band-aid fix to avoid

Before diagnosing anything, the agent reads this file and reuses what a human has already worked out rather than re-deriving a cause it has gotten wrong before.

The rule governing that file matters just as much as the file itself.

Confirmed causes only.

Never a fresh guess.

Codifying an unverified diagnosis would teach the agent to repeat exactly the mistake the file exists to prevent. A provisional hunch stays in the Jira ticket, where a human can weigh it. It never graduates to institutional memory until someone confirms it.

What Actually Changed

Flaky tests now get triaged within minutes instead of never.

The team wakes up to a Slack summary and a short stack of tickets, many with a draft fix already attached and the rest clearly marked as something a person needs to investigate.

We can finally see, month over month, whether the suite is getting healthier.

The outcome we did not anticipate is that a meaningful share of what we had lazily filed under "flaky" turned out to be genuine product race conditions—bugs that now receive a bug's attention instead of a timeout bump.

If I could leave other Cypress teams with one reflection, it is this:

The agent's most valuable trait is not how much it automates. It is that it knows the difference between a test problem and a product bug, and refuses to paper over the second.

AI can accelerate the triage none of us had time for. But the judgment about what deserves a fix—and what deserves the truth—still has to be built in on purpose.

Cypress Ambassador Spotlight: Boris Selivanov

Melissa Milligan — Fri, 24 Jul 2026 13:43:32 +0000

What motivates you to be a Cypress Ambassador?

I see being an Ambassador as the ultimate form of asynchronous collaboration. My goal is to share things that move the needle for other engineers. By comparing how different teams solve the same testing problems, we can turn isolated project victories into shared wins.

How do you currently help others that are either using Cypress or interested in using Cypress?

I'm the person teammates ping when a test goes flaky or they're not sure how to approach a complex scenario. I always try to answer with a reusable pattern rather than a one-off fix so the knowledge scales past me. A lot of that is helping people pick selectors that survive a redesign, semantic and stable, over cosmetic and brittle.

What is your favorite Cypress feature?

cy.intercept(). It's the ultimate tool for eliminating flake caused by unstable backend environments or slow APIs. Being able to intercept, modify, or stub network traffic means you can test frontend behavior under any condition imaginable, instantly. It guarantees your tests are deterministic, isolated, and entirely repeatable.

What is your favorite "Cypress Best Practice" and why?

Never using arbitrary cy.wait(ms). Hard waits are a confession that you don't trust your tooling. They either slow every run down or paper over a real race condition. Leaning on retry-ability and cy.intercept() aliases instead means the suite waits exactly as long as it needs to, no more, no less.

Outside of work, what are your favorite things to do (hobbies, passions, etc.)?

Catching FIFA World Cup matches with friends. It's the perfect way to unwind and watch a defensive line get tested for a change, instead of my own automation suite.

What is one professional milestone you are proud of?

Building stable automation frameworks from scratch and successfully scaling that knowledge across large, cross-functional teams. Throughout my career, my favorite milestones haven't just been writing clean architectural patterns, but leading training sessions for 20+ engineers and clients to get them comfortable with test automation. Demystifying complex testing concepts and giving teams the leverage to confidently own their builds is exactly what drives me.

For new users - what is the best way to "get started" with Cypress?

Skip the boring configuration routines. Just run npm install cypress, open the runner, and write a real test against your actual app: visit a page, fill a form, submit, and assert the result. Letting the native retry-ability handle the async waiting while watching it interact with your live, real-world codebase is the absolute fastest way to make the framework click.

What is your favorite quote or saying?

"It works on my machine."

Connecting AWS Account with Cypress Automation: A Simple STS Connection Test

Sehani Chathurangi — Fri, 17 Jul 2026 12:42:14 +0000

When building Cypress automation that interacts with AWS services, the first step is verifying that your test framework can successfully authenticate and communicate with your AWS account.

In this article, you'll learn how to connect Cypress to AWS and perform a simple authentication test using AWS Security Token Service (STS) and the GetCallerIdentity API.

This approach helps confirm that:

AWS credentials are correctly configured.
Cypress can invoke AWS SDK operations through Node.js tasks.
The automation environment is connected to the expected AWS account.

Establishing this connection first provides a solid foundation before automating interactions with services such as AWS Lambda, Amazon S3, Amazon DynamoDB, Amazon SNS, or Amazon SQS.

Prerequisites

Before getting started, ensure you have:

Node.js installed
A Cypress project
Valid AWS credentials:
- AWS Access Key ID
- AWS Secret Access Key
- AWS Session Token (if using temporary credentials)
- AWS Region

Note:If you're running Cypress in an AWS environment (such as AWS CodeBuild, an EC2 instance with an IAM role, or GitHub Actions using OpenID Connect), you may not need to provide credentials manually. The AWS SDK can automatically retrieve credentials from the execution environment.

Step 1: Install the AWS SDK

Install the AWS STS client package:

npm install @aws-sdk/client-sts

For this connectivity test, we only need the AWS Security Token Service (STS) client.

The package provides:

STSClient – Creates a client for communicating with AWS STS.
GetCallerIdentityCommand – Returns details about the authenticated AWS identity associated with the configured credentials.

Step 2: Configure AWS Credentials

For local development, create or update your cypress.env.json file.

{
  "AWS_ACCESS_KEY_ID": "",
  "AWS_SECRET_ACCESS_KEY": "",
  "AWS_SESSION_TOKEN": "",
  "AWS_REGION": ""
}

Populate the file with your AWS credentials.

Example:

{
  "AWS_ACCESS_KEY_ID": "your-access-key",
  "AWS_SECRET_ACCESS_KEY": "your-secret-key",
  "AWS_SESSION_TOKEN": "your-session-token",
  "AWS_REGION": "us-east-1"
}

Important: Never commit cypress.env.json containing real AWS credentials to source control. Add it to your .gitignore file.

Best Practice: For CI/CD pipelines, prefer environment variables, IAM roles, or OpenID Connect (OIDC) instead of storing credentials in a file.

Step 3: Configure Cypress to Use AWS Credentials

Update your cypress.config.ts.

First, import the required AWS SDK classes.

import { defineConfig } from "cypress";
import { STSClient, GetCallerIdentityCommand } from "@aws-sdk/client-sts";

Inside setupNodeEvents, map the Cypress environment variables to Node.js environment variables.

setupNodeEvents(on, config) {

  const awsKeys = [
    "AWS_ACCESS_KEY_ID",
    "AWS_SECRET_ACCESS_KEY",
    "AWS_SESSION_TOKEN",
    "AWS_REGION",
  ] as const;

  for (const key of awsKeys) {
    if (config.env[key]) {
      process.env[key] = config.env[key];
    }
  }

}

Cypress stores environment variables in config.env, while the AWS SDK automatically reads credentials from the standard Node.js environment (process.env).

By copying the values into process.env, the AWS SDK can authenticate automatically without requiring any additional credential configuration.

The AWS SDK follows the AWS Credential Provider Chain, and environment variables are one of the first credential sources it checks.

Step 4: Create an AWS Connection Task

Create a Cypress task that authenticates with AWS using STS.

on("task", {
  async awsConnectionTest() {
    try {
      const client = new STSClient({
        region: process.env.AWS_REGION || "us-east-1",
      });

      const response = await client.send(
        new GetCallerIdentityCommand({})
      );

      return {
        Account: response.Account,
        Arn: response.Arn,
        UserId: response.UserId,
      };
    } catch (error) {
      throw new Error(`AWS authentication failed: ${error}`);
    }
  },
});

Why use a Cypress task?

AWS SDK calls must run in Cypress tasks because tasks execute in the Node.js process.

Cypress test code runs in the browser context, where direct access to Node.js APIs is not available. Using cy.task() allows your tests to securely execute backend operations such as invoking AWS services.

What happens during this task?

Cypress calls the awsConnectionTest task.
The AWS SDK creates an STS client using the configured region.
The SDK automatically resolves credentials from the environment.
AWS validates the credentials.
STS returns details about the authenticated IAM user or role.

A successful response looks like this:

{
  "Account": "123456789012",
  "Arn": "arn:aws:iam::123456789012:user/test-user",
  "UserId": "AIDAxxxxxxxx"
}

Step 5: Create a Cypress Test

Create a new test file.

testing/awsConnection.cy.ts

Add the following test:

describe("AWS connection", () => {

  it("connects to AWS using STS GetCallerIdentity", () => {

    cy.task("awsConnectionTest").then((identity) => {

      cy.log(JSON.stringify(identity));

      expect(identity).to.have.property("Account");
      expect(identity).to.have.property("Arn");
      expect(identity).to.have.property("UserId");

    });

  });

});

Step 6: Run the Cypress Test

Execute either of the following commands:

npx cypress open

npx cypress run

If authentication is successful, Cypress logs the authenticated AWS identity, including:

AWS Account ID
IAM User or Role ARN
User ID

This confirms that Cypress can successfully authenticate with your AWS account.

Why Start with GetCallerIdentity?

Before interacting with AWS services such as:

AWS Lambda
Amazon S3
Amazon DynamoDB
Amazon SNS
Amazon SQS

it's recommended to verify that authentication is working correctly.

GetCallerIdentity is ideal because it:

Confirms that authentication is successful.
Identifies the AWS account and IAM identity being used.
Helps diagnose credential-related issues early.
Does not require permissions beyond the ability to authenticate.

Conclusion

Successfully calling GetCallerIdentity confirms that Cypress can authenticate with AWS using the configured credentials.

In this article, you learned how to:

Install the AWS STS SDK.
Configure AWS credentials for local development.
Map Cypress environment variables to the Node.js environment.
Create a Cypress task that authenticates with AWS.
Validate the connection using GetCallerIdentity.

Once this authentication step is working, you can extend the same approach to automate testing against other AWS services such as Lambda functions, S3 buckets, DynamoDB tables, SNS topics, SQS queues, and many more.

How I leveraged Claude Code skills to help me migrate Cypress 16 deprecations in time

Marcelo C. — Fri, 03 Jul 2026 15:05:58 +0000

Have you ever stared at a deprecation warning scrolling by in your terminal and thought "eh, future me will deal with that"? We all have! But here's the thing about future you: he eventually shows up. And in my case, he showed up wearing a shirt that said Cypress v16, holding a changelog, and pointing at the line that says Cypress.env() will be fully removed.

Warning in 15.10. Gone in 16. And sprinkled across every config, page object, and spec file in the massive E2E repository I maintain at my work monorepo. Configs, support files, fluent page-object chains — everywhere.

So let's get to the grain here: even though Cypress has a great documentation about it, I didn't want to execute a find-and-replace job manually, and I also wanted to move fast. So instead of pasting a prompt into a chat window forty times, I did something better: I turned the migration playbook itself into a Claude Code Skill — a reusable, self-triggering unit of expertise that lives in my machine and outlives this one migration.

Why Cypress.env() had to die

If you've written E2E tests, you know Cypress.env(). Synchronous, available everywhere, dead simple.

And that simplicity was exactly the problem: it hydrated the entire env object straight into the browser runtime. Every value. Including the ones a given test never reads. Your admin password, your API tokens — all of it, sitting in browser-accessible memory, one window inspection away, in every single spec.

Easy to use? Absolutely. A credential-leaking surface baked into your test runner? Also absolutely.

The v16 API splits the concern into two deliberately asymmetric halves:

cy.env(['key']).then(...) — asynchronous, resolved Node-side, strictly read-only. Values never touch the browser context until you explicitly consume them inside the callback. This is where credentials and tokens live now.
Cypress.expose('key') — synchronous, a drop-in replacement, but only for values you've explicitly opted in to exposing via a new top-level expose: block in your config (a sibling to env:, not nested inside it).

Notice the design: the safe path is ergonomic, the sensitive path is deliberately awkward. That asymmetry is the whole point.

The strategy: teaching the AI a classification heuristic

Doing a mindless regex sweep across thousands of files would have been fast — and catastrophically wrong, because every single call site needed a classification decision first. So instead of doing the work 3,000 times, I did it once: I encoded a strict heuristic and let Claude Code apply it mechanically.

The heuristic:

Does the value contain a password, a username paired with a password, or any secret? → It's sensitive. It stays in the env: block and every read site gets rewritten to the async cy.env([...]).then(...) form.
Is it a feature flag (our idp_active, xbrl_active), a locale, a timeout, a base URL fragment? → It's public. It moves to the expose: block and the read becomes a one-line swap to Cypress.expose().

Rule 2 is boring. Rule 1 is where the migration earns its war stories.

From prompt to Skill: making the knowledge permanent

The Cypress team actually ships an official starting point for this — the remove-cypress-env-usage prompt from the Cypress AI Toolkit:

It's good. But a prompt in a library has two problems: you have to remember it exists, and you have to re-paste it every session. A Claude Code Skill solves both. A Skill is just a folder with a SKILL.md — a markdown file with a small YAML frontmatter (name + description) followed by the instructions. Claude Code scans the descriptions on every task and auto-loads the skill when the context matches, so the moment I say "migrate this spec off Cypress.env", the whole playbook is already in its head. No copy-paste, no drift between sessions.

~/
└── .claude/
    └── skills/
        └── cypress-v16-migration/
            └── SKILL.md    # frontmatter + the full migration playbook

But here's the important part — I didn't just copy the official prompt into a file. I transformed it, layering in everything the generic version can't know about my repo:

The classification heuristic above, with our real flag names (idp_active, xbrl_active) as worked examples, so it never has to guess what "sensitive" means in our codebase.
The command-queue traps you're about to read below, written as explicit "never do this / always do this" rules — because I hit them once and never wanted the AI to reproduce them.
Our repo topology: all four active config files that need the expose: block and the final flag flip, so nothing gets a partial migration.
The verification sequence (grep → flag → CI) as a mandatory checklist the skill must run before declaring victory.

The generic prompt is the textbook; the Skill is the textbook annotated by someone who took the exam. And since it's a personal skill (kept local, not committed to the repo), I can keep sharpening it without a PR review debate about my prompt-engineering style. 😄

Where the plot thickens 🕵️

You might be thinking: "Ok, this is still just a glorified find-and-replace with two output templates. What's the big deal?"

The big deal is the Cypress command queue.

Swapping a synchronous read for an asynchronous one inside a fluent page-object chain changes the execution semantics of everything around it. Take our global cy.login() command — the one every spec in the codebase depends on:

// BEFORE — synchronous, credentials resolved at enqueue time
Cypress.Commands.add('login', () => {
  const user = Cypress.env('username');
  const pass = Cypress.env('password');

  cy.session([user], () => {
    loginPage.visit().typeUser(user).typePass(pass).submit();
  });
  cy.goToHome();
});

Naive migration attempt:

// BROKEN — do you see it?
Cypress.Commands.add('login', () => {
  cy.env(['username', 'password']).then(({ username, password }) => {
    cy.session([username], () => {
      loginPage.visit().typeUser(username).typePass(password).submit();
    });
  });
  cy.goToHome(); // 💥
});

Looks reasonable. It's a time bomb. Here's why:

Trap #1 — silent reordering. Cypress enqueues commands synchronously as JavaScript executes, but runs them later. That trailing cy.goToHome() gets enqueued before the .then() callback ever fires — and any non-Cypress code after the block (variable assignments, page-object state mutations) executes immediately, before the credentials even exist. No error. No warning. Just your test quietly doing things in the wrong order. This is, by far, the easiest mistake to make in the entire migration, and grep will never find it for you.

Trap #2 — cy.session() needs a resolved ID. The session ID argument is evaluated at call time, not at run time. You can't hand it a promise or a pending value. So the entire cy.session(...) invocation — not just its setup callback — has to move inside the cy.env().then() callback:

// CORRECT — everything downstream of the credentials lives inside the callback
Cypress.Commands.add('login', () => {
  cy.env(['username', 'password']).then(({ username, password }) => {
    cy.session([username], () => {
      loginPage.visit().typeUser(username).typePass(password).submit();
    });
    cy.goToHome();
  });
});

And here's the payoff of years of discipline: because every login flow was registered through Cypress.Commands.add, this entire architectural shift happened behind the command boundary. Thousands of cy.login() call sites across the specs didn't change by a single character. The abstraction held. This, kids, is why you wrap your login logic in a custom command instead of copy-pasting it into 5k tests (ask me how I know 😉).

The final lockdown 🔒

A migration you can't verify is just a migration you hope worked. Cypress v16 gives you a kill switch for exactly this: allowCypressEnv: false. With it set, any surviving Cypress.env() call becomes a hard runtime failure — not a warning, a crash.

My verification sequence:

grep the branch for live Cypress.env( calls → zero hits (comments and the migration doc don't count).
Flip allowCypressEnv: false across all four active config files — no partial lockdowns, no "we'll enable it on that config later."
Ship it to CI and let the full E2E stages be the judge.

Green across the board. And here's the subtle part that made it safe: we only changed the read API, never the injection mechanism. Every CI secret, every --env CLI override, every pipeline variable kept flowing exactly as before — they just land in a place the browser can no longer see by default.

The commit log tells the real story 📜

Want proof that the Skill approach actually moved fast? Read the git history like a detective:

First PR:
Tue 11:27  Migration to v16
Tue 12:11  [E2E] Migration to Cypress v16 architecture
Tue 14:44  Updating Cypress env flag
Wed 16:04  Updating Typescript types

Fixing login issue:
Thu 10:23  [E2E] Fixing idp override with v16 Cy migration

Look at Tuesday morning: the bulk rewrite of the entire architecture landed in about 45 minutes, between the first pass and the structured [E2E] commit. That's thousands of call sites, classified and rewritten, in less time than a sprint planning meeting. Two hours later, allowCypressEnv: false was already flipped — the kill switch armed on day one.

Then comes the honest part, the part most migration posts conveniently forget: the long tail. Wednesday was TypeScript's turn — cy.env() returning a promise-like of a keyed object meant the old string-based typings had to be reshaped, so the compiler could catch a mistyped key at build time instead of CI catching it at run time.

And Thursday? Thursday delivered the one trap the Skill didn't know about yet — Trap #3, the runtime override. One special spec family runs against a different server with IDP/SSO enabled, and it used to flip that on with a runtime Cypress.env('idp_active', true) in a beforeEach. In v16, idp_active now lives in the expose: block — and exposed values are resolved from config, read-only at runtime. The old setter didn't crash; it just silently did nothing, and the spec calmly logged into the wrong server. The fix was moving the override where v16 wants it: into the spec-level config override, resolved before the test runs, not mutated during it.

Guess what happened next? That trap went straight into the SKILL.md. The next migration Claude Code runs already knows about runtime overrides of exposed values. That's the whole point of a Skill over a prompt: it compounds.

The takeaway

A breaking-change migration at this scale isn't a refactor problem, it's a classification + execution-semantics problem. The AI didn't make the hard decisions — the heuristic did. The AI just made applying that heuristic across thousands of files not cost me a month of my life. And by encoding it as a Skill instead of a throwaway prompt, every trap I hit made the next migration cheaper.

What about you? Have you ever had to architect a massive, breaking-change migration across thousands of tests? What was the trap that almost got you — and did your abstractions hold when it mattered? Leave me a comment, I'd love to hear!

Meet the CypressConf 2026 Keynote: Bas Dijkstra

Ronald Williams — Mon, 13 Apr 2026 16:32:16 +0000

As CypressConf 2026 gets closer, the focus is simple.

How do you move fast and still trust your test results?

With more automation and AI in the mix, teams are shipping faster than ever. But speed has never been the hard part. Confidence is.

Across teams, the same patterns keep showing up. Test suites grow, pipelines get faster, and more signals are generated at every stage of development. But when it comes time to make a decision, teams are still asking the same question.

Can we trust this?

Quality issues rarely belong to one person or one role anymore. Confidence in what ships depends on how well teams interpret and act on the signals coming from their tests, pipelines, and production systems. That is the shift happening across the industry, and it is what this year’s theme is built around.

To kick things off, we are excited to announce our keynote speaker, Bas Dijkstra.

Bas is a global test automation consultant, trainer, and speaker who has spent years working directly with engineering teams to improve how they approach quality. His work is grounded in real systems, real constraints, and the realities of modern development. He is known for helping teams cut through noise, reduce flake, and build testing strategies they can actually rely on.

More importantly, he understands that testing is no longer a single function. It is a shared responsibility that spans developers, QA, and engineering leadership. The teams that succeed are the ones that align around clear signals and act on them with confidence.

That perspective is exactly what makes this keynote the right fit for CypressConf this year.

The industry is not short on tools. It is not short on automation. What teams are working through now is how to make sense of everything those systems produce. AI is increasing the volume of signals. Pipelines are accelerating feedback. But without clarity, more signal can just as easily create more noise.

The challenge is no longer generating results. It is knowing what matters.

At CypressConf 2026, you will hear from teams who are working through this in real time. They are improving how they collaborate across roles, finding ways to respond earlier without introducing risk, and turning test results into decisions they can stand behind. They are not slowing down. They are getting better at understanding the systems they have already built.

The keynote sets the tone for that conversation.

With Bas Dijkstra, expect a session grounded in experience, focused on what teams are actually dealing with today, and clear about where things are going next.

This is the first announcement for CypressConf 2026. More speakers, sessions, and content are on the way.

The signal is up.

Agent-Driven E2E Testing with Cypress: A Practical Guide to Harness Engineering with Cursor Subagents

Darpan Shah — Tue, 07 Apr 2026 22:13:28 +0000

Teams have done end-to-end testing deliberately for years: exploring the app, writing tests from what they see, fixing failures in focused sessions. That's skilled work, not guesswork.

The hard part is usually organizational. Knowledge sits in people's heads or scattered across chat histories and tickets. What you see on a live screen is tough to describe clearly to whoever writes the automated test. Each new flow forces everyone to reload the same context from scratch.

Agent-driven development doesn't replace that judgment. It packages skilled work into narrow roles (explore, implement, execute, repair) with clear inputs and outputs. Quality builds over time instead of starting from zero every sprint.

This approach mirrors harness engineering: the system around the agents that makes them reliable, not just capable.

What Is a Harness, and Why Does It Matter?

The term "harness" has emerged as shorthand for everything in an AI agent system except the model itself. Put simply: Agent = Model + Harness. "The core challenge of long-running agents is that they must work in discrete sessions, and each new session begins with no memory of what came before." According to Anthropic's engineering research, imagine a software project staffed by engineers working in shifts, where each new engineer arrives with no memory of what happened on the previous shift. Without structure, agents drift, repeat work, or declare victory too early.

Their solution? A two-fold approach: an initializer agent that sets up the environment on the first run, and a coding agent that makes incremental progress in every session, while leaving clear artifacts for the next session.

When you talking about a coding agent. Martin Fowler's team breaks harness engineering into key components:

Context engineering: Provides us with the means to make guides and sensors available to the agent.
Architectural constraints: Rules that mechanically enforce quality (not just suggestions).
Feedback loops: The human's job is to steer the agent by iterating on the harness. Whenever an issue happens multiple times, the feedforward and feedback controls should be improved to make the issue less probable or even prevent it.

Here's the counterintuitive insight: increasing trust and reliability in AI-generated code requires constraining the solution space rather than expanding it. Narrow roles, explicit handoffs, and clear boundaries make agents more productive, not less.

How This Applies to E2E Testing with Cypress

This article describes four agents specialized for E2E testing using Cypress and how they form a closed loop:

cypress-browser-explorer: Maps UI flows with live browser tooling
cypress-builder: Implements specs per team conventions
cypress-runner: Executes tests consistently
cypress-debugger: Classifies failures and applies fixes

Each agent produces a structured artifact (exploration report, spec file, run summary, debug notes) that becomes the input for the next agent. This is the harness in action: each step creates a plan that keeps the next agent on track.

In Cursor, each of these agents maps directly to a custom subagent -- a markdown file in .cursor/agents/ with a name, description, and focused prompt. The explorer subagent leverages Cursor's built-in browser tool to navigate your app, take snapshots, read the live DOM, and capture network activity without leaving the IDE. That means the exploration report isn't hand-written -- it's generated from real page state.

It seems reasonable that specialized agents like a testing agent, a quality assurance agent, or a code cleanup agent could do an even better job at sub-tasks across the software development lifecycle. That's exactly what this workflow does for E2E automation when Cypress is your tool.

Evidence from the real UI flows into code. Code gets verified by a standard test run. Failures get handled with clear escalation rules instead of improvisation.

The Feedback Loop

The loop in one sentence: Explore → build → run; on failure, debug and re-run; if the UI changed, explore again and rebuild.

This closed loop is where the efficiency gains come from:

Less rework: Selectors and URLs come from live exploration, not memory
Faster green builds: Runner standardizes execution; debugger applies evidence-based fixes
Clear escalation: Stale DOM leads to re-explore; flaky patterns get documented
Single-test discipline: Fix one failure, re-run, then move on

The Four Agents at a Glance

Agent	Role	Primary Inputs	Primary Outputs	Must Not
cypress-browser-explorer	Map scoped UI flows using Cursor's browser tool	URL, steps, ticket scope	Exploration report with selectors, network map	Wander outside scope; invent selectors without proof
cypress-builder	Implement specs per team rules	Exploration report	Spec and support code; handoff to runner	Skip exploration for unfamiliar pages
cypress-runner	Execute tests consistently	Spec path, tags/env	Pass/fail summary with failure context	Fix failing tests (send to debugger)
cypress-debugger	Classify failures, apply fixes	Failure output, artifacts	Code changes; handoff to runner or explorer	Invent selectors when DOM has changed

Important: These agents are blueprints, not universal standards. Your stack, auth flow, and naming conventions will differ. Expect to:

Edit agent instructions to reference your scripts and config
Pair agents with project rules (lint, selector policy, test ID format)
Add or trim steps where your org needs tighter guardrails

The value is the shape of the workflow and clean handoffs, not a one-size-fits-all prompt.

Handoff Templates: Structured Artifacts That Bridge Context

The key insight here was finding a way for agents to quickly understand the state of work when starting with a fresh context window. Structured handoffs are what prevent "context amnesia" between agents.

Explorer → Builder

## Handoff to cypress-builder

Prompt: "Create cypress/e2e/[feature].cy.js using this exploration report:
- Scope source: [quote from ticket/steps]
- URL map: [ordered list]
- Selector inventory: [element, purpose, selector, stability]
- Network map: [method, pattern, suggested alias]"

Builder → Runner

## Handoff to cypress-runner

Prompt: "Run <spec path> to verify the new/updated spec."

Runner → Debugger (on failure)

## Handoff to cypress-debugger

Prompt: "Triage these E2E test failures (Cypress):

**Failing specs:** cypress/e2e/<spec>.cy.js

**Failures:**
1. [TEST-ID] <describe> > <it>
   Error: <message>
   Screenshot: cypress/screenshots/<path>

**Notes:** <auth errors, timeouts, etc.>"

Debugger → Runner (after fix)

## Handoff to cypress-runner

Prompt: "Re-run <spec path> to verify the fix for [TEST-ID]."

Debugger → Explorer (stale DOM)

## Handoff to cypress-browser-explorer

Prompt: "Re-explore <URL/flow> because selectors are stale for <spec>. Return updated report to builder."

Explorer Report Checklist

When using the explorer agent, require a report that includes:

Scope source: Ticket, pasted steps, or URL/feature
Flow summary: Scoped path, completion or blocked state
URL map: Ordered URLs visited
Selector inventory: Element, purpose, selector, stability rating
Network map: Method, pattern, suggested intercept alias
Test strategy: E2E vs shift-left rationale per scenario
Notes: Gaps, fragile selectors, missing test hooks

Steering the Harness: How to Keep Agents Aligned

Rather than personally inspecting what the agents produce, we can make them better at producing it. The collection of specifications, quality checks, and workflow guidance that control different levels of loops inside the how loop is the agent's harness. The emerging practice of building and maintaining these harnesses, Harness Engineering, is how humans work on the loop.

This is working "on the loop" rather than just "in the loop." You're not micromanaging every output. You're improving the harness so agents naturally produce better results.

Practical steps:

Scope every request: URL, role, numbered steps, or ticket excerpt. The explorer especially needs to know what path to follow.
Encode standards in the repo: Lint rules, skills files, and agent instructions should match. Otherwise the model follows whatever file it read most recently.
Use explicit handoffs: Paste the structured blocks so the next agent gets data, not a summary.
Review diffs like any PR: Generated specs need scrutiny, especially auth, network mocks, and assertions on money or permissions.
Keep secrets out of chat: Credentials belong in .env or your secret manager.
Turn fixes into constraints: When an agent makes a mistake, you take the time to engineer a solution such that the agent never makes that mistake again. Add a lint rule, update the instructions, or create a check.

Review Gates: Keeping Humans on the Loop

Agents execute evaluations automatically, but human oversight remains important for initial calibration and quality validation. Keep humans at judgment points:

After build: Review spec structure, selector quality, and assertion coverage before treating a run as final.
After green: Quick coverage and risk check before merge.
After repeated debug failure: If the same failure persists after three fix attempts, escalate to a person.

The agents handle the repetitive cycle. Engineers keep the judgment calls.

Team-Owned Content

The harness above doesn't define these items. Your team documents them in skills, rules, or extended agent files:

Authentication flows, secrets file layout, and commands patterns
Exact run commands (local vs Docker), CI script names
Tag/grep filters, base URLs per environment
Selector policy beyond "prefer stable hooks" (data-*, roles, aria)
Test ID formats, coverage scripts, Lint/Cypress config conventions

Why This Approach Works

The principles from Anthropic and Martin Fowler's research explain why the four-agent pattern is effective:

Constraints as multipliers: Paradoxically, constraining the solution space makes agents more productive, not less. When an agent can generate anything, it wastes tokens exploring dead ends.
Structured artifacts bridge context: Structured progress files and feature lists let a new agent quickly understand the state of work, analogous to a shift handoff between engineers who've never met.
Feedback loops catch issues early: Run follows build. Debug follows failure. Re-explore only when needed. This order cuts rework.
Clean escalation prevents endless retries: If the DOM is wrong, hand to explorer. If three fixes fail, hand to a human. No guessing.
The harness evolves: Coding agents make it much cheaper to build more custom controls and more custom static analysis. Agents can help write structural tests, generate draft rules from observed patterns, scaffold custom linters, or create how-to guides from codebase archaeology.

Implementing This in Cursor with Subagents and Browser

The four-agent workflow maps to four Cursor subagents: one markdown file per role under .cursor/agents/, each with YAML frontmatter (name, description, model and any optional fields you need) plus a focused instructions and prompt body. How you create them is always the same—only the name, description, and instructions change to match explorer, builder, runner, or debugger.

Below is one example (the browser explorer). The other three files use the identical shape; plug in the responsibilities from the agent table and handoff templates earlier in this article instead of pasting four full prompts here.

---
name: cypress-browser-explorer
model: inherit
description: Explores the application UI using browser tools to discover selectors, network calls, and page flows for Cypress test development. Use when exploring a new feature, finding selectors, mapping user flows, building new tests, or when the user says to explore a page. ALWAYS launch the browser - never assume selectors without navigating and snapshotting.
---

You are a browser exploration specialist for E2E tests using Cypress.

When invoked:

1. **Authenticate** if the target page requires login (see above)
2. **Navigate** to the target URL or flow entry point
3. **Take a snapshot** to capture the page structure
4. **Follow the exploration checklist** below for every flow

## Exploration Checklist

### Page URLs
- Record the entry page URL
- Navigate through each step of the flow, recording intermediate URLs
- Record the confirmation/success page URL

### Selectors (capture in priority order)
Priority order:
1. `[data-cy]`, `[data-test]`, `[data-testid]` -- purpose-built for testing
2. Any other `[data-*]` attribute -- stable, not styling-dependent
3. Any `[test-*]` attribute (e.g. `test-auto`, `test-id`) -- also for testing
4. `[role="..."]`, `[aria-label="..."]`, `[aria-labelledby]` -- semantic/accessible
5. `label[for="..."]` + associated input -- form elements
6. Stable visible text via `cy.contains()` -- only when text itself is the assertion
7. Tag + attribute combos (e.g. `input[name="email"]`) -- last resort

**Never use**: CSS classes, generated IDs, tag names alone, XPath, positional selectors

### Network Calls
- Monitor network requests during the flow using browser tools
- For each significant API call, record:
  - HTTP method and URL pattern
  - Suggested intercept alias (e.g., `get:cart-items`, `post:place-order`)
  - Whether the response contains data needed for assertions
- Pay attention to: auth calls, data fetching, form submissions, redirects

## Authentication

When the target page requires login (e.g. `/dashboard`, `/account`, any page that
redirects to `/login`), authenticate **before** exploring. Never ask the user
for credentials -- resolve them from project files.

### Credential Resolution (priority order)

1. **`.env`** file in the project root -- parse `KEY=VALUE` lines.
2. **`cypress.env.json`** in the project root -- parse JSON object.

## Handoff to cypress-builder

Prompt: "Create cypress/e2e/[feature].cy.js using this exploration report:
- Scope source: [quote from ticket/steps]
- URL map: [ordered list]
- Selector inventory: [element, purpose, selector, stability]
- Network map: [method, pattern, suggested alias]
- Draft spec: [snippet if applicable]
"

## Output Format

Return a structured report:
1. **Scope source:** Ticket, pasted steps, or URL/feature 
2. **Flow summary**: Scoped path, completion or blocked state
3. **URL map:** Ordered URLs visited
4. **Selector inventory:** Element, purpose, selector, stability rating
5. **Network map:** Method, pattern, suggested intercept alias
6. **Test strategy:** E2E vs shift-left rationale per scenario
7. **Notes:** Gaps, fragile selectors, missing test hooks

Save as .cursor/agents/cypress-browser-explorer.md. Add cypress-builder.md, cypress-runner.md, and cypress-debugger.md the same way, then invoke with /cypress-browser-explorer (and so on) or let the parent agent delegate from each file’s description.

Cursor's browser tool powers the explorer

The explorer subagent is where Cursor's built-in browser tool becomes essential. Rather than asking an engineer to describe what's on screen, the agent:

Navigates directly to URLs and follows multi-step flows
Takes snapshots of live DOM state, capturing element structure, attributes, and text
Reads selectors from the actual page -- data-testid, ARIA roles, form labels -- instead of guessing
Captures network activity to identify API calls that need cy.intercept() aliases

This means the exploration report is evidence-based from the start. Selectors come from the real DOM, not from memory or a other sources that may be out of date. When the debugger detects stale selectors and hands back to the explorer, the browser tool re-navigates and captures the current state -- closing the feedback loop with live data.

Why subagents fit this workflow

Cursor subagents provide three properties that align with the harness model:

Context isolation: Each subagent gets its own context window. The explorer's noisy DOM snapshots and network logs don't pollute the builder's context. The debugger's stack traces don't crowd the runner. This is the same isolation principle the harness pattern demands.
Parallel execution: Multiple subagents run simultaneously, cutting wall-clock time on multi-spec work.
Structured handoffs: A subagent returns a final message to the parent agent. That message is the handoff artifact -- the exploration report, the run summary, the debug notes. The templates in this article become the return format each subagent follows.

The Orchestration Pattern

The parent agent acts as an orchestrator, coordinating the four subagents in sequence:

Invoke /cypress-browser-explorer with URL and steps -- get exploration report
Pass the report to /cypress-builder -- get spec files
Hand spec paths to /cypress-runner -- get pass/fail summary
On failure, send details to /cypress-debugger -- get fixes, then back to step 3

Each handoff uses the structured templates from earlier in this article. The parent agent doesn't need deep knowledge of Cypress APIs—it routes data between specialists. This is the same orchestrator pattern Cursor's documentation recommends for complex workflows.

If you use Cypress MCP, you can also point /cypress-debugger at MCP tools to fetch failures from Cypress Cloud. The debugger triages, patches the spec or support code, then uses the Debugger → Runner handoff to re-run and stays in that loop until failures are addressed. That keeps run, fail, fetch, fix, re-run inside one workflow.

Closing

Treating exploration, implementation, execution, and repair as separate agent roles mirrors how strong teams already work. The harness makes this pattern repeatable and easy to hand off inside the IDE.

The largest efficiency win is the closed loop: run follows build, debug follows failure, re-explore only when the page structure actually changed.

The most effective harnesses don't just constrain the agent. They create an environment where the agent naturally produces better output with less correction needed. This is a critical insight. The best harnesses aren't restrictive. They're enabling.

Since shipping these specialized Cypress agents, I have hardly written tests by hand. The agents produce specs; I review them, merge when they are right, and when something drifts or misfires I adjust the agent definitions, skills, or prompts so the next run is better. The work shifts from typing cy.* to curating the harness -- continuous improvement on the automation itself, not just on individual tests.

The loop is sequential, but each step stays small: one subagent, one job, less noise in context than doing it all in a single chat.

Agent-driven development pays off when agents are blueprints you maintain. With Cursor subagents, those blueprints live in your repo as markdown files -- versioned, reviewable, and shared across the team. The browser tool gives the explorer agent direct access to your running app, so the entire loop from live UI to green test stays inside the IDE. Tighten instructions as your app and pipeline evolve. Keep guidance in the loop so automation stays trustworthy, not just clever.

References

Anthropic: Effective Harnesses for Long-Running Agents
Martin Fowler: Harness engineering for coding agent users
Cursor: Subagents and Browser Tool

DEV Community: Cypress

How to connect Claude Code to Cypress

First, some terminology

Which setup do you need?

Quick start: install the Cypress plugin

Step 1: Install Cypress AI Skills

Install all Cypress skills

Install one Cypress skill

Use a skill

Step 2: Connect Claude Code to Cypress Cloud

Ask an admin to turn on the Cloud MCP integration

Option 1: Add the Cypress Cloud connector

Option 2: Add the Cloud MCP server from your terminal

Choose a scope for the Cloud MCP

Use a personal access token instead of OAuth

Option 3: Use the Cypress Cloud CLI

Cloud MCP or the Cloud CLI?

Prompts to try with Cypress Cloud MCP

Step 3: Let Claude Code check its work with cypress tap

How it differs from cypress run

Start a cypress tap session

Ask Claude Code to verify a test

Step 4: give your Cypress tests their own CLAUDE.md

Create a CLAUDE.md file in your cypress folder

How Claude Code scopes a CLAUDE.md file to the folder

Scope Cypress rules by file pattern instead

Share it with your team

Put them together: from a CI failure to a verified fix

What Cypress data Claude Code can and can’t see

Get started

Frequently asked questions

Do I need Cypress Cloud to use Claude Code with Cypress?

Is Cloud MCP free?

Are Cypress AI Skills free?

Can Cypress see my Claude Code conversations?

Does this work with Cursor or GitHub Copilot?

Find elements the way your users do with cy.getByRole()

What cy.getByRole() does

Why native elements are the default in cy.getByRole()

What a role attribute does not support natively

What people experience when the native element doesn’t match the role

When to pass native: false to cy.getByRole()

Moving off of Cypress Testing Library

Do you need to migrate cy.findByRole() to cy.getByRole() right now?

Custom command failing with cy.getByRole()

How cy.getByRole() and Cypress Accessibility fit together

What to do next

Frequently asked questions

What is cy.getByRole() in Cypress?

Which version of Cypress includes cy.getByRole()?

What about test IDs?

Do I still need @testing-library/cypress to find elements by role?

Why doesn’t cy.getByRole() find my <div role="button">?

Why is a native <button> more accessible than role="button"?

How is cy.getByRole() different from Testing Library’s findByRole()?

How do I find a checked checkbox or a level 2 heading with cy.getByRole()?

Does cy.getByRole() work inside shadow DOM?

Should I use cy.getByRole() or cy.prompt self-healing to keep tests stable?

Does Cypress Accessibility replace cy.getByRole()?

Will Cypress add other Testing Library queries?

Skip tests that pass on the current build: Re-run optimization in Cypress Cloud

Why do teams re-execute failed Cypress runs?

How much time is saved with Re-run optimization in Cypress Cloud?

Choose spec-level or test-level reruns in Cypress Cloud

Controlling the re-run behavior in Cypress Cloud

Turn it on

Build custom workflows with Cypress Cloud Webhooks

Integration support in Cypress Cloud

Why webhooks?

When to use a webhook

Get started

What's next

cypress tap: Closing the Loop Between Your Agent and Your Suite

A Read Interface, Not a Writer

Breaking a Test Purposefully

Scale This Up

What It Needs to Run

Final Thoughts

Building Mocks-First Automated Testing with Cypress and AWS DynamoDB

Why Mocks-First Testing?

Step 3: Let Claude Code check its work with `cypress tap`

How it differs from `cypress run`

Start a `cypress tap` session

Create a CLAUDE.md file in your `cypress` folder

What `cy.getByRole()` does

Why native elements are the default in `cy.getByRole()`

What a `role` attribute does not support natively

When to pass `native: false` to `cy.getByRole()`

Do you need to migrate `cy.findByRole()` to `cy.getByRole()` right now?

Custom command failing with `cy.getByRole()`

How `cy.getByRole()` and Cypress Accessibility fit together

What is `cy.getByRole()` in Cypress?

Which version of Cypress includes `cy.getByRole()`?

Do I still need `@testing-library/cypress` to find elements by role?

Why doesn’t `cy.getByRole()` find my `<div role="button">`?

Why is a native `<button>` more accessible than `role="button"`?

How is `cy.getByRole()` different from Testing Library’s `findByRole()`?

How do I find a checked checkbox or a level 2 heading with `cy.getByRole()`?

Does `cy.getByRole()` work inside shadow DOM?

Should I use `cy.getByRole()` or `cy.prompt` self-healing to keep tests stable?

Does Cypress Accessibility replace `cy.getByRole()`?