Testing
Test tours end to end with a Playwright fixture, and in unit tests with React Testing Library helpers, layout mocks and a memory router.
@awesome-tour/testing holds the helpers this project uses to test itself.
pnpm add -D @awesome-tour/testingnpm i -D @awesome-tour/testingTour health checks
Tours break quietly: someone renames a button, moves a panel to another page, and the tour that pointed at it falls back to a centered card in production. A health check walks every step of every tour your app registers — on the page the step shows on, through your own router — and fails when a target is gone:
npx awesome-tour-check http://localhost:3000✓ onboarding ○ welcome (/) ✓ sidebar (/) ✓ library (/library) ✗ export (/mix) — not on the page after 3000ms – mastering (/) — `when` is false for the current data
1 of 5 tours have missing targets.It exits with 1 when a target is missing, so it fails CI. Options: --tour <id> (repeatable),
--param id=42 to visit pattern routes such as /projects/:id, --timeout <ms>, --json.
The same check inside your Playwright suite:
import { expectToursHealthy } from '@awesome-tour/testing/playwright';
test('tours still find their targets', async ({ page }) => { await expectToursHealthy(page, { url: '/', params: { id: 'demo-project' } });});How it works: the test asks the page for its tours (an init script creates
window.__AWESOME_TOUR_HOOK__), and TourProvider hands over its manager and router only when that
hook exists — nothing is exposed in normal use. Steps without a route are checked on the previous
step’s page (or the tour’s trigger.route), steps whose when is false for the current data are
reported as hidden, and the app is left on the page it started on. Without a provider, call
auditTours(manager, { router }) from @awesome-tour/core yourself.
Playwright
@awesome-tour/testing/playwright exports Playwright’s test with a tour fixture. It works on
the stable attributes the primitives render (data-step, data-phase, data-tour-next…), so it
doesn’t care about your copy or your styling.
import { expect, test } from '@awesome-tour/testing/playwright';
test('onboarding', async ({ page, tour }) => { await page.goto('/'); await page.getByRole('button', { name: 'Start onboarding' }).click(); await tour.expectStep('welcome'); await tour.next(); await tour.expectStep('sidebar'); await tour.expectTarget('nav.sidebar'); await tour.expectNotObscuring('nav.sidebar'); // WCAG 2.4.11 await tour.close(); await tour.expectClosed();});| Helper | Does |
|---|---|
tour.dialog |
Locator for the step on screen. |
expectStep(id) |
Waits for that step to be visible and ready (target resolved, scrolled). |
expectClosed() |
Waits until no step is on screen. |
expectTarget(target) |
The element is highlighted (data-tour-target). |
expectNotObscuring(target) |
The card doesn’t cover the element. |
next() prev() close() skip() |
Click the matching button in the step. |
Not using the fixture? tourHelpers(page) returns the same object.
Unit tests (Vitest, Jest)
import { createMemoryRouter, mockLayout, waitForStep, waitForTourEnd } from '@awesome-tour/testing';import { renderWithTour } from '@awesome-tour/testing/react';
test('multi-page onboarding', async () => { const router = createMemoryRouter('/'); const { manager } = renderWithTour(<App />, { tours: [onboarding], router }); mockLayout({ '#search': { x: 100, y: 40, width: 240, height: 36 } }); // jsdom has no layout
await act(() => manager.start('onboarding')); await waitForStep(onboarding, 'search'); await act(() => onboarding.next()); expect(router.history).toEqual(['/', '/settings']);});| Helper | Does |
|---|---|
renderWithTour(ui, options) |
RTL render inside a TourProvider (tours, router, messages, impressions); returns the manager too. |
waitForStep(tour, id) |
Resolves when the step is shown and ready; rejects with the current state on timeout. |
waitForTourEnd(tour) |
Resolves with the final status. |
mockRect(el, rect) / mockLayout(map) |
Give elements a layout (returns a restore function). |
createMemoryRouter(path) |
A router adapter with a history you can assert on. |