Run your Cypress Tests in a Github Workflow

Introduction

In my previous Cypress posts I've walked through how to get Cypress setup and running locally. To this point I haven't talked about how to run the tests in a CI pipeline. Well that all changes today!

In this post I'm going to show you how to easily get your tests running in Github Actions.

Github Workflow

Github Workflow allows us to us define a workflow that that runs when certain triggering events occur, such as merging code to the repo. The workflow is defined with YAML, and is based on a documented formatting syntax.

When the .yml (or .yaml) file is placed in the expected location and merged to the repo, it will be parsed by Github. If the file syntax is good, the workflow will be executed. You can view progress of the workflow execution via the Github UI.

The basic workflow I'm going to walk through will get you started, and I'll provide links help you learn more.

So let's do this!

Setup

For this post I'm assuming you have a bit of familiarity with Cypress. I have more detail in a previous Cypress post, so please take a look if you want that detail.

I'm going to use the tests in the initial Cypress setup to get us started. To follow along at home:

1. create a new folder for your project
2. run npm init
3. run npm install cypress --save-dev
4. run npx cypress open
5. run one of the tests through the Cypress runner to make sure everything looks good locally

The workflow

OK, so what do we want this workflow to do? Our workflow is going to be pretty basic. For every push to the main branch, the workflow will pull the code and run the Cypress tests on Firefox. If tests fail, the workflow fails. We also want to be able to trigger the workflow manually from the Github UI.

Let's take a look at the .yml file for this workflow:

name: run my vanilla Cypress tests
on: 
  push:
    branches:
      - 'main'
  workflow_dispatch:

jobs:
  checkout-and-test:
    runs-on: ubuntu-latest
    steps:
      - run: echo "🎉 The job was automatically triggered by a ${{ github.event_name }} event."

      - name: Check out repository code
        uses: actions/checkout@v2

      - name: run cypress tests with firefox
        uses: cypress-io/github-action@v2
        timeout-minutes: 10
        with:
          browser: firefox

Hopefully the flow of this workflow is pretty self-explanatory. The key sections include:

• Define the triggering events with on. We want our workflow triggered with a push to main or when manually triggered via the Github UI or APIs (workflow_dispatch):

on: 
  push:
    branches:
      - 'main'
  workflow_dispatch:

• Checkout the code:

- name: Check out repository code
  uses: actions/checkout@v2

• Run the tests on Firefox with the Cypress Github Action:

- name: run cypress tests with firefox
  uses: cypress-io/github-action@v2
  timeout-minutes: 10
  with:
    browser: firefox

For much more info regarding the Cypress Github Action, check out their detailed documentation. I'm just barely scratching the surface of its capabilities here.

To allow Github to find the workflow file, the file needs to be in the ./.github/workflows folder. I'm naming my file CI.yml, but the name doesn't matter. Only the file extension (.yml or .yaml) and file location matters.

Viewing workflow in Github

Once your branch is pushed to Github, Github will parse the file and verify it conforms to the syntax specification. If you want to validate syntax before pushing, take a look at the Github Actions for VS Code plugin.

To view your workflow execution, go to your repo in the Github UI and click on the Actions tab. You should see your most recent workflow run at the top of the list:

If the file syntax is not valid, the job will fail and you'll see an error. If the syntax is valid, you can click on the job and watch it as it runs. You should see messages very similar to want you see when running locally:

To trigger the workflow via the UI, just click on your workflow in the left nav, and then click the Run workflow button:

Wrap-up

So there we go, we now have our tests running with each push to the Github repo. Although the demo was focused on Github, you can accomplish the same with any of the major CI providers.

I hope you learned something with this post, and can see just how easy it is to get your tests moved to a CI pipeline where they belong.

As always, let me know if you have any comments or questions. Feel free to subscribe to my blog site for more test automation content. Thanks!

Comments

[Colin F]

Thank you for the guide! I spent like 3 hours trying to figure this out with Cypress' documentation. I read your blog this morning and got it working ASAP.

[Dennis Whalen]

Thanks for that Colin, it made me smile!