Files

Bryce 3ecd115f76 docs(skill): distil ssr-form-migration skill from transaction-edit reference (Phase 1)

Capture the proven whole-form hx-select swap method as a reusable skill so every
later modal migration is cheaper and consistent. No app code changes.

- SKILL.md: the per-migration playbook (classify → baseline → characterize →
  consolidate render fns → templatize → wire HTMX → collapse routes → verify →
  commit → feed skill) + Growth contract + non-negotiables.
- reference/swap-doctrine.md: the four swap rules, focus invariant, Alpine-survives-
  swap hardening, target-selector strategy — worked from the real edit.clj swaps
  (memo no-request, account→location targeted cell, amount→totals sibling-tbody,
  vendor/mode/row whole-form). 0 OOB.
- reference/render-functions.md: explicit-data or top-rooted cursor; the MapCursor
  fake + transaction-account-row-no-cursor* twin as the smell to remove.
- reference/form-vs-wizard.md: classification + the data-driven session-backed
  (formtools SessionStorage) engine that replaces the snapshot round-trip + protocol.
- reference/selmer-conventions.md: STUB, validated in Phase 2.
- component-cookbook.md / gotchas.md / test-recipes.md / scorecard.md: seeded from
  what transaction-edit proves (7 cookbook entries, caret-survival + typeahead test
  recipes, scorecard baseline LOC 1608 / ~12 routes / 1 no-cursor twin / 2 faked
  roots / 0 OOB).

Scorecard (Transaction Edit baseline, before Phase 2): LOC 1608, routes ~12,
no-cursor twins 1, faked-cursor roots 2, snapshot merges ~75, OOB 0, mixed hx- 8.

2026-06-03 00:05:11 -07:00

4.3 KiB

Raw Blame History

Test recipes

GROWS every migration. How to characterize and verify a modal. Consistent with the project testing-conventions skill: test user-observable behavior, assert DB state directly, don't test the means.

The three test layers

Characterization e2e first (Playwright). Before changing a modal, write/confirm a spec capturing current behavior — focus/caret survival across swaps, each field round-trip, validation errors, the real save. This is the parity contract; keep it green through every commit.
Pure-function checks via REPL. Once render/data-prep fns are pure, exercise them with clojure-eval / clj-nrepl-eval -p <port>. Assert on returned data; for markup use string matches ((re-find #"accounts\[0\]\[account\]" (str html))) — this style survives the Selmer switch. Avoid brittle structural assertions.
DB-state assertions for mutations. If a submit writes Datomic, verify by querying the DB, not by asserting on markup.

Running e2e

npx playwright test                              # full suite
npx playwright test e2e/transaction-edit-swap.spec.ts   # one spec

Config: playwright.config.ts, baseURL http://localhost:3333, webServer: lein run -m auto-ap.test-server, reuseExistingServer: !CI.
The server must be from the worktree you're testing. reuseExistingServer will silently reuse any server on :3333 — including another worktree's. Confirm with ls -la /proc/$(lsof -ti :3333)/cwd (or restart on a clean port) before trusting a run.
The test-server port is hardcoded (test_server.clj run-jetty {:port 3333}); to run a second server from another worktree, change that or parameterise it.

Driving a typeahead in e2e (Solr unavailable in tests)

await typeahead.locator('a[x-ref="input"]').click();      // open tippy dropdown
const search = page.locator('[data-tippy-root] input[x-model="search"]').first();
await search.fill('te');                                  // under 3-char Solr threshold
await typeahead.evaluate((el, id) => {                     // inject a clickable result
  window.Alpine.$data(el).elements = [{ value: id, label: 'Test Account' }];
}, accountId);
await page.locator('[data-tippy-root] a', { hasText: 'Test Account' }).first().click();

Entity ids come from GET /test-info ({accounts:{test-account, vendor, vendor2, ...}}).

Proving the focus invariant (caret survival) — the key swap test

// before the debounced swap lands, capture the live focused node...
await page.evaluate(() => { window.__focused = document.activeElement; });
await swap;                                       // waitForResponse on the *-form-changed POST
const ok = await page.evaluate(() => {
  const a = document.activeElement;
  return { sameNode: a === window.__focused, value: a?.value, caret: a?.selectionStart };
});
// ...assert the SAME node survived with value + caret intact.

trackErrors(page) (collect pageerror + console.error, assert []) catches a swap that throws on a stale $refs/tippy — pair it with every swap test.

Asserting "no request" (Rule 1 fields)

let posts = 0;
page.on('request', r => { if (r.url().includes('edit-form-changed') && r.method()==='POST') posts++; });
// ...type in the memo...
expect(posts).toBe(0);   // memo affects nothing → issues no request

E2E baseline (the regression gate — never drop below this)

The full suite must stay green after every migration. Specs touching the migrated modals:

Spec	Tests	Role
`e2e/transaction-edit-swap.spec.ts`	8	Phase 2 parity contract — whole-form `hx-select` swaps, caret survival, no-request memo, vendor re-select
`e2e/transaction-edit.spec.ts`	15	transaction edit behavior
`e2e/bulk-code-transactions.spec.ts`	18	Phase 3 (bulk code)
`e2e/transaction-import.spec.ts`	4	import
`e2e/transaction-navigation.spec.ts`	13	navigation

Pass/fail baseline: TO BE CAPTURED at the first Phase 2 e2e run against a test server booted from this worktree (integreat-execute-refactor). At distillation time :3333 was occupied by the integreat-render-whole-form worktree (morph version), so a run then would not reflect the merged hx-select reference. Record the green count here once captured, and never drop below it.

4.3 KiB Raw Blame History