Fixture and oracle design

Test Asset Layout

The tests/assets/projects tree contains redistributable Altium projects plus Altium-generated reference outputs used as command oracles. Tests should treat these assets as inputs and write all generated artifacts to temporary directories that mirror the project-local output/ layout, or to the project-local output/ folder for manual review.

Project Structure

Path	Meaning
`input/`	Committed project source files: `.PrjPcb`, `.SchDoc`, `.PcbDoc`, and `reference_gen.OutJob`.
`reference_output/`	Outputs generated by opening the project in Altium and running `input/reference_gen.OutJob`.
`output/`	Local scratch output only. Tests and agents should put manual review artifacts here, grouped by command, variant, and output kind.

Variant Folders

reference_output/no_variant means Altium generated the output with no variant applied. Variant-specific outputs should live under a folder named for the variant, such as reference_output/B4. BOM, PnP, and JLC review artifacts should use the project-local output folder: tests/assets/projects/<project>/output/<command>/<variant>/....

BOM and PnP Oracles

XML-BOM and CSV-BOM are Altium oracle outputs. BOM tests use them to verify source component coverage, designator resolution, DNP behavior, and key fields such as value and description. The raw JSON output is the main machine-consumable checkpoint because it preserves normalized component data without losing Altium Monkey source detail.

PNP-METRIC contains Altium-generated pick-and-place CSV files. PnP tests use these files for placement designators, side, numeric center coordinates, and rotation checks. Coordinates should be compared with a small numeric tolerance because Altium emits fixed decimal text and the CLI stores floats.

Primary Cases

nxp-frdm-imx93 and ov-tech-pimx8 extend the opt-in toon/SVG performance corpus with larger boards and complex embedded STEP models. Their project-referenced sources retain original relative paths, and source manifests record byte hashes. They have no Altium output oracle and are excluded from fast unit-test workloads. bluetooth_sentinel_flex and Kame_IMU are focused PcbDoc-only board-region and local-stack-thickness fixtures. Together they provide two independent rigid-flex designs for flat Toon rendering, regional materials, coverlay, and bend-line review.

Project	Purpose
`node_test_array`	Primary BOM/PnP test. It exercises hierarchical channel designators and variant `B4`, where one channel has different DNP state from the other channels. It also contains standard `No BOM` component behavior.
`loz-old-man`	High component-count BOM/PnP test. It exercises broad component-type coverage; variant `A` includes alternate component values such as `R6`.
`cutouts`	Primary `pcb-svg` board cutout fixture. It contains four interior cutouts covering rectangular, circular arc, and rounded T-shaped geometry.
`bluetooth_sentinel_flex`	Primary source-aware board-region fixture. Its two rigid regions resolve to 32.1455 mil and its flex region resolves to 3.3267 mil. Focused region-query tests may run normally; full Toon rendering remains opt-in.
`Kame_IMU`	Second source-aware rigid-flex fixture. Its two rigid regions resolve to 34.1479 mil and its flex region resolves to 6.3391 mil. The PcbDoc-only fixture adds an independent 51-component Gate 5 case for regional surface materials, coverlay, bend lines, and documented multi-region placement limits.
`single-throughhole` and `single-smt`	Paired top- and bottom-placement fixtures for affine placement, board-thickness clipping, and opposite-side SVG visibility-mask regressions. Only the focused PcbDoc files are retained.
`issue67-reporter`	Reporter-authorized real-world PcbDoc from issue 67. It covers mixed component placement and projection defects without retaining reporter attachments or screenshots.
`toon-analytic-bodies`	Generator-owned Gate 6 PcbDoc for component-owned analytic 3D bodies. Its deterministic semantic inventory covers extrusions, cylinders, spheres, top/bottom placement, Z overlap, board crossing, edge/cutout overhangs, color, partial opacity, and zero-opacity omission without STEP geometry.

Manual SVG Review

tests/support_scripts/svg_review_gallery.py builds an offline review page for any ordered JSON array of titled SVG paths. Items may include group and detail labels. The responsive overview opens each original vector in a full-screen modal with pan, wheel and toolbar zoom, fit, and previous/next navigation. The generator embeds the vendored svg-pan-zoom implementation, so review pages do not depend on a CDN or raster preview. Large manifests may set split_by_group_pattern; the root then becomes a lightweight index and each matched group partition is written as an independently loaded subgallery.

uv run python tests/support_scripts/svg_review_gallery.py review.json --output output/svg-review

SvgReviewItem

Rationale

Durable visual qualification needs a small renderer-independent description of each SVG rather than board-specific gallery code.

Purpose

Associates an arbitrary local SVG path with its review title, group, and optional detail text for the offline vector gallery.

Test Requirements

Gallery tests verify vector-native modal embedding, vendored offline pan/zoom, safe markup validation, relative paths, and optional per-group partitioning.

Working Definition

Working when arbitrary titled SVGs can be inspected without rasterization or network access and large manifests can be split without changing item order or labels.

Known Limitations

Altium Monkey does not currently process Altium .annotation files. Projects that rely on external annotation data can still have edge cases in designator resolution. Release notes should keep this limitation visible until annotation-file processing is implemented.