pcbjam/tests/README.md

# KiCad WASM Tests

Playwright tests for verifying the wxWidgets WASM port.

## Prerequisites

- Node.js 18+
- Emscripten SDK (for building)

## Building the Test App

```bash
../scripts/build-wasm-test.sh
```

This builds `apps/minimal_test.{html,js,wasm}` and standalone test apps.

## Running Tests

```bash
npm install
npm test          # setup:kicad + the full merged run (same projects as CI)
```

One merged config (`playwright.config.ts`) drives every wasm suite as
Playwright *projects*; `npm run test:e2e` runs the CI set: `wx-chromium`,
`kicad-firefox`, `kicad-chromium`, `jspi-firefox`, `coroutine-firefox`.
The KiCad specs (heavier — they need the docker-built KiCad WASM) run on BOTH
engines; `npm run test:kicad` is the firefox-only shortcut. The React web app
suite is separate: `npm run test:web` (see `playwright-web.config.ts`).

To run a subset, pick a project (and optionally a spec):
```bash
npx playwright test --project=wx-chromium menu.spec.ts     # wx menu tests only
npx playwright test --project=kicad-firefox kicad/pcbnew.spec.ts
npx playwright test --project=wx-chromium --grep "wxTimer"
```

## Test Structure

```
tests/
├── e2e/                    # Playwright test specs
│   ├── utils/              # Shared test utilities
│   │   ├── fixtures.ts     # Playwright fixtures with auto-logging
│   │   ├── element-tracker.ts  # Element registry utilities (clickByLabel, etc.)
│   │   └── test-utils.ts   # Logging and helper functions
│   ├── menu.spec.ts        # wxMenuBar tests
│   ├── timer.spec.ts       # wxTimer tests
│   ├── dialog.spec.ts      # wxDialog/wxMessageBox tests
│   ├── tree.spec.ts        # wxTreeCtrl tests
│   ├── grid.spec.ts        # wxGrid/wxSpinCtrl/wxSearchCtrl tests
│   ├── wxwidgets.spec.ts   # Comprehensive UI interaction tests
│   └── ...
├── logs/                   # Test logs (auto-generated)
├── test-results/{chromium,firefox}/   # Screenshots per engine (auto-generated)
├── baseline-screenshots/{chromium,firefox}/  # Committed reference screenshots per engine
├── screenshot-manifest.json # Authoritative {name, engine} list (npm run screenshots:manifest)
├── apps/              # Built WASM test applications
│   ├── minimal_test.html  # Main test app
│   └── standalone/        # Individual component test apps
├── playwright.config.ts       # THE merged config (wx / kicad / jspi / coroutine / perf projects)
└── playwright-web.config.ts   # React web-app suite (own server stack)
```

## Logging

Each test automatically captures:
- Console logs with timestamps and log levels
- Page errors with full stack traces

Log files are written to `logs/` after each test:
- `<test-name>.log` - All console output
- `<test-name>.errors.log` - Errors only (created if errors occurred)

Example log format:
```
[2025-11-29T19:39:42.165Z] [LOG] [EVENT] Application started
[2025-11-29T19:39:42.733Z] [WARNING] GPU stall due to ReadPixels
[2025-11-29T19:39:42.801Z] [ERROR] Some error message
```

## Screenshots

Tests capture raw PNGs to `test-results/<engine>/` (engine-scoped via
`stableShot`/`shotPath`). The offline gate compares them against the committed
per-engine baselines:
```bash
npm run screenshots:check
```
CI's Linux render is the source of truth — update baselines by promoting a CI
run (`npm run screenshots:promote -- --run <ci-run-id>`), never by copying
local renders. Rules and details: `TESTING.md`.

## Viewing the App Directly

Start a local server in the apps directory:

```bash
cd apps
npx serve .
```

Then open http://localhost:3000/minimal_test.html in your browser.

Alternative using Python:

```bash
cd apps
python3 -m http.server 8000
```

Then open http://localhost:8000/minimal_test.html

## Test Categories

| Spec File | Tests | Description |
|-----------|-------|-------------|
| `wxwidgets.spec.ts` | Comprehensive | Full UI interaction, stability |
| `menu.spec.ts` | wxMenuBar | Menu bar visibility and interactions |
| `timer.spec.ts` | wxTimer | Timer start/stop/reset functionality |
| `dialog.spec.ts` | wxDialog | Message boxes and custom dialogs |
| `tree.spec.ts` | wxTreeCtrl | Tree control with expand/collapse |
| `grid.spec.ts` | wxGrid | Grid, SpinCtrl, SearchCtrl |
| `aui.spec.ts` | wxAuiManager | Dockable panels |
| `clipboard.spec.ts` | wxClipboard | Copy/paste operations |
| `dataview.spec.ts` | wxDataViewCtrl | List and tree data views (Zone Manager-like) |
| `filedialog.spec.ts` | wxFileDialog | File open/save dialogs |
| `htmlwin.spec.ts` | wxHtmlWindow | HTML rendering (About dialogs, error formatting) |
| `layout.spec.ts` | wxSplitter | Splitter and scrolled windows |
| `toolbar.spec.ts` | wxToolBar | Toolbar buttons and status bar |

