Testing

This document covers the tools to run tests and how to use them.

Django tests

Run the project tests by executing:

$ python src/manage.py test src --keepdb

To measure coverage, use coverage run:

$ coverage run src/manage.py test src --keepdb

It may be convenient to add some aliases:

$ alias runtests='python src/manage.py test --keepdb'
$ runtests src

and:

$ alias cov_runtests='coverage run src/manage.py test --keepdb'
$ cov_runtests src && chromium htmlcov/index.html

OIDC login end-to-end tests

The OIDC login flows are covered by Playwright end-to-end tests (open_inwoner.accounts.tests.test_oidc_login_e2e) that drive a real browser through the full authorization-code flow against a live Keycloak. The request-based OIDC tests (test_oidc_views.py) mock the provider’s HTTP responses, which only works for the backend’s own calls; it cannot cover the browser’s navigation to Keycloak’s login page, hence these separate live tests. They are tagged keycloak (and e2e) and skip themselves when Keycloak is not reachable, so runs without it are safe.

Requirements to run locally:

  • Keycloak must be reachable by BOTH the headless browser and the in-process test server at E2E_KEYCLOAK_REALM_URL (default: the docker dev-stack alias, with the test realm imported from docker/keycloak/fixtures/realm.json). Bring it up with docker compose -f docker-compose.dev.yml up -d and ensure keycloak.open-inwoner.local resolves on the host (/etc/hosts -> 127.0.0.1).

  • The live test server binds localhost:8000 because that host:port is in the testid client’s redirectUris in the realm; Keycloak rejects any other callback origin. Stop the dev web container first, as it also uses :8000.

Run with:

$ python src/manage.py test src --tag=keycloak

In CI these run as part of the regular e2e job, but only on its chromium matrix leg: that leg boots Keycloak, while the other browsers exclude the keycloak tag. The authorization-code flow relies on cross-origin cookies that Firefox, WebKit and Edge drop by default over plain-HTTP localhost, so running it there tests browser cookie policy rather than our code.

Javascript tests

There are quite some options to run the Javascript tests. Karma is used as test-runner, and you need to install it globally if you have never done so:

$ sudo npm install -g karma

By default, the tests are run against Chrome/Chromium. To run the tests, execute:

$ npm test

If you want to target a single browser, you can run karma directly:

$ karma start karma.conf.js --single-run --browsers=PhantomJS

Coverage reports can be found in build/reports/coverage.

To trigger a test run on file change (source file or test file), run:

$ karma start karma.conf.js --single-run=false --browsers=PhantomJS