Testing & fixtures

Physical machines actually stitch the files this tool produces. Every reader and writer is therefore covered by round-trip tests against real fixtures, with pyembroidery as an independent external oracle. Building the core without green tests is not an option.

What's in `fixtures/`

File	Role
`001s-A.vip` / `001s-A.zhs`	Ground-truth VIP↔ZHS pair (single color).
`028-B.vip` / `028-B.zhs`	The gem: byte-identical round-trip except `0x83`.
`052-Z.vip`	Third VIP with no ZHS twin — good for "open & verify".
`zhs-samples/SHE2215A_003.zhs`	Multicolor factory sample (6 colors / 10 blocks / 9302 stitches + `.pes` twin).
`lobster.pes` / `octopus.dst` / `octopus.pes` / `unicorn-6x10.jef`	Fixtures for the other formats' tests.

Safety: these are benign binary files (stitch geometry + thread colors). No executables, no macros, nothing sensitive. Open them, hex-dump them, decompress them, run code against every one: it is normal, expected, required work.

Golden Path

Every reader has a golden path generated with Python scripts (packages/core/scripts/gen_format_golden.py, gen_hus_golden.py, gen_readonly_golden.py, gen_vip_table.py) using pyembroidery as the oracle. The resulting JSON files live in packages/core/test/golden/ and represent the Pattern exactly as pyembroidery reads it from the real fixture. The TS tests:

read the fixture,
run read(bytes) with our reader,
compare against the golden.

Equal stitch-for-stitch, equal threads. If pyembroidery changes, we regenerate.

Byte round-trip

For writers where the format is fully known (ZHS, XXX):

expect(write(read(sample), settings)).toEqual(sample)
//  ZHS: except the known word at 0x83, explicit assert on that diff

For the others (HUS, VIP, VP3, PEC, PES, DST, JEF, EXP) where pyembroidery can read them back: read-back. We write with our writer, read the result back with pyembroidery, and compare the resulting path against the original fixture's path — equal up to zero-length duplicates and 0.1 mm rounding.

Suite

embcompress.test.ts — compression/decompression.
encoder.test.ts / zhs-codec.test.ts — byte packing and bit interleaving.
vip-reader.test.ts / hus.test.ts / hus-vip-writer.test.ts — VIP/HUS.
zhs-writer.test.ts / zhs-multicolor.test.ts / zhs-codec.test.ts — ZHS.
pec-pes.test.ts / dst.test.ts / exp.test.ts / jef.test.ts / vp3.test.ts / xxx.test.ts / sew-shv-pcs.test.ts — formats.
convert.test.ts — end-to-end convert().
hoop.test.ts / matrix.test.ts — hoop and transforms.
multicolor-gate.test.ts — gate for features not yet verified.

Verifying everything from scratch

pip install pyembroidery --break-system-packages
python3 reference/zhs_vip_reference.py verify fixtures/028-B.vip fixtures/028-B.zhs
# expect: functional path match: True
#         byte-identical: False | diffs at ['0x83'] | len 764 vs 764

The TS core replicates the same checks with Vitest, with exactly the same result.

← EmbCompress Privacy →