ONS Design System built CSS, JS, and Nunjucks templates
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.
``bash`
yarn add @ons/design-system
You'll need to install:
- Git
- Node.js
- Yarn (When installing yarn be sure to install yarn through brew using brew install yarn not using npm)
The version of node required is outlined in .nvmrc.
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.
1. install nvm
2. Run nvm install in the project directory (this will use .nvmrc)
`bash`
yarn install
yarn husky
`bash`
yarn start
Once the server has started, navigate to
This project uses LHCI.
`bash`
yarn global add @lhci/cli
yarn test-lighthouse
This project uses jest and supports its command line options.
`bash`
yarn test [jest-args]
Macros and units are tested in the Node execution environment whereas interaction tests are ran in the web browser using puppeteer.
`bash`
yarn test
Tests can be filtered using the testNamePattern jest argument.
To run all macro tests:
`bash`
yarn test --testNamePattern="macro:"
To run tests associated with a specific macro:
`bash`
yarn test --testNamePattern="macro: button"
To run all axe tests:
`bash`
yarn test --testNamePattern="axe"
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:
`bash`
yarn test --testNamePattern="base page template" -u
This will watch for changed files based on git uncommitted files.
`bash`
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.
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 new Promise(r => setTimeout(r, 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.
This project uses Backstop JS for visual regression testing. The tests run in Chrome headless using Puppeteer 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.
Generate a build into ./build.
`bash`
yarn build
Make sure you are logged into the CLI with the DS shared npm account
Make sure dependencies are installed:
`bash`
yarn install
Set the version (replacing "
`bash`
npm version
Create an NPM package by running:
`bash`
yarn npm-bundle
_Once you have published to npm, the version you have published can never be used again so you want to make sure you have the right files included to do this run:_
`bash`
npm pack
Then compare this list with the list of the current version here (https://www.npmjs.com/package/@ons/design-system?activeTab=code)
If these match or have some expected changes then run this to publish:
`bash``
npm publish --access public
- axe Accessibility Linter
- EditorConfig for VS Code
- ESLint
- Nunjucks
- Prettier - Code Formatter
- remark
- SonarLint
- Sass
- Stylelint