This is an API project that exposes an interface for integrating with the Public Protection Unit Database (PPUD). Rather than speak to the PPUD database, it uses Selenium to automate the PPUD UI in order to perform its operations.

The runbook can be found in this repo in the docs/runbooks folder.

Docker desktop needs to be installed

Firefox needs to be installed. Currently, the service does not work with versions after 120, but an upcoming fix to Selenium should address that. When running in a Docker container, the service uses the Extended Support Release (ESR) version of Firefox, so it is advisable to use that version for local testing.

The project uses the following environment variables, which need to be set in order to run the tests or run the application.

• PPUD_USERNAME - your username for logging in to PPUD. For the Internal Test instance of PPUD, the user should belong to the Recall 1 team and be Level 5.
• PPUD_PASSWORD - password for your PPUD account
• PPUD_ADMIN_USERNAME - a username for logging in to PPUD to perform admin functions such as retrieving reference data values. For the Internal Test instance of PPUD, the user can be the same as the non-admin user.
• PPUD_ADMIN_PASSWORD - password for admin PPUD account

The following additional environment variables can be used if required.

• PPUD_URL - the URL of the PPUD application. If not set, defaults to "https://internaltest.ppud.justice.gov.uk"
• AUTOMATION_HEADLESS - set this to false if you want to view browser interactions. If not set, defaults to true.
• AUTOMATION_FIREFOX_BINARY - set this to the path of your Firefox binary if it is not automatically detected (probably not needed locally)

Run the following to start Redis for caching

docker-compose up redis

Start the service in IntelliJ

The service will use the Auth service in the Dev environment, so tokens can be obtained by using the client ID and secret for a calling service (i.e. make-recall-decision-api).

The project uses a couple of testing levels - unit testing and integration testing.

Unit tests can be run without external dependencies.

The integration tests connect to a running instance of PPUD in order to verify that the automation works correctly.

Run the following to start Redis for caching

docker-compose up redis

Run the following script to run all the integration and unit tests locally:

./gradlew check

or to run linting followed by all tests, similar to running in CI, use:

./build.sh

In order to inject a level of independence and avoid clashes with other tests that might be running, the integration tests create offenders to use in each test.

These offenders can be identified because their family name is "FamilyName-", where is an identifier for a particular test run. At the end of the test run, the matching offenders are deleted automatically.

Occasionally, something may happen that means the offenders do not get deleted. This would typically be running tests locally and stopping them before they get a chance to tidy up. Perhaps when stepping through to debug something.

Therefore, every so often, it's worth checking that there aren't any "FamilyName-" offenders in PPUD, and deleting any that do exist. They may cause test failures at some point if there is a prison number clash.

The service is set up to use Firefox as the browser, along with its associated WebDriver implementation, geckodriver. It isn't necessary to install geckodriver explicitly as this is managed using WebDriverManager.
WebDriverManager detects and installs the correct driver for the installed browser version.

When running in a Docker container, the "Extended Support Release (ESR)" version of Firefox is used, which is a few versions behind the latest version and changes less frequently. In the docker container, the path to the browser binary needs to be set in the environment variable AUTOMATION_FIREFOX_BINARY. This is not normally necessary locally.

The Firefox version is specified explicitly in the CircleCI config.yml and will need updating as and when a new ESR version is released.

Chrome has also been used for the service locally on a Mac, but this could not be installed in the docker container because a matching installation was not available.