Schedule Storybook Screenshots with Loki: A Guide

This guide walks you through setting up automated, scheduled screenshot testing for your Storybook components using Loki. You’ll learn how to configure Loki to capture visual snapshots of your stories and run them on a schedule (e.g., nightly via CI), so you catch UI regressions without manual effort. By the end, you’ll have a repeatable process that integrates into your existing workflow.

What You’ll Need

A Storybook project (v6 or later) with stories for the components you want to test.
Node.js and npm (or yarn) installed.
A CI service (like GitHub Actions, GitLab CI, or CircleCI) if you want scheduled runs; otherwise, you can use a local cron job.
Basic familiarity with the command line and editing configuration files.

Step-by-Step

Install Loki
In your project root, run: npm install --save-dev loki (or yarn add --dev loki). This adds Loki and its dependencies to your devDependencies.
Configure Loki
Create a loki.config.js file in your project root. At minimum, specify the Storybook configuration directory and the target browsers. A basic config looks like:
```
module.exports = {
  configurations: {
    'chrome.laptop': {
      target: 'chrome.app',
      width: 1366,
      height: 768,
    },
  },
};
```
You can also define multiple configurations for different viewports.
Add a Storybook Static Build
Loki needs a static version of your Storybook to capture screenshots. Add a script to your package.json to build Storybook: "build-storybook": "build-storybook -o .out" (adjust the output folder as needed). Run it once to ensure it works.
Create a Baseline
Before scheduling, you need a baseline set of screenshots to compare against. Run npx loki update to generate initial screenshots for all stories. This creates a __loki__ folder with reference images. Commit these to your repository.
Test Locally (Optional)
Run npx loki test to verify Loki works and that your baseline is correct. It should pass with no diffs.
Set Up a Schedule in CI
Choose your CI platform. For GitHub Actions, create a workflow file (e.g., .github/workflows/loki-schedule.yml) with a schedule trigger using cron syntax. Example:
```
on:
  schedule:
    - cron: '0 2 * * *'  # runs at 2 AM UTC daily
```
For GitLab CI, use schedule in your .gitlab-ci.yml with a cron-like rule. For CircleCI, use a scheduled pipeline.

Add the Loki Job Steps
In your CI job, set up the environment (Node, Chrome), install dependencies, build Storybook, and run Loki. A typical GitHub Actions job:

jobs:
  loki:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm ci
      - run: npm run build-storybook
      - run: npx loki test --requireReference

The --requireReference flag ensures that a reference exists for every story; if not, the test fails.

Handle Failures
If Loki finds visual diffs, the CI job fails. You can add a step to upload the diff images as artifacts (e.g., using actions/upload-artifact) so you can review them.
Update Baseline When Needed
When you intentionally change a component’s appearance, you need to update the baseline. Run npx loki update locally (or in a CI job with a manual trigger) and commit the new screenshots.

Common Mistakes

Forgetting to build Storybook before running Loki. Loki needs the static files; always run build-storybook first.
Not committing the baseline screenshots. If you don’t commit the __loki__ folder, CI won’t have a reference to compare against.
Using a browser that isn’t installed in CI. Loki uses Chrome by default; ensure your CI image has Chrome or use a Docker container that includes it.
Ignoring the --requireReference flag. Without it, new stories won’t be tested, and you might miss regressions.
Running Loki on a schedule but not on pull requests. If you only run scheduled tests, regressions may go unnoticed for a day. Consider also running on PRs for immediate feedback.

Tips

Use a dedicated viewport set. Test both desktop and mobile widths to catch responsive issues.
Keep the baseline small. Only include stories that are stable and unlikely to change frequently, to avoid constant baseline updates.
Use Loki’s --diffMethod options. For example, --diffMethod pixelmatch gives more sensitive pixel-level diffing, while --diffMethod blur is more tolerant to small shifts.
Integrate with your notification system. Have CI send alerts (e.g., Slack) when the scheduled test fails, so you don’t have to check manually.
Run Loki in a Docker container. This ensures a consistent browser environment across local and CI, reducing flaky diffs.

Troubleshooting

Loki says “No reference found” – This means the story is new or the baseline is missing. Run npx loki update to create references, then commit them.
Chrome fails to launch in CI – Install Chrome in your CI environment or use a pre-built Docker image that includes it. For GitHub Actions, you can use actions/setup-chrome or a container like browserless/chrome.
Diffs appear even though nothing changed – This can be due to font rendering differences or animations. Try using --diffMethod blur or add --disableAnimations to your Loki config to stabilize screenshots.
The scheduled job doesn’t run – Check your cron syntax and timezone. For GitHub Actions, the schedule is in UTC by default. Also ensure the workflow file is in the default branch.
Loki runs locally but fails in CI – Often due to missing system dependencies or different Chrome versions. Use a Docker container with a pinned Chrome version to match your local setup.

Frequently Asked Questions

Can I run Loki without a CI service?

Yes, you can use a local cron job (e.g., crontab on Linux/macOS) to run the same commands. However, CI is more reliable and provides a central place for results.

How do I exclude certain stories from Loki?

Use the skip option in your story’s parameters or in the Loki config. For example, in a story file: export default { parameters: { loki: { skip: true } } }.

Does Loki work with Storybook v7?

Yes, Loki supports Storybook v7. Make sure you use a recent version of Loki (v0.30+). If you encounter issues, check the Loki GitHub issues for known compatibility notes.

Can I test multiple browsers with Loki?

Yes, you can define multiple configurations in loki.config.js, each targeting a different browser (e.g., chrome, firefox, webkit). Note that you’ll need those browsers installed in your CI environment.

What is the difference between `loki test` and `loki update`?

loki test compares current screenshots against the baseline and reports differences. loki update overwrites the baseline with new screenshots. Use update only when you intentionally change the UI.

How do I see the actual diffs?

Loki generates diff images in the __loki__/diff folder. In CI, you can upload these as artifacts. Locally, you can open them in your browser or image viewer.

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.

More cards in this drawer

The whole Numbers and Powers drawer →