hmpps-breach-notice-ui

Get started

Pre-requisites

You'll need to install:

• Node 20.x*
• Docker
• Java 21**

*If you're already using nvm or fnm, run: nvm install --latest-npm at the project root to install the correct Node version automatically.

**To simplify switching between Java versions it is advisable to use sdkman

Dependencies

Install NPM package dependencies (from the root of the project):

First - Create a .env file in the root of the project (only on first run copy the example env file by running the following command)

cp .env.example .env

Then, to run the service locally with dependencies in WireMock:

npm run start:dev

Open http://localhost:3000 in your browser.

Running the API locally

To start the service with a locally running instance of hmpps-breach-notice-api on port 8080, add the following to your .env file:

HMPPS_AUTH_URL=http://localhost:9090/auth
BREACH_NOTICE_API_URL=http://localhost:8080

Integrate with dev services running on MOJ Cloud Platform

Alternatively, you can integrate your local UI with the dev/test services deployed on MOJ Cloud Platform. This removes the need for using Docker.

Create a .env file at the root of the project:

NODE_ENV=development
ENVIRONMENT=dev
REDIS_ENABLED=false
HMPPS_AUTH_URL=https://sign-in-dev.hmpps.service.justice.gov.uk/auth
MANAGE_USERS_API_URL=https://manage-users-api-dev.hmpps.service.justice.gov.uk

Run the following to grab client credentials from the dev namespace:

kubectl -n hmpps-breach-notice-dev get secret hmpps-breach-notice-ui -o json \
| jq -r '.data | map_values(@base64d) | to_entries[] | "\(.key)=\(.value)"' \
| grep CLIENT >> .env

Then, start the UI service:

npm run start:dev

Formatting

Check formatting

npm run lint

Fix formatting

npm run lint:fix

Intellij Config

For formatting nunjucks files it is recommended to install the Twig Plugin for IntelliJ and configure a filetype association for *.njk files

To automatically format TypeScript files go to settings, enable the ESLint "fix on save" setting in IntelliJ. See Fix problems automatically on save

Testing

Run unit tests

npm run test

Running integration tests

To run the Cypress integration tests locally:

# Start the UI in test mode
npm run start-feature:dev

# Run the tests in headless mode:
npm run int-test

# Or, run the tests with the Cypress UI:
npm run int-test-ui

Dependency Checks

The template project has implemented some scheduled checks to ensure that key dependencies are kept up to date. If these are not desired in the cloned project, remove references to check_outdated job from .circleci/config.yml

Logging in with a test user

Once the application is running you should then be able to login with:

username: AUTH_USER password: password123456

To request specific users and roles then raise a PR to update the seed data for the in-memory DB used by Auth

Run linter

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

Run unit tests

npm run test

Running integration tests

For local running, start a wiremock instance by:

docker compose -f docker-compose-test.yml up

Then run the server in test mode by:

npm run start-feature (or npm run start-feature:dev to run with auto-restart on changes)

And then either, run tests in headless mode with:

npm run int-test

Or run tests with the cypress UI:

npm run int-test-ui