Skip to content

Latest commit

 

History

History
162 lines (96 loc) · 8.29 KB

testing.md

File metadata and controls

162 lines (96 loc) · 8.29 KB
Raw

Test your GOV.UK Frontend contribution

Before you submit your contribution to GOV.UK Frontend, you should:

  • fix any CSS or JavaScript style errors
  • check your changes look right and behave correctly
  • test your changes in supported browsers and assistive technology
  • run the automated tests
  • update the tests or add new tests if you need to

Let us know in your pull request or contact us if:

  • you cannot do some of the checks or tests
  • your contribution might affect other parts of GOV.UK Frontend

1. Fix any CSS or JavaScript style errors

In your project folder, run npm run lint.

Fix any CSS or JavaScript style errors that the linting tests report.

2. Fix any invalid HTML

To make sure your HTML markup is valid, check your page with W3C's markup validator.

You should also check your HTML markup is valid after JavaScript has modified it. To make sure, check your page with W3C's 'Check serialized DOM of current page’ bookmarklet.

You should use the bookmarklet if:

  • your page has a lot of JavaScript
  • you can only check your page when you've logged in to a site

If you can, fix any errors or warnings reported by either the validator or bookmarklet.

You do not need to fix any known issues with our components reported by either the validator or bookmarklet.

If you need help with fixing an error or a warning, leave a note in your pull request or contact the Design System team.

3. Check your changes in the ‘review app’

In your project folder, run npm start, then go to http://localhost:3000/ in your browser to open the 'review app'.

Check that:

  • the examples in the review app look right and behave correctly with your changes
  • your design is consistent with the rest of GOV.UK Frontend

Add an example

You should add an example to the review app if the existing examples do not reflect the changes you've made.

  1. Open packages/govuk-frontend/src/govuk/components/<COMPONENT>/<COMPONENT>.yaml, where <COMPONENT> is the component you've changed.
  2. Add or update examples in the examples list.

If you've created a new component, create a new packages/govuk-frontend/src/govuk/<COMPONENT>/<COMPONENT>.yaml file instead, where <COMPONENT> is the name of the component you've created.

4. Test in supported browsers and assistive technology

You should test that your contribution works:

5. Run the automated tests

Automated testing helps ensure that the code changes we make do not unintentionally break functionality. Tests are automatically run against a branch, pull request, or when the project is built for release, and will notify us if a test has failed.

In your project folder, run npm test to run the automated tests and npm run lint for linting checks.

If a test fails, you should check your code for any errors, then update any tests you need to.

6. Write new tests

You can read more about the different types of tests in this project.

You should write new tests if you’ve created a new component, or changed the way a component works by:

  • changing or adding to the component's JavaScript code
  • changing or adding to the component's Nunjucks macro
  • creating or updating a Sass mixin or function

If you're new to testing, see existing test files for examples of things to do. Do not let the tests keep you from submitting your contribution! If you're not sure which tests are needed or are having trouble updating them, submit your pull request anyway. We will help you create the tests and solve problems during code review.

Some test files use examples from each component’s .yaml file, for example packages/govuk-frontend/src/govuk/components/button/button.yaml. When you add or update these tests, you can use the existing examples or add new ones.

Use hidden: true in a new example if you do not want to include the example in the review app. The example will still appear in our test fixtures.

All tests should try and meet our testing conventions

If you created a component

Create the following files in the packages/govuk-frontend/src/govuk/components folder:

  • <COMPONENT>/<COMPONENT>.test.js - to test functionality if the component uses JavaScript
  • <COMPONENT>/<COMPONENT>.unit.test.mjs - to unit test any JavaScript logic
  • <COMPONENT>/template.test.js - to test the Nunjucks macro

Where <COMPONENT> is the name of the component you created.

You can use the existing files in the packages/govuk-frontend/src/govuk/components folder as templates for your new files.

If you changed or added to a component

In the packages/govuk-frontend/src/govuk/components folder, update or add tests to:

  • <COMPONENT>/<COMPONENT>.test.js - if you updated functionality
  • <COMPONENT>/<COMPONENT>.unit.test.mjs - if you updated JavaScript logic
  • <COMPONENT>/template.test.js - if you updated the Nunjucks macro

Where <COMPONENT> is the name of the component you changed or added to.

If you created or updated a Sass mixin or function

Update or add tests in the .test.js file that matches the name of the .scss file you created or updated. Create the .test.js file if it does not exist.

For example, if you updated a mixin in packages/govuk-frontend/src/govuk/helpers/_colour.scss, update or add tests in packages/govuk-frontend/src/govuk/helpers/colour.test.js.

7. Update the snapshot tests

If your component uses another component, one of the Jest snapshot tests may fail. Snapshot tests compare a component's current markup with a previously stored version.

If a snapshot test fails, follow these steps.

  1. Check that the component's new markup is correct.
  2. Run npm test -- -u packages/govuk-frontend/src/govuk/components/<COMPONENT> to update the snapshot test with the new markup.
  3. Commit the updated file in the /packages/govuk-frontend/src/govuk/components/<COMPONENT>/__snapshots__/ folder.
  4. In the commit message, tell us you're updating the snapshot file and why.

Where <COMPONENT> is the name of the component you've changed.

8. Test that your changes work in the GOV.UK Design System (optional)

To make sure your changes work in the Design System, use npm link to test before publishing, as follows:

cd ../govuk-design-system
git checkout main
git pull
npm ci # note running `npm ci` after `npm link` will destroy the link.
npm link ../govuk-frontend/packages/govuk-frontend/

When you've finished testing, run this command to unlink the package:

npm unlink ../govuk-frontend/packages/govuk-frontend/

9. Tell us what you’ve tested and checked

When you create the pull request for your contributions, list what you’ve tested and checked in the pull request description.

If your contribution changes how a component looks, include before and after screenshots if you can.

If GitHub shows that some checks were not successful

At the bottom of your pull request in GitHub, find the checks marked as Failing.

For each failing check, select 'Details' and use the build log to find the problem and fix your code.