HMPPS Accredited Programmes UI

Prerequisites

• Docker
• Node.js

Setup

When running the application for the first time, run the following command:

script/setup

However, if you intend to run the application using the dev apis then following command instead:

script/setup --dev-api

This will create .env files and bootstrap the application. If using the --dev-api flag then you will need to replace any variables set to <retrieve-from-k8s-and-add-here>, in the generated .env file.

If you're coming back to the application after a certain amount of time, you can run:

script/bootstrap

Running the application

With the current API

To start Docker, run all backing services including a local copy of the Accredited Programmes API (port 9091) and the Prison Register (port 9092), a mocked version of the Prisoner Search (see below), and then the application itself, run:

  script/server

As the Prisoner Search is a complex API with multiple dependencies, we've opted to mock it when running locally. The above script will generate two mocked people in prison to be served from the Prisoner Search /prisoner/:prisonNumber endpoint with details available in /wiremock/stubs/prisoners.json.

With a mocked API

Warning: only some parts of the journey are available with the mocked API.

Mocked referral summaries and referrals are mocked to have been referred by ACP_POM_USER. To view these referrals with the status set to referral_started, you must be logged in as ACP_POM_USER.

To run the application as above but with a mocked Accredited Programmes API (port 9099), run:

script/server --mock-api

API endpoint stubbing is set up in /wiremock/scripts/stubAccreditedProgrammesApi.ts.

With the dev API

script/server --dev-api

Local user accounts

There are three user accounts with different roles that can be used when running the application locally:

Username	Description	Roles	Password
ACP_POM_USER	Prisoner Offender Manager user - responsible for making referrals and viewing the progress of a referral	POM, ACP_REFERRER	password123456
ACP_PT_USER	Programme Team user - responsible for assessing the suitability of a person to an Accredited Programme and updating the status of referrals	ACP_PROGRAMME_TEAM	password123456
ACP_PT_REFERRER_USER	Programme Team user - all the responsibilities of a Programme Team user above, but with the ability to also make referrals	ACP_PROGRAMME_TEAM, ACP_REFERRER	password123456

Seeded resources

The local copy of the Accredited Programmes API has various seeds in place providing data to work with in local development. These include courses, course offerings, referrals, and associated data.

The SQL used to generate the seed data can be viewed at hmpps-accredited-programmes-api/blob/main/src/main/resources/seed/db/migration/R__Seed_Data.sql.

If the seeds no longer meet our needs and need updating, the process is as follows:

1. update the relevant parts of generate-api-seeds/script/utils/generateApiSeeds
2. run generate-api-seeds, which will output a new API SQL script to the terminal
3. copy this output into the API seed file (linked above) and open a pull request with the changes
4. merge the pull request and await completion of the build_docker CircleCI job
5. update the API Docker image in your local copy of the the UI repository

Running the tests

To run linting, typechecking and the test suite, run:

  script/test

By default, this will update backing service images (e.g. the API) and dependencies. If you want skip the update when running the full test suite, run:

  script/test --skip-update

The Accredited Programmes API will run on port 9199 in the test environment.

Running unit tests

You can run the suite of unit tests with:

  npm run test:unit

Running end-to-end tests with Cypress

To run the end-to-end tests by themselves in a headless browser, run:

  npm run test:integration:cli

You can run them with the Cypress UI with:

  npm run test:integration:ui

Feature flag tests

We currently have a feature flag to prevent Refer pages and functionality from being shown in the preproduction and production environments. We have a set of separate tests to check that the feature flag works as expected. To run these, run either of the following:

  npm run test:integration:refer-disabled:cli

  npm run test:integration:refer-disabled:ui

Using Postman

We have a Postman team for interacting with APIs - please ask to be added to it.

You'll need to populate secret environment variables in the Environments section of Postman.

Ensure you put these in the "Current value" box, rather than "Initial value" or they will be shared!

Local

These secrets can be copied across from .env.example in this repo.

Dev & Dev (API credentials)

You can use project-specific credentials for interacting with dev APIs. You'll need to fetch the secrets for this section from Kubernetes.

See instructions in the Manage Infrastructure docs for accessing these secrets.

Preprod

You'll need to have a personal client created for you by the HMPPS Auth, Audit and Registers team to view preprod data. This will require you to have Security Clearance and be on the MOJ VPN. Ask for this in the #hmpps-auth-audit-registers Slack channel.