Skip to content

README.md

Latest commit

 

History

History
295 lines (199 loc) · 8.29 KB

README.md

File metadata and controls

295 lines (199 loc) · 8.29 KB

pcs-frontend

Getting Started

Prerequisites

Running the application requires the following tools to be installed in your environment:

NVM

A better alternative to installing nodejs directly is to use a version manager like nvm then running the command:

nvm use

will ensure you are running the same version of node as determined in the CICD pipelines (it autodetects the .nvmrc file within this repository).

You can take this a step further and integrate auto-detection directly into your shell

Running the application

Runtime secrets are pulled live from the AAT key vault (pcs-aat) at startup via @hmcts/properties-volume, so you no longer need to copy secret values into .env by hand. Authenticate once with the Azure CLI:

az login

Any secrets declared in charts/pcs-frontend/values.yaml under nodejs.keyVaults.pcs.secrets are fetched on boot. To opt out (e.g. offline work, or if you don't have vault access), set USE_VAULT=false and populate the secrets in .env yourself — see .env.example for the test-user credentials that are still .env-only.

Install dependencies by executing the following command:

yarn install

If necessary, login to the hmctsprod ACR:

> az acr login -n hmctsprod

Redis and Wiremock run in a local Docker container; yarn start:dev now brings it up automatically (via the deps:up script) on first run and reuses the pcs-redis container on subsequent runs. If you prefer to manage it yourself:

> docker compose up -d
 ✔ Network pcs-frontend_default       Created                                                                                                                     0.0s
 ✔ Container pcs-frontend-cache-1     Started                                                                                                                     0.2s
 ✔ Container pcs-frontend-wiremock-1  Started

Development

Bundle:

yarn build

Run:

yarn start:dev

To run against a local PCS backend started from the pcs-api repository with:

./gradlew bootWithCCD

use the dedicated local script:

yarn start:dev:pcs-local

This points the frontend at the local services exposed by pcs:bootWithCCD:

Production

Bundle:

yarn build:prod

Run:

yarn start

The application's home page will be available at http://localhost:3209

Running with Docker

Authenticate to HMCTS ACR

The Docker images used by this service (both the application base image and the Redis image) are now hosted in the hmctsprod Azure Container Registry and require authentication.

Before running any Docker-based commands you must be logged in to hmctsprod:

az login            # if not already logged in
az acr login --name hmctsprod

You only need to do this once per Azure CLI session.

Create docker image:

yarn docker:login:hmctsprod
docker compose build

Run the application by executing the following command:

yarn docker:login:hmctsprod
docker compose up

This will start the frontend container exposing the application's port on 3209, and a redis instance on port 6379.

In order to test if the application is up, you can visit http://localhost:3209/ in your browser. You should get a very basic home page (no styles, etc.).

Developing

Code style

We use ESLint alongside sass-lint

Running the linting with auto fix:

yarn lint:fix

Running the tests

This template app uses Jest as the test engine. You can run unit tests by executing the following command:

yarn test

Creating IDAM users for tests

Use this command to create a temporary IDAM user:

yarn createIdamUser --roles=<ROLES> --email=<EMAIL> [--surname=<SURNAME>] [--forename=<FORENAME>]

where

  • --roles: is a comma separated list of user roles without spaces
  • --email: should not match any existing user's email ID
  • [--surname]: is optional - defaults to 'Test' if not supplied
  • [--forename]: is optional - defaults to 'User' if not supplied

For example, if you want to create an IDAM user with the email 'test@test.com', forename 'Dummy', Surname 'Casworker' and the roles 'citizen' and 'caseworker', use the following command:

yarn createIdamUser --roles=citizen,caseworker --email=testUser@test.com --surname=Caseworker --forename=Dummy

or with abbreviated param names and single role:

yarn createIdamUser -r=citizen -e=test2@test.com

Note: An auto-generated password will be output when the script runs.

The functional UI tests use Playwright, and the pr suite can be run with the following command:

yarn test:functional

By default, the tests will run against http://localhost:3209/, please update the value on line 7 of src/test/config.ts to change this.

There are also several custom test scripts available:

  • yarn test:changed - runs only changed spec files
  • yarn test:E2e - runs Playwright tests tagged @nightly for one browser/device project. Set PLAYWRIGHT_PROJECT (defaults to chrome if unset), for example: PLAYWRIGHT_PROJECT=firefox yarn test:E2e. Projects: chrome, firefox, webkit, edge, mobile-android, mobile-ios, mobile-ipad.

Stubbing Wiremock for local development

Wiremock is used locally to stub responses from other services, (just the Fee Service at the time of writing). To alter or extend the mappings, edit or add to the files in wiremock/mappings.

Ensure that you have run the docker compose command referenced earlier to get the wiremock container running locally.

See the Wiremock documentation for more details on how to create mapping files.

Security

CSRF prevention

Cross-Site Request Forgery prevention has already been set up in this template, at the application level. However, you need to make sure that CSRF token is present in every HTML form that requires it. For that purpose you can use the csrfProtection macro, included in this template app. Your njk file would look like this:

{% from "macros/csrf.njk" import csrfProtection %}
...
<form ...>
  ...
    {{ csrfProtection(csrfToken) }}
  ...
</form>
...

Helmet

This application uses Helmet, which adds various security-related HTTP headers to the responses. Apart from default Helmet functions, following headers are set:

There is a configuration section related with those headers, where you can specify:

  • referrerPolicy - value of the Referrer-Policy header

Here's an example setup:

    "security": {
      "referrerPolicy": "origin",
    }

Make sure you have those values set correctly for your application.

Healthcheck endpoint

The application exposes a health endpoint (http://localhost:3209/health), created with the use of Nodejs Healthcheck library. This endpoint is defined in health.ts file and currently checks the following components:

  • Redis
  • pcs-api

Info endpoint

The application also exposes an info endpoint (http://localhost:3209/info), created with the use of nodejs-info-provider library. This endpoint is defined in info.ts file and currently displays info from:

  • This service
  • pcs-api

License

This project is licensed under the MIT License - see the LICENSE file for details

The following environment variables are needed to run the tests:

  • NODE_CONFIG_ENV
  • TEST_URL
  • PCS_FRONTEND_IDAM_SECRET
  • IDAM_SYSTEM_PASSWORD
  • IDAM_SYSTEM_USERNAME
  • IDAM_PCS_USER_PASSWORD
  • DATA_STORE_URL_BASE
  • PCS_API_URL
  • PCS_API_CHANGE_ID