How to Update Loki Reference Screenshots Without Hiding Real UI Changes
Review Loki’s current screenshots and diffs before approving a baseline update. This guide covers safe approvals, CI safeguards, troubleshooting, and alternatives.
Update Loki reference screenshots only after reviewing the screenshots from the latest run and deciding that each visual change is intentional. The safe sequence is: run yarn loki test, inspect the rendered screenshots and differences, fix unintended changes and rerun, then run yarn loki approve for changes you mean to keep.
Approval replaces reference images with images generated in the last run and can prune outdated references. Treat it as a review decision, not routine cleanup. Loki documents --diffOnly for limiting approval to tests that failed the preceding run; it does not decide whether those changes are correct.
1. Understand what Loki is comparing
Loki captures Storybook stories and compares the resulting screenshots with committed reference images. A test can report a difference when the UI changed, but also when the capture environment, fonts, browser, timing, or assets changed. A visual diff is a signal to investigate; it does not tell you whether the change is intended.
The Loki documentation describes a workflow of starting Storybook and any required simulator or emulator, creating initial references with yarn loki update, making UI changes, testing with yarn loki test, reviewing the output, and approving intended changes with yarn loki approve. See the Loki project README and its Getting Started guide. Check commands and defaults against the Loki version pinned by your project.
2. Review and update references safely
- Start the capture environment. Run Storybook and any simulator or emulator your selected target requires. Loki does not start these for you. Use the same target and relevant environment settings as the run you intend to compare.
- Run the comparison. Execute
yarn loki test. If this is the first reference set, create it withyarn loki updateas described in the project setup instructions. - Inspect the rendered output and visual differences. The Getting Started guide describes screenshots in
loki/currentand differences inloki/difference. Those are documented examples; output locations can differ with version and configuration. Inspect the actual output paths for your project. - Classify each difference. Confirm that the changed appearance matches the intended product change. Check for missing assets, font loading, viewport or browser changes, animation, and capture timing when the result is unexpected.
- Fix unintended changes. If a diff shows a regression or a flaky capture, do not approve it. Correct the UI or test setup and run
yarn loki testagain. - Approve only reviewed changes. Once you decide the new appearance is correct, run
yarn loki approve. Review the staged or untracked reference-file changes afterward; approval can prune outdated references. - Commit code and references together. Loki’s guide recommends checking reference images into Git. Keeping the implementation change and its approved screenshots in the same review lets reviewers evaluate them together. Git LFS is an optional storage choice.
# Start Storybook in a separate terminal, using your project's configured script.
# Then run the visual comparison:
yarn loki test
# Inspect the configured current screenshots and difference images.
# If every approved visual change is intentional:
yarn loki approve
# Review the code and reference image changes together before committing.3. Choose full approval or diff-only approval
The CLI documentation describes loki approve as updating references from images generated in the last run and pruning old references. The --diffOnly option limits approval to files that failed the previous test run. Consult the Loki CLI reference for your installed version before relying on exact options or defaults.
| Choice | Use it when | Review implication |
|---|---|---|
yarn loki approve |
You reviewed the run and intend to update the references it generated. | Review the full reference-file change set, including removals or replacements. |
yarn loki approve --diffOnly |
You want approval limited to tests that failed the preceding test run, and your Loki CLI version supports this option. | Every affected failure still needs human review. A smaller approval scope is not evidence that a change is safe. |
Do not use approval as a way to make a failing comparison green without understanding it. If the test failed because of a real regression, preserve the existing reference and fix the implementation.
4. Make CI fail when references are missing
Loki’s CI documentation describes --requireReference, which makes tests fail if a reference is missing. This helps catch an absent baseline instead of silently treating a new capture as an accepted expectation. Follow the CI pattern documented for the Loki version you use, including its static Storybook build and test setup: Loki CI documentation.
# Example shape only: use your project's actual build and Storybook scripts.
yarn build-storybook
yarn loki test --requireReferenceRun baseline updates deliberately, review the resulting image changes in the pull request, and keep reference updates out of unrelated changes where practical. CI should test against known references; a developer should approve a changed baseline after reviewing it.
5. Account for capture targets and environment differences
The Loki README lists Chrome in Docker, Chrome in AWS Lambda, local Chrome, iOS simulator, and Android emulator among its targets, and lists Node 16+ as a prerequisite. These details are version-sensitive: verify the requirements and supported targets for the version pinned in your repository. The CLI documentation calls Docker Chrome recommended, but the right target depends on the project and environment.
- Web stories: Keep browser, viewport, fonts, dependencies, and relevant environment settings consistent between reference generation and CI.
- Mobile stories: Start the simulator or emulator required by the selected target before capture. Differences in OS or simulator configuration can affect rendering.
- Timing-sensitive stories: Ensure content and assets have loaded before capture. Investigate animation, network-dependent content, and transient state if repeated runs disagree.
- Large reference sets: Review which files changed and consider Git LFS if repository storage needs it. The Loki guide describes Git LFS as optional.
6. Troubleshoot unexpected diffs
| Symptom | Likely cause | What to check |
|---|---|---|
| Many unrelated stories changed | Capture environment or shared dependency changed, such as browser, fonts, OS, or Storybook build. | Compare the local and CI target, dependency lockfile, browser setup, viewport, and shared styles. Restore consistency, then rerun. |
| Text wraps differently | A font failed to load, a font version changed, or the viewport differs. | Confirm the intended font is available before capture and compare viewport and browser settings. |
| Images or remote content are missing | Assets were unavailable or had not loaded when the screenshot was captured. | Check asset paths and network access, and ensure the story reaches a stable loaded state before capture. |
| The same story changes between runs | Animation, time-dependent content, random data, or asynchronous loading makes the story nondeterministic. | Make story data deterministic, stabilize time-dependent state, and wait for required content. Rerun before considering approval. |
| Approval includes unexpected files or removals | Approval uses images from the last run and may prune outdated references. | Review the full diff before committing. Use --diffOnly only if supported and appropriate, and inspect every changed file. |
| CI reports a missing reference | The baseline was not committed, the story or reference identity changed, or the reference path/configuration differs. | Check the committed reference files and Loki configuration. Create or approve a reference only after reviewing the intended screenshot. |
| The command or option is unrecognized | The project’s Loki version differs from the documentation version or script configuration. | Check the installed version and its CLI help or version-matched documentation before changing scripts. |
7. Performance, reliability, and storage considerations
Screenshot capture cost in developer time grows with the number of stories and with how often the capture environment varies. Keep runs reproducible, avoid unnecessary baseline churn, and inspect changed-file scope so reviewers can focus on the relevant differences. The supplied Loki documentation does not establish universal runtime or accuracy benchmarks, so measure performance in your own CI environment.
For reliability, treat the reference set as version-controlled test input. Pin dependencies and use a consistent capture target where possible. A passing comparison is useful only when the baseline is trusted; updating references without review weakens that signal. Reference PNGs can add repository size, and Git LFS is an optional choice described by Loki’s guide.
Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server for capturing a URL with one GET request. It does not update Loki reference files or replace Loki’s Storybook comparison workflow; use it when you need standalone website captures or want an AI agent to capture a page.
For a runnable request and the available options, see the ScreenshotNeo API documentation. Replace the example target URL with the page you want to capture and set your API key:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);ScreenshotNeo removes cookie banners, popups, and chat widgets before the shot. Bot checks, blank pages, and failed loads are never billed, and response headers report the page verdict and billing status. Its MCP server lets AI agents use screenshot tools. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots. Sign up for 1,000 free screenshots a month, with no card required.
FAQ
Should I approve a diff if the test failed?
Only if you inspected the changed screenshot and decided the new appearance is intended. A failed comparison alone is not a reason to replace the reference.
Does --diffOnly confirm that a change is intentional?
No. It limits which failed files approval affects; it does not review the visual changes for you.
Should reference screenshots be committed?
Loki’s Getting Started guide recommends checking them into Git so baseline changes can be reviewed with the code change. Git LFS is an optional storage choice.
Can ScreenshotNeo approve Loki references?
No. ScreenshotNeo captures web pages through its API or MCP server. Loki’s reference approval remains part of the Loki workflow.
