Skip to content

Testing

Jump to bottom
afwilcox edited this page Sep 25, 2025 · 2 revisions

End-to-end

This project uses Playwright (https://playwright.dev/) as the e2e testing framework. The migration from Cypress (https://www.cypress.io/) was done after an assessment of the two tool for new modules being built. Playwright was chosen for its parallelization and overall superior performance over Cypress, as well as having out-of-the-box support for Apple WebKit (Safari). The significance of Safari support is inflated by the amount of iPad and iPhone traffic this system sees from users in the field.

Configuration

Configuration of Playwright can be found in frontend/playwright.config.ts. Here, dependencies can be set, and browsers to run the tests against can be selected. Environment variables have also been added to the sample.env that will need to be copied to frontend/.env with the appropriate values.

Authentication

The Playwright test suite has been setup to use shared authentication across the tests. Setup can be found in frontend/e2e/authStorage.setup.ts. Since our tool has multiple test users with different roles, the following is performed for each test user:

  • The user is logged into keycloak using the appropriate environments realm and the credentials sourced from the environment variables.
  • The resulting cookie containing the token and session info are saved to the frontned/e2e/.auth directory whose contents should never be committed. The .gitignore covers all contents of that directory, however if the directory moves or changes, the .gitignore file will need to be updated as well. The path of each cookie is added to the exported STORAGE_STATE_BY_ROLE variable found in frontend/e2e/utils/authConfig.ts.
  • In frontend/playwright.config.ts, the setup step has been marked as a requirement for all subsequent tests, making the cookie available to all tests that depend on the setup.
  • All other tests can make use of the stored credentials, e.g. test.use({ storageState: STORAGE_STATE_BY_ROLE.COS }). In doing so, that test can bypass the process of logging in and go straight to visiting and testing the appropriate protected routes.
  • If different tests within a test group need to use different users, the browser object can be passed into the individual tests which can then create a page object using the appropriate storage state: `const page = await browser.newPage({ storageState: STORAGE_STATE_BY_ROLE.});

Adding Tests

Tests can be added either directly in frontend/e2e/tests if they are a top level test, or in the appropriate sub-directory of frontend/e2e/tests if they are a more tightly scoped test that will be imported to a top level spec. Test files must follow the naming convention <descriptor>.spec.ts or <descriptor>.test.ts to be detected when running the tests.

See"Authentication" above for instructions on writing tests to run as specific users with select roles.

If a test group need to be run sequentially, include the following in the group: test.describe.configure({ mode: "serial" });

Running Tests

Two scripts have been added to the package.json for running Playwright tests:

  • npm run test:e2e will run the tests
  • npm run test:e2e-ui will open the Playwright UI where you can visually run and debug the tests

A note when using the UI: by default it filters the tests that it shows to just the setup tests. In the UI itself, open the filters tab and select the appropriate browsers and the other tests will appear.

Debugging CI Failures

In the action that runs the Playwright tests in CI there is a step that follows the tests run titled "upload-artifact" that will provide an artifact download url to the Playwright report for the run. To view the report, download the file from the url, unzip it and run: npx playwright show-report <path/to/unzipped-report-directory> The report will open in your browser.

Note: if you do not have Playwright installed globally on your computer, run the command from the frontend directory. The report path can be absolute, so it does not matter where the report directory is.

Jest Unit Tests

Jest unit tests are maintained for the backend.

npm test

Cypress Automated e2e Tests

Cypress tests are considered legacy and will eventually be converted to Playwright. This project incorporates Cypress tests into the pipeline. If you want to run the tests locally, you can use this command.

npx cypress run --browser chromium --config baseUrl=http://localhost:3000

To run a specific test, use --spec

npx cypress run --browser chromium --config baseUrl=http://localhost:3000 --spec {path to spec file}

Make sure the CYPRESS_KEYCLOAK_USER and CYPRESS_KEYCLOAK_PASSWORD environment vars are set to the appropriate test credentials, as there's a specific test account that is used in the pipeline (username ENCETST1).

Use Cypress to View Test Runs

  1. cd frontend
  2. npm run cypress:open
  3. Select "e2e Testing"
  4. Select your browser of choice
  5. Select your tester
image

Clone this wiki locally