ecadforge_app

# Testing

## Strategy

- Unit-test normalized viewer state behavior
- Verify integration with the converged Altium, KiCad, Gerber, CircuitJSON,
  and PCB Scene3D package family
- Parse horizontal, diagonal, and vertical plated Gerber routed slots through
  the real project loader and assert canonical dimensions and board-space angle
  at viewer intake
- Preserve disjoint Gerber profiles as separate runtime/export substrates and
  route real KiCad ZIPs away from Gerber detection
- Pin the registry Gerber Toolkit release that rejects pen-separated mechanical
  frame strokes as canonical cutouts; detailed draw-run, transparent
  containment, step-repeat, region, profile, concave-intersection, scale, and
  quantized-arc regressions stay in the toolkit-owned suite
- Retain exact STEP bytes for both KiCad ZIP and directory-upload companions
  under bounded `decodeAssets: 'full'` project loading
- Load the bundled multi-entry KiCad demo through the published browser worker
  protocol and verify public project entries, binary assets, and caller-buffer
  ownership without app-private transport fields
- Resolve KiCad `${KIPRJMOD}` to the canonical asset name and verify the real
  viewer receives exact bytes, board placement, and independent local model
  transforms without an app resolver
- Prove independent mixed-format project groups start concurrently while
  canonical results remain in deterministic toolkit order
- When overlapping project groups report the same canonical asset, retain the
  payload-bearing record instead of an earlier metadata-only duplicate
- Verify canonical envelope routing, context/index reuse, and retained native
  `/extensions` imports. Fidelity-sensitive Altium/KiCad schematic and KiCad
  PCB interaction paths must resolve the native extension before the canonical
  fallback; BOM and KiCad 3D must remain canonical.
- Verify explicit Altium and KiCad native-model selection preserves theme
  colors, symbol bodies, wiring, text placement, free graphics, packed images,
  hidden labels, and canonical document identity.
- Verify canonical KiCad 3D preserves `source.format`, keeps omitted trace,
  pour, and via mask-opening values covered, and leaves explicit openings
  exposed with the correct material groups.
- Verify real project loading resolves native project strings and the
  toolkit-owned renderer suppresses hidden fallback labels without an app
  rewrite helper
- Verify direct files, folder trees, project companions, and session assets
  preserve 3MF format and exact source path through viewer intake
- Validate required project structure and source/test file line limits

## Commands

```bash
npm test
npm run check:structured-data
npm run build:static
```

## Current Coverage

- `tests/app-state.test.mjs`: state defaults, patching, subscriptions
- `tests/ui/renderers.test.mjs`: ECAD Forge 3D shell renderer coverage
- `tests/app-meta-loader.test.mjs`: browser metadata endpoint fallback behavior
- `tests/php-app-meta-endpoint.test.mjs`: deployable PHP metadata endpoint payloads
- `tests/static-deploy-builder.test.mjs`: static Apache artifact cache-busting coverage
- `tests/server-startup.test.mjs` and `tests/static-deploy-builder.test.mjs`:
  installed OCCT ESM, WASM, worker, and license assets remain byte-exact at the
  scoped package path; removed vendored aliases stay unavailable
- `tests/deploy-ftp-workflow.test.mjs`: FTP workflow deployment coverage for static frontend, `api/`, and metadata
- `tests/seo-pages.test.mjs`: canonical SEO page metadata, JSON-LD graph shape, and structured-data drift tooling
- `tests/project-structure.test.mjs`: required file presence
- `tests/mjs-line-limit.test.mjs`: source and test file length guard
- `tests/toolkit-api-convergence.test.mjs`: converged dependency versions and
  extension-entrypoint enforcement, plus schema-valid KiCad parser and project
  output for legacy values and transformed artwork
- `tests/core/ecad-format-registry-canonical.test.mjs`: canonical source
  identity, viewer compatibility, shared context reuse, render reuse, and BOM
  derivation
- `tests/core/ecad-native-fidelity-routing.test.mjs`: native-first Altium/KiCad
  schematic routing, native KiCad PCB/hit/layer routing, canonical fallback,
  and canonical BOM behavior
- Viewer-owned package tests cover all live model formats, safe companion
  resources, opt-in URL policy, exact cache identities, retry eviction, and raw
  ZIP format/payload parity; app integration tests verify the direct canonical
  document/session boundary without app resolver wrappers
- App intake coverage includes direct and folder-discovered 3MF assets and
  asserts the renderer service contains no native schematic rewrite path

## Visual regression check

After dependency or renderer-routing changes, load the bundled Altium and
KiCad demos in a real browser. Check the full schematic palette, symbol fills,
wire continuity, text placement, and sheet decorations. For KiCad 3D, check a
top and isometric view: solder-mask-covered traces, pours, and tented vias must
use the board mask palette, while pads and explicitly opened copper remain
exposed. Record console errors and failed network requests in addition to the
screenshots.

## Rules

- Add/update app tests for ECAD Forge interaction, server, state, and package integration behavior
- Add parser, deterministic renderer, and non-interactive scene-data tests in the relevant toolkit repository
- Keep fixture expectations in the toolkit repository and preserve the existing obfuscation rules