Screenshot Testing for E-commerce: Cart, Checkout, and Product Pages
A page-by-page plan for e-commerce screenshot testing: what to capture with an API, what needs fixtures or browser automation, and how to make captures repeatable.
E-commerce pages are hard to test visually. Prices, stock badges, recommendations, countdown timers and rotating banners change on their own, and the pages that matter most (cart and checkout) depend on session state that a plain URL does not carry.
This guide goes through an online store page by page. For each page type it shows what a screenshot API can capture directly, what needs a seeded fixture, and what belongs in a browser-automation tool. It then covers how to make captures repeatable enough to compare.
The examples use the Screenshotly API. The split of work applies to any capture service.
Who does what
A screenshot API is a capture step. It does not run your test suite. Planning starts with being clear about the split:
| Responsibility | Screenshot API (one request = one capture) | Your test harness |
|---|---|---|
| Render a public or cookie-authenticated URL at a set viewport | Yes | — |
| Wait for an element or network idle before capturing | Yes (waitForSelector, waitForNetworkIdle) |
— |
| Hide noisy elements, run a short script before capture | Yes, Growth plan (hideSelectors, javascript) |
— |
| Click, type, submit forms, move through checkout steps | No | Fixtures, or Playwright/Cypress |
| Seed carts, orders and test accounts | No | Your staging API or database seeds |
| Store baselines, diff images, decide pass/fail | No | Your scripts or a visual-testing tool |
Two platform limits affect test design:
- Target URLs must be publicly reachable. Requests to localhost, private networks and other non-public addresses are rejected. Point captures at a staging or preview deployment, not at
localhost:3000. - Failures are explicit, but waits are not assertions. If
waitForSelectordoesn't find its element within 10 seconds, the capture continues anyway. If ajavascriptsnippet throws, the error is swallowed. An element capture withselector, on the other hand, fails with a 400 if the element is missing. Use that when a missing element should fail the test.
Page-type matrix
| Page / state | How to reach the state | Capture directly? | Minimum plan |
|---|---|---|---|
| Product detail page (PDP), default variant | Public URL | Yes | Free |
| PDP, specific variant | Variant in the URL (if your storefront supports it); otherwise a javascript click |
Usually; the script route is fragile | Free / Growth |
| PDP, out of stock or low stock | Dedicated fixture products on staging | Yes | Free |
| Category / listing (PLP), filters, sort, grid vs list | Query parameters | Yes | Free |
| Search results | Query parameters | Yes | Free |
| Cart with items | Seeded test account + session cookie | Yes | Basic |
| Checkout steps with entered data | Fixture route that renders the step, or Playwright | Only with a fixture route | Basic (cookies) |
| Payment errors, address validation errors | Playwright with your payment provider's test mode | No | — |
| Order confirmation | Fixture order + session cookie | Yes | Basic |
| Promo and landing pages | Public URL | Yes | Free |
| Account pages (orders, addresses) | Session cookie | Yes | Basic |
If a state can be expressed as URL + cookies, capture it with the API. If it only exists after a sequence of user actions, script it in a browser-automation tool, or build a staging-only route that renders it from fixture data.
A small capture helper
All examples below use this helper (Node 18+, which has fetch built in). It saves the binary response and turns error responses into readable exceptions. On a 429 it waits for the Retry-After interval once before retrying, because the Free plan allows 5 requests per minute.
// capture.mjs
import { writeFile } from 'node:fs/promises';
const API = 'https://screenshotly.app/api/screenshot';
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
export async function capture(body, outFile, { retried = false } = {}) {
const res = await fetch(API, {
method: 'POST',
headers: {
'x-api-key': process.env.SCREENSHOTLY_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify(body),
});
if (res.status === 429 && !retried) {
const waitSeconds = Number(res.headers.get('retry-after') ?? 60);
await sleep(waitSeconds * 1000);
return capture(body, outFile, { retried: true });
}
if (!res.ok) {
const err = await res.json().catch(() => ({}));
throw new Error(`${res.status} ${err.error ?? ''} ${err.message ?? ''} (${body.url})`);
}
// Successful captures return the image bytes directly.
await writeFile(outFile, Buffer.from(await res.arrayBuffer()));
}
Product and category pages: the responsive matrix
Product and listing pages are public, so they are the easiest place to start. Capture every important template at each device preset. The presets map to fixed viewports: desktop 1920×1080, laptop 1366×768, tablet 768×1024 and mobile 375×812. If you leave out both device and width/height, the viewport defaults to 1920×1080.
// matrix.mjs
import { mkdir } from 'node:fs/promises';
import { capture } from './capture.mjs';
const BASE = 'https://staging.store.example.com';
const PAGES = {
'pdp': '/products/basic-tee?visual_test=1',
'pdp-sold-out': '/products/fixture-sold-out?visual_test=1',
'plp-sorted': '/collections/shirts?sort=price-asc&visual_test=1',
'search': '/search?q=tee&visual_test=1',
};
const DEVICES = ['desktop', 'laptop', 'tablet', 'mobile'];
await mkdir('captures', { recursive: true });
for (const [name, path] of Object.entries(PAGES)) {
for (const device of DEVICES) {
await capture(
{
url: BASE + path,
device,
format: 'png',
fullPage: true,
waitForNetworkIdle: true,
waitForSelector: '[data-testid="price"]',
timezone: 'UTC',
},
`captures/${name}-${device}.png`,
);
}
}
This matrix is 4 pages × 4 devices = 16 captures per run. The Free plan includes 100 captures in total, which is enough to settle on the matrix. A suite that runs on every pull request needs a paid plan: Basic includes 2,500 captures a month, so a 16-capture suite can run about 150 times. Failed captures don't count toward the quota. See pricing for the current limits.
visual_test=1 is a flag you add to your storefront, not a Screenshotly parameter. Use it to turn off carousels, autoplay, recommendation widgets and lazy loading in test captures. It is the most reliable way to get stable captures, and it works on every plan.
Variants
If your storefront puts the selected variant in the URL (many do, as a query parameter or a path segment), capture that URL directly. If it doesn't, the Growth plan lets you run a script before capture:
{
"url": "https://staging.store.example.com/products/basic-tee",
"device": "desktop",
"javascript": "document.querySelector('[data-variant=\"red\"]')?.click();",
"delay": 500,
"waitForNetworkIdle": true
}
This approach has limits. A click dispatched from a script is not a real user gesture. If the selector matches nothing, the default variant is captured with no error. Treat it as a fallback, and keep at least one assertion (such as an element capture of the variant label) to show the right state rendered.
Making captures repeatable
A diff is only useful when the same code produces the same pixels. Common sources of noise on e-commerce pages, and how to control them:
| Source of noise | Control | Plan |
|---|---|---|
| Prices, stock counts, review counts from live data | Fixture products on staging with frozen data | — |
| "Recently viewed", personalized recommendations | Test-mode flag, or hideSelectors |
Free / Growth |
| Carousels, autoplaying hero banners, CSS animations | Test-mode flag, or a javascript snippet that disables animations |
Free / Growth |
| Countdown timers, "order in the next 3 hours" delivery estimates | Fixed timezone, plus hiding server-rendered timers |
Free / Growth |
| Late-loading prices or images | waitForNetworkIdle, waitForSelector |
Free |
| Cookie and newsletter popups | Dismiss with a test cookie, blockAds, or AI element removal |
Free / Basic / Growth |
A Growth-plan request that combines these controls:
{
"url": "https://staging.store.example.com/products/basic-tee",
"device": "mobile",
"fullPage": true,
"waitForNetworkIdle": true,
"timezone": "UTC",
"hideSelectors": [
"[data-testid=\"recently-viewed\"]",
"[data-testid=\"recommendations\"]",
".countdown-timer"
],
"javascript": "const s = document.createElement('style'); s.textContent = '*, *::before, *::after { animation: none !important; transition: none !important; }'; document.head.appendChild(s);"
}
Some rendering details to know when you compare captures:
- Timezone emulation changes the browser's clock, not your server's. It fixes dates rendered client-side. Dates the server renders into the HTML still follow server time, so freeze those in your fixtures.
- Web fonts are only loaded for full-page captures. For viewport-only captures (
fullPage: false), font requests are skipped to speed up loading, so text renders in fallback fonts. UsefullPage: truewhen typography matters, and never compare a full-page baseline with a viewport capture. - Video and audio are not loaded. Media requests and websockets are blocked. A product video shows its poster frame or an empty player, which is consistent from run to run but isn't a test of the video itself.
- Compare like with like. Same device preset, same
deviceScaleFactor, same format. Different settings produce different pixel dimensions, and the diff becomes meaningless.
Cart, account and confirmation pages: seeded sessions
Cart and account pages depend on who is logged in. If your staging environment can seed a test account with a known cart, the API can capture it by sending that session's cookie (Basic plan or higher):
import { capture } from './capture.mjs';
// TEST_SESSION comes from your seed script, never from a real customer.
await capture(
{
url: 'https://staging.store.example.com/cart',
device: 'mobile',
fullPage: true,
waitForSelector: '[data-testid="cart-line-item"]',
cookies: [
{ name: 'session_id', value: process.env.TEST_SESSION, httpOnly: true },
],
},
'captures/cart-two-items-mobile.png',
);
The cookie domain defaults to the target URL's host and must match it. A cookie scoped to a different domain is rejected with a 400. Keep test sessions short-lived and scoped to staging. They are credentials, so store them as CI secrets. For more on logged-in captures, see the authenticated screenshot guide.
Order confirmation and account pages follow the same pattern. Seed a fixture order, then capture /orders/<fixture-id> with the same cookie.
Checkout: fixtures or browser automation
Checkout is where a single-URL capture stops working. The interesting states are shipping details entered, a payment declined, or an address rejected. They exist only after a user fills in forms, and often only inside payment-provider iframes.
You have two honest options:
- Fixture routes. Build staging-only routes that render a checkout step from fixture data, for example
/checkout/_fixture/shipping-filled. Those are plain URLs, so the API captures them like any other page, including the device matrix. - Browser automation. If the state depends on real interaction, use a tool built for it. With Playwright, the flow and the comparison happen in the same test:
import { test, expect } from '@playwright/test';
test('checkout shipping step', async ({ page }) => {
await page.goto('https://staging.store.example.com/products/basic-tee');
await page.getByRole('button', { name: 'Add to cart' }).click();
await page.goto('https://staging.store.example.com/checkout');
await page.getByLabel('Postal code').fill('10115');
await expect(page).toHaveScreenshot('checkout-shipping.png', { fullPage: true });
});
You don't need a screenshot API for that test. A common split is to script the interactive checkout flows in Playwright, and use the API for the large matrix of public and cookie-authenticated pages across devices. That way you don't have to maintain browser images for the matrix. For payment error states, use your payment provider's test-mode cards, never live ones.
Locale and currency
If you sell in several regions, pin the locale in the request instead of hoping the right one is detected:
{
"url": "https://staging.store.example.com/products/basic-tee",
"device": "desktop",
"headers": { "Accept-Language": "de-DE,de;q=0.9" },
"cookies": [{ "name": "currency", "value": "EUR" }]
}
Custom headers and cookies need the Basic plan. Two other options are often confused with locale:
geolocation(Growth) sets the coordinates returned by the browser's Geolocation API. It only matters if your page asks for location in the browser.proxyRegion(Scale;us,euorapac) changes the region the capture request comes from. That only affects currency or content if your storefront chooses them from the visitor's IP address.
If your store uses locale paths (/de/products/...), capture those URLs. This is the most explicit approach and works on every plan.
Comparing captures
Pixel comparison happens in your code. A minimal comparison with pixelmatch and pngjs:
// compare.mjs
import { readFileSync, writeFileSync } from 'node:fs';
import pixelmatch from 'pixelmatch';
import { PNG } from 'pngjs';
export function compare(baselinePath, currentPath, diffPath) {
const a = PNG.sync.read(readFileSync(baselinePath));
const b = PNG.sync.read(readFileSync(currentPath));
// pixelmatch needs equal dimensions; a height change on a full-page
// capture is itself a finding (an added row of products, a taller banner).
if (a.width !== b.width || a.height !== b.height) {
return { changed: true, reason: `size ${a.width}x${a.height} -> ${b.width}x${b.height}` };
}
const diff = new PNG({ width: a.width, height: a.height });
// threshold is a per-pixel colour distance (0-1), not a percentage of the image.
const mismatched = pixelmatch(a.data, b.data, diff.data, a.width, a.height, { threshold: 0.1 });
writeFileSync(diffPath, PNG.sync.write(diff));
return { changed: mismatched > 0, mismatched, ratio: mismatched / (a.width * a.height) };
}
Decide per page how many mismatched pixels count as a failure, and check that decision against a few runs of unchanged code before you enforce it. The visual regression testing guide covers baselines, approvals and thresholds in more depth. The CI/CD guide shows how to run this on pull requests.
Running larger suites asynchronously
A synchronous request holds the connection open until the image is ready. For bigger suites, queue captures instead:
POST /api/jobs(Basic plan or higher) queues one capture and returns a job ID. PollGET /api/jobs/{id}until the status isSUCCEEDEDorFAILED, then download from the short-livedresultUrl.POST /api/jobs/batch(Growth plan or higher) queues up to 20 captures in one call:{ "captures": [ ... ] }.
The async jobs reference has the full request and response shapes.
Checklist
- List your page templates and states, and mark each one as URL, URL + cookie, fixture route or needs automation.
- Add a test-mode flag to the storefront that freezes carousels, recommendations and lazy loading.
- Create fixture products for edge cases: sold out, low stock, on sale, long titles, missing images.
- Capture the URL and cookie states across the four device presets with the API.
- Script the interactive checkout and payment-error flows in Playwright.
- Store baselines, diff each run, and review changes before accepting new baselines.
Ready to try it on your own storefront?
Get your free API key →. 100 free captures to settle on your page matrix.
See also:
About the Author

Asad Ali
CTO at ZTABS and the developer behind Screenshotly. Writes about screenshot automation, API design, and building reliable SaaS backends with Next.js, Node.js, and TypeScript.
Credentials: CTO at ZTABS, full-stack developer, builder and maintainer of Screenshotly and its official JavaScript and Python clients
Frequently Asked Questions
Can a screenshot API click "Add to cart" and walk through checkout?
Not as a sequence of steps. Screenshotly loads one URL per request and captures it. It does not click, type or move between pages. On the Growth plan you can run a short JavaScript snippet before the capture, but that is not a substitute for a scripted flow. To get a cart or checkout state you need either a URL that renders that state for a seeded test session (send the session cookie on the Basic plan or higher) or a browser-automation tool such as Playwright.
How do I capture the cart page without changing real inventory?
Seed a dedicated test account on staging with a fixed cart, then send that account's session cookie in the capture request with the cookies field (Basic plan or higher). Never capture a real customer's cart. Inventory and price changes will show up as diffs that have nothing to do with your code.
Should I test checkout in several locales and currencies?
Yes, if you sell in several regions. The most dependable approach is to pin the locale explicitly: an Accept-Language header or a currency cookie (Basic plan or higher), or a locale path such as /de/. The regional capture proxy on the Scale plan changes the region the request leaves from, which only matters if your storefront picks currency from the visitor's IP address.
Promotional banners keep breaking my visual diffs. How do I fix that?
Treat promos as content, not layout. Hide them in regression captures with hideSelectors (Growth plan) or a test-mode flag your storefront honours, then test each promo separately on its own landing-page capture. Banners are meant to rotate, so they will always produce diffs if you leave them in the baseline.
Ready to capture your first screenshot?
Get started with 100 free screenshots. No credit card required.