How to Run Loki Screenshot Tests for an Indian Ecommerce Website

Loki runs visual regression tests against Storybook stories: it captures screenshots, compares them with approved reference images, and reports differences. To use it for an Indian ecommerce website, model the storefront states you want to protect as deterministic stories, create and review an initial baseline, run Loki against that baseline locally and in CI, and update references only when a change is intentional. Loki tests component and page-story appearance; it does not test whether checkout, payment, or other backend behavior works.

This guide uses the Loki workflow documented for Storybook. Its setup details are version-sensitive: the Loki guide lists Node.js 16 or newer and was last updated on 2024-08-27. Check the current Loki documentation and your project’s Node, Storybook, package-manager, and browser versions before adopting the commands unchanged.

1. Decide what the screenshots should cover

Start with the visible states whose changes could affect a shopper’s understanding or ability to act. Use fixed story data rather than live production data, so a price, inventory update, network response, or personalization rule does not create an unrelated diff.

Storefront area	Useful story states	What the comparison can catch
Product discovery	Product card, product detail, representative price, discount or offer, unavailable item	Layout changes, clipped prices, missing offer labels, image sizing, and responsive regressions
Cart and checkout UI	Empty cart, populated cart, validation errors, confirmation, purchase-consent control	Visible state and copy changes; not successful payment or order processing
Help and seller information	Seller details, customer-care details, grievance contact or mechanism, where relevant	Accidental removal, hiding, or visual degradation of information shoppers need to find
Cancellation and refunds	Relevant cancellation terms, refund messaging, and confirmation states	Changes to displayed wording and presentation; not whether the policy is legally sufficient or honored operationally

The Consumer Protection (E-Commerce) Rules, 2020 describe display and process requirements that may inform these UI cases, including entity and contact details, a grievance mechanism, affirmative purchase consent, and cancellation and refund rules. Applicability depends on the business and the current operative law. Treat the stories as a way to detect unintended interface changes, not as legal review or proof of compliance. One rule says: “Every e-commerce entity shall only record the consent of a consumer for the purchase of any good or service offered on its platform where such consent is expressed through an explicit and affirmative action, and no such entity shall record such consent automatically, including in the form of pre-ticked checkboxes.” Confirm current requirements with authoritative legal sources before relying on this coverage.

2. Install and initialize Loki

From the project root, install Loki as a development dependency and run its initializer:

yarn add loki --dev
yarn loki init

Review the loki configuration the initializer adds to package.json. The documented web defaults include laptop and iPhone configurations using the local Chrome app. Loki also documents a GraphicsMagick dependency for the gm diff engine, Docker for the chrome.docker target, Chrome 59 or later for chrome.app, and a React Native Android dev-settings package for emulator crash recovery. These are target-specific options, not requirements for every web project; install only what your selected target and diff engine need.

Loki compares rendered output, so setup is not complete until the Storybook it will capture can run. For a browser target, start Storybook before running Loki. For iOS or Android targets, run the relevant simulator or emulator with the Storybook app. Loki does not start or build Storybook on your behalf.

3. Make Storybook states repeatable

Give each important storefront state its own named story. Keep the fixture data, viewport, fonts, assets, locale, and browser target stable. Prefer bundled test fixtures to live APIs. If a story includes prices or text that vary by locale, set the intended locale and provide fixed values.

Use fixed product names, prices, offer values, seller details, and validation messages.
Use stable local or versioned image and font assets; avoid relying on a third-party asset that may change or fail to load.
Set viewport and device configuration explicitly for states where wrapping or responsive behavior matters.
For asynchronous components, use Loki’s documented async callback pattern when rendering needs to finish before capture; verify the story has reached the intended state before the screenshot is taken.
Disable, freeze, or replace animations in test fixtures when a single still image is the intended assertion.

Loki’s guide says it disables common CSS transitions and animations and requestAnimationFrame by default, but documents limitations including looping requestAnimationFrame, GIFs, SVG animations, and React Native Animated. These states may still produce unstable captures. Make them deterministic or omit a story when one screenshot cannot meaningfully represent the state.

4. Create and review the reference images

Start the Storybook server, then create the initial references:

yarn loki update

Loki’s guide says references are stored in a loki folder. Review the generated images before committing them. A baseline is the expected visual output, so generating it from a broken state can make later comparisons consistently wrong. Check in the references with the code, or use Git LFS if that fits the repository’s asset workflow.

5. Run a visual comparison and inspect every diff

After a UI change, run:

yarn loki test

Inspect the captured images under loki/current and the difference images under loki/difference. For each changed story, decide whether the diff represents an intended design change, an accidental regression, or capture noise. Fix the UI or the source of nondeterminism when the change is unintended or noisy. If the change is intentional, use Loki’s suggested targeted reference-update command or approve the reviewed changes with:

yarn loki approve

Commit approved reference changes alongside the corresponding UI change. Do not approve a diff just to make a failing job green: first identify why the pixels changed and confirm the new result is the intended baseline.

