govuk_publishing_components: Testing components
Tests directory structure
As per Rails convention, most of the directories within the
spec directory contain Ruby unit tests with the directories matching those within the
app directory. Code that is stored in the
lib directory has corresponding tests in the
spec that don’t contain Ruby unit tests are as follows:
dummy- contains a generic frontend application to test the gem with;
dummy_gem- required to test the component auditing;
features- contains feature tests, which test that a user can accomplish a task by interacting with a component;
support- contains helper files for shared test methods and logic;
visual_regression_tests- contains the visual regression test runner.
The purpose of these tests is to test individual units of the system in isolation. They are intended to provide exhaustive tests of the code paths through a particular class or view through its public interface. As per the test pyramid approach to software testing, these should provide the greatest volume of tests for the library.
Characteristics of unit tests:
- they should be concerned with the logic within the class/view being tested, and not test logic defined elsewhere;
- they may mock dependent objects and/or assert that particular external methods are called;
- they should test all code paths through a class/view;
- they should follow the conventions of RSpec Rails view tests.
The purpose of these tests is to assert that a user can accomplish a task through interacting with components (for example switching a tab or opening an accordion section).
This type of test provides a high level functional test and helps to validate that a user can use a component to complete the tasks they use it for. This makes these tests some of the most valuable of the application, however they are slower than other tests to run and can be difficult to debug. Therefore they are not intended to exhaustively test all the scenarios that can occur as part of a distinct feature.
Characteristics of feature tests:
- they should navigate the application through the web interface with a minimal amount of set-up and direct visiting of links, for example most navigation should be achieved by user clicking;
- they may mock and/or assert that particular API calls are made to external services.
If you create a component in the application, you can run accessibility tests against it.
The gem includes integration tests to check that your component guide and examples are error free and that they meet basic accessibility needs.
Automated accessibility tests use aXe. Using our
You can set this up by adding the following integration test.
# test/integration/component_guide_test.rb require 'govuk_publishing_components/minitest/component_guide_test' class ComponentGuideTest < ActionDispatch::IntegrationTest include GovukPublishingComponents::Minitest::ComponentGuideTest end
(There's no RSpec variant for this yet, PRs welcome)
Exclude accessibility rules
Sometimes you will have a component that will throw an error due to it being in isolation, for example radio buttons not being in a fieldset.
For this case you can add
accessibility_excluded_rules to your components' documentation yml file with the rules you want to exclude. These rules can be found in brackets in the error messages displayed.
For an example of this check test-component-with-duplicate-ids.yml
Visual regression testing
Visual regression tests are run on each pull request using a third-party tool called Percy using a GitHub Action workflow. This isn't a mandatory check, so any changes that are highlighted by Percy won't prevent a pull request from being merged in.
The screenshots are public, so they can be checked without logging in. A BrowserStack account is needed to approve or reject any changes. It's the responsibility of the person reviewing the pull request code to approve any visual changes that Percy highlights.
Relevant Percy setup documentation: