Playwright visual testing for product tours

Product tours break quietly. Someone renames a button, moves a menu item or adds a sticky header, and the onboarding tour that greets every new user now points at nothing. No error is thrown, the tests stay green, and you find out from a confused customer, if at all.

I wanted a test that fails when a tour step looks wrong, not only when it crashes. So I built a small dashboard with a Driver.js tour, wrote Playwright tests that screenshot every step, and then broke the app in two realistic ways to see what the tests catch.

All the code is in screenshotone/blog-examples. Clone it and run npm test to follow along.

What I tested with

I ran everything on November 6, 2026 on macOS with Playwright 1.65.0, Chrome Headless Shell 158.0.8127.18, Driver.js 1.10.2, TypeScript 7.0.2 and Node.js 24. The viewport was 1280 × 800 at a device scale factor of 2, so every screenshot is 2560 × 1600.

The app and the tour

The demo app is a dashboard called Lumen. It has a sidebar, a search field, a few stats and a five-step tour:

I keep the tour in a JSON file instead of hardcoding it in JavaScript. The app and the tests read the same file, so a test always checks the steps your users see:

1
{
2
    "showProgress": true,
3
    "steps": [
4
        {
5
            "element": "#new-project",
6
            "popover": {
7
                "title": "Create your first project",
8
                "description": "Start here. A project collects visitors, signups and conversions for one site.",
9
                "side": "bottom",
10
                "align": "end"
11
            }
12
        },
13
        {
14
            "element": "#search",
15
            "popover": {
16
                "title": "Find anything",
17
                "description": "Search across projects, reports and teammates.",
18
                "side": "bottom",
19
                "align": "start"
20
            }
21
        }
22
    ]
23
}

The real file has three more steps: the stats, the Reports link and the Invite team button.

The app exposes one small function, window.startTour(). It starts the tour at any step, so a test for step 4 doesn’t have to click Next three times first:

1
import type { Config, Driver, driver as createDriver } from "driver.js";
2

3
declare global {
4
    interface Window {
5
        // The Driver.js IIFE build loaded with a <script> tag.
6
        driver: { js: { driver: typeof createDriver } };
7
        // Set by the ScreenshotOne script, which inlines the tour config.
8
        TOUR_CONFIG?: Config;
9
        startTour: (stepIndex?: number, overrides?: Config) => Promise<void>;
10
        tour?: Driver;
11
    }
12
}
13

14
const { driver } = window.driver.js;
15

16
async function loadTourConfig(): Promise<Config> {
17
    if (window.TOUR_CONFIG) {
18
        return window.TOUR_CONFIG;
19
    }
20

21
    const response = await fetch("/tour.json");
22
    return response.json();
23
}
24

25
window.startTour = async (stepIndex = 0, overrides = {}) => {
26
    const config = await loadTourConfig();
27
    const tour = driver({ ...config, ...overrides });
28
    tour.drive(stepIndex);
29
    window.tour = tour;
30
};

The overrides argument lets the tests turn off Driver.js animations. I’ll come back to window.TOUR_CONFIG in the ScreenshotOne section.

The whole example is in TypeScript. The import type only brings in Driver.js types, so tsc compiles app/app.ts to plain JavaScript that uses the Driver.js build from the <script> tag. The test server and the ScreenshotOne script are .ts files too, and Node.js 22.18 or newer runs them directly.

The Playwright tests

The test file reads the same tour.json and creates one test per step. Each test does three things:

1. Checks that the step’s selector matches exactly one visible element. Driver.js highlights the first match, so two matches are a bug too.
2. Starts the tour at that step and checks the popover title.
3. Compares a screenshot of the whole page with the baseline.

1
import { readFileSync } from "node:fs";
2
import { test, expect } from "@playwright/test";
3

4
type TourStep = {
5
    element: string;
6
    popover: { title: string; description: string };
7
};
8

9
const tour: { steps: TourStep[] } = JSON.parse(
10
    readFileSync(new URL("../app/tour.json", import.meta.url), "utf-8")
11
);
12

13
declare global {
14
    interface Window {
15
        startTour: (stepIndex?: number, overrides?: object) => Promise<void>;
16
    }
17
}
18

19
for (const [index, step] of tour.steps.entries()) {
20
    const name = `step ${index + 1}: ${step.popover.title}`;
21

22
    test(name, async ({ page }) => {
23
        await page.goto("/");
24

25
        // Driver.js highlights the first match, so the selector must match exactly one visible element.
26
        const target = page.locator(step.element);
27
        await expect(target, `"${step.element}" must match one element`).toHaveCount(1);
28
        await expect(target).toBeVisible();
29

30
        await page.evaluate((i) => window.startTour(i, { animate: false }), index);
31

32
        const popover = page.locator(".driver-popover");
33
        await expect(popover).toBeVisible();
34
        await expect(popover.locator(".driver-popover-title")).toHaveText(step.popover.title);
35

36
        await expect(page).toHaveScreenshot(`step-${index + 1}.png`);
37
    });
38
}

I also added one test that clicks through the whole tour like a user would:

1
test("the tour can be completed with the Next button", async ({ page }) => {
2
    await page.goto("/");
3
    await page.getByRole("button", { name: "Take the tour" }).click();
4

5
    const popover = page.locator(".driver-popover");
6
    for (const step of tour.steps) {
7
        await expect(popover.locator(".driver-popover-title")).toHaveText(step.popover.title);
8
        await popover.locator(".driver-popover-next-btn").click();
9
    }
10

11
    await expect(popover).toBeHidden();
12
});

In playwright.config.ts, Playwright builds and starts the demo app before the tests. A few settings matter for the screenshots:

• deviceScaleFactor: 2 renders the page like a Retina screen, and scale: "device" keeps that resolution in the screenshot. Playwright scales screenshots down to CSS pixels by default, so without it you get blurry 1280 × 800 images instead of sharp 2560 × 1600 ones.
• Playwright names each baseline after the screenshot, the project and the operating system, like step-1-desktop-darwin.png. darwin means macOS. On Linux, the same test looks for step-1-desktop-linux.png, so each OS keeps its own baselines.
• animations: "disabled" and maxDiffPixelRatio keep the comparison stable. More on that below.

1
import { defineConfig, devices } from "@playwright/test";
2

3
export default defineConfig({
4
    testDir: "./tests",
5
    reporter: [["list"], ["html", { open: "never" }]],
6
    use: {
7
        baseURL: "http://localhost:3000",
8
    },
9
    expect: {
10
        toHaveScreenshot: {
11
            // Allow tiny anti-aliasing differences, catch real layout changes.
12
            maxDiffPixelRatio: 0.01,
13
            animations: "disabled",
14
            // Keep the full 2x resolution instead of scaling down to CSS pixels.
15
            scale: "device",
16
        },
17
    },
18
    projects: [
19
        {
20
            name: "desktop",
21
            use: {
22
                ...devices["Desktop Chrome"],
23
                viewport: { width: 1280, height: 800 },
24
                // Render at 2x, like a Retina screen, so the screenshots are sharp.
25
                deviceScaleFactor: 2,
26
            },
27
        },
28
    ],
29
    webServer: {
30
        command: "npm start", // builds app/app.ts and starts server.ts
31
        url: "http://localhost:3000",
32
        reuseExistingServer: !process.env.CI,
33
    },
34
});

The first run creates the baselines

There is nothing to compare with on the first run, so the five screenshot tests fail on purpose and Playwright saves what it rendered:

1
Error: A snapshot doesn't exist at .../tests/tour.spec.ts-snapshots/step-5-desktop-darwin.png, writing actual.
2
...
3
  5 failed
4
  1 passed

I looked at every image before going further. That review is the important part: a baseline is only useful if it shows the tour the way you want it. Here is step 4, with the popover to the right of the Reports link:

From then on, every run compares against those images:

1
Running 6 tests using 1 worker
2

3
  ✓  1 [desktop] › tests/tour.spec.ts:22:5 › step 1: Create your first project (221ms)
4
  ✓  2 [desktop] › tests/tour.spec.ts:22:5 › step 2: Find anything (152ms)
5
  ✓  3 [desktop] › tests/tour.spec.ts:22:5 › step 3: Your key numbers (151ms)
6
  ✓  4 [desktop] › tests/tour.spec.ts:22:5 › step 4: Share reports (147ms)
7
  ✓  5 [desktop] › tests/tour.spec.ts:22:5 › step 5: Invite your team (154ms)
8
  ✓  6 [desktop] › tests/tour.spec.ts:40:1 › the tour can be completed with the Next button (352ms)
9

10
  6 passed (1.8s)

I ran it a few more times to make sure the screenshots didn’t change between runs. They didn’t.

Break 1: someone renames a button

The first change is the most common one. A developer renames id="new-project" to id="create-project" during a refactor. The tour config still points at #new-project.

Driver.js doesn’t throw an error when the element is missing. It shows the popover in the middle of the screen and highlights nothing:

The user sees “Create your first project” with no idea where to click. The step 1 test fails before it even takes a screenshot, and the message says exactly what is wrong:

1
Error: "#new-project" must match one element
2

3
expect(locator).toHaveCount(expected) failed
4

5
Locator:  locator('#new-project')
6
Expected: 1
7
Received: 0

You don’t need screenshots to catch this one. A selector check is enough, and it’s the cheapest test you can add to any tour.

Break 2: a sticky header covers the tour

The second change is the reason I wanted screenshots. A developer makes the top bar sticky and gives it a high z-index, so dropdowns don’t slide under it:

1
.topbar {
2
    position: sticky;
3
    top: 0;
4
    z-index: 100000;
5
}

Every selector still exists and every popover still opens. The click-through test passes. But the header now sits above the Driver.js overlay, so it stays bright while the rest of the page is dimmed:

All five screenshot tests failed:

1
  ✘  1 [desktop] › tests/tour.spec.ts:22:5 › step 1: Create your first project (665ms)
2
  ✘  2 [desktop] › tests/tour.spec.ts:22:5 › step 2: Find anything (565ms)
3
  ✘  3 [desktop] › tests/tour.spec.ts:22:5 › step 3: Your key numbers (568ms)
4
  ✘  4 [desktop] › tests/tour.spec.ts:22:5 › step 4: Share reports (544ms)
5
  ✘  5 [desktop] › tests/tour.spec.ts:22:5 › step 5: Invite your team (568ms)
6
  ✓  6 [desktop] › tests/tour.spec.ts:40:1 › the tour can be completed with the Next button (380ms)
7

8
    291852 pixels (ratio 0.08 of all image pixels) are different.

Playwright saves a diff image for every failure. Open it with npx playwright show-report. The changed pixels are red, and here it’s the whole header:

This is the kind of bug a functional test can’t see. Nothing is missing or broken in the DOM. It only looks wrong.

How I keep the screenshot tests stable

Screenshot tests have a reputation for failing for no reason. These settings kept mine stable:

• Turn off animations. I pass { animate: false } to Driver.js and set animations: "disabled" in the config. Otherwise the screenshot can catch the popover halfway through its fade-in.
• Allow a tiny difference. maxDiffPixelRatio: 0.01 ignores anti-aliasing noise. The sticky header changed 8% of the pixels, far above that limit.
• Use one viewport per project. Tours often change sides on smaller screens. If you support mobile, add a second Playwright project with a phone viewport and give it its own baselines.
• Hide data that changes. My demo has fixed numbers. In a real app, pass mask: [page.locator(".stat-value")] to toHaveScreenshot() so live stats don’t fail the tests.
• Make baselines for the OS your CI uses. Fonts render differently on macOS and Linux, which is why the baseline names include the OS. My baselines are from macOS, so for Linux CI I make the -linux baselines in the official Playwright Docker image and run the tests in the same image:

1
docker run --rm -v "$(pwd)":/work -w /work mcr.microsoft.com/playwright:v1.65.0-noble \
2
  sh -c "npm ci && npx playwright test --update-snapshots"

When you change the tour on purpose, run npx playwright test --update-snapshots, look at the new images and commit them with the change. The review in the pull request then shows exactly how the tour changed.

Render the tour steps with ScreenshotOne

The Playwright tests protect the tour in CI. Sometimes I also need the images outside the tests: to show a new tour in a pull request, to put the steps in the docs, or to check how the tour looks on staging without installing browsers anywhere.

For that, I use the ScreenshotOne API. The render-with-screenshotone.ts script in the repository renders every step with the same startTour() hook the tests use:

1
for (const [index, step] of tour.steps.entries()) {
2
    const response = await fetch("https://api.screenshotone.com/take", {
3
        method: "POST",
4
        headers: {
5
            "Content-Type": "application/json",
6
            "X-Access-Key": accessKey,
7
        },
8
        body: JSON.stringify({
9
            ...page,
10
            // Wait until Driver.js and the app's scripts have loaded.
11
            wait_until: ["load"],
12
            // Start the tour at this step, the same hook the Playwright tests use.
13
            scripts: `window.startTour(${index}, { animate: false });`,
14
            // The scripts run first, then the API waits for the popover.
15
            wait_for_selector: ".driver-popover",
16
            viewport_width: 1280,
17
            viewport_height: 800,
18
            device_scale_factor: 2,
19
            format: "png",
20
            block_cookie_banners: true,
21
            block_chats: true,
22
            cache: false,
23
        }),
24
    });
25

26
    if (!response.ok) {
27
        const error: { error_code?: string; error_message?: string } = await response.json().catch(() => ({}));
28
        throw new Error(`Step ${index + 1} failed with ${response.status}: ${error.error_code} ${error.error_message}`);
29
    }
30

31
    await writeFile(`screenshots/step-${index + 1}.png`, Buffer.from(await response.arrayBuffer()));
32
}

A few details matter here:

• wait_until set to load makes the API wait for Driver.js and the app’s scripts. My first run didn’t have it: with HTML input, the script ran while the page was still loading, window.startTour didn’t exist yet, and every request timed out waiting for the popover.
• scripts runs JavaScript on the page after it loads. Here it starts the tour at the right step.
• wait_for_selector waits until the popover exists, so the screenshot never catches the page before the tour opens.
• block_cookie_banners and block_chats keep consent banners and chat widgets from covering the tour on a real site.
• page is either { url } or { html }. For a deployed app, set TOUR_URL to your staging URL. The API can’t reach localhost, so for the demo the script inlines the app’s CSS, compiled JavaScript and tour config into one HTML document and loads Driver.js from a CDN. That’s where window.TOUR_CONFIG comes from.

Run it with your access key:

1
SCREENSHOTONE_ACCESS_KEY=<your access key> npm run render
2
SCREENSHOTONE_ACCESS_KEY=<your access key> TOUR_URL=https://staging.example.com/ npm run render

All five steps took about 11 seconds. With device_scale_factor: 2, each image is 2560 × 1600, sharp enough for docs and pull requests. Here is step 3 as the API rendered it:

The fonts differ slightly from my macOS screenshots because the API renders on Linux. That’s also why I don’t use these images as Playwright baselines: compare screenshots made in the same environment.

If your tour only shows up for logged-in users, pass a session with the cookies option.

Summary

A product tour is UI like any other, but it breaks in ways normal tests don’t notice. What worked for me:

• Keep the tour in a JSON file, so the app and the tests read the same steps.
• Expose a startTour(step) hook, so a test can open any step directly.
• Check that every selector matches one visible element. It catches renamed and removed targets.
• Compare a screenshot of every step with toHaveScreenshot(). It catches the bugs you can only see, like a header covering the overlay.

The full example, with the app, the tests, the baselines and the ScreenshotOne script, is in screenshotone/blog-examples. If you’re new to Playwright screenshots, start with how to render screenshots with Playwright and how to wait for a page to load before a screenshot.

Frequently Asked Questions

If you read the article, but still have questions. Please, check the most frequently asked. And if you still have questions, feel free reach out at support@screenshotone.com.

How do I test a product tour with Playwright?

Start the tour at each step from the test, check that the step's target element exists and is visible, and compare a screenshot of the page with a baseline using expect(page).toHaveScreenshot(). Add one test that clicks through the whole tour with the Next button.

Why did my Driver.js tour show the popover in the middle of the screen?

Driver.js couldn't find the step's element, usually because its selector changed. It then shows the popover in the center without highlighting anything and doesn't throw an error. Check that every step's selector matches one visible element in your tests.

Why do Playwright screenshot tests fail on CI but pass on my machine?

Fonts and anti-aliasing differ between operating systems, so Playwright stores baselines per platform. Generate Linux baselines in the official Playwright Docker image and use the same image on CI.