autom8

A template repository for web and backend automation using Cypress, Node, and Docker (plus some extras).

goal

The aim of this repository is to provide the scaffolding needed to make it easy to quickly plug into and test most layers of a web application while adhering to some industry best practices.

Most web applications can be roughly divide into three parts:

• front end (client side applications, SPAs, traditional web apps)
• back end (server side applications, APIs, REST, SOAP, etc)
• database layer (MYSQL, Casandra, MongoDB, etc)

principles

Nearly all modern web applications use some form of authentication, employ one or more public (and sometimes private) APIs, and rely on a persistence layer for storing information. There are also a few principles (best practises) test engineers should adhere to when building automation suites:

• use true end-to-end integration tests sparingly and only for critical application paths
• isolate and manage your own testing database (don't rely on staging for automated tests!)
• randomised test data should always generate a repeatable seed in case of failures
• unit tests should always generate a code coverage report of some kind
• component tests should be preferred over any sort of UI navigation when and where possible
• specs should separate page logic from business logic (PageObject pattern)
• specs should be able to be run in parallel (if so desired)
• specs should be able to be run individually or in groups/buckets
• specs should only assert what they need to and test for one specific thing per test case
• specs should be able to be run locally or as part of a continuous integration environment

methodology

While each product and stack will require it's own unique tests and logic, given the above principles and conservative assumptions about most modern web application stacks, this repo:

• relies on a MongoDB docker image that can be interacted with using cy.task()
• reads/writes fixtures based on the data retrieved/seeded from the MongoDB test database
• ships with examples that employ the PageObject pattern for writing clean integration tests
• ships with examples of Cypress custom commands
• can be run against a local Cypress Real World Application app straight out of the box

install

1. git clone clone the repository
2. run npm install
3. run docker pull mongo

prerequisites

• you will need Docker in order to pull the MongoDB image which we rely on for testing
• you will need NodeJS since we use Node and NPM to manage and install localised packages

usage

As this repository is a template repository you can easily use it as the basis for your own automation suite. By using this template as a foundation your repository can be marked as private, and it will have a unique, seperate commit history, not to mention be owned and managed by you/your organisation. Live long and prosper!

tips

• read the code comments! there's a lot of comments and logging, things that should help clarify concepts and make the reasoning behind certain things explicit (including code smells...)
• update the baseURL inside cypress.json to point to your local or hosted application
• update the apiURL inside cypress.json to point to your API
• add urls to cypress.env.json that you may want to use outside of page objects (i.e. from within custom commands) to use as command defaults

troubleshooting

Sometimes a test can hang or something can go wrong which prevents the teardown() method from being called in the after:run hook. If this happens you may need to manually stop and remove the mongo docker image by running this command inside your terminal:

docker stop mongo-on-docker && docker rm mongo-on-docker

If you have updated the image name inside cypress.env.json replace the image name above with whatever custom image name you have chosen.

feature list

• Sample integration login test using PageObject pattern (works against Cypress RWA)
• Sample API test for directly testing an API (works against Cypress RWA)
• Sample component test for testing a React component (works against Cypress RWA)
• ChanceJS used to randomised test data generation with identical seed used when retrying tests
• MongoDB setup method called once per run as part of before:run hook example
• MongoDB teardown method called once per run as part of after:run hook example
• Seed database task working, can be called from individual specs
• Fixture generation task working, can be called from individual specs

further reading

• Cypress example recipes -- great resource covering nearly all aspects of Cypress
• PageObjects in Cypress guide -- a look at using the PageObject pattern alongside Cypress
• Reproducible Random Tests with ChanceJS and Jest -- excellent guide, thanks VSBMeza
• Excellent 4 part series on using statically typed JavaScript -- just because