Accredited Programmes API

Prerequisites

For building and running:

• Docker
• Java 21

Additionally, for running scripts:

• kubectl (see Manage Infrastructure docs for further details)
• jq
• curl
• bash version 4.2 or later

Setup

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

./gradlew clean build

Running the application

The running application expects to connect to a PostgresQL database and an hmpps-auth instance. Use the docker-compose.yml file to pull and start these:

docker compose up hmpps-auth postgresql localstack

Then, to run the server:

./gradlew bootRunLocal

This runs the project as a Spring Boot application on localhost:8080

You can confirm that the application is running by querying an endpoint using one of the scripts in script/local-scripts. For example:

./script/local-scripts/all-courses

should output a nicely formatted JSON document containing information about courses.

Running/Debugging from IntelliJ

To run from IntelliJ, first start hmpps-auth, localstack and the postgresql database in Docker as above.

You may need to manually install the Java 21 SDK to run the application. We've used temurin-21 for this in most developer environments.

To set this, in the "Project Structure" window (File -> Project Structure), expand the SDK select, and if the version you need (e.g. temurin-21) isn't available, click Add SDK -> Download JDK..., then search for it and download it.

To then run the project, in the "Gradle" panel (View -> Tool Windows -> Gradle if not visible), expand hmpps-accredited-programmes-api, Tasks, application, right-click on bootRunLocal and select either Run or Debug.

Running the tests

Running localstack is necessary for gradle and intellij tests

docker compose up localstack

To run linting and tests, do:

./gradlew clean build

Repository integration tests use an embedded H2 database. REST API tests start a local server which listens on a random port, and spin up a containerised Postgres instance as a backend Database via the test containers API.

Pact

We use Pact for testing the interactions between the UI and API services:

• UI Course client tests
• UI Referral client tests

When the client tests are updated, the API tests need to be kept in sync, otherwise the build will fail. Test state is currently set up in an SQL migration file which retains state between tests, and is unfortunately very brittle. We would like to refactor this as soon as possible to set up and clear state between tests.

End to End Tests

We use Playwright for running our end to end tests. These are run against the deployed development environment on each merge to main. These tests log in with a test user account ACP_TEST, linked to one of the developers' email addresses. From time to time the password needs to be reset, causing the tests to fail. When this happens, we need to update the HMPPS_AUTH_PASSWORD environment variable set in the CircleCI project settings.

OpenAPI documentation

The API which is offered to front-end UI apps is documented using Swagger/OpenAPI.

This is available in development at http://localhost:8080/swagger-ui/index.html

There's currently a slight issue with one of the environments, so you may need to refresh a couple of times before the OpenAPI documentation loads.

Dependency updates

As with other MOJ projects, we use Renovate to automate dependency updates.

This will open PRs for us to update any outdated packages. We'll want to ensure the build is passing on these and ideally smoke test after merging to dev to ensure all is still working as expected. There may be some that require manual intervention to get working with our build.

HMPPS Gradle Spring Boot package

We may get reports of vulnerabilities in our dependencies through Trivy. Most of these can be resolved by updating the uk.gov.justice.hmpps.gradle-spring-boot package in build.gradle.kts, as the team managing that package have fixed them for us.