## Debugging WASM Crashes

When a test fails with a WASM crash (e.g., "memory access out of bounds"), you can build with debug symbols to get meaningful stack traces:

### Debug Build

```bash
# Build test apps with DWARF symbols and source maps
../scripts/build-wasm-test.sh --debug
```

This enables:
- `-g` for DWARF debug info
- `-gsource-map` for browser source maps
- `-O0` for no optimization (preserves debugging context)

### Reading Stack Traces

With a debug build, WASM stack traces show actual function names:

**Before (release build):**
```
RuntimeError: memory access out of bounds
    at wasm-function[102]:0xfdf8
    at wasm-function[99]:0xe6e0
```

**After (debug build):**
```
RuntimeError: memory access out of bounds
    at grid_test.wasm.GridTestFrame::LogEvent(wxString const&)
    at grid_test.wasm.GridTestFrame::OnGridCellSelect(wxGridEvent&)
    at grid_test.wasm.wxEventFunctorMethod<...>::operator()
```

### Using LLVM Tools

For deeper analysis, use Emscripten's LLVM tools:

```bash
LLVM_DIR="/opt/homebrew/Cellar/emscripten/4.0.20/libexec/llvm/bin"

# Check if WASM has DWARF info
$LLVM_DIR/llvm-dwarfdump --debug-info apps/standalone/grid/grid_test.wasm

# Disassemble with function names
$LLVM_DIR/llvm-objdump -d grid_test.wasm | head -200
```

## Element Registry (Recommended)

The wxWidgets WASM port includes an element registry that tracks all wxWindow instances with their positions, labels, and types. This enables tests to find UI elements by semantic identifiers instead of hardcoded pixel coordinates.

### Usage

```typescript
import { waitForRegistry, clickByLabel, findByLabel, findByType } from './utils/fixtures';

// Wait for registry to be available
await waitForRegistry(page);

// Click buttons by label text
await clickByLabel(page, 'Copy to Clipboard');
await clickByLabel(page, 'Save File...');

// Find elements for inspection
const button = await findByLabel(page, 'OK');
if (button) {
  console.log(`Button at (${button.centerX}, ${button.centerY})`);
}

// Find all elements of a type
const buttons = await findByType(page, 'wxButton');
```

### Available Functions

| Function | Description |
|----------|-------------|
| `waitForRegistry(page)` | Wait for element registry to initialize |
| `findByLabel(page, label, options?)` | Find element by label text |
| `findByName(page, name, options?)` | Find element by wxWindow name |
| `findByType(page, typeName, options?)` | Find all elements of a type (e.g., 'wxButton') |
| `clickByLabel(page, label, options?)` | Click element by label |
| `clickByName(page, name, options?)` | Click element by name |

### Options

```typescript
interface FindOptions {
  visible?: boolean;  // Filter by visibility (default: true)
  enabled?: boolean;  // Filter by enabled state
  exact?: boolean;    // Exact label match (default: substring)
  type?: string;      // Filter by type name
}
```

### When to Use

Use the element registry for tests that click on **wxButton** and other wxWindow-based controls. The registry tracks:
- wxButton, wxTextCtrl, wxStaticText, wxPanel, wxFrame, etc.

**Not trackable** (use pixel coordinates instead):
- wxToolBar tool items (rendered by toolbar)
- wxMenuBar menu items (rendered by menu system)
- wxAuiManager panel controls (title bars, close buttons)
- wxGrid cells (rendered by grid)
- wxSplitterWindow sash (rendered by splitter)

### Migrated Tests

These tests use the element registry:
- `clipboard.spec.ts` - Copy, Paste, Check, Clear buttons
- `dialog.spec.ts` - Info, Yes/No, Error, Custom dialog buttons
- `timer.spec.ts` - Start, Stop, Reset buttons
- `filedialog.spec.ts` - Open, Save, Open Multiple buttons
- `logerror.spec.ts` - Trigger Error, Flush Log buttons

### Available Test Apps

