GitHub Actions
What you'll learn​
- How to run Cypress tests with GitHub Actions as part of a CI/CD pipeline
- How to parallelize Cypress test runs within GitHub Actions
- How to cache build artifacts between installation jobs and worker jobs
GitHub offers developers Actions that provide a way to automate, customize, and execute your software development workflows within your GitHub repository. Detailed documentation is available in the GitHub Action Documentation.
Cypress GitHub Action​
Workflows can be packaged and shared as GitHub Actions. GitHub maintains many, such as the checkout and Upload/Download Artifact Actions actions used below.
The official Cypress GitHub Action is maintained by Cypress and our community to help ease the setup of Cypress in a GitHub Action. The action provides dependency installation (via npm, yarn, or pnpm), built-in caching of Node dependencies, and additional configuration options for advanced workflows.
Version Number Selection​
We recommend binding to the action's latest major version by specifying v6
when using the action.
For Example:
jobs:
cypress-run:
steps:
- uses: cypress-io/github-action@v6
Alternatively, as a mitigation strategy for unforeseen breaks, bind to a
specific
release version tag, for
example cypress-io/[email protected]
. Read the
Cypress GitHub Action documentation
for more information.
Basic Setup​
The example below is a basic CI setup and job using the
Cypress GitHub Action to
run Cypress tests within the Electron browser. This GitHub Action configuration
is placed within .github/workflows/main.yml
.
name: Cypress Tests
on: push
jobs:
cypress-run:
runs-on: ubuntu-22.04
steps:
- name: Checkout
uses: actions/checkout@v4
# Install npm dependencies, cache them correctly
# and run all Cypress tests
- name: Cypress run
uses: cypress-io/github-action@v6
with:
build: npm run build
start: npm start
To try out the example above yourself, fork the
Cypress Kitchen Sink
example project and place the above GitHub Action configuration in a newly
created main.yml
file within .github/workflows/
.
How this action works:
- On push to this repository, this job will provision and start a
GitHub-hosted Ubuntu Linux instance to run the outlined
steps
for the declaredcypress-run
job within thejobs
section of the configuration. - The GitHub checkout Action is used to check out our code from our GitHub repository.
- Finally, our Cypress GitHub Action will:
- Install npm dependencies
- Build the project (
npm run build
) - Start the project web server (
npm start
) - Run the Cypress tests within our GitHub repository within Electron.
Testing on GitHub with Installed Browsers​
GitHub-hosted runners offer images
with pre-installed browsers to use for testing. The ubuntu
and windows
runners each include Google Chrome, Mozilla Firefox, and Microsoft Edge
pre-installed. The macos
runners additionally include Apple Safari. Refer to
GitHub Actions Runner Images
for current details.
Use the action's browser
parameter to select the desired browser. To change
the above example to select Chrome instead of the default browser Electron, add
browser: chrome
as follows.
- name: Cypress run
uses: cypress-io/github-action@v6
with:
build: npm run build
start: npm start
browser: chrome
For more examples, see the action's Browser section.
If you are specifying a browser in a parallel job, see Specifying Browsers in Parallel Builds for more info on how to avoid errors during runs due to GitHub runner images being updated with the latest browsers.
Testing with Cypress Docker Images​
GitHub Actions provides the option to specify a container image for the job. Cypress offers various Docker Images for running Cypress locally and in CI.
Below we extend the previous example by adding the container
attribute using a
Cypress Docker Image
built with the version of Google Chrome embedded in the tag name of the Docker image
shown as chrome-xxx
.
Specifying a browser version allows our tests to
execute without any influence from browser version changes in the GitHub runner
image.
name: Cypress Tests using Cypress Docker Image
on: push
jobs:
cypress-run:
runs-on: ubuntu-22.04
container:
image: cypress/browsers:node-20.9.0-chrome-118.0.5993.88-1-ff-118.0.2-edge-118.0.2088.46-1
options: --user 1001
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Cypress run
uses: cypress-io/github-action@v6
with:
build: npm run build
start: npm start
browser: chrome
If you are testing with Firefox, you must specify the non-root user 1001
as above. Refer to Firefox not found for more information.
Caching Dependencies and Build Artifacts​
When working with actions that have multiple jobs, it is recommended to have an initial "install" job that will download any dependencies and build your app, and then cache these assets for use later by subsequent jobs.
The Cypress GitHub Action will automatically cache and restore your Node dependencies for you.
For build assets, you will need to cache and restore them manually.
The install
job below uses the
upload-artifact
action and saves the state of the build
directory for the cypress-run
worker
job.
The
download-artifact
action retrieves the build
directory saved in the install
job, as seen below
in the cypress-run
worker job.
name: Cypress Tests with Dependency and Artifact Caching
on: push
jobs:
install:
runs-on: ubuntu-22.04
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Cypress install
uses: cypress-io/github-action@v6
with:
# Disable running of tests within install job
runTests: false
build: npm run build
- name: Save build folder
uses: actions/upload-artifact@v4
with:
name: build
if-no-files-found: error
path: build
cypress-run:
runs-on: ubuntu-22.04
needs: install
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Download the build folder
uses: actions/download-artifact@v4
with:
name: build
path: build
- name: Cypress run
uses: cypress-io/github-action@v6
with:
start: npm start
browser: chrome
View GitHub's guide on Storing workflow data as artifacts for more info.