venetian 0.2.0-aarch64-linux → 0.2.2-aarch64-linux

data/exe/aarch64-linux/package/lib/tools/skills/playwright-component-testing/references/gallery-spec.md

@@ -0,0 +1,144 @@
+# 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.
+
+```tsx
+// 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;
+};
+```
+
+```html
+<!-- 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()`:
+
+```ts
+// 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.

data/exe/aarch64-linux/package/lib/tools/skills/playwright-component-testing/references/migration.md

@@ -0,0 +1,85 @@
+# Migrating from @playwright/experimental-ct-react / -vue
+
+The CT packages compiled JSX in the test file and marshalled it into the browser. The gallery
+pattern moves the scenario into a story export that runs natively in the browser: structure (which
+component, its children, providers) plus behavior (state and callbacks, recorded into a hidden
+form for the test to assert on). Plain data props travel through `mount(storyId, props)`;
+`update()` and `unmount()` work as before.
+
+## Concept mapping
+
+| `@playwright/experimental-ct-*` | Gallery pattern |
+|---|---|
+| `mount(<Button title="…" onClick={spy} />)` | Stateful story: the story provides `onClick`, records the effect into a hidden form input; the test asserts `toHaveValue()` |
+| Plain data props from the test | Unchanged in spirit: `mount(id, props)` |
+| JSX children / slots from the test | Cannot cross — bake each composition into its own story export (Vue: `.story.vue` for slot-heavy scenarios) |
+| `component.update(<Button count={2} />)` | `component.update({ count: 2 })` — state-preserving, needs the gallery to reuse its root (`gallery-spec.md`) |
+| `component.unmount()` | `component.unmount()` — backed by the gallery's `window.unmount()` |
+| `beforeMount`/`afterMount` in `playwright/index.ts` | The body of the gallery's `window.mount` (global), or story decorators (per-story) |
+| `hooksConfig` per-test variation | Props: `mount('App/Routing', { route: '/dashboard' })` — the story/decorator interprets them |
+| `router` fixture / MSW handlers in Node | `page.route()` in the test, or MSW `setupWorker` inside a story/decorator |
+| `playwright/index.html` (styles, fonts, theme) | The gallery's `index.html` / entry module imports |
+| `ctViteConfig`, `ctPort`, `ctTemplateDir`, `ctCacheDir` | Gone — the gallery runs through the app's own dev server; port lives in `webServer` + `baseURL`; location is `playwright/gallery/` |
+| `defineConfig` from `@playwright/experimental-ct-react` | Plain `defineConfig` from `@playwright/test`, with `baseURL` = gallery URL, `serviceWorkers: 'block'`, `reuseContext: true` (see `SKILL.md`) |
+
+## Steps
+
+1. Set up the gallery and config per `SKILL.md`. Keep the old CT project running until the last
+   spec is migrated.
+2. For each CT spec, split every `mount(<…/>)` call: JSX structure becomes a story export next to
+   the component; plain data props stay in the test as `mount`'s second argument. Callback spies
+   become story state recorded into a hidden form. A call site that only varies data props usually
+   needs just one generic story that spreads them:
+   `export const Default = (props: ButtonProps) => <Button title="Submit" {...props} />`.
+3. Rewrite the spec: import `test`/`expect` from `@playwright/test`; `mount(<X a={1}/>)`
+   → `mount('X/Default', { a: 1 })`; `update(<X a={2}/>)` → `update({ a: 2 })`;
+   `unmount()` unchanged. `mount` returns a locator for the gallery root — scope the queries:
+   `component.getByRole('button').click()`. Spy assertions become `toHaveValue()` on the story's
+   recorded state.
+4. Port `beforeMount` hooks: app-wide setup into the gallery's `window.mount`; per-test
+   `hooksConfig` branches into props interpreted by a story or decorator.
+5. When all specs are green, delete the CT project from the config, drop the
+   `@playwright/experimental-ct-*` dependency, and remove `playwright/index.html`,
+   `playwright/index.ts*` and `playwright/.cache`.
+
+## Gotchas
+
+- **Story ids are strings.** Renaming or moving a story breaks specs at runtime, not compile time
+  — and the suffix-matching resolution can silently match a different story after a rename.
+- **Per-test JSX is gone.** Any test that built a different JSX tree per test (children matrices,
+  inline wrappers) becomes one story export per composition.
+
+## Before / after
+
+```tsx
+// Before (CT)
+import { test, expect } from '@playwright/experimental-ct-react';
+import Button from '../src/components/Button';
+
+test('click', async ({ mount }) => {
+  const messages: string[] = [];
+  const component = await mount(<Button title="Submit" onClick={data => messages.push(data)} />);
+  await component.click();
+  expect(messages).toEqual(['hello']);
+});
+```
+
+```tsx
+// After: src/components/Button.story.tsx
+import Button from './Button';
+
+export const Default = (props: { onClick?: (data: string) => void }) =>
+  <Button title="Submit" {...props} />;
+```
+
+```ts
+// After: src/components/Button.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('click', async ({ mount }) => {
+  const messages: string[] = [];
+  const component = await mount('components/Button/Default', { onClick: (data: string) => messages.push(data) });
+  await component.click();
+  expect(messages).toEqual(['hello']);
+});
+```

data/exe/aarch64-linux/package/lib/tools/skills/playwright-component-testing/references/react.md

@@ -0,0 +1,67 @@
+# React setup
+
+Follow the setup workflow in `SKILL.md`. Implement the gallery per `references/gallery-spec.md` (which has a React worked example); this page covers React-specific details.
+
+## Files
+
+- `playwright/gallery/` — the gallery you implement to `references/gallery-spec.md` (an `index.html` + a `main.tsx` module). Requires `react` and `react-dom` 18+ (`createRoot`).
+- Stories: `src/**/*.story.tsx` (the glob also picks up `.story.jsx`); example in `templates/react/Button.story.tsx`.
+
+## StrictMode
+
+Wrap the rendered story in `<React.StrictMode>` in your gallery to match how most apps render. In development builds StrictMode intentionally double-invokes render functions and effects. This matters for stories that record events with counters set in effects — recording via state updates from event handlers (like the `CountsClicks` example story) is unaffected. If a story misbehaves under StrictMode, that is usually a real finding about the component; drop the wrapper only if the app itself does not use StrictMode.
+
+## Global providers
+
+If components require context (theme, store, i18n, router), create one shared decorator and use it in stories, so each story states its scenario and nothing more:
+
+```tsx
+// src/stories/decorators.tsx
+import { ThemeProvider } from '../theme';
+import { MemoryRouter } from 'react-router-dom';
+
+export function AppScaffold({ children, route = '/' }: { children: React.ReactNode, route?: string }) {
+  return (
+    <ThemeProvider theme="light">
+      <MemoryRouter initialEntries={[route]}>{children}</MemoryRouter>
+    </ThemeProvider>
+  );
+}
+```
+
+```tsx
+// src/components/ProfilePage.story.tsx
+export const LoggedIn = () => (
+  <AppScaffold route="/profile/42">
+    <ProfilePage user={{ id: 42, name: 'Test User' }} />
+  </AppScaffold>
+);
+```
+
+Do not build the decorator into the gallery — keeping it in story files makes the wrapping visible and lets stories opt out.
+
+## Typed props
+
+`mount` is generic over the story: pass the story type as a template argument to type-check per-test props (and `update()`). Props are inferred from the component signature; function and class components both work.
+
+```tsx
+// src/components/Button.story.tsx
+export const WithTitle = ({ title = 'Default' }: { title?: string }) =>
+  <Button title={title} />;
+```
+
+```ts
+// src/components/button.spec.ts
+import type { WithTitle } from './Button.story';
+
+const component = await mount<typeof WithTitle>('components/Button/WithTitle', { title: 'Hello' });
+```
+
+## CSS
+
+- Global stylesheets: import them in your gallery entry (`playwright/gallery/main.tsx`, e.g. `import '../../src/index.css'`), mirroring the app's own entry point.
+- Tailwind: if content scanning is path-based, make sure `*.story.tsx` files are covered.
+
+## Data fetching
+
+For libraries with client objects (React Query, Apollo), create the client inside the story or decorator so each navigation starts fresh.

data/exe/aarch64-linux/package/lib/tools/skills/playwright-component-testing/references/vue.md

@@ -0,0 +1,75 @@
+# Vue setup
+
+Follow the setup workflow in `SKILL.md`. Implement the gallery per `references/gallery-spec.md`, exposing `window.mount`/`window.unmount` — in Vue, mount with `app = createApp(h(story, props)); app.mount('#root')` and unmount with `app.unmount()`; this page covers Vue-specific details.
+
+## Files
+
+- `playwright/gallery/` — the gallery you implement to `references/gallery-spec.md` (an `index.html` + a `main.ts` module). Requires Vue 3.
+- Stories: `src/**/*.story.{ts,js,vue}`; example in `templates/vue/Button.story.ts`.
+
+## Two ways to write stories
+
+**Render-function stories** (`Button.story.ts`) — several scenarios per file, one named export each; see `templates/vue/Button.story.ts`. Uses `defineComponent` + `h()`, no SFC compilation involved.
+
+**Single-file-component stories** (`Button.primary.story.vue`) — one story per file, full template syntax:
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import Button from './Button.vue';
+const clicks = ref(0);
+</script>
+
+<template>
+  <Button title="Submit" @click="clicks++" />
+  <form hidden><input data-testid="click-count" readonly :value="String(clicks)" /></form>
+</template>
+```
+
+An SFC story is addressed by its path without the extension: `mount('components/Button.primary')`. Prefer SFC stories when the scenario needs slots or non-trivial templates.
+
+## Global plugins
+
+Apps that rely on plugins (Pinia, vue-router, i18n) should wrap components with a decorator story helper that creates a fresh instance per story:
+
+```ts
+// src/stories/decorators.ts
+import { defineComponent, h, type Component } from 'vue';
+import { createPinia } from 'pinia';
+
+export function withStore(story: Component) {
+  return defineComponent(() => {
+    const pinia = createPinia();
+    return () => h(story, { pinia });
+  });
+}
+```
+
+For plugins that must be installed on the app instance (`app.use(...)`), add them in your gallery right after `createApp(...)` — that is the equivalent of the app's own bootstrap.
+
+## Typed props
+
+A story that takes per-test props declares them twice: in the setup signature (for the type) and in the `props` option (so Vue delivers them as props rather than `attrs`):
+
+```ts
+// src/components/Button.story.ts
+export const WithTitle = defineComponent(
+  (props: { title?: string }) => () => h(Button, { title: props.title ?? 'Default' }),
+  { props: ['title'] },
+);
+```
+
+`mount` is generic over the story: pass the story type as a template argument to type-check the props (and `update()`):
+
+```ts
+// src/components/button.spec.ts
+import type { WithTitle } from './Button.story';
+
+const component = await mount<typeof WithTitle>('components/Button/WithTitle', { title: 'Hello' });
+```
+
+Options-API stories (`defineComponent({ props: { ... } })`) infer props the same way. For `.story.vue` SFC stories, prop types are only inferable when the setup generates SFC types (Volar/vue-tsc); otherwise pass the props type directly: `mount<{ title?: string }>('components/Button.primary', { title: 'Hello' })`.
+
+## CSS
+
+Import global stylesheets in your gallery entry (`playwright/gallery/main.ts`, e.g. `import '../../src/assets/main.css'`), mirroring the app's entry point.

