Pattern Test To Integration

Pattern Test to Integration

Treat the pattern test as the behavioral story, not as code to transliterate. Re-express its meaningful state transitions through the real shell, browser, rendered controls, and visible outcomes.

Start from the current map

Read the source test, the pattern it instantiates, and these current references:

• docs/common/ai/pattern-testing-guide.md — pattern-test semantics, including multi-user participants.
• packages/patterns/deno.jsonc — the three test lanes and their CI/coverage roles.
• docs/development/UI_TESTING.md — shadow DOM, semantic locators, presentation behavior, and browser interaction rules.
• docs/development/TESTING.md — integration and deno task demo commands.
• docs/development/waiting-in-tests.md — required reading before introducing any polling.
• packages/patterns/integration/cfc-browser-helpers.ts — shared interaction, settling, effect-wait, and StepTimer seams.
• packages/patterns/integration/pieces-controller.ts — the local PiecesController initializer with the shared compile-byte cache.

Use working integration tests as executable examples:

• packages/patterns/integration/nested-counter.test.ts for a small single-browser interaction.
• packages/patterns/integration/cfc-render-policy-demo.test.ts for a concise, captioned demo.
• packages/patterns/integration/lunch-poll-vote.test.ts for two independent identities, browsers, and recordings on one shared timeline.

Prefer the nearest current test with the same topology over copying a generic fixture. Tests are authoritative when a prose example has drifted.

Before choosing a destination, search packages/patterns/integration/ for the pattern name, source path, and intended scenario. Extend current browser coverage when it already owns the story. If a separate scenario is clearer, give it a specific filename and selector; never overwrite or duplicate an existing test merely because the unit test has the shorter name.

Preserve both test contracts

Keep the original colocated *.test.tsx. Pattern tests are the authored-pattern coverage lane; a browser integration test does not replace that coverage.

Add the browser test under packages/patterns/integration/ as *.test.ts. The new test covers boundaries the pattern test intentionally omits: shell navigation, rendering, shadow DOM, real event dispatch, browser identity, and cross-client propagation.

Do not call the conversion complete if the browser test still performs the primary scenario by sending the same output streams and reading the same result fields directly. Direct piece operations remain useful for setup, invisible invariants, persistence checks, and diagnostics; they are not substitutes for the user-visible action and outcome.

Translate intent across the boundary

Use this map as a starting point, then follow the actual UI:

Preserve the scenario's causal ordering and important edge cases, but optimize for a coherent browser story rather than one it block per unit assertion. Group assertions that describe one visible state. An exhaustive internal invariant with no UI manifestation should stay in the pattern test unless the product is meant to expose it.

If the pattern has no rendered path for the behavior, say so explicitly. Add a product UI seam only when the user's task authorizes changing the product; do not create a test-only button or browser backdoor merely to force a conversion.

Use the real integration lifecycle

Build from the closest fixture, retaining the local invariants it demonstrates:

• Bind every ShellIntegration lifecycle.

• Generate explicit identities and keep all participants in the intended shared space. Reuse one identity across multiple shells when the source test models multiple sessions for the same user; use distinct identities for distinct users.

• Build the program with resolveLocalProgram from @commonfabric/runner/local-program.deno, passing the harness's own resolve. Give it root when the source imports siblings outside its own directory, and dataFilePaths when the pattern reads an attached data file with dataFile():

  const program = await resolveLocalProgram(
    (resolver) => cc.runtime.harness.resolve(resolver),
    { main: sourcePath, root: rootPath, dataFilePaths: [dataPath] },
  );
  

  A pattern reading a data file compiles and type-checks without the attachment, so omitting it fails at the read rather than at the build. deno task check-local-program refuses a FileSystemProgramResolver built by hand, because a program assembled that way silently carries no data files.

• Pass initial unit-test inputs through PiecesController.create's input option when they are part of the scenario.

• Keep the result demanded with a result-cell sink when pull-mode reactivity requires it, and cancel every sink during cleanup.

• Call ensureDefaultPattern() before browser navigation when the selected topology would otherwise race or cold-compile the space root; copy this seam only from a current fixture that explains why it is needed.

• Navigate with ShellIntegration.goto(...) and the generated identity.

• Dispose controllers and let bound shell lifecycles close browsers.

Use the helpers in packages/patterns/integration/cfc-browser-helpers.ts where they already encode shadow traversal, one trusted interaction, view settling, commit semantics, or an effect wait. Prefer accessible names and stable product-facing selectors. Do not select by transient DOM structure when the UI offers a semantic role, label, or explicit stable id.

Make the scenario's scale a knob

A browser test written at one fixed size answers whether the feature works. The same test with its size parameterized also answers how the feature behaves as data grows, which is a different and usually more valuable question — and it costs one constant to keep both. Read the size from the environment with a small default, so CI keeps paying the small number while an investigation can ask for a large one.

Three distinctions are worth building in, because retrofitting them later means rewriting the scenario:

• Composed versus seeded. A couple of items driven through the real composer are what make the test a regression test; the rest exist only to establish size and should be created through the verb. Keep the two counts separate and derive the seeded count from the total. Presentation mode animates every keystroke, so a large board built through the composer is also an unwatchable recording.
• Where the bulk is created. Seeding before the view is ever opened and seeding while it is on screen measure different things — the first is the cost with nothing rendering, the second is the cost of the live view keeping up. Make that a knob too rather than picking one.
• Extra timed operations after the bulk exists. What a regression actually cares about is what one more costs on a board of that size, which is not recoverable by dividing the time it took to build it.

Emit measurements as parseable single lines carrying the size they were taken at, rather than only as step durations, so a sweep across sizes can be collected without re-reading logs by eye.

packages/patterns/integration/topic-board-scale.bench.ts is the same idea in the benchmark lane, including how it declares sizes it cannot yet run. When the task is measurement rather than conversion, skills/perf-investigation/SKILL.md picks up from here.

Keep correctness timing separate from presentation

Wait for a real state or DOM effect. Do not add sleep, waitForTimeout, or a larger correctness timeout to make the video readable. Read docs/development/waiting-in-tests.md before adding a bounded poll, and explain why no event-driven observation exists if one is still necessary.

Make demo pacing an annotation of the same test:

• Give each shell stable presentation metadata; use distinct labels and colors for multiple participants.
• Wrap viewer-meaningful scenario boundaries in StepTimer.run(label, action). Write labels for the viewer: describe what changes without leaking hidden or protected values before the UI reveals them.
• Keep using the existing click, fill, keyboard, and element paths. Presentation mode observes those paths; do not invent demo.click() or demo.type().
• Preserve one real browser per participant. The demo compositor owns the side-by-side or grid layout.

The demo command records the complete selected *.test.ts file, including all of its it blocks. Keep the file's ordered scenario meaningful as a whole. Do not silently select ignored or environment-gated tests as default demos.

Verify the paired result

Run the original pattern test before conversion to establish a clean baseline, and again after any source/interface change:

deno task cf test packages/patterns/<pattern>/<name>.test.tsx

If the test imports sibling modules above its own directory, pass their common source root just as the CLI error suggests, for example:

deno task cf test packages/patterns/<pattern>/<name>.test.tsx --root packages/patterns

Run the browser test through the integration selector, using its exact filename stem:

deno task integration patterns <integration-test-name>

When demo output is part of the request and FFmpeg is available, record the same test rather than a demo-only variant:

deno task demo patterns <integration-test-name>

Inspect the video or gallery when presentation quality matters. Passing tests prove correctness; they do not prove that labels, pacing, framing, and multi-user composition are understandable to a viewer.