hmpps-community-payback-ui

UI for Community Payback

Running the application

Using CP stack

In order to spin up a full local stack with the API (integrating with dependent services) use (CP stack)[https://github.com/ministryofjustice/hmpps-community-payback-api/tree/main/tools/cp-stack].

NB. This project is the focus of our development tooling and is likely to receive future updates.

After following the setup the common commands are:

When running the API as a docker container and deploying everything (inc. this UI):

cp-stack start --local-ui

# or
script/server

When running the API locally and deploying everything (inc. this UI):

cp-stack start --local-ui --local-api

# or
script/server --local-api

The service should then be available at http://localhost:3000

The same credentials used to login to the dev instance of the Community Payback UI should be used.

To stop the deployment:

cp-stack stop

Run tests

Run all tests

You can run all lint checks and tests in the project in one go by running:

script/test

This script will also generate the latest types from the API schema (generated locally, to enable testing against a specific branch). You can rollback these changes if the test suite passes—as we have an automated workflow to handle this type generation when the Community Payback API main branch is updated.

Pre-requisites

The script will set up most of your dependencies for you, but you will need to do the following to get it running:

• Set up CP Stack
• Run ./script/generate-e2e-env.sh to generate an .e2e.env configuration file (this will automatically be created if running npm run test:e2e:local)

Test options

You can customise the test script with any or all of the following options:

script/test
  --skip-update # => skip installation of dependencies
  --skip-build # => skip building the project
  --skip-server # => run checks against existing local running application
  --skip-generate-types # => run checks without generating any new types against the API project

  --skip-all # => or combine all of the above skip options

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, use:

npm run test:integration:local

Or to run with Cypress UI:

npm run test:integration:local:ui

Running e2e tests

1. Run ./script/generate-e2e-env.sh to generate an .e2e.env configuration file (this will automatically be created if running npm run test:e2e:local)

2. Install Playwright

npm run setup
npx playwright install

3. Start the server

script/server

4. Test with and without UI

npm run test:e2e:local:ui
# or
npm run test:e2e:local

Managing dependencies

This app uses hmpps-npm-script-allowlist to restrict pre/post install scripts to help mitigate supply-chain attacks using this vector. Any npm ci that you would normally execute or put in scripts, should be replaced by npm run setup which ensures the allowlist checks are run.

This library forbids these scripts to run as part of npm install. If the library you are installing depends on them, you will need to run npm run setup afterward and then go through any warnings and check any scripts it needs.

If a change to the allow list configuration is required (as prompted when running npm run setup), follow the guidance in the package README on how to investigate whether scripts should be allowed or forbidden.

If you're unsure about whether a script should be allowed, ask in the #typescript channel on Slack.

Change log

A changelog for the service is available here