WIP replacement for SROC Charging Module API Acceptance tests
This project contains API acceptance tests for the service. It is built using Cypress and the cypress-cucumber-preprocessor. We favour writing our tests in a BDD style using Gherkin hence the cucumber-preprocessor plugin.
You just need Node.js installed, ideally an LTS version.
You'll also need Chrome. It's what we use when working on the tests, and is one of 2 browsers available to our users.
The tests can be run using Docker; for this, you will first need to install Docker. Chrome should not be needed in this case.
First clone the repository and then drop into your new local repo
git clone https://github.com/DEFRA/sroc-charging-module-api-tests.git && cd sroc-charging-module-api-testsNext download and install the dependencies
npm installAlternatively, if you will be running the tests with Docker, just clone the repo -- npm install is not required at this stage.
Important! Do not add environment files to source control
We have 6 environments where the CHA could be running; local, development, test, pre-production, integration, and production.
Each has its own config file stored in environments/. Any configuration shared across the environments is stored in cypress.json. But this can be overidden in the environment config files.
The config or 'environment' files hold environment variables which are key-value pairs; name of the thing and the value of the thing. For example, CYPRESS_ADMIN_USER=cognitoadminusername.
Depending on the environment selected the Cypress dotenv plugin will read in the values and make them available via Cypress.env() in the tests.
Using these .env files allows us to store both config and credentials that change across environments in one place but it is important they are never committed to source control.
Checkout environments/.example.env for an example of the file you'll need to create for each environment.
If you are running the tests in Docker, you should instead create a .env file in the root folder of the repo, using .env.example as a guide. Note that the format is exactly the same as environments/.env.example except the base URL is specified as CYPRESS_BASE_URL instead of baseUrl.
You can run tests using the Cypress test runner, or headlessly using either the Cypress CLI or Docker.
Cypress runs tests in a unique interactive runner that allows you to see commands as they execute while also viewing the application under test.
To open the test runner use npm run cy:open:[env] replacing [env] with your chosen environment
npm run cy:open:localThe project supports only running scenarios tagged as @wip. This can be very useful when working on new scenarios or trying to debug failing ones. Reducing the number being run reduces the noise and test output allowing you to focus.
Behind the scenes it behaves the same as using the Test runner only you use a different command to start Cypress.
npm run cy:wip:localThe test runner will open as normal but when you run a feature only those scenarios tagged with @wip will run.
Runs Cypress tests to completion. By default, cypress run will run all tests headlessly in the Electron browser.
To open the test runner use npm run cy:run:[env] replacing [env] with your chosen environment
npm run cy:run:localRuns Cypress tests to completion using a headless instance of Chrome. The output will be similar to the CLI output and will be visible in the terminal which Docker is being run from.
For convenience, we use VSCode tasks to build and run the tests in Docker. These are defined in .vscode/tasks.json and are are accessed by bringing up the command palette then selecting Tasks: Run Task followed by the task you wish to run.
Start by running the task 🚧 BUILD (CMA-TEST), which will build the Docker image. The task ✅ TEST (CMA-TEST) can then be used to run the tests. Tasks for rebuilding and dropping images are also defined in tasks.json.
If you prefer not to use VSCode tasks then simply refer to .vscode/tasks.json for details of the underlying commands.
Any changes to the tests, including changes to
.env, will require the image to be built again as bind mounts are not currently used.
In order to test our environments as well as our application, we created a standalone project rather than install Cypress into an existing one.
We have also opted to write our tests as features using the BDD style. As such our project's structure is a little different from the common examples you'll find Googling.
Feature files (*.feature) need to be stored in cypress/integration/ to be visible as tests. Along with each feature you will need to create a folder with the same name. In the folder create a *.js and add your steps for the feature there.
The steps file can be called anything. But we have opted to use the same name as the feature file and folder. This way makes it a little easier to track things when working across multiple files.
Any steps which can be shared across features can be placed in cypress/integration/common/. Check the existing files to see if one that fits already exists and add your steps to it. Else create a new *.js file. Again, the name of the file does not matter.
Another preference of the team is to use the Page object pattern. In a typical web app with a UI this would mean storing all the code to interact with a page in one place. As an API we don't have pages but we do have endpoints. Tests interact with our endpoint (page) object and not the endpoint directly. So, should something change, we only have to change it in one place.
Endpoints live in cypress/endpoints/.
If you have an idea you'd like to contribute please log an issue.
All contributions should be submitted via a pull request.
THIS INFORMATION IS LICENSED UNDER THE CONDITIONS OF THE OPEN GOVERNMENT LICENCE found at:
http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3
The following attribution statement MUST be cited in your products and applications when using this information.
Contains public sector information licensed under the Open Government licence v3
The Open Government Licence (OGL) was developed by the Controller of Her Majesty's Stationery Office (HMSO) to enable information providers in the public sector to license the use and re-use of their information under a common open licence.
It is designed to encourage use and re-use of information freely and flexibly, with only a few conditions.