| App URL | Description |
|---------|-------------|
| `/standalone/clipboard/clipboard_test.html` | Copy, Paste, Check, Clear buttons |
| `/standalone/dataview/dataview_test.html` | wxDataViewListCtrl and wxDataViewTreeCtrl (Zone Manager-like data) |
| `/standalone/dialog/dialog_test.html` | Info, Yes/No, Error, Custom dialog buttons |
| `/standalone/htmlwin/htmlwin_test.html` | wxHtmlWindow with various HTML content |
| `/standalone/tree/tree_test.html` | Expand All, Collapse All, etc. |
| `/standalone/menu/menu_test.html` | Menu bar testing |
| `/standalone/grid/grid_test.html` | Grid controls |
| `/standalone/aui/aui_test.html` | AUI panel controls |
| `/standalone/toolbar/toolbar_test.html` | Toolbar buttons |
| `/standalone/timer/timer_test.html` | Timer controls |
| `/standalone/filedialog/filedialog_test.html` | File dialog buttons |
| `/standalone/layout/layout_test.html` | Layout controls |

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `APP_URL` | (required) | URL path to scan |
| `STEP` | `10` | Pixel step size for scanning (smaller = more accurate but slower) |
| `START_X` | `0` | X coordinate to start scanning |
| `END_X` | canvas width | X coordinate to end scanning |
| `START_Y` | `0` | Y coordinate to start scanning |
| `END_Y` | canvas height | Y coordinate to end scanning |

### Output

The utility outputs:
- Button positions with labels (from console log keywords)
- Generated test code snippets
- Results JSON file at `test-results/button-finder-results.json`

Example output:
```
RESULTS: Found 4 buttons

Button positions (relative to canvas):

  Copy         at (352, 196)
    Log: [CLIPBOARD_EVENT] Attempting to copy text to clipboard...

  Paste        at (600, 196)
    Log: [CLIPBOARD_EVENT] Attempting to paste from clipboard...
```

## Known Issues

- **Timer tests**: May fail due to timing sensitivity
- **Tree tests**: Button click positions may vary

## Open tasks

- ~~Research: are the Asyncify fiber shims still needed under native-EH?~~
  **Resolved at doc 20 D-1, then mooted by the JSPI migration (2026-08)**: the
  ablation builds (`races_test_noheal` / `races_test_nosleepfix`) and their
  shim-redundancy pins (in the since-deleted `asyncify/asyncify-races.spec.ts`)
  pinned a runtime that no longer exists, and the asyncify scheduler shim they
  were measured against retired with the backend. The semantic race battery
  lives on in `jspi/suspend-races.spec.ts` against the JSPI runtime.

## Collab e2e — legacy vs v2 bundles, and repro markers

Two esbuild bundles (`npm run build:collab`, rebuilt by the specs' `beforeAll`):

- `apps/kicad/collab-bundle.js` — the LEGACY scalar wire (`startCollab` /
  `kicadCollabSnapshot/Apply` / `onDelta`). Dead in production (nothing registers
  `onDelta`); driven by the pre-existing `*-collab.spec.ts` two-tab tests. Kept only
  until the scalar wire is deleted.
- `apps/kicad/collab-bundle-v2.js` — the PRODUCTION v2 "items" stack
  (`bindKicadCollab` over `kicadCollabSnapshotItems/ApplyItems/onItems`, Y keys
  `kdoc_*`), from `collab/browser-entry-v2.ts`. Driven by `kicad/ysync-two-tab.spec.ts`.
  The build aliases `yjs` to ONE copy (the two web pnpm workspaces otherwise bundle two,
  and Y types are instanceof-checked).

### ysync repro tests

`kicad/ysync-two-tab.spec.ts`, `kicad/ysync-repros-{pcbnew,eeschema}.spec.ts` reproduce
the bugs of the 2026-07-02 Yjs⇄KiCad sync review (`docs/features/ysync-review/` on the
`ysync-review` branch; unit-level repros live in
`web/pcbjam-shared/test/ysync-repros.test.ts` and
`web/standalone/src/wasm/collab/ysync-repros.test.ts`).

Convention: a repro asserts the CORRECT behavior and is marked expected-fail
(`test.fail()` / vitest `it.fails`) with a comment naming the bug doc. The suite stays
green while the bug is open; fixing the bug flips the repro to "unexpected pass",
forcing the marker's removal — the repro becomes the regression test. Green companion
tests pin each repro's preconditions (harness, apply path, emit path) so an expected
failure can only come from the bug itself. The "local move emits" controls double as
the headless-emit probes gating the emit-dependent repros.

Follow-up (tracked in review miss 11): once the v2 specs are trusted, un-skip/retire
the legacy two-tab specs together with the legacy wire.