data/exe/aarch64-linux/package/lib/tools/utils/extension.js

@@ -28,6 +28,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var extension_exports = {};
 __export(extension_exports, {
+  findPlaywrightExtensionProfile: () => findPlaywrightExtensionProfile,
   isPlaywrightExtensionInstalled: () => isPlaywrightExtensionInstalled,
   playwrightExtensionId: () => playwrightExtensionId,
   playwrightExtensionInstallUrl: () => playwrightExtensionInstallUrl
@@ -37,20 +38,41 @@ var import_fs = __toESM(require("fs"));
 var import_path = __toESM(require("path"));
 const playwrightExtensionId = "mmlmfjhmonkocbjadbfplnigmagldckm";
 const playwrightExtensionInstallUrl = `https://chromewebstore.google.com/detail/playwright-extension/${playwrightExtensionId}`;
-async function isPlaywrightExtensionInstalled(userDataDir) {
+async function findPlaywrightExtensionProfile(userDataDir) {
+  const profiles = await listProfileDirectories(userDataDir);
+  const lastUsed = await readLastUsedProfile(userDataDir);
+  const ordered = lastUsed && profiles.includes(lastUsed) ? [lastUsed, ...profiles.filter((profile) => profile !== lastUsed)] : profiles;
+  for (const profile of ordered) {
+    if (await isExtensionInstalledInProfile(import_path.default.join(userDataDir, profile)))
+      return profile;
+  }
+  return void 0;
+}
+async function listProfileDirectories(userDataDir) {
   let entries;
   try {
     entries = await import_fs.default.promises.readdir(userDataDir);
   } catch {
-    return false;
+    return [];
   }
-  for (const entry of entries) {
-    if (entry !== "Default" && !entry.startsWith("Profile "))
-      continue;
-    if (await isExtensionInstalledInProfile(import_path.default.join(userDataDir, entry)))
-      return true;
+  const profiles = entries.filter((entry) => entry === "Default" || /^Profile \d+$/.test(entry));
+  profiles.sort((a, b) => profileRank(a) - profileRank(b));
+  return profiles;
+}
+function profileRank(profile) {
+  return profile === "Default" ? -1 : parseInt(profile.slice("Profile ".length), 10);
+}
+async function readLastUsedProfile(userDataDir) {
+  try {
+    const localState = JSON.parse(await import_fs.default.promises.readFile(import_path.default.join(userDataDir, "Local State"), "utf-8"));
+    const lastUsed = localState?.profile?.last_used;
+    return typeof lastUsed === "string" ? lastUsed : void 0;
+  } catch {
+    return void 0;
   }
-  return false;
+}
+async function isPlaywrightExtensionInstalled(userDataDir) {
+  return await findPlaywrightExtensionProfile(userDataDir) !== void 0;
 }
 async function isExtensionInstalledInProfile(profileDir) {
   if (await pathExists(import_path.default.join(profileDir, "Extensions", playwrightExtensionId)))
@@ -72,6 +94,7 @@ async function pathExists(p) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  findPlaywrightExtensionProfile,
   isPlaywrightExtensionInstalled,
   playwrightExtensionId,
   playwrightExtensionInstallUrl