Gallery contract

The gallery is a single page, served by your dev server at the URL you set as baseURL in your Playwright config, that exposes two methods on window for Playwright to drive:

• window.mount(params) — render a story.
• window.unmount() — unmount the current story.

The built-in mount fixture navigates to the gallery, then calls window.mount via page.evaluate(). Keep props to plain serializable data — where the component takes callbacks, the story creates the state, provides the callbacks and records the state into a hidden form for the test to assert on.

window.mount(params)

params is { story, props }, straight from the test's mount(story, props) call:

• story — the story id (string). Resolve it (see id grammar) to a component.
• props — the plain serializable props object passed to the component.

Render the resolved component with props into #root. Return a Promise that resolves once the component is mounted and rejects on failure (unknown story, render throw). The rejection surfaces as the test's await mount(...) throwing, with a real stack — there is no HTTP-status or DOM-attribute signalling.

Reuse the root across calls. The test's component.update(props) calls window.mount again with the same story and new props, without navigating. If you render into the same root / instance rather than recreating it, the framework reconciles and component-internal state is preserved — that is CT's update(). Recreating the root each call (or navigating) resets state, so reuse it: create it on first mount and render into it on every call. The framework reconciles, remounting on its own only when the story (component type) changes.

window.mount is your setup/teardown hook. It is the browser-side equivalent of CT's beforeMount / afterMount: install providers or plugins, seed a store, start an in-browser mock server before you render, and run post-render work after — all inside this one function, branched on the story / props the test passed. There is no separate hook registry; the function you own is the hook.

window.unmount()

Unmount the current story from #root and return a Promise. The test calls it via component.unmount(). Needed only to assert teardown/cleanup effects — each mount navigates fresh, so tests are already isolated.

#root

Render the component into an element with id="root". mount returns a Locator for #root itself, so tests scope their queries from there — component.getByRole('button').click(), not component.click(). Stories are free to render fragments, e.g. the component plus a hidden form recording its state.

Story id grammar (recommended)

The gallery owns resolution; mount passes the id through untouched. Recommended scheme:

• <path under src, without the .story.* extension>/<ExportName> — e.g. src/components/Button.story.tsx export Primary → components/Button/Primary.
• Any unique trailing suffix resolves too: Button/Primary.
• A single-file-component story (Button.story.vue) is one story, addressed by its path alone (its default export): components/Button.

Worked example (React + Vite SPA)

An illustration of the contract, not a file to copy — implement the equivalent for your stack. import.meta.glob stays inline here: Vite analyzes it statically, relative to this file, so it cannot be moved into shared/shipped code. That is exactly why the gallery is yours to own.

// playwright/gallery/main.tsx
import { flushSync } from 'react-dom';
import { createRoot, type Root } from 'react-dom/client';

const stories = import.meta.glob('../../src/**/*.story.{tsx,jsx}');
const id = (f: string) => f.replace(/^(\.\.\/)+src\//, '').replace(/\.story\.\w+$/, '');

async function resolve(storyId: string) {
  const sep = storyId.lastIndexOf('/');
  const [path, name] = [storyId.slice(0, sep), storyId.slice(sep + 1)];
  const file = Object.keys(stories).find(f => id(f) === path || id(f).endsWith('/' + path));
  const mod = (file && await stories[file]()) as Record<string, any> | undefined;
  return mod?.[name] ?? mod?.default;
}

const rootEl = document.getElementById('root')!;
let root: Root | undefined;

(window as any).mount = async ({ story, props }: { story: string, props?: Record<string, any> }) => {
  const Story = await resolve(story);
  if (!Story)
    throw new Error(`Unknown story: ${story}`);
  root ??= createRoot(rootEl);   // reuse the root so update() reconciles and preserves state
  // flushSync so a render error rejects the promise instead of being swallowed.
  flushSync(() => root!.render(<Story {...props} />));
};

(window as any).unmount = async () => {
  root?.unmount();
  root = undefined;
};

<!-- playwright/gallery/index.html -->
<!DOCTYPE html>
<div id="root"></div>
<script type="module" src="./main.tsx"></script>

Vue variant (state-preserving)

Vue's createApp(...).mount() builds a fresh instance each call, so mount a small reactive host once and update its refs — updating them re-renders in place, which is what preserves state across update():

// playwright/gallery/main.ts
import { createApp, h, shallowRef, type App, type Component } from 'vue';

// resolve() and the import.meta.glob are the same as the React example.
const story = shallowRef<Component | null>(null);
const props = shallowRef<Record<string, any>>({});
const host = { render: () => (story.value ? h(story.value, props.value) : null) };
let app: App | undefined;

(window as any).mount = async ({ story: id, props: next }: { story: string, props?: Record<string, any> }) => {
  const resolved = await resolve(id);
  if (!resolved)
    throw new Error(`Unknown story: ${id}`);
  story.value = resolved;
  props.value = next ?? {};
  if (!app) {                    // mount once; the ref updates above re-render in place
    app = createApp(host);
    app.mount('#root');
  }
};

(window as any).unmount = async () => {
  app?.unmount();
  app = undefined;
};

Keep the story-resolution glob and the framework mount in this file; everything else lives in your stories and tests.