6. Run Loki in CI with required references

Build a static Storybook and ask Loki to compare it while failing if a reference is missing:

build-storybook && loki --requireReference --reactUri file:./storybook-static

Here, --requireReference makes missing baselines fail the check, and --reactUri points Loki at the static build. Use the equivalent build command and output path for your Storybook setup. Keep reference creation and comparison aligned: use the same operating system, browser version, fonts, device settings, and capture mode where possible. Playwright’s visual-comparison documentation independently notes that host OS, browser version, settings, hardware, power source, and headless mode can affect screenshots, and recommends using the same environment for baselines and comparisons. That is general screenshot guidance, not a Loki-specific compatibility guarantee.

Keep baseline updates in a deliberate review path. A practical pull request should show the UI change, the current screenshots or diffs, and the updated references together. If CI reports a missing reference, create and review it in the project’s agreed baseline environment rather than silently weakening the required-reference check.

7. Know what Loki does not verify

Loki answers a visual question: does this Storybook story look different from its approved screenshot in this capture environment? It does not establish that a purchase can be completed, a payment gateway responds correctly, an order is persisted, a refund is issued, or content is legally compliant. Add functional checkout and payment tests for behavior, and use a separate review process for legal applicability and wording.

Playwright also documents visual screenshot comparison, with guidance about consistent capture environments. Storybook documents Chromatic as a hosted visual-testing service. These are separate approaches and execution models; the cited material does not establish feature parity, price advantages, or direct Loki compatibility. Choose based on whether the project needs Storybook-story comparison, broader browser behavior checks, or hosted review workflows.

8. Troubleshooting

Symptom	Likely cause	Fix
Loki cannot connect or capture	Storybook is not running, the configured URI or port is wrong, or the static build path does not exist	Start Storybook for local capture; in CI, confirm the build completed and the URI points to its actual output.
A story is missing a reference in CI	No baseline was committed, or the required-reference check is running against a different story or target configuration	Run the approved baseline-generation workflow, review the image, and commit the reference for the same story and target.
Many stories show pixel diffs after a CI image change	Browser, operating system, fonts, rendering settings, or headless mode differ from the baseline environment	Align baseline generation and CI capture environments, then regenerate references only if the resulting rendering is the chosen standard.
Only stories with delayed content fail intermittently	Capture starts before an asynchronous component finishes rendering, or its network/image dependency is unstable	Use fixed data and assets and Loki’s async callback pattern where needed; wait for a meaningful rendered state.
Animated content differs between runs	The animation type may be among Loki’s documented limitations or may have no stable frame	Freeze or disable it in the fixture, assert a deterministic state, or skip visual comparison for that state.
Reference update changes far more files than expected	A broad rendering change or environment shift affected many stories	Inspect representative diffs first, check browser and fixture changes, and update only after the cause and intended appearance are understood.
The selected diff engine or target fails to start	An optional dependency for that engine or target is absent or incompatible	Check Loki’s current setup documentation for the selected engine or target; install the relevant GraphicsMagick, Docker, browser, or emulator support only when needed.

9. Performance, reliability, and cost

The research materials provide no reliable benchmark for Loki runtime or defect reduction, so plan capacity from your own suite. Capture time grows with the number of stories and configured targets; keep the suite focused on meaningful states and avoid duplicating identical coverage. Reuse deterministic fixtures and assets to reduce network waits and flaky output. A stable browser image and intentional baseline review improve reliability more than repeatedly accepting unexplained diffs.

Loki is open-source software, but running it still uses developer or CI compute and storage for screenshot references. Budget for the browser or container environment, simulator/emulator resources if used, and baseline artifacts. No measured cost or performance figure is implied here.

Or skip the browser setup

If you need a clean screenshot of a live storefront page alongside component regression coverage, ScreenshotNeo is a website screenshot API and MCP server. It does not replace Loki’s Storybook baseline comparison: use Loki for reviewed component or story diffs and ScreenshotNeo for captures of target URLs.

One GET request returns an image or PDF. For example, this cURL request saves a WebP capture of a product page:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

See the ScreenshotNeo API documentation for the available formats and options. ScreenshotNeo removes cookie and consent banners, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers report the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 shots.

FAQ

Does Loki take screenshots of any URL?

Loki’s documented workflow captures Storybook stories from a running Storybook or static Storybook build. For a screenshot of a live website URL, use a website capture tool such as ScreenshotNeo.

Should every Indian ecommerce page be a Loki story?

No. Prioritize representative states where a visual change could confuse shoppers or hide important information, then add stories as the storefront’s risks and design evolve.

Can a passing visual test prove checkout is compliant or functional?

No. It checks rendered appearance against references. Test checkout behavior separately and verify current legal duties with qualified, authoritative guidance.

When should I update the baseline?

After reviewing the diff and deciding the new appearance is intentional. Update references together with the change that produced them.