Skip to content

03-testing.md

Latest commit

 

History

History
179 lines (112 loc) · 5.86 KB

03-testing.md

File metadata and controls

179 lines (112 loc) · 5.86 KB
Raw

Testing

This guide is split into two sections:

  1. Running tests locally
  2. Testing with your application

Running tests locally

We have a number of different layers of tests:

  • Static analysis (linting, code-formatting)
  • Unit tests (jest for client-side code, rspec for ruby components)
  • Cypress tests (for behavioural tests as well as accessibility checks)
  • Backstop (for visual regression testing)

For development purposes we provide a top-level script to run all checks:

just check-all

This can take a while to run so is most useful to check your local environment and to run once you've finished developing a new feature. The rest of this guide covers the each type of check in more detail and how to run them individually.

Formatting

We provide a just command for formatting the codebase:

just format

You can check the formatting without making changes with just format-check

Prettier, Stylelint, Oxlint, and Jest

The repository is centred around a node module which is managed by the package.json at the top-level of the repository. This provides commands for running prettier against the project as well as linting (oxlint) and unit tests (jest) for client-side code.

All top-level package commands can be run using npm run:

Command Description
test Runs all jest tests
lint Runs all linting checks (prettier, oxlint, stylelint)
lint:css Runs only stylelint on the project code
lint:js Runs only oxlint on the project code
lint:format Run prettier --check on the project code
format Auto-format all eligible code with prettier

RuboCop

For ruby code we run rubocop checks against our engine, demo, and website directories. From any of these directories run:

rake rubocop

You can also run rake rubocop:autocorrect or rake rubocop:autocorrect_all to handle auto-corrections.

ERB Lint

We run erb_lint as templating lint check against our engine directory. From the engine directory run:

rake erb_lint

RSpec

We run a suite of RSpec tests against our engine directory. From the engine directory run:

rake spec

We use Appraisal for managing different gemfiles for older Rails versions as well as for testing new ViewComponent versions. You can run appraisals using:

bundle exec appraisal install

Followed by:

bundle exec appraisal rake spec

See the Appraisal docs for a full list of commands.

Cypress

We use Cypress for two main things:

  1. To run accessibility checks against every component example using cypress-axe
  2. For behavioural tests against any interactive components (e.g. targeted content) as well as end-to-end tests for the design system form builder.

You can run both from within the demo directory by either running:

./bin/rails cypress:open

Which will open the Cypress UI for interactive testing, or by running:

./bin/rails cypress:run

Which will run all tests in a headless browser.

BackstopJS

We use BackstopJS to automate visual regression testing of components by comparing DOM screenshots over time. The tests are run inside of Docker to ensure rendering consistency across different environments.

Firstly, run the demo app using:

./bin/rails server -e test

With the demo app running, you can start the backstop tests using:

npm run backstop

After a test run is complete you can run view the report in a browser using:

npm run backstop:report

If the test you ran looks good, then go ahead and approve it. Approving changes will update your reference files with the results from your last test. Future tests are compared against your most recent approved test screenshots.

npm run backstop:approve

You can run tests for a specific set of scenarios by passing a filter to the backstop command where Example is the search term you want to filter by.

npm run backstop -- --filter=Example

For more details see the BackstopJS Github page

Testing with your application

If you'd like to test design system changes locally with your own Rails application you can configure it to run against local copy of the design system.

You'll first need to check out a copy of this repository locally and follow the setup instructions.

The rest of the instructions assume that the design system has been checked out in the same parent directory as your project with the directory name design-system. If this is different you'll need to adjust the relative paths to suit your application.

You'll first need to change the path to the design system in your package.json to:

"@citizensadvice/design-system": "file:../design-system"

Then run npm install or yarn install depending on your project set up to install the local version of the node package.

You'll also want to change the path to the design system in your Gemfile to:

gem "citizens_advice_components", path: "../design-system/engine"

Then run run bundle install to install the local version of the Rails engine.

Following this you can run your application as normal to start using a local copy of the design system.

If you are making local changes to the design system you may need to restart your application to pick up any new changes.

Once you've finished testing remember to reset the change to your application's package.json and Gemfile respectively.

Read next

Release process →