Loki Storybook Testing: Desktop & Mobile

This guide shows you how to use Loki to visually compare Storybook components across desktop and mobile viewports. You’ll set up Loki, configure viewports, run visual regression tests, and catch unintended UI changes before they reach production.

What You’ll Need

• A project with Storybook already installed and configured (Storybook 6 or newer recommended)
• Node.js (version 14 or later) and npm or yarn
• Chrome or Chromium installed (Loki uses headless Chrome by default)
• Basic familiarity with the command line

Step-by-Step

1. Install Loki
   Run npm install --save-dev loki or yarn add --dev loki in your project root. This adds Loki as a dev dependency.
2. Create a Loki configuration file
   In your project root, create a file named loki.config.js. This file tells Loki where your Storybook is and what viewports to test.
3. Configure viewports for desktop and mobile
   Inside loki.config.js, add a viewports object. For example:

   module.exports = {
     chromeSelector: '.storybook-container',
     viewports: {
       desktop: { width: 1280, height: 800 },
       mobile: { width: 375, height: 667 }
     }
   };

   You can add more viewports (tablet, etc.) as needed. The keys (desktop, mobile) are labels you’ll reference later.

4. Add Loki scripts to package.json
   In your package.json, under scripts, add:

   "loki:test": "loki test",
   "loki:update": "loki update"

   This lets you run tests and update reference images easily.

5. Start Storybook
   Loki needs Storybook running. Start it in a separate terminal with npm run storybook (or your usual command). Note the port (usually 6006).
6. Run Loki with the correct Storybook URL
   If Storybook is running on the default port, simply run npm run loki:test. If you’re using a different port, pass it: npm run loki:test -- --port 6007.
7. Generate initial reference images
   On the first run, Loki won’t have any reference images. Run npm run loki:update to create the baseline screenshots for both viewports. These will be stored in a .loki folder.
8. Run visual tests
   After you make changes to your components, run npm run loki:test. Loki will take new screenshots and compare them pixel-by-pixel against the reference images for each viewport.
9. Review the results
   Loki outputs a summary in the terminal. If there are differences, it will list the affected stories and viewports. You can open the generated HTML report (usually in .loki/report.html) to see side-by-side comparisons with highlighted differences.
10. Approve or update baselines
    If the changes are intentional (e.g., you redesigned a button), run npm run loki:update to set new reference images. If they are unexpected, fix your component and re-run the test.

Common Mistakes

• Forgetting to start Storybook – Loki will fail with a connection error. Always ensure Storybook is running before executing Loki.
• Using wrong viewport dimensions – Make sure your mobile viewport matches common device widths (e.g., 375px for iPhone X). Inconsistent sizes lead to false positives.
• Not updating baselines after intentional changes – If you don’t run loki update, you’ll keep seeing failures for changes you meant to make.
• Ignoring dynamic content – If your components render dates, random data, or animations, Loki will flag differences every run. Use Loki’s --storiesFilter or mock data to stabilize.
• Running tests while Storybook is in dev mode – Hot reloading can cause mid-render screenshots. Use a production build of Storybook (build-storybook) for more stable results.

Tips

• Use a dedicated Storybook build – Run build-storybook and serve it statically for faster, more reliable tests.
• Set a stable viewport for each story – You can override the default viewport in your story’s parameters, e.g., parameters: { loki: { viewports: ['mobile'] } } to test only mobile for that story.
• Add Loki to your CI pipeline – Run loki test on every pull request to catch regressions early.
• Use --diffingEngine options – Loki supports different diffing engines (like pixelmatch or looks-same). Experiment to find the one that best suits your UI.
• Group related stories – Use Storybook’s tags or naming conventions to filter which stories Loki tests, saving time.

Troubleshooting

• Loki can’t connect to Storybook – Check that Storybook is running and the port matches. Use --port flag if needed. Also verify that loki.config.js has the correct storybookUrl (defaults to http://localhost:6006).
• Chrome not found – Loki uses Puppeteer, which downloads its own Chromium. If this fails (e.g., due to network restrictions), install Chrome manually and set chromeFlags or chromePath in the config.
• Too many false positives – Disable animations in your CSS (e.g., * { transition: none !important; }) and mock any external data. Use Loki’s --storiesFilter to test a subset first.
• Reference images not generated – If loki update produces no images, check that your stories are correctly named and that Storybook is accessible. Run loki --verbose for more details.
• Differences only on mobile – This is often due to responsive layout changes. Verify that your mobile viewport width is correct and that your CSS media queries are working as expected.

Frequently Asked Questions

Can I use Loki with other browsers?

Yes, Loki supports Firefox and WebKit via Puppeteer, but Chrome is the default and most stable. Configure browser: 'firefox' or 'webkit' in loki.config.js.

How do I ignore a specific story from visual tests?

Add parameters: { loki: { skip: true } } to the story’s meta or to individual stories.

What is the difference between loki test and loki update?

loki test compares current screenshots against stored baselines and reports differences. loki update overwrites the baselines with the current screenshots, effectively accepting them as the new reference.

Can Loki test multiple viewports in one run?

Yes, that’s the default. It will capture screenshots for every viewport defined in your config for each story, unless you override per-story.

How long does a typical test run take?

It depends on the number of stories and viewports. A small project with 20 stories and 2 viewports might take under a minute. Larger projects can take several minutes, especially on CI.

Can I run Loki on a CI service like GitHub Actions?

Yes, Loki works well in CI. You’ll need to install Chrome or use the Puppeteer-bundled Chromium. Add a step to start Storybook, then run loki test.

Related

• Show Developer Tab in Excel Ribbon (Windows & Mac)
• Comodo Antivirus Firewall: What to Know
• Human Oversight for AI Database Operations