From 8d5acbc0ab476109694dea332c6cf70702fd8a1e Mon Sep 17 00:00:00 2001 From: Mike McCready <66998419+MikeMcC399@users.noreply.github.com> Date: Fri, 4 Sep 2026 15:58:08 +0200 Subject: [PATCH] test: use Docker image cypress/browsers in parallel record example --- .github/workflows/example-recording.yml | 7 +++++- README.md | 31 ++++++++++++++++++++----- 2 files changed, 31 insertions(+), 7 deletions(-) diff --git a/.github/workflows/example-recording.yml b/.github/workflows/example-recording.yml index 386729d7e..ff92280c3 100644 --- a/.github/workflows/example-recording.yml +++ b/.github/workflows/example-recording.yml @@ -49,8 +49,13 @@ jobs: fail-fast: false matrix: # run copies of the current job in parallel - containers: [1, 2] + recording-job: [1, 2] # the name of the matrix variable is arbitrary, we just need two copies of the job if: needs.check-record-key.outputs.record-key-exists == 'true' + # Use a Cypress Docker image with browsers pre-installed + # to ensure that the tests run in the same consistent environment across each parallel run + container: + image: cypress/browsers:24.20.0 + options: --user 1001 steps: - name: Checkout uses: actions/checkout@v7 diff --git a/README.md b/README.md index 9ce255bab..9be408c4d 100644 --- a/README.md +++ b/README.md @@ -751,7 +751,9 @@ jobs: **Note:** Cypress parallelization requires a [Cypress Cloud](https://on.cypress.io/cloud-introduction) account. -You can spin multiple containers running in parallel using `strategy: matrix` argument. Just add more dummy items to the `containers: [1, 2, ...]` array to spin more free or paid containers. Then use `record` and `parallel` parameters to [load balance tests](https://on.cypress.io/parallelization). +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](https://on.cypress.io/parallelization). ```yml name: Parallel Cypress Tests @@ -768,13 +770,16 @@ jobs: fail-fast: false matrix: # run 3 copies of the current job in parallel - containers: [1, 2, 3] + 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 containers will load balance all found tests among themselves + # these jobs will load balance all found tests among themselves - name: Cypress run uses: cypress-io/github-action@v7 with: @@ -784,14 +789,18 @@ jobs: env: # pass the Cypress Cloud record key as an environment variable CYPRESS_RECORD_KEY: ${{ secrets.EXAMPLE_RECORDING_KEY }} - # Recommended: pass the GitHub token lets this action correctly + # 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 }} ``` ![Parallel run](images/parallel.png) -The Cypress GH Action does not spawn or create any additional containers - it only links the multiple containers 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](https://docs.cypress.io/cloud/features/smart-orchestration/overview/) guide for a detailed explanation. +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](https://docs.cypress.io/cloud/features/smart-orchestration/overview/) guide +for a detailed explanation. If you use the GitHub Actions facility for [Re-running workflows and jobs](https://docs.github.com/en/actions/managing-workflow-runs/re-running-workflows-and-jobs), note that [Re-running failed jobs in a workflow](https://docs.github.com/en/actions/managing-workflow-runs/re-running-workflows-and-jobs?tool=webui#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. @@ -800,7 +809,17 @@ To optimize runs when there are failing tests present, refer to optional [Cypres - [Spec Prioritization](https://docs.cypress.io/cloud/features/smart-orchestration/spec-prioritization) - [Auto Cancellation](https://docs.cypress.io/guides/cloud/smart-orchestration/run-cancellation). See also [Auto cancel after failures](#auto-cancel-after-failures) for details of how to set this option in a Cypress GitHub Action workflow. -During staged rollout of a new GitHub-hosted runner version, GitHub may provide a mixture of current and new image versions used by the container matrix. It is recommended to use a [Docker image](#docker-image) in the parallel job run which avoids any Cypress Cloud errors due to browser major version mismatch from the two different image versions. A [Docker image](#docker-image) is not necessary if testing against the default built-in Electron browser because this browser version is fixed by the Cypress version in use and it is unaffected by any GitHub runner image rollout. +During staged rollout of a new [GitHub-hosted runner image](https://github.com/actions/runner-images#readme) 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](#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. + +[![recording example](https://github.com/cypress-io/github-action/actions/workflows/example-recording.yml/badge.svg)](.github/workflows/example-recording.yml) ### Component and E2E Testing