Spiderplan 🕷️

Does whatever a Spiderplan can

A test runner that crawls over your CASA Plan to provide assurance that it's working as it should.

Features:

• Traverses an end-to-end journey across your service in seconds (or less)
• Tests journeys through the eyes of real users
• Run exactly the same tests for all supported languages
• Executes your whole application middleware/route stack for a true reflection of interactions
• Supports concurrent test execution across multiple threads
• Reports include a coverage indicator, listing any waypoints you may have missed from your Plan
• When a field selectors doesn't work, a list of suggested CSS selectors will be presented for you to try instead
• Supports a plugin mechanism to extend functionality

This is not a replacement for browser testing as, for performance reasons, it will not execute any JavaScript, or take into account any CSS rendering. Its intent is to get through a user journey as efficiently as possible so that journey, error and content tests can be completed quickly and at scale. For the majority of services this should be sufficient as services should not be reliant on JavaScript as per the GOVUK Service Standards.

Pre-requisites

• NodeJS 18+

Getting started

Install the tool:

npm i -DE @dwp/casa-spiderplan

There's quite a bit of initial setup required, but once done your efforts are rewarded with a super-simple way to write tests.

Our setup guide takes you through the steps from the point of view of an example CASA application.

Writing tests

Tests generally comprise of two parts:

• A Persona describing a journey through your Plan
• One or more nunjucks templates describing the expected content for each page in that journey

And at the end of each test you will have coverage for:

• The routes between waypoints
• Confirmation that errors are triggered when given certain inputs
• Error messages
• Page content

Read through our documentation for Personas and Nunjucks to get started.

Running tests

Assuming you have installed the tool locally, you can execute your Personas using something like this:

# Runs all Personas found in the `./personas/` directory tree.
# Note that it's important to encapsulate any glob paths in quotes.
./node_modules/.bin/casa-spiderplan --worker-init bootstrap.js --language en './personas/**/*.yaml'

Plugins

The test runner supports a number of hooks at key points of the test lifecycle. These can be used to create plugins that alter or enhance the behaviour of those tests.

Read our guide on how to create your own plugins, or check out some others already available:

• ZAP
• A11Y