@itmetsam/samurai-framework 0.1.0 → 0.2.0

package/docs/superpowers/plans/2026-09-29-expect.md

@@ -1,1350 +0,0 @@
-# `expect` Assertions Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Add a single `expect()` API with auto-retrying locator matchers and synchronous value matchers; failures throw `AssertionError` and are reported as `type: "assertion"`.
-
-**Architecture:** `expect(x)` dispatches on `x instanceof Locator`: locators get `LocatorAssertions` (async, polling `Locator` read methods every 100 ms until a timeout), everything else gets `ValueAssertions` (sync, check once). Both throw `AssertionError`, which the runner maps to a `type: "assertion"` test error. A module-level registry of running locator assertions lets the runner fail tests that forgot to `await` one.
-
-**Tech Stack:** TypeScript (`module: nodenext`, `strict`, `verbatimModuleSyntax`, `noUncheckedIndexedAccess`), tsx, Node 26 built-in `node:test` + `node:assert/strict`, WebDriver BiDi `script.evaluate`.
-
-**Spec:** `docs/superpowers/specs/2026-09-29-expect-design.md`
-
-## Global Constraints
-
-- No new dependencies. Unit tests use `node:test` via `tsx --test`.
-- Relative imports use the `.js` extension (e.g. `"./assertion-error.js"`), as everywhere in `src/`.
-- Type-only imports use `import type` (`verbatimModuleSyntax` is on).
-- Locator retry: poll interval `100` ms; timeout resolution per-call `{ timeout }` → config `expect.timeout` → default `5000` ms; at least one read even with `timeout: 0`.
-- Errors thrown while reading (evaluate exception, closed socket) are rethrown immediately, never retried.
-- `AssertionError` message format (locator):
-  ```
-  expect(locator).toHaveText
-    locator: //h1
-    expected: "Contact"
-    received: "Home"
-  ```
-  For values the first line is `expect(value).<matcher>` and there is no `locator:` line. Negated matchers are named `not.<matcher>`.
-- Value formatting: strings quoted (`JSON.stringify`), RegExp as `/src/flags`, everything else `util.inspect(value, { depth: 2 })`.
-- Type misuse of a value matcher throws `TypeError`, not `AssertionError`.
-- Report: `type: "assertion"` with `expected` / `actual`; a RegExp is stored as its formatted string.
-- `tsc --noEmit -p .` must show no errors other than the pre-existing `src/config/default.ts(3,14): error TS2739`.
-- Leave `result/report.json` and `bun.lock` uncommitted; never `git add -A`.
-
----
-
-## File Structure
-
-| File | Status | Responsibility |
-|---|---|---|
-| `package.json` | modify | `test` script → `tsx --test "src/**/*.test.ts"` |
-| `src/assert/assertion-error.ts` | create | `AssertionError`, `format()`, `toReportValue()` |
-| `src/assert/assertion-error.test.ts` | create | unit tests for the above |
-| `src/assert/expect.ts` | create (currently empty) | `expect()` overloads, `ValueAssertions`, `LocatorAssertions`, polling, pending-assertion registry |
-| `src/assert/expect.test.ts` | create | value matcher tests |
-| `src/assert/expect-locator.test.ts` | create | locator matcher + registry tests |
-| `src/locator/locator.ts` | modify | public reads: `selector`, `isVisible`, `textContent`, `inputValue`, `getAttribute`, `count` |
-| `src/locator/locator.test.ts` | create | unit tests for the reads |
-| `src/testing/stub-connector.ts` | create | fake `BiDiConnector` answering `script.evaluate` from a queue |
-| `src/types/config.d.ts` | modify | `expect?: { timeout?: number }` |
-| `src/types/test.d.ts` | modify | `TestError.type` adds `"assertion"`, optional `expected` / `actual` |
-| `src/runner/test-error.ts` | create | `toTestError(err)` mapping thrown values to `TestError` |
-| `src/runner/test-error.test.ts` | create | unit tests for `toTestError` |
-| `src/runner/test-runner.ts` | modify | use `toTestError`, missing-await guard, reset registry per test |
-| `src/tests/index.spec.ts` | modify | end-to-end assertions |
-
----
-
-### Task 1: Test script, `AssertionError` and `format`
-
-**Files:**
-- Modify: `package.json` (`scripts.test`)
-- Create: `src/assert/assertion-error.ts`
-- Test: `src/assert/assertion-error.test.ts`
-
-**Interfaces:**
-- Consumes: nothing.
-- Produces:
-  - `export function format(value: unknown): string`
-  - `export function toReportValue(value: unknown): unknown` — RegExp → `format(value)`, anything else unchanged.
-  - `export interface AssertionErrorDetails { matcher: string; expected: unknown; actual: unknown; locator?: string | undefined }`
-  - `export class AssertionError extends Error { readonly matcher: string; readonly expected: unknown; readonly actual: unknown; readonly locator: string | undefined; constructor(details: AssertionErrorDetails) }` with `name === "AssertionError"`.
-
-- [ ] **Step 1: Point the test script at tsx**
-
-In `package.json` replace
-
-```json
-    "test": "echo \"Error: no test specified\" && exit 1"
-```
-
-with
-
-```json
-    "test": "tsx --test \"src/**/*.test.ts\""
-```
-
-- [ ] **Step 2: Write the failing test**
-
-Create `src/assert/assertion-error.test.ts`:
-
-```ts
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { AssertionError, format, toReportValue } from "./assertion-error.js";
-
-test("format quotes strings, prints regexps and inspects other values", () => {
-  assert.equal(format("Home"), '"Home"');
-  assert.equal(format(/err/i), "/err/i");
-  assert.equal(format(42), "42");
-  assert.equal(format(null), "null");
-  assert.equal(format({ a: 1 }), "{ a: 1 }");
-});
-
-test("toReportValue stringifies regexps and keeps other values", () => {
-  assert.equal(toReportValue(/err/i), "/err/i");
-  assert.equal(toReportValue("Home"), "Home");
-  assert.deepEqual(toReportValue({ a: 1 }), { a: 1 });
-});
-
-test("locator assertion message includes the locator line", () => {
-  const err = new AssertionError({
-    matcher: "toHaveText",
-    expected: "Contact",
-    actual: "Home",
-    locator: "//h1",
-  });
-  assert.ok(err instanceof Error);
-  assert.equal(err.name, "AssertionError");
-  assert.equal(
-    err.message,
-    'expect(locator).toHaveText\n  locator: //h1\n  expected: "Contact"\n  received: "Home"',
-  );
-  assert.equal(err.matcher, "toHaveText");
-  assert.equal(err.expected, "Contact");
-  assert.equal(err.actual, "Home");
-  assert.equal(err.locator, "//h1");
-});
-
-test("value assertion message has no locator line", () => {
-  const err = new AssertionError({ matcher: "toBe", expected: 2, actual: 1 });
-  assert.equal(err.message, "expect(value).toBe\n  expected: 2\n  received: 1");
-  assert.equal(err.locator, undefined);
-});
-```
-
-- [ ] **Step 3: Run it to verify it fails**
-
-Run: `npm test`
-Expected: FAIL — `Cannot find module '.../src/assert/assertion-error.js'` (or `ERR_MODULE_NOT_FOUND`), `ℹ fail 1`.
-
-- [ ] **Step 4: Implement**
-
-Create `src/assert/assertion-error.ts`:
-
-```ts
-import { inspect } from "node:util";
-
-/** Formats a value for assertion messages */
-export function format(value: unknown): string {
-  if (typeof value === "string") return JSON.stringify(value);
-  if (value instanceof RegExp) return value.toString();
-  return inspect(value, { depth: 2 });
-}
-
-/** Converts a value into something JSON can store in the report */
-export function toReportValue(value: unknown): unknown {
-  return value instanceof RegExp ? format(value) : value;
-}
-
-export interface AssertionErrorDetails {
-  /** Matcher name, prefixed with `not.` when negated */
-  matcher: string;
-  expected: unknown;
-  actual: unknown;
-  /** XPath of the asserted locator, only for locator assertions */
-  locator?: string | undefined;
-}
-
-export class AssertionError extends Error {
-  public readonly matcher: string;
-  public readonly expected: unknown;
-  public readonly actual: unknown;
-  public readonly locator: string | undefined;
-
-  constructor({ matcher, expected, actual, locator }: AssertionErrorDetails) {
-    const subject = locator === undefined ? "value" : "locator";
-    const lines = [`expect(${subject}).${matcher}`];
-    if (locator !== undefined) {
-      lines.push(`  locator: ${locator}`);
-    }
-    lines.push(`  expected: ${format(expected)}`, `  received: ${format(actual)}`);
-
-    super(lines.join("\n"));
-    this.name = "AssertionError";
-    this.matcher = matcher;
-    this.expected = expected;
-    this.actual = actual;
-    this.locator = locator;
-  }
-}
-```
-
-- [ ] **Step 5: Run tests to verify they pass**
-
-Run: `npm test`
-Expected: `ℹ pass 4`, `ℹ fail 0`.
-
-- [ ] **Step 6: Type-check**
-
-Run: `npx tsc --noEmit -p .`
-Expected: only `src/config/default.ts(3,14): error TS2739`.
-
-- [ ] **Step 7: Commit**
-
-```bash
-git add package.json src/assert/assertion-error.ts src/assert/assertion-error.test.ts
-git commit -m "feat(assert): add AssertionError and node:test script"
-```
-
----
-
-### Task 2: Value matchers
-
-**Files:**
-- Modify: `src/assert/expect.ts` (currently empty)
-- Test: `src/assert/expect.test.ts`
-
-**Interfaces:**
-- Consumes: `AssertionError` from `./assertion-error.js` (Task 1).
-- Produces:
-  - `export function expect<T>(value: T): ValueAssertions<T>` (Task 4 turns this into overloads)
-  - `export class ValueAssertions<T>` with `get not(): ValueAssertions<T>` and matchers returning `void`: `toBe(expected: unknown)`, `toEqual(expected: unknown)`, `toBeTruthy()`, `toBeFalsy()`, `toContain(item: unknown)`, `toMatch(pattern: string | RegExp)`, `toBeGreaterThan(expected: number | bigint)`, `toBeGreaterThanOrEqual(...)`, `toBeLessThan(...)`, `toBeLessThanOrEqual(...)`.
-  - `function matchesText(actual: string, expected: string | RegExp, mode: "exact" | "contains"): boolean` (module-private; reused by Task 4).
-
-- [ ] **Step 1: Write the failing test**
-
-Create `src/assert/expect.test.ts`:
-
-```ts
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { expect } from "./expect.js";
-import { AssertionError } from "./assertion-error.js";
-
-/** Asserts `fn` throws an AssertionError with the given matcher/expected/actual */
-function assertFails(
-  fn: () => void,
-  matcher: string,
-  expected: unknown,
-  actual: unknown,
-) {
-  assert.throws(fn, (err: unknown) => {
-    assert.ok(err instanceof AssertionError, "expected an AssertionError");
-    assert.equal(err.matcher, matcher);
-    assert.deepEqual(err.expected, expected);
-    assert.deepEqual(err.actual, actual);
-    return true;
-  });
-}
-
-test("toBe uses Object.is", () => {
-  expect(1).toBe(1);
-  expect(NaN).toBe(NaN);
-  assertFails(() => expect(1).toBe(2), "toBe", 2, 1);
-  assertFails(() => expect({ a: 1 }).toBe({ a: 1 }), "toBe", { a: 1 }, { a: 1 });
-  expect(1).not.toBe(2);
-  assertFails(() => expect(1).not.toBe(1), "not.toBe", 1, 1);
-});
-
-test("toEqual compares deeply", () => {
-  expect({ a: [1, 2] }).toEqual({ a: [1, 2] });
-  assertFails(() => expect({ a: 1 }).toEqual({ a: 2 }), "toEqual", { a: 2 }, { a: 1 });
-  expect({ a: 1 }).not.toEqual({ a: 2 });
-});
-
-test("toBeTruthy / toBeFalsy", () => {
-  expect(1).toBeTruthy();
-  expect("").toBeFalsy();
-  assertFails(() => expect(0).toBeTruthy(), "toBeTruthy", "truthy", 0);
-  assertFails(() => expect("x").toBeFalsy(), "toBeFalsy", "falsy", "x");
-  expect(0).not.toBeTruthy();
-});
-
-test("toContain works on arrays and strings", () => {
-  expect([1, 2, 3]).toContain(2);
-  expect("hello world").toContain("world");
-  assertFails(() => expect([1, 2]).toContain(3), "toContain", 3, [1, 2]);
-  expect("abc").not.toContain("z");
-  assert.throws(() => expect(42).toContain(4), TypeError);
-  assert.throws(() => expect("abc").toContain(1), TypeError);
-});
-
-test("toMatch accepts substrings and regexps", () => {
-  expect("Contact us").toMatch("Contact");
-  expect("Contact us").toMatch(/contact/i);
-  expect("aaa").toMatch(/a/g);
-  expect("aaa").toMatch(/a/g); // global regexps must not keep lastIndex state
-  assertFails(() => expect("Home").toMatch(/contact/), "toMatch", /contact/, "Home");
-  expect("Home").not.toMatch("Contact");
-  assert.throws(() => expect(1).toMatch("1"), TypeError);
-});
-
-test("number comparisons", () => {
-  expect(3).toBeGreaterThan(2);
-  expect(3).toBeGreaterThanOrEqual(3);
-  expect(2).toBeLessThan(3);
-  expect(3).toBeLessThanOrEqual(3);
-  expect(3n).toBeGreaterThan(2);
-  assertFails(() => expect(2).toBeGreaterThan(3), "toBeGreaterThan", 3, 2);
-  assertFails(() => expect(3).not.toBeLessThanOrEqual(3), "not.toBeLessThanOrEqual", 3, 3);
-  assert.throws(() => expect("3").toBeGreaterThan(2), TypeError);
-});
-```
-
-- [ ] **Step 2: Run it to verify it fails**
-
-Run: `npm test`
-Expected: FAIL — `expect.test.ts` errors with `does not provide an export named 'expect'` (the file is empty); Task 1 tests still pass.
-
-- [ ] **Step 3: Implement**
-
-Write `src/assert/expect.ts`:
-
-```ts
-import { isDeepStrictEqual } from "node:util";
-import { AssertionError } from "./assertion-error.js";
-
-function matchesText(
-  actual: string,
-  expected: string | RegExp,
-  mode: "exact" | "contains",
-) {
-  // search() ignores lastIndex, so global regexps behave the same on every call
-  if (expected instanceof RegExp) return actual.search(expected) !== -1;
-  return mode === "exact" ? actual === expected : actual.includes(expected);
-}
-
-function isNumeric(value: unknown): value is number | bigint {
-  return typeof value === "number" || typeof value === "bigint";
-}
-
-export class ValueAssertions<T> {
-  private readonly actual: T;
-  private readonly negated: boolean;
-
-  constructor(actual: T, negated = false) {
-    this.actual = actual;
-    this.negated = negated;
-  }
-
-  /** Inverts the next matcher */
-  get not(): ValueAssertions<T> {
-    return new ValueAssertions(this.actual, !this.negated);
-  }
-
-  private assert(pass: boolean, matcher: string, expected: unknown) {
-    if (pass !== this.negated) return;
-    throw new AssertionError({
-      matcher: this.negated ? `not.${matcher}` : matcher,
-      expected,
-      actual: this.actual,
-    });
-  }
-
-  private compare(
-    matcher: string,
-    expected: number | bigint,
-    check: (actual: number | bigint, expected: number | bigint) => boolean,
-  ) {
-    const actual = this.actual;
-    if (!isNumeric(actual) || !isNumeric(expected)) {
-      throw new TypeError(
-        `${matcher} expects numbers, received ${typeof actual} and ${typeof expected}`,
-      );
-    }
-    this.assert(check(actual, expected), matcher, expected);
-  }
-
-  /** Strict identity (`Object.is`) */
-  toBe(expected: unknown) {
-    this.assert(Object.is(this.actual, expected), "toBe", expected);
-  }
-
-  /** Deep structural equality */
-  toEqual(expected: unknown) {
-    this.assert(isDeepStrictEqual(this.actual, expected), "toEqual", expected);
-  }
-
-  toBeTruthy() {
-    this.assert(Boolean(this.actual), "toBeTruthy", "truthy");
-  }
-
-  toBeFalsy() {
-    this.assert(!this.actual, "toBeFalsy", "falsy");
-  }
-
-  /** Array includes `item`, or string contains substring `item` */
-  toContain(item: unknown) {
-    const actual = this.actual;
-    if (typeof actual === "string") {
-      if (typeof item !== "string") {
-        throw new TypeError(`toContain on a string expects a string, received ${typeof item}`);
-      }
-      this.assert(actual.includes(item), "toContain", item);
-      return;
-    }
-    if (Array.isArray(actual)) {
-      this.assert(actual.includes(item), "toContain", item);
-      return;
-    }
-    throw new TypeError(`toContain expects an array or string, received ${typeof actual}`);
-  }
-
-  /** String contains `pattern` (string) or matches it (RegExp) */
-  toMatch(pattern: string | RegExp) {
-    const actual = this.actual;
-    if (typeof actual !== "string") {
-      throw new TypeError(`toMatch expects a string, received ${typeof actual}`);
-    }
-    this.assert(matchesText(actual, pattern, "contains"), "toMatch", pattern);
-  }
-
-  toBeGreaterThan(expected: number | bigint) {
-    this.compare("toBeGreaterThan", expected, (a, b) => a > b);
-  }
-
-  toBeGreaterThanOrEqual(expected: number | bigint) {
-    this.compare("toBeGreaterThanOrEqual", expected, (a, b) => a >= b);
-  }
-
-  toBeLessThan(expected: number | bigint) {
-    this.compare("toBeLessThan", expected, (a, b) => a < b);
-  }
-
-  toBeLessThanOrEqual(expected: number | bigint) {
-    this.compare("toBeLessThanOrEqual", expected, (a, b) => a <= b);
-  }
-}
-
-export function expect<T>(value: T): ValueAssertions<T> {
-  return new ValueAssertions(value);
-}
-```
-
-- [ ] **Step 4: Run tests to verify they pass**
-
-Run: `npm test`
-Expected: `ℹ pass 10`, `ℹ fail 0`.
-
-- [ ] **Step 5: Type-check**
-
-Run: `npx tsc --noEmit -p .`
-Expected: only the pre-existing `src/config/default.ts` error.
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add src/assert/expect.ts src/assert/expect.test.ts
-git commit -m "feat(assert): add value matchers"
-```
-
----
-
-### Task 3: Locator read methods + stub connector
-
-**Files:**
-- Create: `src/testing/stub-connector.ts`
-- Modify: `src/locator/locator.ts` (`buildExpression` at lines 51-75; new methods after `getBoundingClientRect`, before `wait`)
-- Test: `src/locator/locator.test.ts`
-
-**Interfaces:**
-- Consumes: existing `Locator` constructor `(xpath: string, biDiConnector: BiDiConnector, contextId: BrowsingContext, options?: LocatorOptions)` and private `evaluate(expression: string): Promise<RemoteValue>` (throws `Failed to locate element <xpath>. Details: <text>` on an evaluate exception).
-- Produces:
-  - `stubConnector(...responses: StubResponse[]): { connector: BiDiConnector; expressions: string[] }` — each `script.evaluate` consumes the next response; the last one repeats. `type StubResponse = RemoteValue | { exception: string }`.
-  - On `Locator`:
-    - `get selector(): string` — normalised XPath (`"h1"` → `"//h1"`).
-    - `isVisible(): Promise<boolean>`
-    - `textContent(): Promise<string | null>` (trimmed)
-    - `inputValue(): Promise<string | null>`
-    - `getAttribute(name: string): Promise<string | null>`
-    - `count(): Promise<number>`
-
-- [ ] **Step 1: Create the stub connector**
-
-Create `src/testing/stub-connector.ts`:
-
-```ts
-import type { BiDiConnector } from "../transport/bidi-connection.js";
-import type { RemoteValue } from "../types/bidi-modules/script.js";
-
-export type StubResponse = RemoteValue | { exception: string };
-
-/**
- * Fake BiDiConnector for unit tests. Every `script.evaluate` answers with the next
- * queued response; the last response repeats. Evaluated expressions are recorded.
- */
-export function stubConnector(...responses: StubResponse[]) {
-  if (responses.length === 0) {
-    throw new Error("stubConnector needs at least one response");
-  }
-  const expressions: string[] = [];
-  let calls = 0;
-
-  const connector = {
-    async send(method: string, params: { expression: string }) {
-      if (method !== "script.evaluate") {
-        throw new Error(`stubConnector does not handle ${method}`);
-      }
-      expressions.push(params.expression);
-      const response = responses[Math.min(calls++, responses.length - 1)]!;
-      if ("exception" in response) {
-        return {
-          type: "exception",
-          exceptionDetails: { text: response.exception },
-          realm: "stub",
-        };
-      }
-      return { type: "success", result: response, realm: "stub" };
-    },
-  };
-
-  return { connector: connector as unknown as BiDiConnector, expressions };
-}
-```
-
-- [ ] **Step 2: Write the failing test**
-
-Create `src/locator/locator.test.ts`:
-
-```ts
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import Locator from "./locator.js";
-import { stubConnector, type StubResponse } from "../testing/stub-connector.js";
-
-function locatorWith(xpath: string, ...responses: StubResponse[]) {
-  const { connector, expressions } = stubConnector(...responses);
-  return { locator: new Locator(xpath, connector, "ctx"), expressions };
-}
-
-test("selector normalises the xpath", () => {
-  assert.equal(locatorWith("h1", { type: "null" }).locator.selector, "//h1");
-  assert.equal(locatorWith("//div", { type: "null" }).locator.selector, "//div");
-  assert.equal(
-    locatorWith("a[text()='Start']", { type: "null" }).locator.selector,
-    '//a[text()="Start"]',
-  );
-});
-
-test("textContent returns the string, or null when the element is missing", async () => {
-  const found = locatorWith("h1", { type: "string", value: "Contact" });
-  assert.equal(await found.locator.textContent(), "Contact");
-  assert.match(found.expressions[0]!, /\/\/h1/);
-  assert.match(found.expressions[0]!, /FIRST_ORDERED_NODE_TYPE/);
-
-  const missing = locatorWith("h1", { type: "null" });
-  assert.equal(await missing.locator.textContent(), null);
-});
-
-test("inputValue returns the value, or null", async () => {
-  assert.equal(
-    await locatorWith("input", { type: "string", value: "test" }).locator.inputValue(),
-    "test",
-  );
-  assert.equal(await locatorWith("input", { type: "null" }).locator.inputValue(), null);
-});
-
-test("getAttribute passes the attribute name as a JSON string", async () => {
-  const { locator, expressions } = locatorWith("a", { type: "string", value: "/home" });
-  assert.equal(await locator.getAttribute("href"), "/home");
-  assert.match(expressions[0]!, /getAttribute\("href"\)/);
-});
-
-test("isVisible returns the boolean result", async () => {
-  assert.equal(await locatorWith("div", { type: "boolean", value: true }).locator.isVisible(), true);
-  assert.equal(await locatorWith("div", { type: "boolean", value: false }).locator.isVisible(), false);
-});
-
-test("count evaluates an XPath count()", async () => {
-  const { locator, expressions } = locatorWith("li", { type: "number", value: 3 });
-  assert.equal(await locator.count(), 3);
-  assert.match(expressions[0]!, /count\(\/\/li\)/);
-  assert.match(expressions[0]!, /NUMBER_TYPE/);
-});
-
-test("reads throw on an evaluate exception", async () => {
-  const { locator } = locatorWith("h1[", { exception: "SyntaxError: bad xpath" });
-  await assert.rejects(locator.textContent(), /Failed to locate element/);
-});
-
-test("reads reject unexpected result types", async () => {
-  const { locator } = locatorWith("h1", { type: "number", value: 1 });
-  await assert.rejects(locator.textContent(), /Expected a string or null/);
-});
-```
-
-- [ ] **Step 3: Run it to verify it fails**
-
-Run: `npm test`
-Expected: FAIL — `locator.test.ts` fails with `TypeError: ... is not a function` / `selector` is `undefined` (`ℹ fail` ≥ 7). Tasks 1-2 tests still pass.
-
-- [ ] **Step 4: Implement**
-
-In `src/locator/locator.ts`, replace the start of `buildExpression`:
-
-```ts
-  /** Builds the expression to evaluate on */
-  private buildExpression(action?: string) {
-    let parsedXpath = this.xpath.startsWith("//")
-      ? this.xpath
-      : "//" + this.xpath;
-    parsedXpath = parsedXpath.replaceAll("'", '"');
-
-    const xpathResultType = this.useMultiple
-```
-
-with
-
-```ts
-  /** Normalises the xpath: always starts with `//` and uses double quotes */
-  private parsedXpath() {
-    const xpath = this.xpath.startsWith("//") ? this.xpath : "//" + this.xpath;
-    return xpath.replaceAll("'", '"');
-  }
-
-  /** The normalised xpath this locator evaluates */
-  public get selector(): string {
-    return this.parsedXpath();
-  }
-
-  /** Builds the expression to evaluate on */
-  private buildExpression(action?: string) {
-    const parsedXpath = this.parsedXpath();
-
-    const xpathResultType = this.useMultiple
-```
-
-(the rest of `buildExpression` is unchanged; it still uses `parsedXpath`).
-
-Then insert after `getBoundingClientRect()` (before the `/** Wait for certain time` comment):
-
-```ts
-  /** Evaluates `body` with `el` bound to the first matching element, or null when nothing matches */
-  private readElement(body: string) {
-    return this.evaluate(`(() => {
-      const el = document.evaluate(
-        '${this.parsedXpath()}',
-        document,
-        null,
-        XPathResult.FIRST_ORDERED_NODE_TYPE,
-        null
-      ).singleNodeValue;
-      ${body}
-    })()`);
-  }
-
-  private stringOrNull(value: RemoteValue): string | null {
-    if (value.type === "string") return value.value;
-    if (value.type === "null") return null;
-    throw new Error(`Expected a string or null but received "${value.type}"`);
-  }
-
-  /** Whether the element exists, has a non-empty box and is not hidden by CSS */
-  public async isVisible(): Promise<boolean> {
-    const result = await this.readElement(`
-      if (!el) return false;
-      const rect = el.getBoundingClientRect();
-      const style = getComputedStyle(el);
-      return rect.width > 0 && rect.height > 0 &&
-        style.display !== "none" && style.visibility !== "hidden" && style.opacity !== "0";
-    `);
-    return result.type === "boolean" && result.value;
-  }
-
-  /** Trimmed text content, or null when the element is missing */
-  public async textContent(): Promise<string | null> {
-    return this.stringOrNull(
-      await this.readElement(`return el ? el.textContent.trim() : null;`),
-    );
-  }
-
-  /** Value of an input/textarea/select, or null when missing */
-  public async inputValue(): Promise<string | null> {
-    return this.stringOrNull(
-      await this.readElement(`return el && typeof el.value === "string" ? el.value : null;`),
-    );
-  }
-
-  /** Attribute value, or null when the element or attribute is missing */
-  public async getAttribute(name: string): Promise<string | null> {
-    return this.stringOrNull(
-      await this.readElement(`return el ? el.getAttribute(${JSON.stringify(name)}) : null;`),
-    );
-  }
-
-  /** Number of elements matching the xpath */
-  public async count(): Promise<number> {
-    const result = await this.evaluate(
-      `document.evaluate('count(${this.parsedXpath()})', document, null, XPathResult.NUMBER_TYPE, null).numberValue`,
-    );
-    if (result.type !== "number") {
-      throw new Error(`Expected a number but received "${result.type}"`);
-    }
-    return result.value;
-  }
-```
-
-`RemoteValue` is already imported as a type at the top of `locator.ts`.
-
-- [ ] **Step 5: Run tests to verify they pass**
-
-Run: `npm test`
-Expected: `ℹ pass 18`, `ℹ fail 0`.
-
-- [ ] **Step 6: Type-check**
-
-Run: `npx tsc --noEmit -p .`
-Expected: only the pre-existing `src/config/default.ts` error.
-
-- [ ] **Step 7: Commit**
-
-```bash
-git add src/testing/stub-connector.ts src/locator/locator.ts src/locator/locator.test.ts
-git commit -m "feat(locator): add null-safe read methods"
-```
-
----
-
-### Task 4: Locator matchers, polling and pending-assertion registry
-
-**Files:**
-- Modify: `src/types/config.d.ts` (add `expect` to `SamuraiTestConfig`)
-- Modify: `src/assert/expect.ts`
-- Test: `src/assert/expect-locator.test.ts`
-
-**Interfaces:**
-- Consumes: `Locator` reads + `selector` (Task 3), `AssertionError` (Task 1), `matchesText` + `ValueAssertions` (Task 2), `stubConnector` (Task 3), `readConfig(key)` from `src/config/config.ts` (`readConfig<K extends keyof SamuraiTestConfig>(key: K): Promise<SamuraiTestConfig[K]>`).
-- Produces:
-  - `expect(locator: Locator): LocatorAssertions` and `expect<T>(value: T): ValueAssertions<T>` (overloads)
-  - `export interface LocatorAssertionOptions { timeout?: number }`
-  - `export class LocatorAssertions` with `get not(): LocatorAssertions` and matchers returning `Promise<void>`: `toBeVisible(options?)`, `toHaveText(expected: string | RegExp, options?)`, `toContainText(expected: string | RegExp, options?)`, `toHaveValue(expected: string | RegExp, options?)`, `toHaveAttribute(name: string, expected: string | RegExp, options?)`, `toHaveCount(expected: number, options?)`
-  - `export function takePendingAssertions(): string[]` — matcher names (e.g. `"not.toBeVisible"`) of locator assertions still running; clears the registry.
-
-- [ ] **Step 1: Add the config option**
-
-In `src/types/config.d.ts`, inside `SamuraiTestConfig` after `groups?: SamuraiGroup[];` add:
-
-```ts
-  /** Options for `expect` assertions */
-  expect?: {
-    /**
-     * Time (ms) locator assertions keep retrying before failing
-     * @default 5000
-     */
-    timeout?: number;
-  };
-```
-
-- [ ] **Step 2: Write the failing test**
-
-Create `src/assert/expect-locator.test.ts`. Every call passes an explicit `timeout` so the tests never read `samurai.config.ts`.
-
-```ts
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import Locator from "../locator/locator.js";
-import { stubConnector, type StubResponse } from "../testing/stub-connector.js";
-import { expect, takePendingAssertions } from "./expect.js";
-import { AssertionError } from "./assertion-error.js";
-
-function locatorWith(xpath: string, ...responses: StubResponse[]) {
-  const { connector, expressions } = stubConnector(...responses);
-  return { locator: new Locator(xpath, connector, "ctx"), expressions };
-}
-
-const text = (value: string): StubResponse => ({ type: "string", value });
-const missing: StubResponse = { type: "null" };
-const bool = (value: boolean): StubResponse => ({ type: "boolean", value });
-
-test("toHaveText retries until the text matches", async () => {
-  const { locator, expressions } = locatorWith("h1", missing, missing, text("Contact"));
-  await expect(locator).toHaveText("Contact", { timeout: 2000 });
-  assert.equal(expressions.length, 3);
-});
-
-test("times out with the last received value", async () => {
-  const { locator } = locatorWith("h1", text("Loading"), text("Home"));
-  const start = Date.now();
-  await assert.rejects(expect(locator).toHaveText("Contact", { timeout: 250 }), (err) => {
-    assert.ok(err instanceof AssertionError);
-    assert.equal(err.matcher, "toHaveText");
-    assert.equal(err.expected, "Contact");
-    assert.equal(err.actual, "Home");
-    assert.equal(err.locator, "//h1");
-    return true;
-  });
-  const elapsed = Date.now() - start;
-  assert.ok(elapsed >= 250 && elapsed < 1000, `elapsed ${elapsed}ms`);
-});
-
-test("timeout 0 reads exactly once", async () => {
-  const { locator, expressions } = locatorWith("h1", text("Home"));
-  await assert.rejects(expect(locator).toHaveText("Contact", { timeout: 0 }), AssertionError);
-  assert.equal(expressions.length, 1);
-});
-
-test("read errors are rethrown without retrying", async () => {
-  const { locator, expressions } = locatorWith("h1[", { exception: "SyntaxError" });
-  await assert.rejects(expect(locator).toBeVisible({ timeout: 2000 }), (err) => {
-    assert.ok(!(err instanceof AssertionError));
-    assert.match((err as Error).message, /Failed to locate element/);
-    return true;
-  });
-  assert.equal(expressions.length, 1);
-});
-
-test("not.toBeVisible waits until the element is hidden", async () => {
-  const { locator, expressions } = locatorWith("div", bool(true), bool(false));
-  await expect(locator).not.toBeVisible({ timeout: 2000 });
-  assert.equal(expressions.length, 2);
-});
-
-test("negated failure is named not.<matcher>", async () => {
-  const { locator } = locatorWith("h1", text("Contact"));
-  await assert.rejects(expect(locator).not.toHaveText("Contact", { timeout: 0 }), (err) => {
-    assert.ok(err instanceof AssertionError);
-    assert.equal(err.matcher, "not.toHaveText");
-    return true;
-  });
-});
-
-test("toHaveText is exact, toContainText is a substring, both accept regexps", async () => {
-  const { locator } = locatorWith("p", text("Hello world"));
-  await assert.rejects(expect(locator).toHaveText("Hello", { timeout: 0 }), AssertionError);
-  await expect(locator).toContainText("Hello", { timeout: 0 });
-  await expect(locator).toHaveText(/world$/, { timeout: 0 });
-  await expect(locator).toContainText(/WORLD/i, { timeout: 0 });
-});
-
-test("a missing element never matches text", async () => {
-  const { locator } = locatorWith("p", missing);
-  await assert.rejects(expect(locator).toContainText("", { timeout: 0 }), (err) => {
-    assert.ok(err instanceof AssertionError);
-    assert.equal(err.actual, null);
-    return true;
-  });
-});
-
-test("toHaveValue, toHaveAttribute and toHaveCount", async () => {
-  await expect(locatorWith("input", text("test")).locator).toHaveValue("test", { timeout: 0 });
-  await expect(locatorWith("a", text("/home")).locator).toHaveAttribute("href", /home/, { timeout: 0 });
-  await expect(locatorWith("li", { type: "number", value: 3 }).locator).toHaveCount(3, { timeout: 0 });
-  await assert.rejects(
-    expect(locatorWith("li", { type: "number", value: 2 }).locator).toHaveCount(3, { timeout: 0 }),
-    AssertionError,
-  );
-});
-
-test("expect(value) still returns value matchers", () => {
-  expect(1).toBe(1);
-  assert.throws(() => expect("a").toBe("b"), AssertionError);
-});
-
-test("takePendingAssertions lists assertions that were not awaited", async () => {
-  takePendingAssertions();
-  const { locator } = locatorWith("div", bool(false));
-  const pending = expect(locator).not.toBeVisible({ timeout: 200 });
-  const failing = expect(locator).toBeVisible({ timeout: 200 });
-  assert.deepEqual(takePendingAssertions(), ["not.toBeVisible", "toBeVisible"]);
-  assert.deepEqual(takePendingAssertions(), []);
-  await pending;
-  await assert.rejects(failing, AssertionError);
-});
-
-test("awaited assertions are not pending", async () => {
-  takePendingAssertions();
-  await expect(locatorWith("div", bool(true)).locator).toBeVisible({ timeout: 0 });
-  await assert.rejects(
-    expect(locatorWith("div", bool(false)).locator).toBeVisible({ timeout: 0 }),
-    AssertionError,
-  );
-  assert.deepEqual(takePendingAssertions(), []);
-});
-```
-
-- [ ] **Step 3: Run it to verify it fails**
-
-Run: `npm test`
-Expected: FAIL — `does not provide an export named 'takePendingAssertions'`. Earlier test files still pass.
-
-- [ ] **Step 4: Implement**
-
-In `src/assert/expect.ts`:
-
-a) Replace the imports at the top with:
-
-```ts
-import { isDeepStrictEqual } from "node:util";
-import { setTimeout as sleep } from "node:timers/promises";
-import { AssertionError } from "./assertion-error.js";
-import Locator from "../locator/locator.js";
-import { readConfig } from "../config/config.js";
-
-const DEFAULT_EXPECT_TIMEOUT = 5000;
-const POLL_INTERVAL = 100;
-
-/** Locator assertions still running, mapped to their matcher name */
-const pendingAssertions = new Map<Promise<void>, string>();
-
-/**
- * Returns the matcher names of locator assertions that are still running and stops
- * tracking them. The runner calls this after a test to detect a missing `await`.
- */
-export function takePendingAssertions(): string[] {
-  const names = [...pendingAssertions.values()];
-  pendingAssertions.clear();
-  return names;
-}
-
-function track(matcher: string, assertion: Promise<void>): Promise<void> {
-  pendingAssertions.set(assertion, matcher);
-  // Handling both outcomes also keeps an un-awaited failure from becoming an unhandled rejection
-  const untrack = () => {
-    pendingAssertions.delete(assertion);
-  };
-  assertion.then(untrack, untrack);
-  return assertion;
-}
-
-export interface LocatorAssertionOptions {
-  /** Time (ms) to keep retrying. Defaults to config `expect.timeout`, then 5000 */
-  timeout?: number;
-}
-
-async function resolveTimeout(options?: LocatorAssertionOptions) {
-  if (options?.timeout !== undefined) return options.timeout;
-  return (await readConfig("expect"))?.timeout ?? DEFAULT_EXPECT_TIMEOUT;
-}
-```
-
-b) Keep `matchesText`, `isNumeric` and `ValueAssertions` from Task 2 unchanged.
-
-c) Add after `ValueAssertions`:
-
-```ts
-export class LocatorAssertions {
-  private readonly locator: Locator;
-  private readonly negated: boolean;
-
-  constructor(locator: Locator, negated = false) {
-    this.locator = locator;
-    this.negated = negated;
-  }
-
-  /** Inverts the next matcher: it retries until the condition is false */
-  get not(): LocatorAssertions {
-    return new LocatorAssertions(this.locator, !this.negated);
-  }
-
-  /** Re-reads the element every POLL_INTERVAL ms until `check` passes or the timeout expires */
-  private assertEventually<V>(
-    matcher: string,
-    expected: unknown,
-    read: () => Promise<V>,
-    check: (actual: V) => boolean,
-    options?: LocatorAssertionOptions,
-  ): Promise<void> {
-    const name = this.negated ? `not.${matcher}` : matcher;
-
-    return track(
-      name,
-      (async () => {
-        const timeout = await resolveTimeout(options);
-        const start = Date.now();
-        while (true) {
-          const actual = await read();
-          if (check(actual) !== this.negated) return;
-          if (Date.now() - start >= timeout) {
-            throw new AssertionError({
-              matcher: name,
-              expected,
-              actual,
-              locator: this.locator.selector,
-            });
-          }
-          await sleep(POLL_INTERVAL);
-        }
-      })(),
-    );
-  }
-
-  toBeVisible(options?: LocatorAssertionOptions) {
-    return this.assertEventually(
-      "toBeVisible",
-      true,
-      () => this.locator.isVisible(),
-      (visible) => visible,
-      options,
-    );
-  }
-
-  /** Trimmed text content equals `expected` (string) or matches it (RegExp) */
-  toHaveText(expected: string | RegExp, options?: LocatorAssertionOptions) {
-    return this.assertEventually(
-      "toHaveText",
-      expected,
-      () => this.locator.textContent(),
-      (text) => text !== null && matchesText(text, expected, "exact"),
-      options,
-    );
-  }
-
-  /** Text content contains `expected` (string) or matches it (RegExp) */
-  toContainText(expected: string | RegExp, options?: LocatorAssertionOptions) {
-    return this.assertEventually(
-      "toContainText",
-      expected,
-      () => this.locator.textContent(),
-      (text) => text !== null && matchesText(text, expected, "contains"),
-      options,
-    );
-  }
-
-  toHaveValue(expected: string | RegExp, options?: LocatorAssertionOptions) {
-    return this.assertEventually(
-      "toHaveValue",
-      expected,
-      () => this.locator.inputValue(),
-      (value) => value !== null && matchesText(value, expected, "exact"),
-      options,
-    );
-  }
-
-  toHaveAttribute(
-    name: string,
-    expected: string | RegExp,
-    options?: LocatorAssertionOptions,
-  ) {
-    return this.assertEventually(
-      "toHaveAttribute",
-      expected,
-      () => this.locator.getAttribute(name),
-      (value) => value !== null && matchesText(value, expected, "exact"),
-      options,
-    );
-  }
-
-  toHaveCount(expected: number, options?: LocatorAssertionOptions) {
-    return this.assertEventually(
-      "toHaveCount",
-      expected,
-      () => this.locator.count(),
-      (count) => count === expected,
-      options,
-    );
-  }
-}
-```
-
-d) Replace the Task 2 `expect` function with the overloads:
-
-```ts
-/** Auto-retrying assertions on a page element */
-export function expect(locator: Locator): LocatorAssertions;
-/** Synchronous assertions on a plain value */
-export function expect<T>(value: T): ValueAssertions<T>;
-export function expect(value: unknown) {
-  return value instanceof Locator
-    ? new LocatorAssertions(value)
-    : new ValueAssertions(value);
-}
-```
-
-- [ ] **Step 5: Run tests to verify they pass**
-
-Run: `npm test`
-Expected: `ℹ pass 30`, `ℹ fail 0`, and no `unhandledRejection` warnings in the output.
-
-- [ ] **Step 6: Type-check**
-
-Run: `npx tsc --noEmit -p .`
-Expected: only the pre-existing `src/config/default.ts` error.
-
-- [ ] **Step 7: Commit**
-
-```bash
-git add src/types/config.d.ts src/assert/expect.ts src/assert/expect-locator.test.ts
-git commit -m "feat(assert): add auto-retrying locator matchers"
-```
-
----
-
-### Task 5: Report assertion failures and missing awaits
-
-**Files:**
-- Modify: `src/types/test.d.ts:40-44` (`TestError`)
-- Create: `src/runner/test-error.ts`
-- Test: `src/runner/test-error.test.ts`
-- Modify: `src/runner/test-runner.ts` (`executeTestCase`, currently lines 70-130)
-
-**Interfaces:**
-- Consumes: `AssertionError`, `toReportValue` (Task 1); `takePendingAssertions` (Task 4).
-- Produces:
-  - `TestError` = `{ message: string; type: "timeout" | "error" | "assertion"; stack?: string | undefined; expected?: unknown; actual?: unknown }`
-  - `export function toTestError(err: unknown): TestError`
-
-- [ ] **Step 1: Extend `TestError`**
-
-In `src/types/test.d.ts` replace
-
-```ts
-interface TestError {
-  message: string;
-  type: "timeout" | "error";
-  stack?: string | undefined;
-}
-```
-
-with
-
-```ts
-interface TestError {
-  message: string;
-  type: "timeout" | "error" | "assertion";
-  stack?: string | undefined;
-  /** Only for `type: "assertion"` */
-  expected?: unknown;
-  /** Only for `type: "assertion"` */
-  actual?: unknown;
-}
-```
-
-- [ ] **Step 2: Write the failing test**
-
-Create `src/runner/test-error.test.ts`:
-
-```ts
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { toTestError } from "./test-error.js";
-import { AssertionError } from "../assert/assertion-error.js";
-
-test("AssertionError becomes an assertion error with expected/actual", () => {
-  const err = new AssertionError({
-    matcher: "toHaveText",
-    expected: /contact/i,
-    actual: "Home",
-    locator: "//h1",
-  });
-  const result = toTestError(err);
-  assert.equal(result.type, "assertion");
-  assert.equal(result.message, err.message);
-  assert.equal(result.stack, err.stack);
-  assert.equal(result.expected, "/contact/i");
-  assert.equal(result.actual, "Home");
-});
-
-test("other errors stay type error", () => {
-  const err = new Error("boom");
-  assert.deepEqual(toTestError(err), { message: "boom", stack: err.stack, type: "error" });
-});
-
-test("thrown strings stay type error", () => {
-  assert.deepEqual(toTestError("PORT 9223 is already in use!"), {
-    message: "PORT 9223 is already in use!",
-    stack: undefined,
-    type: "error",
-  });
-});
-```
-
-- [ ] **Step 3: Run it to verify it fails**
-
-Run: `npm test`
-Expected: FAIL — `Cannot find module '.../src/runner/test-error.js'`.
-
-- [ ] **Step 4: Implement `toTestError`**
-
-Create `src/runner/test-error.ts`:
-
-```ts
-import { AssertionError, toReportValue } from "../assert/assertion-error.js";
-import type { TestError } from "../types/test.js";
-
-/** Maps anything a test threw to the error stored in the report */
-export function toTestError(err: unknown): TestError {
-  if (err instanceof AssertionError) {
-    return {
-      message: err.message,
-      stack: err.stack,
-      type: "assertion",
-      expected: toReportValue(err.expected),
-      actual: toReportValue(err.actual),
-    };
-  }
-  return {
-    message: err instanceof Error ? err.message : String(err),
-    stack: err instanceof Error ? err.stack : undefined,
-    type: "error",
-  };
-}
-```
-
-- [ ] **Step 5: Run tests to verify they pass**
-
-Run: `npm test`
-Expected: `ℹ pass 33`, `ℹ fail 0`.
-
-- [ ] **Step 6: Wire it into the runner**
-
-In `src/runner/test-runner.ts`:
-
-a) Add imports next to the existing ones:
-
-```ts
-import { takePendingAssertions } from "../assert/expect.js";
-import { toTestError } from "./test-error.js";
-```
-
-b) In `executeTestCase`, replace
-
-```ts
-          await test?.function(launched.page, launched.browser);
-          // Already reported as timed out
-          if (timeoutController.signal.aborted) return resolve();
-          reporter.onTestEnd(test);
-          resolve();
-        } catch (err) {
-          if (timeoutController.signal.aborted) return resolve();
-          reporter.onTestEnd(test, {
-            message: err instanceof Error ? err.message : (err as string),
-            stack: err instanceof Error ? err.stack : undefined,
-            type: "error",
-          });
-          resolve();
-        }
-```
-
-with
-
-```ts
-          await test?.function(launched.page, launched.browser);
-          // Already reported as timed out
-          if (timeoutController.signal.aborted) return resolve();
-          const unawaited = takePendingAssertions();
-          if (unawaited.length > 0) {
-            reporter.onTestEnd(test, {
-              message: unawaited
-                .map((matcher) => `expect(locator).${matcher}() was not awaited`)
-                .join("\n"),
-              type: "assertion",
-            });
-            return resolve();
-          }
-          reporter.onTestEnd(test);
-          resolve();
-        } catch (err) {
-          if (timeoutController.signal.aborted) return resolve();
-          reporter.onTestEnd(test, toTestError(err));
-          resolve();
-        }
-```
-
-c) After the race, reset the registry so leftovers from a failed or timed-out test cannot fail the next one. Replace
-
-```ts
-    clearTimeout(timeoutTimer);
-```
-
-with
-
-```ts
-    clearTimeout(timeoutTimer);
-    takePendingAssertions();
-```
-
-- [ ] **Step 7: Type-check and run unit tests**
-
-Run: `npx tsc --noEmit -p .`
-Expected: only the pre-existing `src/config/default.ts` error.
-
-Run: `npm test`
-Expected: `ℹ pass 33`, `ℹ fail 0`.
-
-- [ ] **Step 8: Commit**
-
-```bash
-git add src/types/test.d.ts src/runner/test-error.ts src/runner/test-error.test.ts src/runner/test-runner.ts
-git commit -m "feat(runner): report assertion failures and missing awaits"
-```
-
----
-
-### Task 6: End-to-end verification against Firefox
-
-**Files:**
-- Modify: `src/tests/index.spec.ts`
-
-**Interfaces:**
-- Consumes: `expect` (Task 4); runner reporting (Task 5).
-- Produces: nothing new.
-
-Note: `bun run dev` launches real Firefox against `https://itmetsam.nl` and needs network access. Run it from a normal terminal (not a restricted sandbox). The report is written to `result/report.json`.
-
-- [ ] **Step 1: Add assertions to the spec**
-
-`src/tests/index.spec.ts` currently has an uncommitted blank line before the commented-out submit block; keep it. Change the import line to:
-
-```ts
-import { test } from "../runner/test-runner.js";
-import { expect } from "../assert/expect.js";
-```
-
-and insert directly after the `messageField.fill(...)` call:
-
-```ts
-  await expect(nameField).toBeVisible();
-  await expect(nameField).toHaveValue("test");
-  await expect(emailField).toHaveValue("sammiedegroot@gmail.com");
-  await expect(subjectField).toHaveValue("Test subject");
-  await expect(messageField).toHaveValue(/very long message/);
-```
-
-- [ ] **Step 2: Run end-to-end, expect success**
-
-Run: `bun run dev; echo "exit $?"; grep -E '"(status|type|message)"' result/report.json`
-Expected: `exit 0`; report shows `"status": "success"` for the summary and the test.
-If a `toHaveValue` fails, the report's `actual` shows what `fill()` really typed — that is a genuine finding about `fill()`; report it rather than loosening the assertion.
-
-- [ ] **Step 3: Verify an assertion failure is reported (temporary change)**
-
-Temporarily change `toHaveValue("test")` to `toHaveValue("wrong", { timeout: 1000 })`.
-Run: `bun run dev; grep -E '"(status|type|message|expected|actual)"' result/report.json`
-Expected: test `"status": "failed"`, `"type": "assertion"`, `"expected": "wrong"`, `"actual": "test"`, message starts with `expect(locator).toHaveValue\n  locator: //input[@id=\"contact-name\"]`.
-Revert the change.
-
-- [ ] **Step 4: Verify the missing-await guard (temporary change)**
-
-Temporarily add, as the last line of the test body, without `await`:
-
-```ts
-  expect(page.locator("div[@id='does-not-exist']")).toBeVisible({ timeout: 3000 });
-```
-
-Run: `bun run dev; grep -E '"(status|type|message)"' result/report.json`
-Expected: `"type": "assertion"`, `"message": "expect(locator).toBeVisible() was not awaited"`, and the process still exits by itself.
-Remove the line.
-
-- [ ] **Step 5: Final checks**
-
-Run: `npm test` → `ℹ fail 0`.
-Run: `npx tsc --noEmit -p .` → only the pre-existing `src/config/default.ts` error.
-Run: `git diff src/tests/index.spec.ts` → only the import, the five assertions and the pre-existing blank line.
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add src/tests/index.spec.ts
-git commit -m "test: assert filled contact form values end-to-end"
-```