Integration tests - global-121/121-platform GitHub Wiki

[!NOTE] Why not run all tests outside Docker?

With the exception of retry-failed-jobs-on-startup-during-queue-processing-test-ts, all integration tests run within the Docker container on CI. You might wonder why we don't run all tests outside Docker in production mode for consistency.

The reason: our coverage collection workflow depends on tests running inside the Docker container where the instrumented code lives. The lcov report from 121-service generation step requires this setup. Moving all tests outside Docker would require significant restructuring of the coverage collection process.

The restart test is the only exception because it has a unique requirement—it must remain active while the service restarts, which is impossible if running inside the container.

What are Integration tests?

Integration tests are a type of software testing that evaluates how multiple software components work together in an application or system. They test the interactions between different parts(modules, components, services) to ensure that they function correctly and produce the expected results.

In an integration test, the individual parts are combined and tested as a group, rather than tested individually in isolation. Integration tests are often conducted after unit testing to verify that the different units or modules work correctly when integrated together.

We use a form of integration tests, more specifically called API-tests.
API-tests can be used to ensure that the API works as expected and that they meet the specifications and requirements. Our API-tests can verify that the API(including its dependencies, like the database) functions correctly, handles inputs and outputs (from outside systems) properly, and returns the expected results.

How to write Integration tests

We use Jest to run our API tests; In it we also use, amongst other things, SuperAgent.

The test files can be found in the services/121-service/test folder. You can make a new *.test.ts file to create a new test (in a relevant folder).

(The .test. part in the name is required, as this is used to 'find' all relevant files by the test-runner.)

How to run Integration tests

All configuration/set-up to run the integration-tests is contained in the Docker-container of the 121-service.
So be sure to run all commands below within the shell of the Docker-container, or prefixed with docker exec 121-service

  • To run all integration tests once: npm run test:integration:all
  • To watch for changes on all test-files: npm run test:integration:watch
  • To run all tests in a specific file: (in this example it will run update-pa.test.ts): npm run test:integration:all 'update-pa'
  • Other options are in the Jest CLI docs: https://jestjs.io/docs/cli

Exception: Running retry-failed-jobs-on-startup-during-queue-processing.test.ts

This test requires a special setup because it must remain active while the 121-service restarts.

Requirements

  1. Run 121-service in production mode: (from your local/development-machine)
npm run start:services:ci:production
  1. Execute the test using: (from your local/development-machine, not within the Docker-container)
npm run test:integration:local

Why this setup is needed

  • Production mode ensures that 121-service properly restarts during the test's 'force a restart'-step
  • Running outside Docker (local npm run instead of docker exec 121-service) keeps the test-process active while the 121-service restarts inside its container
  • The :local variant includes the --env-file=../.env flag, which imports environment variables that are not accessible from within the Docker container