@ddwang/magnitude-core 0.3.1-ddwang.2 → 0.3.1-ddwang.21

package/node_modules/patchright-core/lib/tools/skills/playwright-component-testing/references/migration.md

@@ -0,0 +1,89 @@
+# 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`) |
+
+The CT packages were removed in Playwright 1.63 and are no longer published, so migrate while
+pinned to Playwright 1.62 and upgrade once the last spec is ported.
+
+## 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, remove `playwright/index.html`,
+   `playwright/index.ts*` and `playwright/.cache`, and lift the Playwright version pin.
+
+## 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.
+  Gallery types (`typing.md`) turn registered ids into a compile-time check.
+- **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']);
+});
+```

package/node_modules/patchright-core/lib/tools/skills/playwright-component-testing/references/react.md

@@ -0,0 +1,69 @@
+# 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' });
+```
+
+Alternatively, generate gallery types so the id itself is typed and no type import is needed: `mount('acme-ui/components/Button/WithTitle', { title: 'Hello' })` — see `references/typing.md`.
+
+## 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.

package/node_modules/patchright-core/lib/tools/skills/playwright-component-testing/references/typing.md

@@ -0,0 +1,173 @@
+# Typing `mount()`
+
+`mount(storyId, props?)` accepts any string id and any serializable props. Two optional layers
+add type checking on top; both are supported and can be mixed in one project.
+
+| | Explicit story type | Gallery types |
+|---|---|---|
+| Call | `mount<typeof WithTitle>('components/Button/WithTitle', { title })` | `mount('acme-ui/components/Button/WithTitle', { title })` |
+| Checks | props and `update()` | props, `update()`, and the id itself (autocomplete, rename safety) |
+| Needs | `import type { WithTitle } from './Button.story'` in the spec | a generated `stories.d.ts` kept in sync by a gallery plugin |
+| Id grammar | any suffix the gallery resolves | full id, prefixed with the package name |
+
+## Explicit story type
+
+Pass the story type as a template argument. Nothing to set up; works in every project.
+
+```ts
+import type { WithTitle } from './Button.story';
+
+const component = await mount<typeof WithTitle>('components/Button/WithTitle', { title: 'Hello' });
+await component.update({ title: 'Again' });
+```
+
+Use `import type` so the story (and with it React/Vue and CSS imports) is never loaded into the
+Node test process. Function components, class components and `defineComponent` stories all infer
+their props; see the `Typed props` sections in `react.md` / `vue.md` for framework details.
+
+## Gallery types
+
+`@playwright/test` exports an empty `interface Stories {}`. When a story id is a key of `Stories`,
+`mount` types the props from that entry; any other string keeps untyped props, so adoption can be
+partial. A tiny Vite plugin next to the gallery generates `stories.d.ts`, which fills `Stories` in
+via module augmentation:
+
+```ts
+// playwright/gallery/stories.d.ts (generated)
+type StoriesOf<Prefix extends string, Mod> = { [K in keyof Mod & string as `${Prefix}/${K}`]: Mod[K] };
+
+declare module '@playwright/test' {
+  interface Stories extends
+    StoriesOf<'acme-ui/components/Button', typeof import('../../src/components/Button.story')>,
+    StoriesOf<'acme-ui/components/Expandable', typeof import('../../src/components/Expandable.story')> {}
+}
+
+export {};
+```
+
+One line per story file; export names and prop types come from the story module itself, so the
+file only changes when a story file is added, removed or moved. Specs then need no type imports:
+
+```ts
+const component = await mount('acme-ui/components/Button/WithTitle', { title: 'Hello' });
+//                            ^ autocompletes registered ids       ^ checked against WithTitle's props
+```
+
+### Namespace ids with the package name
+
+`Stories` is merged per TypeScript program. In a monorepo whose packages share one `tsconfig`,
+two packages both registering `components/Button/Default` with different props fail with
+`TS2320: Interface 'Stories' cannot simultaneously extend types ...` at the `Stories` declaration,
+and even distinct ids leak into each other's autocomplete. Prefix every id with the package name,
+`<package>/<path under src>/<Export>`, from the start, so the convention holds when a project
+becomes a package. Read the name from `package.json` in both places that derive ids, so they
+cannot drift:
+
+```ts
+// playwright/gallery/main.tsx
+import packageJSON from '../../package.json';
+
+const id = (f: string) => packageJSON.name + '/' + f.replace(/^(\.\.\/)+src\//, '').replace(/\.story\.\w+$/, '');
+```
+
+Suffix resolution keeps working at runtime, so `mount('Button/Primary')` still renders; only the
+full prefixed id is typed.
+
+### The plugin
+
+Framework-agnostic: it only lists story files. Adjust `storyFile` to match the gallery's glob.
+
+```ts
+// playwright/gallery/storyTypes.ts
+import fs from 'fs';
+import path from 'path';
+import type { Plugin } from 'vite';
+
+const storyFile = /\.story\.(tsx|jsx)$/;
+
+export function storyTypes(options: { prefix: string, src: string, outFile: string }): Plugin {
+  const generate = () => {
+    const content = render(listStoryFiles(options.src), options);
+    if (fs.existsSync(options.outFile) && fs.readFileSync(options.outFile, 'utf8') === content)
+      return;
+    fs.writeFileSync(options.outFile, content);
+  };
+  return {
+    name: 'story-types',
+    buildStart() {
+      this.addWatchFile(options.src);
+      generate();
+    },
+    configureServer(server) {
+      const onFile = (file: string) => {
+        if (storyFile.test(file))
+          generate();
+      };
+      server.watcher.on('add', onFile);
+      server.watcher.on('unlink', onFile);
+    },
+  };
+}
+
+function listStoryFiles(dir: string): string[] {
+  const result: string[] = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const file = path.join(dir, entry.name);
+    if (entry.isDirectory())
+      result.push(...listStoryFiles(file));
+    else if (storyFile.test(entry.name))
+      result.push(file);
+  }
+  return result.sort();
+}
+
+function render(files: string[], { prefix, src, outFile }: { prefix: string, src: string, outFile: string }): string {
+  const outDir = path.dirname(outFile);
+  const posix = (p: string) => p.split(path.sep).join('/');
+  const entries = files.map(file => {
+    const id = prefix + '/' + posix(path.relative(src, file)).replace(storyFile, '');
+    const specifier = posix(path.relative(outDir, file)).replace(/\.\w+$/, '');
+    return `    StoriesOf<'${id}', typeof import('${specifier.startsWith('.') ? specifier : './' + specifier}')>`;
+  });
+  const stories = entries.length ? `interface Stories extends\n${entries.join(',\n')} {}` : 'interface Stories {}';
+  return `// Generated by storyTypes.ts, do not edit.
+
+type StoriesOf<Prefix extends string, Mod> = { [K in keyof Mod & string as \`\${Prefix}/\${K}\`]: Mod[K] };
+
+declare module '@playwright/test' {
+  ${stories}
+}
+
+export {};
+`;
+}
+```
+
+Register it on whichever Vite server serves the gallery (the app's `vite.config.ts`, or the
+standalone `playwright/vite.config.ts`):
+
+```ts
+import packageJSON from './package.json';
+import { storyTypes } from './playwright/gallery/storyTypes';
+
+export default defineConfig({
+  plugins: [
+    react(),
+    storyTypes({
+      prefix: packageJSON.name,
+      src: path.resolve(__dirname, 'src'),
+      outFile: path.resolve(__dirname, 'playwright/gallery/stories.d.ts'),
+    }),
+  ],
+});
+```
+
+The file is regenerated on every dev-server start and build, and while the server runs, whenever
+a story file appears or disappears. Its content is deterministic, so **commit it**: type-checking
+in CI or an editor must not depend on a running dev server. Nothing imports the file, so list it
+explicitly in the project's `tsconfig` (`"files": ["playwright/gallery/stories.d.ts"]`) so that
+`tsc` and editors load it.
+
+For `.story.vue` single-file components, map the `default` export to the bare path in
+`StoriesOf` (`K extends 'default' ? Prefix : \`${Prefix}/${K}\``) and rely on `vue-tsc` for the
+SFC's types; a story without inferable props types as `unknown` props, which accepts anything.

