pcs-frontend

Getting Started

Prerequisites

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

• Node.js v22.0.0 or later
• yarn
• Docker

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

Install dependencies by executing the following command:

yarn install

Development

Bundle:

yarn build

Run:

Get the secret value from the azure keyvault

PCS_FRONTEND_IDAM_SECRET=XXX S2S_SECRET=XXX OS_CLIENT_LOOKUP_SECRET=XXX yarn start:dev

Production

Bundle:

yarn build:prod

Run:

yarn start

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

Running with Docker

Create docker image:

docker-compose build

Run the application by executing the following command:

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 '[email protected]', forename 'Dummy', Surname 'Casworker' and the roles 'citizen' and 'caseworker', use the following command:

yarn createIdamUser --roles=citizen,caseworker [email protected] --surname=Caseworker --forename=Dummy

or with abbreviated param names and single role:

yarn createIdamUser -r=citizen [email protected]

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
• test:E2eChrome - runs the full E2E suite in Chrome
• test:E2eFirefox - runs the full E2E suite in Firefox
• test:E2eSafari - runs the full E2E suite in Safari

Running accessibility tests:

yarn test:accessibility

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:

• Referrer-Policy
• Content-Security-Policy

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