|
| 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