Skip to content

Commit f836f90

Browse files
authored
chore: add manual testing guide to storybook (#4015)
Because the process for running VRTs against the spectrum-two base branch differ from our automated system, this PR adds documentation to help developers through the process.
1 parent f654c8d commit f836f90

File tree

1 file changed

+79
-0
lines changed

1 file changed

+79
-0
lines changed
Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
import { Meta, Title } from "@storybook/blocks";
2+
3+
<Meta title="Visual regression testing" />
4+
<Title>Visual regression testing</Title>
5+
6+
This guide explains how to run visual regression tests using Chromatic for the `spectrum-two` branch.
7+
8+
## Prerequisites
9+
10+
Before running tests in Chromatic, you must have:
11+
12+
- Access to the Spectrum CSS project in Chromatic (request access from project maintainers)
13+
- A valid `CHROMATIC_PROJECT_TOKEN` in your local `.env` file, do not commit this file to version control as it contains sensitive information
14+
15+
## Set up your environment
16+
17+
### Install dependencies
18+
19+
From the project root, install all dependencies if you have not already done so:
20+
21+
```bash
22+
yarn install
23+
```
24+
25+
### Configure Chromatic access
26+
27+
Run `yarn refresh` to create or update your `.env` file with the necessary environment variables. Ensure the `CHROMATIC_PROJECT_TOKEN` is set correctly.
28+
29+
```bash
30+
CHROMATIC_PROJECT_TOKEN=your_project_token_here
31+
```
32+
33+
**Note:** Never commit the `.env` file to version control as it contains sensitive information.
34+
35+
Any global environment updates should be added to `.env.example`, which is used as a template. Tooling will always prefer your settings from `~/.env` if a variable exists there, but will fall back to the `.env.example` value otherwise. No other values from your local `.env` will be used unless it is explicitly set in `.env.example`.
36+
37+
## Running manual tests
38+
39+
### Basic test execution
40+
41+
Because the base branch is not `main`, VRT builds are kicked off locally. This makes the build available in the Chromatic UI in order to create a manual review. To get an up-to-date comparison of your branch against the base branch, run the following command on the branch you are testing.
42+
43+
```bash
44+
yarn test
45+
```
46+
47+
## Manual UI review
48+
49+
Chromatic's [Manual UI review](https://www.chromatic.com/docs/manual-ui-review/) feature allows you to compare visual differences between any pair of branches. This is particularly useful for feature branches based off of `spectrum-two`.
50+
51+
### Creating manual reviews
52+
53+
1. **Create a review**: Navigate to the Reviews page and click "Create review"
54+
2. **Select branches**:
55+
- **Base branch**: The branch we are comparing against (`spectrum-two`)
56+
- **Head branch**: The branch with changes (e.g., feature branch)
57+
3. **Generate review**: Enter a title (be sure to include the Jira ticket number if available) and click "Compare branches"
58+
4. **Post to the PR for review**: Copy the review URL and post it to the PR for validation
59+
60+
## Getting help
61+
62+
If you encounter issues not covered in this guide:
63+
64+
1. **Chromatic documentation**:
65+
- [Main documentation](https://www.chromatic.com/docs/)
66+
- [Manual UI review](https://www.chromatic.com/docs/manual-ui-review/) for branch comparisons
67+
- [Visual testing guide](https://www.chromatic.com/docs/visual/) for best practices
68+
2. **Project resources**:
69+
- Review existing test files in the project for examples
70+
- Check the GitHub issues for known problems
71+
- Contact the project maintainers for access and support
72+
3. **Community support**:
73+
- Chromatic's [Discord community](https://discord.gg/chromatic)
74+
- [GitHub discussions](https://github.com/chromaui/chromatic/discussions)
75+
76+
## Additional resources
77+
78+
- [Chromatic CLI documentation](https://www.chromatic.com/docs/cli)
79+
- [Storybook testing guide](https://storybook.js.org/docs/writing-tests)

0 commit comments

Comments
 (0)