Automated Testing Quick-start with Cypress, GitHub Actions and GitHub Pages

In this article I am going to provide a quick start guide on getting your team up and running with automated testing. I have found that this can generally be applied with any systems that have a front-end UI.

Any test is always better than no test…

There are a lot of resources out there to get you up and running with Cypress in general, especially setting up Mochawesome reports, Github workflows and using Cypress Studio. I have collated these into the same repo and have added references at the end for more information.

Reasons you may find this repo useful are as follows:

• To compliment your current automated testing or plug gaps
• You find it difficult to up-skill your team or find time and and/or get the resources required to apply a fully fledged automation solution
• Your current automation has broken and may require a lot of effort for which your team does not have enough capacity or time to quickly pivot and resolve.
• Your team has inherited an estate of applications to support, and have peered behind the curtain only to witness something that resembles the party scene in Gremlins 2

Just shut that curtain and breathe

• NOTE — This is by no means a replacement for a proper suite of unit tests for your application. This, however, is still important to strive towards.

Quickstart Steps

The steps are in the repo but for fullness, here are the main points to bring the codebase down and run some tests:

• Fork repository — https://github.com/devunderslash/cypress-quickstart
• Open favourite Terminal OR IDE with Terminal to run commands
• Clone to a folder in your local machine — git clone <your-repo-here>
• Install dependencies — npm install
• After you have added some tests and want to run them — npm run test OR
• If you prefer to Open Cypress — $(npm bin)/cypress open or npx cypress open

Adding Tests

Writing tests in Cypress are relatively straight forward. I was able to use the information from the Cypress docs along with grabbing elements on web pages using Chrome DevTools to construct my tests fairly quickly.

Once you have forked and cloned the repository and opened it up in your favourite editor/IDE, you will be able to add tests into the integration -> tests folder. You will find a test in this folder as an example for you to try out. Cypress documentation is great at helping you get started with your own tests:

Writing Your First Test

This simple test should open Amazon as an example to show structure. I found that the tests that come as standard with Cypress examples are incredibly helpful:

cypress-io/cypress-example-kitchensink

Mochawesome Reports

This is a great library to be used in conjunction with Cypress and it gives you a visual representation of your test results in HTML format. When you have written some tests you can run the following command to execute the tests and generate reports:

npm run test

When your tests have completed, a new file will be created under reports -> mochareports — report.html. You can open this in your browser of choice and will see something similar to this:

As you add more tests you will see them all here as you run them.

GitHub Pages

When you run your first commit or merge into the main branch, it will invoke the GitHub Actions workflow specified in the cypress-report.yaml. This will create a gh-pages branch and deploy to your GitHub page. In order to be able to see your report on your GitHub Page, you will need ensure that your repo is set as Public and update the project settings in GitHub as follows:

You will need to update the branch to gh-pages and the folder will need to point to the /root folder. Once you click Save it will take a little while to take effect but you will get a message similar to above:

“Your site is published at… <Your-GitHub-Page>”

If you click on the link you should now be able to see your tests in the same Mochawesome format that you have seen when running locally.

Please Note: Do not commit sensitive credentials when using this, as your Repository and GH-Page will be fully public.

Cypress Studio

If you have read this far and you don’t want to write any Javascript or test writing then this is the feature for you. If you have a basic test then you can add commands to it through the Cypress Front-End. Make sure you have the following in your cypress.json:

"experimentalStudio": true

From here you will need to Open Cypress:

$(npm bin)/cypress open or npx cypress open

With the Cypress UI open, click the test that you would like to extend and run it. Once the test has ran you will see the following icon:

You can add both new tests and new commands to current tests. Hover over test to create a new test and over current tests to add more commands. Click the magic wand icon and you will now be able to interact with the elements on the page. Once you have ran the required interaction you can then click save to record the new test/commands straight to your IDE. Here is an example of what is written below:

This gives a nice and easy entry to adding tests for your application. This feature also allows quick on-boarding of new team members.

Cypress Studio

GitHub Actions Cron-Job

At the very top of the GitHub workflow cypress-report.yaml you will see the following code:

cron job

If you want to set your tests to run daily, weekly or monthly then you can set the cron job here. Just uncomment the second two lines and update it to the frequency that you would like it to run (within GitHub Actions limits):

schedule:
  - cron: '0 8 1-31 * *

Use this link if you are unfamiliar with cron. This could remove the need for daily and weekly manual checks, reducing TOIL and freeing up time to further better your processes.

Wrap Up

As you can see, this repo should give you a good start into the world of automated testing and provides the required dependencies for visual reports both locally and publicly through gh-pages. It also provides you with Cypress Studio to help on-board your colleagues more efficiently.

If your team doesn’t have any capacity to fix up and construct full test suites for your applications then this is an easier approach to inject quality into your projects quickly. Again, I stress that this is not a replacement for full test automation, it is however a powerful tool to compliment other tools in your testing approach.

If capacity is the issue and you need to start somewhere I would recommend to add tests on a per-bug basis. Add the test if the bug impacts a visual element on your system. Over time your test suite will start to take shape.

Any updates, improvements or feedback is very much welcomed and appreciated. Thanks for reading!

References:

• GH Actions — https://medium.com/swlh/publish-your-cypress-test-report-with-github-actions-47248788713a
• Mochawesome Reporter — https://dev.to/bushraalam/using-mochawesome-reporter-with-cypress-54pf
• Mochawesome — http://antontelesh.github.io/testing/2019/02/04/mochawesome-merge.html
• Netlify Hosting — https://marekpukaj.medium.com/build-with-github-actions-host-on-netlify-ebf5fa505616