Run your Cypress Tests in a Github Workflow
Tags: github, cypress, javascript, testing
Published: 2022-02-20 16:52:22

# 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](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions).  

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](https://tinyurl.com/3df5wm8f), 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:

```yaml
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)`:
```yaml
on: 
  push:
    branches:
      - 'main'
  workflow_dispatch:
```

- Checkout the code:
```yaml
- name: Check out repository code
  uses: actions/checkout@v2
```

- Run the tests on Firefox with the Cypress Github Action:
```yaml
- 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](https://github.com/cypress-io/github-action).  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](https://marketplace.visualstudio.com/items?itemName=cschleiden.vscode-github-actions).

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:
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/wq9srie9ov9twd79k7lb.png)


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:
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/6sjz6gqylhks4ysw35b2.png)

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

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/s683pgl01rbf8scqo14u.png)


# 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](https://dennis-whalen.com) for more test automation content.  Thanks!

<a href="https://dev.to/leading-edje">
  ![Smart EDJE Image](https://dev-to-uploads.s3.amazonaws.com/i/5uo60qforg9yqdpgzncq.png)
</a>