Creating test pages
Note: this page is a fully executable spec for the options it demonstrates. If you are reading this on GitHub, it will render the page nicely and hide all the technical details, so check out the raw markdown to see the actual test configuration.
Appraise makes it easy to create executable specifications for visual examples. It works by extracting inputs and expected outputs from a Markdown file, passing the inputs to a system under test, taking a screenshot of the result, and comparing the actual outcome to the expected results. This means that you need to define three components for a test:
- The input (parameters of the example), normally some human-readable text, JSON, YAML or something else that will tell your system under test what to do.
- The expected output, as a PNG image.
- The fixture -- a piece of code helping Appraise connect to the system under test, and explaining how to execute the input.
Setting the input parameters
To set the input parameters for an example, create a fenced code block and use the
example="<SOME NAME>" in the header of the block to identify the example.
width: 80 height: 100 path: M10,10L70,90 color: blue
You can have more than one example on the same page, but make sure that each example has a unique name.
Setting the expected output
To define the expected output, link to a PNG image, and use the name of the related example as the image name:
The expected image can be anywhere in the page, even before the example inputs. The link between the inputs and expected outputs is the name of the example.
Additionally, you can start without an expected output. The first time when you run a test, it will fail and offer to record the current result as the expected output for the next time.
Setting the fixture
Normally, for a set of related examples, you use the same fixture, as they all go through the same execution workflow. You can set the fixture for all the examples on a page in the YAML preamble of the Markdown file, using the
fixture keyword. This page uses a simple SVG Path fixture, from fixtures/path.js.
For more information on writing fixtures, check out the page documenting Fixture types.
You can customise many execution attributes for each example, such as using a different fixture or setting a clip region. Check out the Customising Execution guide for more information on that.