integreat/.claude/skills/ssr-form-migration/reference/test-recipes.md

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

1. 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.
2. 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.
3. 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

Running e2e from a non-default worktree (recipe)

:3333 is often taken by another worktree's server. To run this worktree's code:

1. Boot the test server in-process on this worktree's REPL at an alternate port — no second JVM, and it live-reloads as you edit:

   (require '[auto-ap.test-server :as ts] '[ring.adapter.jetty :refer [run-jetty]]
            '[datomic.api :as dc])
   ;; reseed helper — call before each full run so state doesn't leak between runs
   (defn reseed! []
     (try (.stop (:server test-srv)) (catch Throwable _))
     (try (dc/delete-database "datomic:mem://playwright-test") (catch Throwable _))
     (def test-srv (let [c (ts/create-test-db) id (ts/seed-test-data c)]
                     (reset! ts/test-transaction-id id)
                     {:server (run-jetty (ts/test-app) {:port 3334 :join? false}) :tx-id id})))
   (reseed!)
   

2. playwright.config.ts honors BASE_URL; setting it also disables the auto-started webServer (so worktrees don't fight over :3333):

   BASE_URL=http://localhost:3334 npx playwright test --workers=1 --reporter=line
   

3. Reseed (reseed!) before each full run. One long-lived in-process server persists its in-mem DB across separate npx playwright invocations; the swap spec's clearAccounts/save mutate the shared transaction and leak into later specs. The normal harness avoids this by booting a fresh server per npx playwright test.

Pass/fail baseline — measured on the merged hx-select reference (Phase 2 start)

Server: in-process from integreat-execute-refactor on :3334, --workers=1, fresh seed.

Spec	Result
transaction-edit-swap.spec.ts	6 / 6 pass — the whole-form swap parity contract
transaction-edit.spec.ts	1 fail (masks 7 via mode: 'serial') — Shared Location … spread on save and reopen fails: the save POST returns a validation error (amount/balance test-data assumption: "$200 = full amount of the 2nd transaction" doesn't hold), so the modal stays open. Pre-existing on the merged reference, not introduced by this work.
Full suite (39)	30 pass / 2 fail / 7 skipped. 2nd failure: transaction-navigation.spec.ts date-range persistence (date-range=all expected, got month) — drift from the base branch's "require Apply for date-range filters" change, unrelated to forms.

Gate for the Transaction Edit refactor: the 6/6 swap-doctrine spec + REPL pure-fn checks. The transaction-edit.spec.ts Shared Location failure must be understood/fixed to unmask the other 7 before that file can serve as a full parity gate — it is not a regression to introduce, but it does cap the available characterization coverage today. Never drop below 30 passing on the full suite.