HMPPS Single Accommodation Service (SAS UI)

Repository for the UI for the Single Accommodation Service (SAS).

Requirements

Node.js version 24
Docker (if running against a containerised local stack)

Initial setup

Install dependencies

npm run setup

Prepare git hooks

npm run prepare

Running the application

To run the SAS service locally, copy the .env.example file to .env. The default variables should be sufficient for local development against a running local API:

cp .env.example .env

Running against the dev stack

You can also run the local service against the dev external service (HMPPS Auth and SAS API). Get the .env file from the CAS vault of the MoJ 1Password account.

You can then start the SAS UI service:

npm run start:dev

The service will be available at http://localhost:3000. You can then login using any of the CAS test credentials available in the CAS vault in 1Password.

Running against a fully mocked stack

You can run the service locally against a fully mocked API. When doing so, a Wiremock instance is spun up which serves the data found in wiremock/fixtures for the various API endpoints:

npm run start:dev:wiremock

Note: this relies on the ts-node package being available globally. If this isn't installed yet, you will be prompted to install it the first time you run the above command.

Updating the Wiremock fixtures

The JSON Wiremock fixtures are located in wiremock/fixtures. These should mostly be updated manually to tailor the data to various testing scenarios. If necessary, a fresh set of data can be regenerated by running the following command:

ts-node wiremock/generateData.ts

Running against a containerised local stack

NOTE: this method is not maintained and is only provided for reference purposes.

First, bring up the local stack:

docker compose up --scale=app=0

You can then start the SAS UI service:

npm run start:dev

The service will be available at http://localhost:3000. You can login with the following credentials:

username: AUTH_USER
password: password123456

Local development

Commit hooks have been set up to run linters, typecheck and unit tests on commit. You can also run these manually.

Running linter

The linter and typecheck are run automatically on commit. To run them manually:

npm run lint runs eslint.
npm run typecheck runs the TypeScript compiler tsc.

Unit tests

The unit tests should cover all TypeScript/implementation code.

To run all the unit tests, run:

npm run test

The unit tests also run a number of contract tests (in server/data) against the API OpenAPI spec. This spec is downloaded to tmp/sas-api.json if the file does not exist. It may sometimes be necessary to remove this file to ensure the latest is downloaded from the dev API. The test:client script clears the existing spec, downloads the latest, and runs the client tests only:

npm run test:client

Integration tests

The integration tests should cover the rendering of all templates, ensuring all elements are present on any given page. They should test that any field with validation can be rendered in an error state, although details of the validation itself (covering the various types of error possible for the field) should be covered in unit tests.

For running the integration tests locally the following command will bring up the required local infrastructure, start the service in dev mode and bring up the PlayWright UI:

npm run test:integration:ui

E2E tests

The E2E tests should cover any journey that interacts with the API, to ensure the correct flow of data between the UI and an actual API. These tests only need to cover 'happy paths', that is, successful journeys through the service, resulting in actions being recorded. The E2E tests only need to verify the rendering of errors that are the result of a business logic violation: for instance, when a user attempts to create a booking for a room that is already booked, the API may return a conflict error.

The E2E tests can be run against other environments from your local machine by setting the E2E_BASE_URL environment variable in the e2e.env file.

The tests can be run headless with:

npm run test:e2e

To run the tests in the PlayWright UI:

npm run test:e2e:ui

Maintenance mode

The service can be put into maintenance mode by setting the MAINTENANCE_MODE environment variable to true.

Additionally, the MAINTENANCE_MODE_ALLOWLIST environment variable can be set to a comma-separated list of usernames that are allowed to access the service while it is in maintenance mode.

Change log

A changelog for the service is available here