This repo contains the source code for the MOD.UK Frontend guidance website.
The library uses Eleventy, Sass, ESLint, Stylelint, dprint and commitlint. Git hooks (via Husky and lint-staged) are used for enforcing linting and formatting rules.
The unit test suite uses Vitest and Testing Library.
The end-to-end test suite uses Playwright. Tests are run across a variety of browsers and configurations against a local web server that serves examples of components. This includes accessibility checks using axe and visual regression tests.
Local development requires Node.js 16 or 18 and npm 8 or newer.
-
Clone the repository via SSH:
git clone [email protected]:defencedigital/moduk-frontend-guidance-site.git cd moduk-frontend-guidance-site
If you haven’t set up an SSH key for GitHub, you can clone via HTTPS instead:
git clone https://github.com/defencedigital/moduk-frontend-guidance-site.git cd moduk-frontend-guidance-site
-
Install dependencies:
npm install
-
Install Playwright browsers and system dependencies:
npm run playwright-install
-
Install Podman using the instructions for your platform.
Podman is required only for running visual regression tests.
-
Ensure jq is installed. On macOS it can be installed using Homebrew:
brew install jq
jq is required only for running visual regression tests.
npm start
npm run lint
npm run format
npm test
npm run test:e2e
This runs end-to-end tests using Playwright for all configured browser configurations. The Eleventy dev server is started automatically, and so does not need to be started separately.
npm run test:e2e <regex>
You can also use test.only
or test.desribe.only
within a test file to run
only that test (and any other tests using .only
).
npm run test:e2e:trace
Playwright traces record failed tests for debugging later, or on a different machine.
You can also debug tests using VS code, or by using the built-in inspector debugger.
Visual regression tests run in a container, using Podman, to ensure screenshots are taken in a consistent environment.
To run the visual regression tests:
npm run test:visual
This will also generate any missing screenshots.
To update any screenshots that have changed:
npm run test:visual:refresh
To delete all existing screenshots:
npm run test:visual:clean
This can be useful after renaming or deleting visual regression tests or component examples.
npm run build
The built site is output to the dist
directory.
podman build --tag moduk-frontend-guidance-site .
podman run --rm -p 8080:8080 -it moduk-frontend-guidance-site
The server will then be available at http://localhost:8080.
The BASE_URL
environment variable can be set at build time to override the
base URL of Open Graph images specified in <meta>
tags. If not set, it
defaults to using the images on the production site.
The NO_INDEX
environment variable can be set at build time to add a noindex
<meta>
tag to all pages.
Some styles and markup are based on the GOV.UK Design System website.