cypress-io/github-action [![Action status][ci-badge]][ci-workflow] [![cypress][cloud-badge]][cloud-project] [![renovate-app badge][renovate-badge]][renovate-bot]
Cypress based cypress-io/github-action runs End-to-End or Component tests in GitHub Actions Continuous Integration (CI) workflows, optionally recording to Cypress Cloud
Introduction
In addition to running Cypress tests, the action includes dependency installation, caching and more:
The following examples demonstrate the actions’ functions.
Examples
Examples contained in this repository, based on current Cypress versions, can be found in the examples directory.
Live examples, such as example-basic.yml are shown together with a status badge. Click on the status badge to read the source code of the workflow, for example
Note: this package assumes that cypress is declared as a development dependency in the package.json file. The cypress npm module is required to run Cypress via its Module API.
End-to-End Testing
name: End-to-end tests
on: push
jobs:
cypress-run:
runs-on: ubuntu-26.04
steps:
- name: Checkout
uses: actions/checkout@v7
# Install dependencies with caching
# and run all Cypress tests
- name: Cypress run
uses: cypress-io/github-action@v7
The workflow file example-basic.yml shows how Cypress runs on GH Actions using Ubuntu (22.04 and 24.04), Windows, and macOS without additional OS dependencies necessary.
This workflow uses the default test type of End-to-End (E2E) Testing. Alternatively, Component Testing can be utilized by referencing the Component Testing section below.
Component Testing
To use Cypress Component Testing add component: true
name: Component tests
on: push
jobs:
cypress-run:
runs-on: ubuntu-26.04
steps:
- name: Checkout
uses: actions/checkout@v7
- name: Cypress run
uses: cypress-io/github-action@v7
with:
component: true
See the example project component-tests and the example-component-test.yml workflow for more details.
Action version
Best practice:
Our examples specify using branch v7 which is the action’s recommended major version:
- name: Cypress run
uses: cypress-io/github-action@v7
When using cypress-io/github-action@v7 from your workflow file, you will automatically use the latest tag from branch v7.
Alternatively, to mitigate unforeseen breaks, bind to a specific tag, for example:
- name: Cypress run
uses: cypress-io/[email protected]
The changes associated with each tag are shown under GitHub’s releases list. Refer also to the CHANGELOG for an overview of major changes.
The workflows in the examples directory use the latest commit from the repo’s current branch. This allows all tests to run in CI before release. If you copy any of the examples to your own repo, you should replace ./ and specify instead the action and version as described above.
- uses: ./ # replace with cypress-io/github-action@v7
Browser
Specify the browser name or path with the browser parameter.
The default browser can be set as a Browser configuration option defaultBrowser.
If no browser parameter is specified and defaultBrowser is also undefined,
the built-in Electron browser is used.
[email protected] deprecated the Electron browser and describes the plan to remove it in a future major version of Cypress.
Each of the examples directories in this repo sets defaultBrowser to chrome.
Chrome
name: Chrome
on: push
jobs:
chrome:
runs-on: ubuntu-26.04
name: E2E on Chrome
steps:
- uses: actions/checkout@v7
- uses: cypress-io/github-action@v7
with:
browser: chrome
Chrome for Testing
To install Google Chrome for Testing
use browser-actions/setup-chrome.
Refer to Chrome for Testing availability for current versions
or JSON API endpoints
for all available versions.
name: Chrome for Testing
on: push
jobs:
chrome:
runs-on: ubuntu-26.04
name: E2E on Chrome for Testing
steps:
- uses: actions/checkout@v7
- uses: browser-actions/setup-chrome@v2
- uses: cypress-io/github-action@v7
with:
browser: chrome-for-testing
Firefox
name: Firefox
on: push
jobs:
firefox:
runs-on: ubuntu-26.04
name: E2E on Firefox
steps:
- uses: actions/checkout@v7
- uses: cypress-io/github-action@v7
with:
browser: firefox
Edge
name: Edge
on: push
jobs:
edge:
runs-on: ubuntu-26.04
name: E2E on Edge
steps:
- uses: actions/checkout@v7
- uses: cypress-io/github-action@v7
with:
browser: edge
Headed
Run the browser in headed mode - as of Cypress v8.0 the cypress run command executes tests in headless mode by default
name: Chrome headed
on: push
jobs:
cypress-run:
runs-on: ubuntu-26.04
steps:
- uses: actions/checkout@v7
- uses: cypress-io/github-action@v7
with:
browser: chrome
headed: true
Docker image
You can run the action in a Docker container.
name: Test in Docker
on: push
jobs:
cypress-run:
runs-on: ubuntu-26.04
# Cypress Docker image from https://hub.docker.com/r/cypress
# with browsers pre-installed
container:
image: cypress/browsers:latest
options: --user 1001
steps:
- uses: actions/checkout@v7
- uses: cypress-io/github-action@v7
with:
browser: chrome
Replace the latest tag with a specific version image tag from cypress/browsers on Docker Hub to avoid breaking changes when new images are released (especially when they include new major versions of Node.js).
Include options: --user 1001 to avoid permissions issues.
When using cypress/included Docker images, set the environment variable CYPRESS_INSTALL_BINARY=0 to suppress saving the Cypress binary cache, otherwise cache restore errors may occur. The example below shows how to do this:
name: Test with Docker cypress/included
on: push
jobs:
cypress-run:
runs-on: ubuntu-26.04
container:
# Cypress Docker image from https://hub.docker.com/r/cypress/included
# with Cypress globally pre-installed
image: cypress/included:latest
options: --user 1001
steps:
- uses: actions/checkout@v7
- uses: cypress-io/github-action@v7
with:
browser: chrome
env:
CYPRESS_INSTALL_BINARY: 0
Refer to cypress-io/cypress-docker-images for further information about using Cypress Docker images. Cypress offers the Cypress Docker Factory to generate additional Docker images with selected components and versions.
Env
To pass an environment variable to Cypress <15.10.0 use the action’s env parameter.
In Cypress 15.10.0 and above, the env is specified for use with secret environment variables.
It is replaced with the expose action parameter for public, non-sensitive environment variables.
name: Cypress tests
on: push
jobs:
cypress-run:
runs-on: ubuntu-26.04
steps:
- name: Checkout
uses: actions/checkout@v7
- name: Cypress run with env
uses: cypress-io/github-action@v7
with:
env: host=api.dev.local,port=4222
When passing the environment variables this way, unfortunately due to GitHub Actions syntax, the variables should be listed in a single line, which can be hard to read. As an alternative, you can use the step’s env block where every variable can be set on its own line. In this case, you should prefix every variable with CYPRESS_ because such variables are loaded by Cypress automatically. The above code example is equivalent to:
name: Cypress tests
on: push
jobs:
cypress-run:
runs-on: ubuntu-26.04
steps:
- name: Checkout
uses: actions/checkout@v7
- name: Cypress run with env
uses: cypress-io/github-action@v7
env:
CYPRESS_host: api.dev.local
CYPRESS_port: 4222
For more examples, see the workflows below, using environment variables for recording.
Expose
Specify the expose argument with expose parameter. Expose variables are for non-sensitive, public config values that are synchronous and exposed to the browser (requires Cypress 15.10.0 or later).
name: Cypress tests
on: push
jobs:
cypress-run:
runs-on: ubuntu-26.04
steps:
- name: Checkout
uses: actions/checkout@v7
- name: Cypress run with expose
uses: cypress-io/github-action@v7
with:
expose: host=api.dev.local,port=4222
For more information, see Cypress.expose() in the Cypress documentation.
Specs
Specify the
spec files to run
with spec parameter
name: Cypress tests
on: push
jobs:
cypress-run:
name: Cypress run
runs-on: ubuntu-26.04
steps:
- name: Checkout
uses: actions/checkout@v7
- name: Cypress run
uses: cypress-io/github-action@v7
with:
spec: cypress/e2e/spec1.cy.js
You can pass multiple specs and wild card patterns using multi-line parameter, see example-config.yml:
spec: |
cypress/e2e/spec-a.cy.js
cypress/**/*-b.cy.js
For more information, visit the Cypress command-line docs.
Project
Specify the project to run with the project parameter
name: Cypress tests
on: push
jobs:
cypress-run:
name: Cypress run
runs-on: ubuntu-26.04
steps:
- name: Checkout
uses: actions/checkout@v7
- name: Cypress run
uses: cypress-io/github-action@v7
with:
project: ./test-subdirectory
The project parameter may be used to pass on the location of a sub-directory containing a Cypress configuration file and Cypress tests specs. For more information, visit the Cypress command-line docs.
A package manager lock file, including Cypress, must be provided in the root of the repository so that the action is able to install Cypress.
If the parameter working-directory is also defined, then this is the location to place the package manager lock file, and the project directory would be a subdirectory of the working-directory. The project parameter location may not be above the level of a specified working-directory in the file hierarchy.
Record test results on Cypress Cloud
By setting the parameter record to true, you can record your test results into Cypress Cloud. Read the Cypress Cloud setup documentation to learn how to sign up to Cypress Cloud, to create and set up a Cloud project to get the required projectId and record key for recording.
-
The projectId can either be stored in the Cypress Configuration File or passed to the action as an environment variable CYPRESS_PROJECT_ID. In the example below, it is retrieved from a GitHub secret variable.
-
The record key is passed to the action as an environment variable CYPRESS_RECORD_KEY. We recommend you treat this value as sensitive and store it as a GitHub secret variable, so that access is restricted.
-
We recommend passing the GITHUB_TOKEN secret (created by the GH Action automatically) as an environment variable. This will allow correctly identifying every build and avoid confusion when re-running a build.
name: Cypress tests
on: push
jobs:
cypress-run:
name: Cypress run
runs-on: ubuntu-26.04
steps:
- name: Checkout
uses: actions/checkout@v7
- name: Cypress run
uses: cypress-io/github-action@v7
with:
record: true
env:
# pass the Cypress Cloud project ID as an environment variable or store it in the Cypress configuration file
CYPRESS_PROJECT_ID: ${{ secrets.EXAMPLE_PROJECT_ID }}
# pass the Cypress Cloud record key as an environment variable
CYPRESS_RECORD_KEY: ${{ secrets.EXAMPLE_RECORDING_KEY }}
# pass GitHub token to allow accurately detecting a build vs a re-run build
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
Cypress uses the @cypress/commit-info package to associate Git details (branch, commit message, author) with each run. It typically uses Git commands, expecting a .git folder. In Docker or similar environments where .git is absent, or if you need different data in the Cypress Cloud, Git information can be passed via custom environment variables.
name: Cypress tests
on: push
jobs:
cypress-run:
name: Cypress run
runs-on: ubuntu-26.04
steps:
- name: Checkout
uses: actions/checkout@v7
- name: Cypress run
uses: cypress-io/github-action@v7
with:
record: true
env:
# Get the short ref name of the branch that triggered the workflow run
COMMIT_INFO_BRANCH: ${{ github.ref_name }}
CYPRESS_RECORD_KEY: ${{ secrets.EXAMPLE_RECORDING_KEY }}
Please refer to the Cypress Cloud Git information environment variables section in our documentation for more examples.
Please refer to the default GitHub environment variables for additional GitHub examples.
Automatic PR number and URL detection
When recording runs to Cypress Cloud, the PR number and URL can be automatically detected if you pass GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
via the workflow env. When set, this value enables the Action to perform additional logic that grabs the related PR number and URL (if they
exist) and sets them in the environment variables CYPRESS_PULL_REQUEST_ID and CYPRESS_PULL_REQUEST_URL, respectively.
Example workflow using the variables:
name: Example echo PR number and URL
on: push
jobs:
cypress-run:
runs-on: ubuntu-26.04
steps:
- name: Checkout
uses: actions/checkout@v7
- name: Cypress run
uses: cypress-io/github-action@v7
with:
record: true
- run: echo "PR number is $CYPRESS_PULL_REQUEST_ID"
- run: echo "PR URL is $CYPRESS_PULL_REQUEST_URL"
env:
CYPRESS_RECORD_KEY: ${{ secrets.EXAMPLE_RECORDING_KEY }}
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
Triggering event: pull_request/pull_request_target
For either of these events, we set CYPRESS_PULL_REQUEST_ID and CYPRESS_PULL_REQUEST_URL to that of the PR number and URL, respectively, of the
PR that triggered the workflow.
Triggering event: push
When a commit on a branch without a PR is made, the Cypress GitHub Action checks to see if the commit that triggered the workflow has a
related PR. If the commit exists in any other PRs, it’s considered a related PR. When there are related PRs, we grab the first related PR
and use that PR’s number and URL for CYPRESS_PULL_REQUEST_ID and CYPRESS_PULL_REQUEST_URL, respectively.
If no related PR is detected, CYPRESS_PULL_REQUEST_ID and CYPRESS_PULL_REQUEST_URL will be undefined.
Merge SHA into SHA
We recommend using the action with on: push rather than on: pull_request or on: merge_group for more accurate commit information in Cypress Cloud. When running on pull_request or merge_group, the commit message defaults to “merge SHA into SHA”. You can overwrite the commit message sent to Cypress Cloud by setting an environment variable.
name: Cypress tests
on: push
jobs:
cypress-run:
name: Cypress run
runs-on: ubuntu-26.04
steps:
- name: Checkout
uses: actions/checkout@v7
- name: Cypress run
uses: cypress-io/github-action@v7
with:
record: true
env:
# overwrite commit message sent to Cypress Cloud
COMMIT_INFO_MESSAGE: ${{github.event.pull_request.title}}
# re-enable PR comment bot
COMMIT_INFO_SHA: ${{github.event.pull_request.head.sha}}
CYPRESS_RECORD_KEY: ${{ secrets.EXAMPLE_RECORDING_KEY }}
See issue 124 for details.
Tag recordings
You can pass a single or multiple tags when recording a run. For example
name: tags
on: push
jobs:
cypress-run:
runs-on: ubuntu-26.04
# let's make sure our "app" works on several versions of Node
strategy:
matrix:
node:
- 22
- 24
- 26
name: E2E on Node v${{ matrix.node }}
steps:
- name: Checkout
uses: actions/checkout@v7
- name: Install Node.js
uses: actions/setup-node@v7
with:
node-version: ${{ matrix.node }}
- run: node -v
- name: Cypress run
uses: cypress-io/github-action@v7
with:
record: true
tag: node-${{ matrix.node }}
env:
CYPRESS_RECORD_KEY: ${{ secrets.EXAMPLE_RECORDING_KEY }}
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
The recording will have tags as labels on the run.
You can pass multiple tags using commas like tag: node-22,nightly,staging.
Auto cancel after failures
Specify the number of failed tests that will cancel a run when using the Cypress Cloud Auto Cancellation feature.
This feature requires Cypress 12.6.0 or later and a Cypress Cloud Business or Enterprise account.
name: Cypress E2E Tests
on: push
jobs:
cypress-run:
runs-on: ubuntu-26.04
name: E2E
steps:
- name: Checkout
uses: actions/checkout@v7
- name: Cypress run
uses: cypress-io/github-action@v7
with:
record: true
# Cancel the run after 2 failed tests
auto-cancel-after-failures: 2
env:
CYPRESS_RECORD_KEY: ${{ secrets.EXAMPLE_RECORDING_KEY }}
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
See Auto Cancellation for more information.
Artifacts
If you don’t record the test run on Cypress Cloud, you can still store generated videos and screenshots as CI artifacts. See the workflow example below.
name: Artifacts
on: push
jobs:
cypress-run:
runs-on: ubuntu-26.04
name: Artifacts
steps:
- uses: actions/checkout@v7
- uses: cypress-io/github-action@v7
# after the test run completes store videos and any screenshots
- uses: actions/upload-artifact@v7
# add the line below to store screenshots only on failures
# if: failure()
with:
name: cypress-screenshots
path: cypress/screenshots
if-no-files-found: ignore # 'warn' or 'error' are also available, defaults to `warn`
- uses: actions/upload-artifact@v7
with:
name: cypress-videos
path: cypress/videos
if-no-files-found: ignore # 'warn' or 'error' are also available, defaults to `warn`
Quiet flag
You can provide quiet flag for cypress run to silence any Cypress specific output from stdout
name: example-quiet
on: push
jobs:
cypress-run:
runs-on: ubuntu-26.04
steps:
- name: Checkout
uses: actions/checkout@v7
# Install dependencies with caching
# and run all Cypress tests with `quiet` parameter
- name: Cypress run
uses: cypress-io/github-action@v7
with:
working-directory: examples/quiet
quiet: true
Config
Specify configuration values with config parameter
name: Cypress tests
on: push
jobs:
cypress-run:
name: Cypress run
runs-on: ubuntu-26.04
steps:
- name: Checkout
uses: actions/checkout@v7
- name: Cypress run
uses: cypress-io/github-action@v7
with:
config: pageLoadTimeout=100000,baseUrl=http://localhost:3000
Config File
Specify the path to your Configuration File with config-file parameter
name: Cypress tests
on: push
jobs:
cypress-run:
name: Cypress run
runs-on: ubuntu-26.04
steps:
- name: Checkout
uses: actions/checkout@v7
- name: Cypress run
uses: cypress-io/github-action@v7
with:
config-file: cypress.config-alternate.js
Parallel
Note: Cypress parallelization requires a Cypress Cloud account.
You can spin multiple jobs running in parallel using the strategy: matrix argument.
Just add more dummy items to the recording-job: [1, 2, ...] array to create multiple job runs.
Then use record and parallel parameters to load balance tests.
name: Parallel Cypress Tests
on: push
jobs:
test:
name: Cypress run
runs-on: ubuntu-26.04
strategy:
# when one test fails, DO NOT cancel the other
# containers, because this will kill Cypress processes
# leaving Cypress Cloud hanging ...
# https://github.com/cypress-io/github-action/issues/48
fail-fast: false
matrix:
# run 3 copies of the current job in parallel
recording-job: [1, 2, 3]
container:
image: cypress/browsers:latest
options: --user 1001
steps:
- name: Checkout
uses: actions/checkout@v7
# because of "record" and "parallel" parameters
# these jobs will load balance all found tests among themselves
- name: Cypress run
uses: cypress-io/github-action@v7
with:
record: true
parallel: true
group: 'Actions example'
env:
# pass the Cypress Cloud record key as an environment variable
CYPRESS_RECORD_KEY: ${{ secrets.EXAMPLE_RECORDING_KEY }}
# Recommended: passing the GitHub token lets this action correctly
# determine the unique run id necessary to re-run the checks
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
The Cypress GitHub Action does not spawn or create any additional jobs -
it only links the multiple jobs spawned using the matrix strategy into a single logical Cypress Cloud run
where it splits the specs amongst the machines.
See the Cypress Cloud Smart Orchestration guide
for a detailed explanation.
If you use the GitHub Actions facility for Re-running workflows and jobs, note that Re-running failed jobs in a workflow is not suited for use with parallel recording into Cypress Cloud. Re-running failed jobs in this situation does not simply re-run failed Cypress tests. Instead it re-runs all Cypress tests, load-balanced over the containers with failed jobs.
To optimize runs when there are failing tests present, refer to optional Cypress Cloud Smart Orchestration Premium features:
During staged rollout of a new GitHub-hosted runner image version,
GitHub may provide a mixture of current and new image versions used by the job matrix.
When running parallel jobs under GitHub-hosted Ubuntu runner images,
it is recommended to use a Docker image
to avoid any Cypress Cloud errors due to browser major version mismatch between the current and new image versions.
Avoid using parallel jobs with GitHub-hosted macOS or Windows runner images,
since there is currently no workaround for the deployment mismatch issue.
On macOS the problem can also occur when there is an upgrade to the macOS version.
Component and E2E Testing
Component Testing and End-to-End (E2E) Testing types can be combined in the same job using separate steps
- name: Run E2E tests
uses: cypress-io/github-action@v7
- name: Run Component Testing
uses: cypress-io/github-action@v7
with:
# we have already installed everything
install: false
component: true
See the example project component-test and the example-component-test.yml workflow for more details.
Build app
You can run a build step before starting tests
name: Build
on: push
jobs:
cypress-run:
runs-on: ubuntu-26.04
steps:
- name: Checkout
uses: actions/checkout@v7
- name: Cypress run
uses: cypress-io/github-action@v7
with:
build: npm run build
Start server
If your tests run against a local server, use the start parameter to start your server. The server will run in the background.
name: With server
on: push
jobs:
cypress-run:
runs-on: ubuntu-26.04
steps:
- name: Checkout
uses: actions/checkout@v7
- name: Cypress run
uses: cypress-io/github-action@v7
with:
start: npm start
Caution: use the start parameter only to start a server, not to run Cypress, otherwise tests may be run twice. The action runs Cypress tests by default, unless the parameter runTests is set to false.
Note: sometimes on Windows you need to run a different start command. You can use the start-windows parameter for this.
name: With server
on: push
jobs:
cypress-run:
runs-on: ubuntu-26.04
steps:
- name: Checkout
uses: actions/checkout@v7
- name: Cypress run
uses: cypress-io/github-action@v7
with:
# Linux and macOS
start: npm start
# Takes precedences on Windows
start-windows: npm run start:windows:server
Note: A server continues to run until the end of the GitHub workflow job that started it. At the end of the job the GitHub workflow runner executes a “Complete job” phase automatically where it terminates any server processes which are still running.
Start multiple servers
You can start multiple server processes. For example, if you have an API to start using npm run api and the web server to start using npm run web you can put those commands in start using comma separation.
name: With servers
on: push
jobs:
cypress-run:
runs-on: ubuntu-26.04
steps:
- name: Checkout
uses: actions/checkout@v7
- name: Cypress run
uses: cypress-io/github-action@v7
with:
start: npm run api, npm run web
You can place the start commands in separate lines
with:
start: |
npm run api
npm run web
Wait-on
If you are starting a local server and it takes a while to start, you can add a parameter wait-on and pass url to wait for the server to respond.
name: After server responds
on: push
jobs:
cypress-run:
runs-on: ubuntu-26.04
steps:
- name: Checkout
uses: actions/checkout@v7
- name: Cypress run
uses: cypress-io/github-action@v7
with:
start: npm start
# quote the url to be safe against YML parsing surprises
wait-on: 'http://localhost:8080'
(also uses wait-on)
By default, wait-on will retry for 60 seconds. You can pass a custom timeout in seconds using wait-on-timeout.
- uses: cypress-io/github-action@v7
with:
start: npm start
wait-on: 'http://localhost:8080/status'
# wait for 2 minutes for the server to respond
wait-on-timeout: 120
You can wait for multiple URLs to respond by separating urls with a comma
- uses: cypress-io/github-action@v7
with:
# API runs on port 3050
# Web server runs on port 8080
start: npm run api, npm run web
# wait for all services to respond
wait-on: 'http://localhost:3050, http://localhost:8080'
The action will wait for the first url to respond, then will check the second url, and so on.
You can even use your own command (usually by using npm, yarn, npx) to wait for the server to respond. For example, if you want to use the wait-on utility to ping the server and run the Cypress tests after the server responds:
- uses: cypress-io/github-action@v7
with:
start: npm start
wait-on: 'npx wait-on --timeout 60000 http://localhost:3000'
See example-wait-on.yml workflow file.
If this action times out waiting for the server to respond, please see Debugging section in this README file.
Custom install command
The action installs dependencies based on a package manager lock file using default commands described in the Installation section below. If you want to overwrite the default install command you can use the install-command option:
- uses: cypress-io/github-action@v7
with:
install-command: yarn --frozen-lockfile --silent
See example-install-command.yml workflow file.
If you do not commit a lock file to the repository, you cannot use the action to install dependencies. In this case you must ensure that dependencies are installed before using the action, and you must use the action option setting install: false.
Command prefix
You can prefix a test command using the command-prefix parameter. This is useful, for example, when running BrowserStack Percy, which requires the test command to be prefixed with percy exec --. When this parameter is used, the action constructs and executes a CLI command using npx in the following form:
npx <command-prefix> cypress run <cli run options>
where the <command-prefix> is the literal string value from the command-prefix parameter and <cli run options> are put together from action parameters such as the value of the browser parameter. The complete constructed command is shown in the logs. For the example below, this is shown as:
Cypress test command: npx percy exec -- npx cypress run --browser chrome
Since command-prefix is run using npx, it is compatible with npm and Yarn Classic. It may also be used with pnpm and Yarn Modern when they are configured for nodeLinker compatibility with the node_modules directory structure of npm. An alternative to using command-prefix is to pass a complete command parameter instead, including the exact command to be passed to the CLI.
name: Visual
on: push
jobs:
e2e:
runs-on: ubuntu-26.04
steps:
- name: Checkout
uses: actions/checkout@v7
- name: Cypress run
uses: cypress-io/github-action@v7
with:
command-prefix: 'percy exec -- npx'
browser: chrome
If command-prefix is used, then no job summary is produced, since it runs Cypress with a CLI cypress run command instead of using the Cypress Module API. The command parameter overrides the command-prefix parameter, preventing these two parameters from being used together.
Custom test command
The command parameter executes a CLI command using the GitHub @actions/exec action.
This parameter is useful for special test cases, for example:
If you don’t have a special case and you just need to convert a cypress run CLI command to use the Cypress GitHub Action, refer to the section Migrating from CLI command which explains how to map CLI options to equivalent action parameters, avoiding the need for the command parameter in most cases.
There are some parameters that cannot be used together with the command parameter, and these are ignored. The parameters include action input parameters listed in the table CLI Run Option / Action Parameter, the publish-summary, summary-title and command-prefix. If any such parameters are passed to the action, a warning message appears in the logs that the parameters have been ignored.
Correct example snippet:
steps:
- uses: actions/checkout@v7
- uses: cypress-io/github-action@v7
with:
command: npm run custom-test
Custom build id
You can overwrite ci-build-id used to link separate machines running tests into a single parallel run.
name: Parallel
on: push
jobs:
test:
runs-on: ubuntu-26.04
strategy:
matrix:
# run 3 copies of the current job in parallel
recording-job: [1, 2, 3]
container:
image: cypress/browsers:latest
options: --user 1001
steps:
- uses: actions/checkout@v7
- uses: cypress-io/github-action@v7
with:
record: true
parallel: true
group: 'Actions example'
ci-build-id: '${{ github.sha }}-${{ github.workflow }}-${{ github.event_name }}'
env:
# pass the Cypress Cloud record key as an environment variable
CYPRESS_RECORD_KEY: ${{ secrets.EXAMPLE_RECORDING_KEY }}
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
Tip: see Learn GitHub Actions, with sections on Expressions, Contexts and Environment variables.
Robust custom build id
If you re-run the GitHub workflow, if you use the same custom build id during recording, Cypress Cloud will cancel the run with “Build already finished” error. To avoid this, you need to generate a new custom build id on every workflow re-run. A good solution showing in the example-custom-ci-build-id.yml file is to run a common job first that just generates a new random ID. This ID can be used by the testing jobs to tie the build together. If the user re-runs the workflow a new unique build id is generated, allowing recording the new Cypress Cloud run.
jobs:
# single job that generates and outputs a common id
prepare:
outputs:
uuid: ${{ steps.uuid.outputs.value }}
steps:
- name: Generate unique ID 💎
id: uuid
# take the current commit + timestamp together
# the typical value would be something like
# "sha-5d3fe...35d3-time-1620841214"
run: echo "value=sha-$GITHUB_SHA-time-$(date +"%s")" >> $GITHUB_OUTPUT
smoke-tests:
needs: ['prepare']
container:
image: cypress/browsers:latest
options: --user 1001
steps:
- uses: actions/checkout@v7
- uses: cypress-io/github-action@v7
with:
record: true
parallel: true
ci-build-id: ${{ needs.prepare.outputs.uuid }}
env:
# pass the Cypress Cloud record key as an environment variable
CYPRESS_RECORD_KEY: ${{ secrets.EXAMPLE_RECORDING_KEY }}
See the example-custom-ci-build-id.yml for the full workflow.
Working directory
In a monorepo, the end-to-end or component test might be placed in a different sub-folder from the application itself. This sub-folder is the Cypress “working directory” which you can specify using the working-directory parameter.
In the following example of a directory layout for end-to-end testing, the Cypress working directory is app-test. The working directory contains the Cypress tests and a package manager lock file:
repo/
app/
app-test/
cypress/
e2e/
fixtures/
support/
cypress.config.js
package.json
package-lock.json
We use working-directory: app-test to match the above example directory structure:
on: push
jobs:
cypress-run:
runs-on: ubuntu-26.04
steps:
- uses: actions/checkout@v7
- uses: cypress-io/github-action@v7
with:
start: npm start
working-directory: app-test
See the Cypress documentation Folder structure section for examples of standard directory layouts, covering end-to-end testing and component testing with both JavaScript and TypeScript options.
Each of the examples in this monorepo is separated from other examples by using different working directories. See example-basic.yml for one end-to-end test example using the parameter working-directory and example-component-test.yml for a component test example.
Subfolders
Sometimes the application under test and the Cypress end-to-end tests may have separately defined dependencies. In the example below, Cypress has its own package.json file in a subfolder:
root/
e2e/
(code for installing and running Cypress tests)
package.json
package-lock.json
cypress.config.js
cypress/
(code for running the "app" with "npm start")
package.json
package-lock.json
In this case you can first install the dependencies for the application (npm ci), then start the application server (npm start) before calling cypress-io/github-action to install the dependencies for Cypress and to run Cypress. You may also need to use the wait-on parameter to make sure that the app server is fully available.
name: E2E
on: push
jobs:
test:
runs-on: ubuntu-26.04
steps:
- uses: actions/checkout@v7
- name: Install root dependencies
run: npm ci
- name: Start server in the background
run: npm start &
# Cypress has its own package.json in folder "e2e"
- name: Install Cypress and run tests
uses: cypress-io/github-action@v7
with:
working-directory: e2e
pnpm
The package manager pnpm is not pre-installed in GitHub Actions runner images
(unlike npm and Yarn Classic) and so it must be installed in a separate workflow step (see below).
If the action finds a pnpm-lock.yaml file, it uses the pnpm command pnpm install --frozen-lockfile by default to install dependencies.
The example below follows pnpm recommendations for installing pnpm and caching the
pnpm store.
Follow the Cypress pnpm configuration instructions
and apply them to your project, to enable pnpm to install the Cypress binary.
name: example-basic-pnpm
on: push
jobs:
basic-pnpm:
runs-on: ubuntu-26.04
steps:
- name: Checkout
uses: actions/checkout@v7
- name: Install pnpm
uses: pnpm/action-setup@v6
with:
version: 12
- name: Install Node.js
uses: actions/setup-node@v7
with:
node-version: 24
cache: 'pnpm'
cache-dependency-path: examples/basic-pnpm/pnpm-lock.yaml
- name: Cypress run
uses: cypress-io/github-action@v7
with:
package-manager-cache: false
working-directory: examples/basic-pnpm
pnpm workspaces
The action does not directly support using pnpm workspaces
(see feature request #1144).
As a workaround, you can install dependencies and run Cypress tests in a workspace in separate steps.
The snippet below shows this principle.
...
- name: Install dependencies
uses: cypress-io/github-action@v7
with:
package-manager-cache: false
runTests: false
working-directory: examples/start-and-pnpm-workspaces
- name: Cypress test
uses: cypress-io/github-action@v7
with:
install: false
working-directory: examples/start-and-pnpm-workspaces/packages/workspace-1
...
See the example project start-and-pnpm-workspaces and the example-start-and-pnpm-workspaces.yml workflow for a full working example.
Yarn Classic
If a yarn.lock file is found, the action uses the Yarn 1 (Classic) command yarn --frozen-lockfile by default to install dependencies.
name: example-yarn-classic
on: push
jobs:
yarn-classic:
runs-on: ubuntu-26.04
steps:
- name: Checkout
uses: actions/checkout@v7
- name: Cypress run
uses: cypress-io/github-action@v7
with:
working-directory: examples/yarn-classic
Yarn Modern
To install dependencies using a yarn.lock file from Yarn Modern (Yarn 2 and later) you need to override the default Yarn 1 (Classic) installation command yarn --frozen-lockfile. You can do this by using the install-command parameter and specifying yarn install as in the example below.
The action supports built-in caching of Yarn Classic dependencies only. To cache Yarn Modern dependencies additionally use actions/setup-node and specify cache: yarn.
name: example-yarn-modern
on: push
jobs:
yarn-modern:
runs-on: ubuntu-26.04
steps:
- name: Checkout
uses: actions/checkout@v7
- run: corepack enable # (experimental and optional)
- name: Set up Yarn cache
uses: actions/setup-node@v7
with:
node-version: 24
cache: yarn
cache-dependency-path: examples/yarn-modern/yarn.lock
- name: Cypress run
uses: cypress-io/github-action@v7
with:
working-directory: examples/yarn-modern
install-command: yarn install
This example covers the .yarnrc.yml configuration nodeLinker: node-modules which Yarn uses by default for projects updated from Yarn Classic. For nodeLinker: pnp see Yarn Plug’n’Play below.
(Note that github-action is not compatible with the nodeLinker: pnpm setting.)
Yarn Plug’n’Play
When using Yarn Modern (Yarn 2 and later) with Plug’n’Play enabled, you will need to use the command parameter to run yarn instead of npx.
See the above Yarn Modern section for information on caching Yarn Modern dependencies.
name: example-yarn-modern-pnp
on: push
jobs:
yarn-classic:
runs-on: ubuntu-26.04
steps:
- name: Checkout
uses: actions/checkout@v7
- name: Cypress run
uses: cypress-io/github-action@v7
with:
working-directory: examples/yarn-modern-pnp
install-command: yarn install
command: yarn run --binaries-only cypress run
This example covers the .yarnrc.yml configuration when nodeLinker is undefined or set to nodeLinker: pnp corresponding to Yarn Plug’n’Play. Yarn uses this by default for projects newly created with Yarn Modern.
Caution: using the action parameter command causes multiple other parameters to be ignored. See command section for more information.
Yarn workspaces
This action should discover the Yarn workspaces correctly. For example, see folder examples/start-and-yarn-workspaces and workflow file example-start-and-yarn-workspaces.yml
name: example-start-and-yarn-workspaces
on: push
jobs:
single:
# the example has Yarn workspace in its "root" folder
# examples/start-and-yarn-workspaces
# and tests in a subfolder like "workspace-1"
runs-on: ubuntu-26.04
steps:
- uses: actions/checkout@v7
- uses: cypress-io/github-action@v7
with:
working-directory: examples/start-and-yarn-workspaces/workspace-1
build: yarn run build
start: yarn start
wait-on: 'http://localhost:5000'
Package manager cache disable
When the action installs dependencies,
it caches the package manager cache from npm or from Yarn 1 (Classic) by default,
based on the lockfile it discovers.
If package manager caching is implemented separately from the action,
for example to work with Yarn Modern or pnpm,
then disable the actions’ package manager caching by setting the parameter
package-manager-cache to false.
GitHub’s actions/setup-node offers a convenient way to install a chosen version of Node.js
and to set up caching of package manager caches in one step.
name: Package manager caching
on: push
jobs:
cypress-run:
runs-on: ubuntu-26.04
name:
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
with:
node-version: lts
cache: 'pnpm'
cache-dependency-path: pnpm-lock.yaml
- uses: cypress-io/github-action@v7
with:
package-manager-cache: false
Custom cache key
Sometimes the default cache key does not work. For example, if you cannot share the Node modules across Node versions due to native extensions. In that case pass your own cache-key parameter.
name: End-to-end tests
on: push
jobs:
cypress-run:
runs-on: ubuntu-26.04
# let's make sure our "app" works on several versions of Node
strategy:
matrix:
node:
- 22
- 24
- 26
name: E2E on Node v${{ matrix.node }}
steps:
- name: Checkout
uses: actions/checkout@v7
- name: Install Node.js
uses: actions/setup-node@v7
with:
node-version: ${{ matrix.node }}
# run Cypress tests and record them under the same run
# associated with commit SHA and just give a different group name
- name: Cypress run
uses: cypress-io/github-action@v7
with:
record: true
group: Tests on Node v${{ matrix.node }}
cache-key: node-v${{ matrix.node }}-on-${{ runner.os }}-hash-${{ hashFiles('yarn.lock') }}
env:
CYPRESS_RECORD_KEY: ${</cli></command-prefix></cli></command-prefix>
> README 内容过长，已截取前 64 KB。完整内容请前往 GitHub 仓库查看。
![renovate[bot]](https://avatars.githubusercontent.com/in/2740?v=4)
评论