GitHub Actions Matrix Job URL for Parallel Cypress Tests

When running cypress tests in a GitHub Actions matrix mode and exploring the tests results in a cloud orchestration dashboard (like Currents, Sorry Cypress or Cypress Cloud) it can be tricky to identify what specific matrix job a test belongs to.

The problem is particulary annoying when many parallel matrix jobs are involved. The test results are presented without any way to identify the associated matrix job. One option is to iterate through the matrix jobs and find the one that matches the failed test. This is a tedious process, and can be difficult to do when there are many jobs.

Unfortunatelty, GitHub actions doesn't provide matrix job URL or identifier as an environment variable. However, one can use the GitHub API to get the matrix job URL.

After obtaining the matrix job URL, it can be printed to the Cypress terminal output. This is useful for getting a reference to the specific matrix build job from cypress terminal output.

TL;DR See the example repository

Getting the Matrix Job URL

The matrix job URL can be obtained by using the GitHub list jobs for a workflow run API. For example:

curl \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>"\
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/repos/OWNER/REPO/actions/runs/RUN_ID/jobs

The required parameters are:

• OWNER - the GitHub owner of the repository
• REPO - the GitHub repository name
• RUN_ID - the GitHub Actions run ID

OWNER/REPO can be obtained from the GITHUB_REPOSITORY env variable, RUN_ID. The output would contain the list of jobs, together with their URLs.

In order to filter the desired job, we need to filter the list of jobs by the job name. The job name is available is in the form JOB_NAME (CONTAINER). For example, for the following configuration file:

jobs:
  cypress-tests:
    runs-on: ubuntu-20.04
    strategy:
      fail-fast: false
      matrix:
        # run 3 copies of the current job in parallel
        containers: [1, 2, 3]

job names would be cypress-tests (1), cypress-tests (2) and cypress-tests (3).

Luckly, there's a ready-to-use GitHub action that can be used to get the matrix job URL.

jobs:
  cypress-tests:
    runs-on: ubuntu-20.04
    permissions:
      contents: read
      actions: read
    strategy:
      fail-fast: false
      matrix:
        # run 3 copies of the current job in parallel
        containers: [1, 2, 3]
    steps:
      - name: Checkout
        uses: actions/checkout@v2

      - name: Get Current Job Log URL
        uses: Tiryoh/gha-jobid-action@v0
        id: jobs
        with:
          github_token: ${{ secrets.GH_TOKEN }} # GH token with actions:read permissions
          job_name: cypress-tests (${{ matrix.containers }}) # job name filter
          per_page: 30 # increase if you have many jobs

      - name: Output and Save Current Job Log URL
        run: |
          echo ${{ steps.jobs.outputs.html_url }}
          echo "MATRIX_JOB_URL=${{ steps.jobs.outputs.html_url }}" >> $GITHUB_ENV

In the example above, we invoke the action with the following parameters:

• github_token - the GitHub token with actions:read permissions
• job_name - the job name filter
• per_page - the number of jobs to return per page. Increase this if you have many jobs

The action Get Current Job Log URL will output the matrix job URL to the html_url output variable. The action Output and Save Current Job Log URL will print the matrix job URL to the terminal output and save it to the MATRIX_JOB_URL environment variable for use in the subsequent steps.

Printing the Matrix Job URL in Cypress tests

When Cypress test are running in record mode, the terminal output is automatically uploaded to the connected cloud orchestration dashboard. The output is stored separately for each spec file, so we need to print the Matrix Job URL before executing a spec file.

before:spec hook of setupNodeEvents cypress configuration is a good place to do this.

setupNodeEvents(on, config) {
  on("before:spec", (spec, details) => {
    console.log(`  GH Job URL: ${process.env.MATRIX_JOB_URL}`);
  });
},

The output will look like this:

  (Run Starting)

  ┌────────────────────────────────────────────────────────────────────────────────────────────────┐
  │ Cypress:        12.1.0                                                                         │
  │ Browser:        Electron 106 (headless)                                                        │
  │ Node Version:   v16.18.1 (/usr/local/bin/node)                                                 │
  │ Specs:          9 found (1000.spec.js, crash.spec.js, fails.spec.js, flaky.spec.js, notests.sp │
  │                 ec.js, orchestration_105.spec.js, orchestration_106.spec.js, retries.spec.js,  │
  │                 skipped.spec.js)                                                               │
  │ Searched:       cypress/integration/*.spec.js                                                  │
  │ Params:         Tag: false, Group: false, Parallel: true                                       │
  │ Run URL:        https://app.currents.dev/run/b502c52cc32c3d96cd91f9b1c0e416a8                  │
  └────────────────────────────────────────────────────────────────────────────────────────────────┘


────────────────────────────────────────────────────────────────────────────────────────────────────

  Running:  fails.spec.js                                                                   (1 of 9)
  GH Job URL: https://github.com/currents-dev/dashboard/actions/runs/3738526471/jobs/6344699219


  Some tests fail
    1) Passing Test A
    2) Failing Test B

Here's an example of the output in the Currents dashboard, attached to the associated spec file: