Skip to content
awesome-tour

Type to search every page.

    BTestingContents

    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.

    Terminal window
    pnpm add -D @awesome-tour/testing
    Terminal window
    npm i -D @awesome-tour/testing

    Tour 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:

    Terminal window
    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.