epr-frontend-journey-tests

The template to create a service that runs WDIO tests against an environment.

• Local
  • Requirements
    • Node.js
    • Gitleaks
    • Mise
  • Setup
  • Running local tests
  • Debugging local tests
• Production
  • Debugging tests
• Licence
  • About the licence

Local Development

Requirements

Node.js

Please install Node.js >= v20 and npm >= v9. You will find it easier to use the Node Version Manager nvm

To use the correct version of Node.js for this application, via nvm:

nvm use

Gitleaks

Gitleaks is required for pre-commit secret scanning and must be available on your PATH.

The simplest install on macOS/Linux is via mise

mise trust && mise install

Alternatively, install directly:

• macOS: brew install gitleaks
• Linux/Windows: see the gitleaks releases page

Mise

mise - a polyglot version manager that reads mise.toml in this repo to install the correct pinned versions

1. Install
2. Activate in your shell

Setup

Install application dependencies:

npm install

Additional configuration in Linux

For Linux based machines, you will need to add this entry into your etc/hosts file for the tests to run locally:

127.0.0.1 defra-id-stub

Running local tests

Start application you are testing on the url specified in baseUrl wdio.local.conf.js

npm run test:local

Running tests with a specific tag locally

GREP='@delprnexp' npm run test:local:grep

If for whatever reason the stable version of Chrome for Testing is not working for you, then you can specify the Chrome version when running locally

WDIO_CHROME_VERSION=146.0.7680.154 npm run test:local:grep

Debugging local tests

npm run test:local:debug

Feature flags in journey tests

compose.yml is the single source of flag state. Each FEATURE_FLAG_* env var defaults in compose.yml (for example ${FEATURE_FLAG_X:-true}), and the suite runs and asserts that one configured state unconditionally. Nothing else sets flags in CI: the run-journey-tests action takes no flag inputs, so every caller (this repo's PR checks and epr-frontend PR checks alike) exercises the same state and cannot drift. Note the interpolation default only fires while the env var is unset, so do not export FEATURE_FLAG_* vars in workflow env blocks.

Most flags stop there. An in-flight feature is typically tested flag-on in CI (ahead of the production flip) while the flag-off gating is covered by the service's own unit and integration tests. When the flag flips on in production and is later retired, the journey suite needs no changes beyond eventually dropping the env var from compose.yml.

Named matrix passes are the escalation, not the default. check-pull-request.yml runs the suite once per named entry in matrix.include. A permanent baseline entry runs the compose.yml defaults. If a flag's two states both genuinely warrant journey coverage (a risky or long-lived divergence, not just new messaging), give it a matrix entry that pins the non-default state, plumb the value through to the container and the runner, and branch the affected specs on it. Cost is linear (N + 1 passes for N overridden flags). Reach for this deliberately: most flags do not earn it.

The plumbing, when a flag earns it: add an action input for the flag, have the action's first step write it once to $GITHUB_ENV (echo "FEATURE_FLAG_X=${{ inputs.feature-flag-x }}" >> "$GITHUB_ENV") so the same value reaches both the frontend container (via compose.yml interpolation) and the wdio runner (via process.env), then pass ${{ matrix.x || '<default>' }} from the matrix step. Read the env var in one shared test/support/flags.js and branch specs on flags.x, for example letting the flag pick the assertion verb: const assert = flags.x ? checkBodyText : checkBodyTextDoesNotInclude. The fully worked version lives in the history of PR #429, which removed it.

The required check is a gate job. Branch protection requires the exact name Run Journey Tests, which a matrix leg (Run Journey Tests (<name>)) can never match. So an aggregate job named Run Journey Tests needs the legs and passes only if all of them did (if: always(), so a failed leg fails the gate rather than skipping it). Its fixed name keeps branch protection decoupled from the matrix contents: adding or retiring an entry edits only matrix.include.

Production

Running the tests

Tests are run from the CDP-Portal under the Test Suites section. Before any changes can be run, a new docker image must be built, this will happen automatically when a pull request is merged into the main branch. You can check the progress of the build under the actions section of this repository. Builds typically take around 1-2 minutes.

The results of the test run are made available in the portal.

Running tests with Profile

By default in the CDP-Portal only tests tagged with @smoketest are run. If you wish to run all the tests, pass in all in the profile section of the CDP Portal UI.

Requirements of CDP Environment Tests

1. Your service builds as a docker container using the .github/workflows/publish.yml The workflow tags the docker images allowing the CDP Portal to identify how the container should be run on the platform. It also ensures its published to the correct docker repository.

2. The Dockerfile's entrypoint script should return exit code of 0 if the test suite passes or 1/>0 if it fails

3. Test reports should be published to S3 using the script in ./bin/publish-tests.sh

Running on GitHub

Alternatively you can run the test suite as a GitHub workflow. Test runs on GitHub are not able to connect to the CDP Test environments. Instead, they run the tests agains a version of the services running in docker. A docker compose compose.yml is included as a starting point, which includes the databases (mongodb, redis) and AWS emulator (floci) pre-setup.

Steps:

1. Edit the compose.yml to include your services.
2. Modify the scripts in docker/scripts to pre-populate the database, if required and create any AWS resources.
3. Test the setup locally with docker compose up and npm run test:github
4. Set up the workflow trigger in .github/workflows/journey-tests.

By default, the provided workflow will run when triggered manually from GitHub or when triggered by another workflow.

If you want to use the repository exclusively for running docker composed based test suites consider displaying the publish.yml workflow.

BrowserStack

Two wdio configuration files are provided to help run the tests using BrowserStack in both a GitHub workflow (wdio.github.browserstack.conf.js) and from the CDP Portal (wdio.browserstack.conf.js). They can be run from npm using the npm run test:browserstack (for running via portal) and npm run test:github:browserstack (from GitHib runner). See the CDP Documentation for more details.

Licence

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

About the licence

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.