ONS Design System

Installing as a dependency

Nunjucks macros for components and templates are available from npm. Built CSS and JS is also available if you need access to pre-release CSS/JS, otherwise CSS and JS should be loaded from the CDN.

yarn add @ons/design-system

Run Locally

You'll need Git, Node.js, and Yarn to run this project locally.

The version of node required is outlined in .nvmrc.

Using nvm (optional)

If you work across multiple Node.js projects there's a good chance they require different Node.js and npm versions.

To enable this we use nvm (Node Version Manager) to switch between versions easily.

install nvm
Run nvm install in the project directory (this will use .nvmrc)

Install dependencies

yarn install
yarn husky install

Start a local server

yarn start

Once the server has started, navigate to http://localhost:3030

Testing - macros and scripts

This project uses jest and supports its command line options.

yarn test [jest-args]

Run macro, unit and in-browser interaction tests

Macros and units are tested in the Node execution environment whereas interaction tests are ran in the web browser using puppeteer.

yarn test

Run specific tests

Tests can be filtered using the testNamePattern jest argument.

To run all macro tests:

yarn test --testNamePattern="macro:"

To run tests associated with a specific macro:

yarn test --testNamePattern="macro: button"

To run all axe tests:

yarn test --testNamePattern="axe"

Snapshot test for base page template

There is a snapshot test of the base page template that runs alongside the component tests. The snapshot will need to be updated if the base page template is changed.

To update the snapshot:

yarn test --testNamePattern="base page template" -u

Run tests locally in watch mode

This will watch for changed files based on git uncommitted files.

yarn test --watch

Note: This command is of limited use since JavaScript and SCSS files will only be processed and bundled once each time the above command is ran. This command is only useful when working on JavaScript units that can be tested without bundling.

Testing tips

It is sometimes useful to adjust the following settings when writing tests or diagnosing issues:

headless in 'jest-puppeteer.config.js' - when set to false will show web browser whilst running tests. Many browser windows open since jest runs tests in parallel so it is useful to also adjust the test script inside 'package.json' such that it targets a specific test file. await page.waitForTimeout(100000) can be temporarily added to a test to allow yourself time to inspect the browser that appears.
testTimeout in 'jest.config.js' - set to a high value such as 1000000 to prevent tests from timing out when doing the above.

Testing - Visual regression tests

This project uses Backstop JS for visual regression testing. The tests run in Chrome headless using pupeteer inside docker and run in three viewports; 1920 (desktop), 768 (tablet) and 375 (mobile). Reference images are stored in Git LFS and any approved changes will automatically be stored in Git LFS when pushed to the repository.

The visual tests will run automatically on pull requests and the result will be available in the Github Action logs. If the tests fail, the process for viewing the failures and approving changes will need to be handled locally using the following workflow and commands.

The first time you run the tests locally you will need to install Git LFS on your machine. Follow the install instructions for Git LFS.

You will need to have Docker installed and started locally. We are using Docker as there are font rendering issues that caused failures across different os versions when we run the tests in CI. There is further information on this in the Backstop JS docs.

Checkout the branch locally and run:

git lfs fetch - This downloads the files into your .git/lfs if you have never run vr test locally.

git lfs checkout - This will pull the current reference images from the repository for you to test against.

yarn test-visual - This will run the same tests locally as were run in Github Actions. After they have completed the report will open in your default browser.

yarn test-visual:approve - This will approve the failures/diff caught by the tests.

git lfs push --all origin - First commit the files in the normal way then run the command. This will push the new reference images to Git LFS.

You can then commit and push the updated references and your changes to your branch. The test images that would have been created when you ran yarn test-visual are gitignored and the new references images will be pushed to Git LFS.

If your local tests are failing but you have approved them, run yarn test-visual:reference. This will update the reference images locally on your machine.

Build

Generate a build into ./build.

yarn build

ONSdigital/design-system