Cypress GitHub Action to Execute Tests

Introduction

Cypress is an amazing new open source web testing tool, and it integrates really well with Continuous Integration Tools, but you can make executing your tests in the cloud even easier by using a GitHub Action that the Cypress team has written for you! I’ve been using Cypress for a while now, I use Microsoft Visual Studio Code (VS Code), Git and GitHub. Now I’m using the GitHub Action to execute my tests, I get instant feedback on test failures, and all without having to setup & kick off a pipeline in a CI tool.

You can even do this with a free GitHub account – When you push your Cypress project up to GitHub, the GitHub Action (Workflow) will start a virtual machine (Linux, Windows, Mac) install Cypress, checkout your Cypress Project and run the test suite for you, with the results going back to GitHub!

So let’s have a look at how easy this is:

Add the GitHub Action YAML to your Cypress Project

At this stage I am assuming that you already have a Cypress project, and are using Git locally, and perhaps are pushing your project up to GitHub. At this point we can add the YAML for GitHub to use.

Create a new folder under your main project folder (root level), called .github then a sub-folder called workflows

Now create a new file under the workflows folder called main.yml

Now we can write the YAML. Beware YAML indentations are important, so make sure you format the YAML correctly!

name: End-to-end tests

on: [push]

jobs:

  cypress-run:

    runs-on: ubuntu-16.04

    steps:

      - name: Checkout

        uses: actions/checkout@v1

      # Install NPM dependencies, cache them correctly

      # and run all Cypress tests

      - name: Cypress run

        uses: cypress-io/github-action@v2

OK, so let’s talk about the YAML. The name at the top can be anything you like, it is just a name for the job. the on: flag allows you to say what triggers the job. Here we have it just as a push, so when we push a commit up to GitHub. This could also be on a Pull Request or both. So we could use:

on: [push, pull_request]

We can even specify the branches:

on:
  # Trigger the workflow on push or pull request,
  # but only for the main branch
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

For the Job itself, we can now specify the platform to execute the tests on (the VM) using the runs-on parameter. Here we are using ubuntu, but we could just as easily be Windows:

Virtual environment	YAML workflow label
Windows Server 2019	`windows-latest` or `windows-2019`
Ubuntu 20.04	`ubuntu-20.04`
Ubuntu 18.04	`ubuntu-latest` or `ubuntu-18.04`
Ubuntu 16.04	`ubuntu-16.04`
macOS Big Sur 11.0	`macos-11.0`
macOS Catalina 10.15	`macos-latest` or `macos-10.15`

For GitHub Actions syntax see this link

Now we have the Steps for the Job. Each Step can have a name, and has an action.

So our first step, checks out the Cypress Repository.

The next Step installs all the npm dependencies (including Cypress) and then Runs the tests. Now this is the nice bit, as the GitHub Action to perform this has been written for us by the Cypress team, so we only need to use the Action cypress-io/github-action@v2

Push the new YAML Workflow to GitHub

Once you have created the YAML, push the project to GitHub. If you have any issues (I did on Windows 10), it maybe that you need to upgrade Git on your local machine to the latest version. Then reset your git credentials globally.

If you successfully pushed the workflow, in GitHub you will have a new tab called Actions, and within this you should see the new workflow executing:

The Run has the last Commit name. Click on the name and you can now see the Cypress tests running and the output:

Once it has finished, you can see the results in GitHub:

Cypress Options

We can pass options into the Cypress GitHub Action, and also we can upload the videos and screenshots if we get a failure to GitHub as well.

Here is an extended example of a YAML script:

name: End-to-end tests
on: [push]
jobs:
  cypress-run:
    runs-on: ubuntu-16.04
    steps:
      - name: Checkout
        uses: actions/checkout@v1
      # Install NPM dependencies, cache them correctly
      # and run all Cypress tests
      - name: Cypress run
        uses: cypress-io/github-action@v2
        with:
          spec: cypress/integration/exercises/*.spec.js
      - name: Upload Screenshots
        uses: actions/upload-artifact@v1
        if: failure()
        with:
          name: cypress-screenshots
          path: cypress/screenshots
      - name: Upload Videos
        uses: actions/upload-artifact@v1
        if: always()
        with:
          name: cypress-videos
          path: cypress/videos

You can see we have restricted the tests we want to run by passing in the Cypress spec parameter, just as we would using the CLI (–spec). So here I am only running tests in the /integration/exercises/ folder.

Also, we have added another two steps to the GitHub job, BUT only if the previous step fails (the test execution). These two steps upload the videos & screenshots from our test run back to GitHub.

These will be found in the Artifacts link at the top of the Action:

Click the number under the Artifacts heading and you can open up the recorded videos to debug failures!

We can also specify our Dashboard key, so have the full results recorded in Cypress.io Dashboard, see here for more information: github.com/cypress-io/github-action

Have a go yourself, I think you’ll really like this new feature!

Edgewords Training

Edgewords has been delivering training on automated testing tools for nearly 20 years now. We have courses on all the most popular testing tools, and a great course on Cypress if you are new to the tool, you can find more information at: www.edgewordstraining.co.uk/automated-software-testing-training-courses/cypress/

Cypress GitHub Action to Execute Tests