package/node_modules/patchright-core/lib/tools/skills/playwright-component-testing/references/vue.md

@@ -0,0 +1,77 @@
+# 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' });
+```
+
+Alternatively, generate gallery types so the id itself is typed and no type import is needed: `mount('acme-ui/components/Button/WithTitle', { title: 'Hello' })` — see `references/typing.md`.
+
+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.

package/node_modules/patchright-core/lib/tools/skills/playwright-trace/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: playwright-trace
+description: Inspect Playwright trace files from the command line — list actions, view requests, console, errors, snapshots and screenshots.
+allowed-tools: Bash(npx playwright trace:*)
+---
+
+# Playwright Trace CLI
+
+Inspect `.zip` trace files produced by Playwright tests without opening a browser.
+
+## Workflow
+
+1. Start with `trace open <trace.zip>` to extract the trace and see its metadata.
+2. Use `trace actions` to see all actions with their action IDs.
+3. Use `trace action <action-id>` to drill into a specific action — see parameters, logs, source location, and available snapshots.
+4. Use `trace requests`, `trace console`, or `trace errors` for cross-cutting views.
+5. Use `trace snapshot <action-id>` to get the DOM snapshot, or run a browser command against it.
+6. Use `trace close` to remove the extracted trace data when done.
+
+All commands after `open` operate on the currently opened trace — no need to pass the trace file again. Opening a new trace replaces the previous one.
+
+## Commands
+
+### Open a trace
+
+```bash
+# Extract trace and show metadata: browser, viewport, duration, action/error counts
+npx playwright trace open <trace.zip>
+```
+
+### Close a trace
+
+```bash
+# Remove extracted trace data
+npx playwright trace close
+```
+
+### Actions
+
+```bash
+# List all actions as a tree with action IDs and timing
+npx playwright trace actions
+
+# Filter by action title (regex, case-insensitive)
+npx playwright trace actions --grep "click"
+
+# Only failed actions
+npx playwright trace actions --errors-only
+```
+
+### Action details
+
+```bash
+# Show full details for one action: params, result, logs, source, snapshots
+npx playwright trace action <action-id>
+```
+
+The `action` command displays available snapshot phases (before, action, after) and the exact command to extract them.
+
+### Requests
+
+```bash
+# All network requests: start time (on the `trace actions` clock), method, status, URL, duration, size
+npx playwright trace requests
+
+# Filter by URL pattern
+npx playwright trace requests --grep "api"
+
+# Filter by HTTP method
+npx playwright trace requests --method POST
+
+# Only failed requests (status >= 400)
+npx playwright trace requests --failed
+```
+
+### Request details
+
+```bash
+# Show full details for one request: headers, body, security
+npx playwright trace request <request-id>
+```
+
+### Console
+
+```bash
+# All console messages and stdout/stderr
+npx playwright trace console
+
+# Only errors
+npx playwright trace console --errors-only
+
+# Only browser console (no stdout/stderr)
+npx playwright trace console --browser
+
+# Only stdout/stderr (no browser console)
+npx playwright trace console --stdio
+
+# Filter by message text pattern
+npx playwright trace console --grep "failed to fetch"
+```
+
+### Errors
+
+```bash
+# All errors with stack traces and associated actions
+npx playwright trace errors
+```
+
+### Snapshots
+
+The `snapshot` command loads the DOM snapshot for an action into a headless browser and runs a single browser command against it. Without a browser command, it returns the accessibility snapshot.
+
+```bash
+# Get the accessibility snapshot (default)
+npx playwright trace snapshot <action-id>
+
+# Use a specific phase
+npx playwright trace snapshot <action-id> --phase before
+
+# Run eval to query the DOM
+npx playwright trace snapshot <action-id> -- eval "document.title"
+npx playwright trace snapshot <action-id> -- eval "document.querySelector('#error').textContent"
+
+# Eval on a specific element ref (from the snapshot)
+npx playwright trace snapshot <action-id> -- eval "el => el.getAttribute('data-testid')" e5
+
+# Take a screenshot of the snapshot
+npx playwright trace snapshot <action-id> -- screenshot
+
+# Redirect output to a file
+npx playwright trace snapshot <action-id> -- eval "document.body.outerHTML" --filename=page.html
+npx playwright trace snapshot <action-id> -- screenshot --filename=screenshot.png
+```
+
+Only three browser commands are useful on a frozen snapshot: `snapshot`, `eval`, and `screenshot`.
+
+### Attachments
+
+```bash
+# List all trace attachments
+npx playwright trace attachments
+
+# Extract an attachment by its number
+npx playwright trace attachment 1
+npx playwright trace attachment 1 -o out.png
+```
+
+## Typical investigation
+
+```bash
+# 1. Open the trace and see what's inside
+npx playwright trace open test-results/my-test/trace.zip
+
+# 2. What actions ran?
+npx playwright trace actions
+
+# 3. Which action failed?
+npx playwright trace actions --errors-only
+
+# 4. What went wrong?
+npx playwright trace action 12
+
+# 5. What did the page look like at that moment?
+npx playwright trace snapshot 12
+
+# 6. Query the DOM for more detail
+npx playwright trace snapshot 12 -- eval "document.querySelector('.error-message').textContent"
+
+# 7. Any relevant network failures?
+npx playwright trace requests --failed
+
+# 8. Any console errors?
+npx playwright trace console --errors-only
+```