RFC-0035: Shared crates for tests and development tools (#55)

This commit is contained in:
.CooCoo authored and GitHub committed 2026-11-18 22:22:48 +07:00
1 parent 5d6da084fe
commit b9d4cb3690
1 file changed
+871
@@ -0,0 +1,871 @@
# RFC-0035: Shared crates for tests and development tools
Every Craft repository carries its own copies of the same test and build helpers: temporary folders
removed on drop, skip-or-fail rules for missing programs and fonts, external test programs, GPU and
other test locks, image comparison, CLI and MCP test clients, seeded random input, egui input steps,
and the `cargo xtask` commands for the gate, layers, assets, versions and icons. Many copies started
from one source and have since diverged, and several carry a fault that another copy has fixed. This
RFC proposes one family of craft-libs crates and features for this code. Each part takes its code from
the repository that already has a tested version, names its first consumers, and replaces the copies
one repository at a time with the same test results. The family follows candidate 11, "Shared tooling
and tests", of the maintainers' source audit (storytold/craft-libs#2).
Related: storytold/craft-libs#2, storytold/craft-libs#9, storytold/craft-libs#115,
storytold/craft-libs#138, storytold/craft-libs#139, storytold/craft-libs#163, storytold/craft-libs#1373,
storytold/craft-libs#172,
storytold/craft-libs#701, storytold/craft-libs#989, storytold/craft-libs#1066, storytold/craft-libs#1112,
storytold/craft-libs#504, storytold/craft-libs#437, storytold/craft-libs#616, storytold/craft-libs#698,
storytold/craft-common-actions#124, storytold/craft-common-actions#185,
storytold/craft-common-actions#225, storytold/craft-contrib#10, storytold/craft-contrib#15,
storytold/craft-contrib#18, storytold/craft-contrib#21, storytold/craft-contrib#23,
storytold/craft-contrib#30, storytold/craft-contrib#39, storytold/craft-contrib#41,
storytold/craft-contrib#43, storytold/craft-contrib#46, storytold/craft-contrib#50,
storytold/craft-contrib#52, storytold/craft-contrib#54, storytold/craft-contrib#56, storytold/lightcraft#3083, storytold/lightcraft#3096,
storytold/pdfcraft#6124, storytold/pdfcraft#6188, storytold/pdfcraft#7173,
storytold/photocraft#10189, storytold/designcraft#1980.
## Summary
The family has four parts:
1. `craft-testkit`, a new test-support crate. Its core modules use `std` and one small dependency: `temp`,
`skip`, `oracle`, `fixtures`, `serial`, `bin`, `deadline`, `growth`, `rng`, `hostile`, `fonts` and
`guards`.
Its feature modules add one dependency each: `image` (PNG), `prop` (proptest), `corpus` (SHA-256),
`mcp` (JSON) and `log`. A `geom` feature adds `craft-geom`, `kurbo` and `proptest` for the geometry
assertions and strategies of RFC-0030.
2. UI test support in the existing `craft-ui` crate: an `input` module and a `snapshot` module in
`craft_ui::testing`, beside the `Screens`, `ime_events`, `compose` and `DockDriver` helpers that it
already ships and that no app uses yet.
3. Test fixtures in the craft-libs format crates: one feature name, `test-support`, for every crate that
exposes fixture writers, and adoption of the writers that already exist (`craft-pdf`, `craft-tiff`,
`craft-psd`, `craft-audio`).
4. `craft-xtask`, a new library of `cargo xtask` commands: the gate's step runner, `layers`, `version`,
`ico` and `icns`, `assets`, a display-name scanner, pinned downloads, `stats` and pinned-dependency
checks. Each app keeps its own `cargo xtask` binary and its app-only commands.
The `guards` module is the one storytold/craft-libs#139 proposes. It comes from
storytold/craft-libs#1373, which supersedes zachshallbetter's storytold/craft-libs#163 and keeps his
commit with its authorship. The time-scaled waits and the watchdog of `deadline` come from THEtheChad's
LightCraft pull requests and are added after they merge. The `growth` module follows addibble's
suggestion in the review of this RFC.
The section "Candidates for later RFCs" lists runtime code that the apps also duplicate, as candidates
for later RFCs. The apps' copies of runtime code that a craft-libs crate already holds are the subject
of RFC-0036 (storytold/craft-contrib#56), which is related work and is not decided here.
## What exists
This section is a non-normative record as of 2026-11-14, as RFC-0023's "Reference implementations,
non-normative" section is. It is not updated after this RFC is accepted, and a renamed file, a changed
count or a consumer that drops out does not change what the RFC decides.
The listings below were read on 2026-11-14 at vectorcraft `460d211995`, photocraft `0d3b1e8523`,
designcraft `8b169f8ee7`, lightcraft `487833ad19`, filmcraft `e4ab3c6a99`, effectcraft `f029bbadb2`,
pdfcraft `346d803080`, gridcraft `c2aba7a3f4`, wordcraft `f8c66d0692`, deckcraft `b0c77ebd6a`,
soundcraft `2688ccac88`, cadcraft `8e69890223`, figcraft `bad07e4433`, anicraft `6784cf72ce`,
materialcraft `bb7434478c`, texturecraft `386630ee85`, craft-libs `7ad4765ee5`, craft-launcher
`ba56c4587f`, craft-anything `58748a7463`, craft-common-actions `f76646c68b`, craft-i18n `e56d2624`,
craft-contrib `ce8827d4`, craft-ai-integrations `e8b31cb059`, craft-extensions `964c71574a`, craft-fonts
`c1db6d1a8e`, winprint.rs `e90c444476`, craft-pr-review-tool `197a26dc9f`, craft-repo-status-app
`b4a2f85f56` and indd-utils `136f973a9d`. Counts made with `git grep` are lower bounds. Line
references into files that changed after those commits were read again on 2026-11-14 at lightcraft
`6b2b7e6d11`, pdfcraft `eead454105`, photocraft `d6557b9a8b` and vectorcraft `107078ad10`.
Of the last seven, craft-ai-integrations holds code this RFC uses: `crates/ai-mcp/src/apps/child.rs` is
an MCP stdio client for each app's `<app>-cli mcp` (`Conn`, `spawn`, `initialize`, `request`, `notify`
and `call_tool`, a `MAX_LINE` cap at `:20`, a deadline on every wait, protocol `2025-06-18` at `:36`),
with 14 tests in `child_tests.rs`, and `crates/ai-mcp/src/mcp.rs` is an MCP stdio server. The other
six have no `xtask/` crate and no testkit crate.
### Test-support crates
- **VectorCraft.** `crates/testkit` (`vectorcraft-testkit`) is a dev-dependency of 11 packages.
`lib.rs` holds `temp_dir(tag)`, a per-process private folder: mode 0o700 on Unix, and it fails the
test (panics) for a symlink, a folder other users can reach or a folder owned by another user
(`lib.rs:48-74`; the crate allows `unwrap_used`, `expect_used` and `panic` at `:23`).
storytold/vectorcraft#4737 made it start empty in each process, and storytold/vectorcraft#5419 added
the owner check. `lib.rs` also holds `TempDir`, a per-test folder removed on drop. `raster.rs` compares
images (`diff`, `perceptual_diff`, and the function `assert_similar` at `:165`), reads PNG through the
`image` crate (`:20-21`) and renders VectorCraft documents (`render_region`, `render_artboard`,
`render_view` at `:55-65`). The other modules hold document fixtures, proptest strategies, invariants,
geometry assertions and hand-written PDF, Illustrator, `.ase`, TIFF and font files.
- **PhotoCraft.** `crates/testkit` (`photocraft-testkit`) holds `gpu_lock()` (`gpu.rs:32`), `Sweep`
(`sweep.rs`) and benchmark helpers (`perf.rs`).
- **LightCraft.** `crates/testkit` (`lightcraft-testkit`) holds a `skip!` macro and `record()`, which
print `skipped (<need>): <reason>` and append one JSON line to the file `LIGHTCRAFT_SKIP_LOG` names.
It has no required variable. Open storytold/lightcraft#3083 adds `deadline.rs` and `watchdog.rs`.
- **FilmCraft.** `crates/testkit` (`filmcraft-testkit`) holds program discovery (`oracle.rs`, with
`find_tool_in` at `:41` taking the explicit path and `PATH` as arguments), the `require_ffmpeg!`,
`require_ffprobe!` and `require_oracles!` macros (`lib.rs:32`, `:49`, `:66`), fixture publication
(`fixtures.rs`), golden images with `FILMCRAFT_BLESS` and a `.attribution` sidecar written with
`chrono` (`golden.rs:7`, `:196-241`; `Cargo.toml:15-17` names `png = "0.18"` and `chrono`), a hang
guard (`deadline.rs:19-23`, `FILMCRAFT_HOSTILE_TIMEOUT_SECS`), `cuts.rs` and a float WAV writer
(`wav.rs`). FilmCraft's `xtask` depends on it (`xtask/Cargo.toml:13`).
- **PdfCraft.** `crates/testkit` (`pdfcraft-testkit`) holds the `Pdf` builder. `crates/oracle`
(`pdfcraft-oracle`) finds qpdf, pdftoppm and pdftotext (`find` at `lib.rs:127`), and its `or_skip!`
macro expands its `assert!` in the calling test. `pixels.rs` compares gray rasters. PdfCraft's
`xtask` depends on `pdfcraft-oracle` (`xtask/Cargo.toml:12`).
- **craft-libs.** `crates/media-testkit` (`craft-media-testkit`) finds ffmpeg and ffprobe, skips or
fails under `CRAFT_MEDIA_REQUIRE_ORACLES`, makes private folders (`private_dir()`), publishes and
generates fixtures, runs `with_deadline` under `CRAFT_TEST_TIMEOUT_SECS` (`lib.rs:221-222`) and holds
the hostile-input hammer `hostile.rs`. `hostile.rs` was ported from storytold/filmcraft#1794 by
storytold/craft-libs#989, and storytold/craft-libs#1066 ported the rest of #1794's container tests.
craft-media, craft-cfb, craft-audio and craft-video depend on the crate.
`crates/audio/tests/codecs/testkit.rs` wraps it and keeps its own `fixtures::generate` (`:55-69`) and a
`generate_and_report` stub that only calls `generate()` (`:72-74`). `crates/pdf/tests/cos/oracle.rs`
is a port of `pdfcraft-oracle`.
- **Craft Anything.** `crates/testkit` (`craft-anything-testkit`) builds reverse-engineering samples.
DeckCraft and CADCraft (`xtask/src/layers.rs:15-17`), DesignCraft (`xtask/src/layers.rs:17`, `:53`,
`:141`) and WordCraft (`xtask/src/layers.rs:17`, `:51`, `:139`) reserve a testkit layer class that
other crates may use only as a dev-dependency, and none of the four has a `crates/testkit`.
DesignCraft also declares `designcraft-testkit` at `Cargo.toml:58` (storytold/designcraft#1980).
GridCraft, FigCraft, MaterialCraft and TextureCraft have no testkit class.
### Helpers copied between repositories
| Helper | Copies | Repositories |
|---|---|---|
| Test-only drop guards that remove a folder | about 74 | LightCraft about 25, FigCraft 8, PdfCraft 7, CADCraft 5, PhotoCraft 5, craft-libs 5, WordCraft 4, FilmCraft 3, VectorCraft 2 outside its testkit, MaterialCraft 2, SoundCraft 2, EffectCraft 2, DeckCraft 1, DesignCraft 1, TextureCraft 1, craft-launcher 1 |
| `static NAME: Mutex<()>` test locks | about 110 | 16 repositories; VectorCraft 20 and PhotoCraft 18 lead |
| GPU test locks outside a testkit | 11 | PhotoCraft (`crates/gpu/tests/it/main.rs:5`), EffectCraft 4, PdfCraft 2, WordCraft, LightCraft, AniCraft, DeckCraft |
| `NEXTEST_BIN_EXE_<name>` lookups | 13 | DeckCraft, SoundCraft 2, EffectCraft 4, FilmCraft, LightCraft, PhotoCraft 2, VectorCraft 2 |
| MCP stdio clients in CLI tests | 12 repositories | CADCraft, DeckCraft, DesignCraft, EffectCraft, FigCraft, FilmCraft, GridCraft, LightCraft, PdfCraft, PhotoCraft, SoundCraft, VectorCraft |
| Seeded test PRNGs (`next`, `below`) | about 75 files | craft-libs 35, GridCraft 7, FigCraft 7, FilmCraft 5, LightCraft 5 and 8 more |
| `ProptestConfig` uses | about 90 | craft-libs 32, VectorCraft 29, LightCraft 9 and 6 more |
| egui_kittest input helpers (`fn click`, `drag`, `key`, `type_text` and others on `&mut Harness`) | about 730 in about 410 files | 17 repositories; PhotoCraft 232, EffectCraft 169, GridCraft 110 |
| UI screenshot folder variables | about 47 names | FilmCraft, MaterialCraft, TextureCraft, EffectCraft, PhotoCraft, craft-launcher, PdfCraft, craft-libs |
| `fn psnr` | about 41 | craft-libs 17, FilmCraft 12, LightCraft 6, EffectCraft 5, PhotoCraft 1 |
| Hand-written RIFF/WAVE fixtures | about 20 | FilmCraft, EffectCraft, DeckCraft, SoundCraft |
| Test files with a hand-written `%PDF-1.x` header | about 310 | PdfCraft 209, craft-libs 34, VectorCraft 33, DesignCraft 15 and 7 more |
| Thread-local warning capture (`test_log.rs`, blob `745ce21fe1`) | 4 identical, 4 inline | WordCraft (`crates/doc`, `crates/formats`), craft-libs (`docx`, `wordmodel`) |
| Process-wide warning capture through a `log::Log` impl | 1 | SoundCraft (`crates/clap-host/tests/editor_main_thread.rs:18-30`, a `static WARNINGS: Mutex<Vec<String>>`) |
| Font family renaming for test fonts | 5 | VectorCraft, DesignCraft, WordCraft |
| Pinned corpus lists | Affinity 3 (different contents), PngSuite 2 (different contents), RAF 2 (identical) | PhotoCraft, VectorCraft, craft-libs, LightCraft |
Skip-or-fail variables of one shape (skip a test when something is missing, fail it when a variable
is set) exist for programs, GPUs, corpora, fixtures and craft-fonts: `FILMCRAFT_REQUIRE_ORACLES`,
`PDFCRAFT_ORACLES_REQUIRED`, `CRAFT_PDF_ORACLES_REQUIRED`, `CRAFT_MEDIA_REQUIRE_ORACLES`,
`FILMCRAFT_REQUIRE_GPU`, `EFFECTCRAFT_REQUIRE_GPU`, `PHOTOCRAFT_REQUIRE_GPU_TESTS`,
`PDFCRAFT_TEST_REQUIRE_GPU`, `LIGHTCRAFT_CORPUS_REQUIRED`, `PHOTOCRAFT_CORPUS_STRICT`,
`CADCRAFT_CORPUS_STRICT`, `AFFINITY_CORPUS_REQUIRED`, `CRAFT_AEP_FIXTURES_REQUIRED`,
`CRAFT_CRW_REQUIRE_SAMPLES`, `CRAFT_PRINT_REQUIRE_QUEUE` and `CRAFT_FONTS_REQUIRED`. The copies read
"set" five ways: any value including `0` (`pdfcraft-oracle` `lib.rs:33-39` and its craft-libs port),
`1`, `true`, `yes` or `on` (`craft-media-testkit` `lib.rs:76-77`, `filmcraft-testkit` `oracle.rs:95-96`),
exactly `1` (`craft-fonts-build` `lib.rs:12` and `embed.rs:183`, GridCraft
`crates/ui-egui/src/craft_fonts_policy.rs:58`, FilmCraft `crates/text/build.rs:23`), anything but empty
or `0` (Craft Anything `crates/ui-egui/build.rs:56`), and any value except `0`, empty included
(VectorCraft `crates/affinity/tests/support/corpus.rs:12`). DeckCraft,
FigCraft and WordCraft read `CRAFT_FONTS_REQUIRED` at compile time with `option_env!` (for example
DeckCraft `crates/fonts/src/tests.rs:345-350`), and GridCraft reads it through a constant its build
script writes (`crates/ui-egui/build.rs:52-55`).
### xtask crates
Seventeen Craft repositories have an `xtask/` crate. AniCraft has none, and craft-libs has no xtask,
build-tool or lint crate; outside the Craft repositories only the egui and wgpu forks have one. Open
storytold/craft-libs#9 adds a root `xtask` package to craft-libs.
| Command | Copies | State |
|---|---|---|
| `ci` step runner | 8 plus 2 | Identical from `let mut done = Vec::new();` to the end in CADCraft, DeckCraft, DesignCraft, GridCraft, PhotoCraft, VectorCraft and WordCraft (`xtask/src/main.rs`); craft-launcher differs by 2 lines. MaterialCraft and TextureCraft have their own runner (`cmd_ci`). |
| `layers` | 5 families | The class-based engine is in 9 repositories; from `check()` to `describe()` CADCraft differs from DesignCraft by 1 line, VectorCraft 3, DeckCraft 4, WordCraft 5, LightCraft 8, PhotoCraft 9, PdfCraft 34, GridCraft 45. EffectCraft, FilmCraft, SoundCraft and Craft Anything use a flat table that flags only a dependency on a higher layer. FigCraft allows listed same-layer pairs. MaterialCraft and TextureCraft map crates by folder. AniCraft checks layers in `src/architecture_tests.rs`. |
| `version` | 15 | Blob `8c4c1fc3` in CADCraft, craft-launcher, DeckCraft, DesignCraft, GridCraft, LightCraft and WordCraft; blob `b2f31b20` in MaterialCraft and TextureCraft; 6 other variants. |
| `ico` | 15 | Nine copies differ only in the committed-icon test path, and SoundCraft's also differs in `run`'s signature (`&[String]`) and a doc comment; VectorCraft and Craft Anything share blob `795a792f`; craft-launcher, MaterialCraft and TextureCraft also pack `.icns`. |
| `assets` | 6 plus 2 | CADCraft, DesignCraft, VectorCraft, DeckCraft, WordCraft and GridCraft share the functions; LightCraft and PdfCraft have their own checkers. The extension lists hold 19 to 41 entries. |
| Display-name scanner | 8 plus 1 | `display_names.rs` integration tests in AniCraft, CADCraft, DeckCraft, FigCraft, GridCraft, LightCraft, PhotoCraft and WordCraft; VectorCraft has `cargo xtask brands`. |
| Pinned downloads with SHA-256 | 6 | LightCraft (`sha2`), VectorCraft and PhotoCraft (hand-written `sha256.rs`, 42 diff lines apart), DesignCraft and WordCraft (no hash), craft-libs (`scripts/fetch-affinity-corpus.sh`). |
| `stats` | 8 | Blob `f40b1300` in PhotoCraft and VectorCraft; the other six diverged when each fixed the same directory walk (storytold/craft-libs#138). |
| `pdf-deps` | 4 | VectorCraft, DesignCraft, EffectCraft and DeckCraft pin `craft-pdf` to four different craft-libs revisions: `9be9a637`, `40525913`, `47107f66` and `63196e66`. |
The craft-common-actions `gate.yml` sets up the runner and runs `cargo xtask ci` (`:15-19`), checks
that `Cargo.lock` did not change (`:337-340` at `5b4eeb2323`, read again on 2026-11-15), sets `CRAFT_FONTS_DIR` and, when the caller asks,
`CRAFT_FONTS_REQUIRED=1` (`:183-187`). It does not define the gate's steps.
### Shared homes that exist
- `craft-ui` ships `craft_ui::testing` (`Screens`, `ime_events`, `compose`) behind its `screen-testing`
feature and `docking::testing::DockDriver` behind `testing` (`crates/ui/Cargo.toml:53`, `:56`). No app
enables either feature. DeckCraft, FigCraft, PhotoCraft, DesignCraft and VectorCraft each build IME
preedit events with their own `fn preedit`.
- `craft-audio` exports `pcm_wav_file`, `pcm_wav_header` and `wav_float_header` behind `pcm-encode`
(`crates/audio/src/lib.rs:110-123` at `7ad4765ee5`, and `:101-106` at the revisions FilmCraft,
EffectCraft, SoundCraft and DeckCraft pin), and all four depend on `craft-audio`.
- `craft-tiff` exposes `writer::IfdBuilder` (`crates/tiff/src/writer.rs:21`), and `craft-psd` exposes
`builder::PsdBuilder` (`crates/psd/src/builder.rs:212`) with fixtures behind `testgen`. Both exist at
the revision PhotoCraft pins.
- `craft-pdf` has a port of the `pdfcraft-testkit` `Pdf` builder in `cos/testkit.rs`, declared
`#[cfg(test)] pub(crate)` (`crates/pdf/src/cos.rs:23-24`), so no other crate can use it.
- `craft-fonts-build` embeds craft-fonts from an app's `build.rs`. Thirteen apps and Craft Anything
instead read `CRAFT_FONTS_DIR` in their own `build.rs` (`fn craft_fonts` in PhotoCraft
`crates/text/build.rs:66`, LightCraft `crates/engine/build.rs:64` and twelve more, all listed in the
`craft-fonts-build` row of RFC-0036 in storytold/craft-contrib#56), and the apps reach
`craft-fonts-build` only through `craft-ui`.
- craft-libs exposes test helpers under seven names today: `test-support` (`craft-zip`, `craft-opc`,
`craft-wordmodel`, `craft-sf2`), `testgen` (`craft-psd`), `testdata` (`craft-heif`), `test-writer`
(`craft-pst`), `testing` and `screen-testing` (`craft-ui`), always-public hidden modules
(`#[doc(hidden)] pub mod testing` in `craft-xlsx` `lib.rs:63-64`, `craft-ods` `lib.rs:33-34` and
`craft-xls` `lib.rs:49-50`), and a test-only private module (`craft-pdf`).
- `craft-plate-test` holds print-color test scenes in craft-libs, and craft-prepress uses it. It stays
where it is.
## The family
| Part | Holds | Dependencies | wasm32 |
|---|---|---|---|
| `craft-testkit` | Core modules for every test: folders, skips, programs, fixtures, locks, binaries, deadlines, growth checks, random input, hostile input, test fonts and source guards | `std`; `tempfile` 3 for `temp` | `growth`, `rng`, `fonts`, `hostile`'s mutators and `guards` (except `rust_sources`) build for `wasm32-unknown-unknown`; the rest is native only |
| `craft-testkit` features | `image`, `prop`, `corpus`, `mcp`, `log`, `geom` | `png` 0.18, `proptest`, `sha2`, `serde_json`, `log`; `craft-geom` and `kurbo` for `geom` | `image` builds for wasm32 |
| `craft_ui::testing` | Headless egui input, screenshot folders, and the existing IME and dock helpers | egui and egui_kittest, behind `screen-testing` | Native only |
| Format crates' `test-support` | Fixture writers for the formats each crate reads | The crate's own dependencies | As the crate |
| `craft-xtask` | `cargo xtask` command functions configured by each app's policy | `serde_json` for `layers` and `pins` (`cargo metadata`) and `runner`'s JSON report, as in the DesignCraft, VectorCraft, DeckCraft and SoundCraft `xtask/Cargo.toml`; behind the optional `fetch` feature, `sha2` and `craft-testkit` with `corpus`, as LightCraft's `xtask/Cargo.toml` takes `sha2`, with the system `curl` and `tar` that DesignCraft's download runs today. `version`, `icon`, `assets`, `names` and `stats` use `std` only; craft-launcher's `jiff` and `semver` are not used by its `icns.rs`, `ico.rs` or `version.rs` and are not carried | Native only |
The parts depend on each other in one direction:
- `craft-testkit` depends on no craft-libs crate except `craft-geom`, and only through the `geom`
feature.
- `craft-geom`, `craft-pathops` and `craft-trace` use the `geom` feature only from integration tests
under `tests/`, never from `#[cfg(test)]` unit tests. A unit test that took it would build a second
copy of `craft-geom` whose types do not match the crate under test.
- `craft-media-testkit` depends on `craft-testkit`.
- `craft_ui::testing` and the format crates' `test-support` modules do not depend on `craft-testkit`.
- `craft-xtask`'s `fetch` feature depends on `craft-testkit` with the `corpus` feature, for the manifest
parser that `fetch` shares with `corpus`.
The "Comes from" and "First consumers" columns of the module tables below, and the sources and first
consumers named under "UI test support in craft-ui" and "Test fixtures in the format crates", are a
non-normative record as of 2026-11-14. Each crate's README keeps the current Origin and Migration
tables (see "Admission" under "Rules for every crate").
## craft-testkit
Apps and craft-libs crates take `craft-testkit` under `[dev-dependencies]`. `craft-media-testkit` and
`craft-xtask`'s `fetch` feature take it as a normal dependency. An `xtask` may also take it as a normal
dependency, as FilmCraft's does with `filmcraft-testkit` and PdfCraft's with `pdfcraft-oracle`.
### Core modules
| Module | Contents | Comes from | First consumers |
|---|---|---|---|
| `temp` | `TempDir`: a folder made by `tempfile::Builder` with a tag prefix and a random suffix, mode 0o700 and an owner check on Unix, removed with its contents on drop, also when the test panics. A folder it did not make is never emptied or reused. The symlink and owner checks apply to the created folder, not to the components of `std::env::temp_dir()`, and `TempDir::path()` returns the canonicalized path, so a test that compares paths sees `/private/var` on macOS (storytold/vectorcraft#6859). The module's tests include a temp root reached through a symlink. `TempDir::file(name)` joins a file name. | VectorCraft `crates/testkit/src/lib.rs` (checks); `craft-media-testkit` `private_dir()`; CADCraft `tests/support/temp_dir.rs`; the `ScratchDir` of storytold/pdfcraft#6124 | LightCraft, PdfCraft, PhotoCraft, WordCraft, CADCraft, FigCraft, MaterialCraft, DeckCraft, VectorCraft, `craft-media-testkit` |
| `skip` | `skip(reason, required_var)` prints the skip line and returns when the variable is unset or empty, fails the test when it is `1`, and fails the test with a message naming the variable and the accepted value `1` for any other value. `or_skip!` binds a value or returns under the same rule. `craft_fonts(present: bool, required: bool)` takes both values from the caller. Today every first consumer passes its own build constant or `option_env!` value (PhotoCraft `crates/text/build.rs:66`, LightCraft `crates/engine/build.rs:64`, DeckCraft `crates/fonts/src/tests.rs:345-350`, GridCraft `crates/ui-egui/build.rs:52-55`), and a repository that switches to `craft-fonts-build` passes the `present` and `required` values from that crate's generated table instead. `craft_fonts_cover(text)` checks coverage as GridCraft's `font_setup.rs:266` does. | LightCraft `lib.rs`; `pdfcraft-oracle` `or_skip!`; FilmCraft `require_*!` macros; `craft-media-testkit` `skip()`; GridCraft `crates/ui-egui/src/theme/font_setup.rs:222-266` | LightCraft, PdfCraft, FilmCraft, DeckCraft, EffectCraft, PhotoCraft, CADCraft, DesignCraft, GridCraft, VectorCraft; craft-libs `aep`, `crw` and `print` tests |
| `oracle` | `find(program, version_arg)`: an explicit path from a variable (a wrong path is an error), then `PATH` with `.exe` on Windows, then known install folders. `find_in(path_var, path_list)` keeps FilmCraft's injectable form for the module's own tests. Results are cached per process with the version. The version output is read up to a byte limit. `ffmpeg_supports_format` and `require_ffprobe!` come along. | `craft-media-testkit` `lib.rs`; FilmCraft `oracle.rs:41`, `:147-181`; `pdfcraft-oracle` `lib.rs:127` | `craft-media-testkit`, `pdfcraft-oracle`, `filmcraft-testkit`, EffectCraft (`crates/opusenc/tests/it/ffmpeg.rs:12-16` and 13 test files that call ffmpeg or ffprobe), SoundCraft (`crates/video/src/tests.rs:327-332`); craft-libs `crates/pdf/tests/cos/oracle.rs` |
| `fixtures` | A collision-free sibling temporary path, publication by rename that reuses a complete concurrent winner, `generate` and `generate_with` under the required-program rule, and `FIXTURE made`, `cached` and `skipped` lines. The root comes from a variable or `<workspace>/target/fixtures`. | FilmCraft `fixtures.rs:56-89` (winner reuse); `craft-media-testkit` `lib.rs:274-289` (required rule) | FilmCraft, EffectCraft (`crates/media/tests/it/footage.rs:19-84`), `craft-media-testkit`; craft-libs `crates/video/tests/vp8/common/mod.rs:75-78` and `crates/audio/tests/codecs/testkit.rs` |
| `serial` | `TestLock`, a const-constructible lock (`static L: TestLock = TestLock::new(); let _g = L.hold();`) that recovers from poisoning and can be held again by the thread that holds it. `gpu_lock()` is one predefined instance, and `hold_gpu_lock()` keeps it until the thread ends. | PhotoCraft `crates/testkit/src/gpu.rs`; DeckCraft `crates/ui-egui/src/gpu_lock.rs`; EffectCraft `crates/ui-egui/tests/it/gpu_test.rs:3-7` and `crates/gpu/src/tests.rs:193-206` (thread-held); PdfCraft `apps/pdfcraft/src/tests.rs:48-53` (poison recovery) | PhotoCraft, DeckCraft, EffectCraft, PdfCraft, WordCraft, LightCraft, AniCraft; the test locks of VectorCraft, CADCraft, FilmCraft and the other repositories in "Helpers copied" |
| `bin` | `bin_path!(name)` expands in the calling test and reads `NEXTEST_BIN_EXE_<name>` with underscores, then with hyphens, then the runtime `CARGO_BIN_EXE_<name>`, then Cargo's compile-time value. A test run from an extracted nextest archive gets the extracted path from `NEXTEST_BIN_EXE_<name>`, and a compile-time path that no longer exists fails the test with a message that names the variables read, instead of OS error 2. The case of storytold/craft-common-actions#225 (storytold/pdfcraft#7173 closed on the same point) is one of the module's tests. `run(path, args, env, max_output) -> Output` runs it and returns an error when stdout or stderr exceeds `max_output` bytes, a limit with a documented default. | SoundCraft `apps/soundcraft-cli/tests/common.rs:7-9` (both spellings); VectorCraft `apps/vectorcraft-cli/tests/it/main.rs:12-15` (runtime lookup) | SoundCraft, VectorCraft, EffectCraft, FilmCraft, LightCraft, PhotoCraft, DeckCraft; the `run` and `cli` helpers in CADCraft, DeckCraft, FilmCraft, GridCraft, PdfCraft, SoundCraft, TextureCraft and WordCraft |
| `deadline` | `with_deadline(limit, label, f)` runs `f` on its own thread and fails the test with the label when the limit passes. `wait_until(limit, what, cond)` polls a condition. Both read an optional limit variable that the caller names. | FilmCraft `deadline.rs:19-23`; `craft-media-testkit` `with_deadline`; PhotoCraft `crates/ui-egui/src/canvas/paint_thread_tests.rs:45` (`wait_until`) | LightCraft (`crates/engine/src/demo/tests.rs:31`), GridCraft (`crates/math/src/lib.rs:675-687`), FilmCraft, Craft Anything (`standin_tools/tests.rs:38`), `craft-media-testkit`; `wait_until` in PhotoCraft, EffectCraft, FilmCraft and LightCraft |
| `growth` | `assert_linear(what, n, make, count)` builds inputs with `make(n)` and `make(scale * n)` (making them is not counted), counts the steps of a run on each with the caller's `count` closure, fails when the run at `n` counted no steps, and fails when the larger input took more than the limit times the steps. `assert_linear` uses WordCraft's scale of 8 and limit of 12 (`1.5 * SCALE`) as documented defaults, and `assert_linear_with(Linear { scale, limit }, what, n, make, count)` takes both as parameters, as `fixtures` pairs `generate` with `generate_with`. It fails the test for a scale below 2 or a limit of `scale * scale` or more, which could not tell a linear walk from a quadratic one. The step counters stay in each crate (WordCraft `crates/doc/src/work.rs` and `crates/layout/src/work.rs`, VectorCraft's `*_WORK` thread-locals in `crates/pathops/src/addons/cleanup.rs`). It counts steps and reads no clock. | WordCraft `assert_linear_steps` (`crates/layout/src/tests/linear.rs:26-33`, `SCALE = 8` at `crates/layout/src/tests.rs:854`, wordcraft `bc0e51ee4d`) | WordCraft (`wordcraft-layout`, `wordcraft-doc`), VectorCraft (`pathops`) |
| `rng` | `XorShift64` (`x ^= x << 13; x ^= x >> 7; x ^= x << 17`) and `XorShift64Star`, each seeded, with `next`, `below`, `byte` and `fill`. A suite that switches keeps the generator it uses today, so its inputs do not change. | FilmCraft `crates/dnx/tests/it/fuzz_hostile.rs:9-20` (xorshift64, `next` and `below`) and its craft-libs port `crates/video/tests/dnx/fuzz_hostile.rs`; craft-libs `crates/jpeg/tests/mutation.rs:28-46` (xorshift64\*, with `byte`) | craft-libs `video` (nine `fuzz_hostile.rs` suites) and `jpeg` (`tests/mutation.rs`), FilmCraft, GridCraft, FigCraft |
| `hostile` | `hammer(bytes, parse)`: every truncation, seeded byte flips and extreme-value overwrites, each run under `catch_unwind` and `with_deadline`, with a run-count multiplier read from a variable the caller names. | `craft-media-testkit` `hostile.rs` | CADCraft (`crates/fonts/src/shx/tests.rs:254-272`), TextureCraft (`crates/formats/src/mesh_import/tests.rs:419-435`), craft-libs `mesh` (`src/tests.rs:20`), `craft-media-testkit` |
| `fonts` | `rename_family(bytes, from, to)` for equal-length names in the UTF-16BE and ASCII name records, and `collection(faces)`, which builds a TTC. The caller supplies the font bytes. The source `rename` asserts that the names have the same length (`:66`), and `collection` indexes the table directory without bounds checks (`:92-96`). `rename_family` returns an error for names of different lengths, and `collection` returns an error for a face shorter than its table directory, each with a test. | VectorCraft `crates/text/src/tests/sysfonts.rs:64-101` (`rename` and `collection`) | VectorCraft (`text` and `testkit`), DesignCraft (`crates/fonts/src/fontdb/tests/sysfonts.rs:68`), WordCraft (`crates/fonts/src/fontdb/tests/sysfonts.rs:11-16`, `crates/fonts/src/fontdb/user/tests.rs:6`) |
| `guards` | `predefined_quit`, `wgsl_float_literals`, `std_instant` and `rust_sources`. | storytold/craft-libs#1373, which supersedes storytold/craft-libs#163 and keeps zachshallbetter's commit | PhotoCraft and FilmCraft, which replace their own copies (`crates/gpu/src/tests.rs:233`; `crates/engine/src/wasm_clock_tests.rs:10-46`); EffectCraft (`crates/gpu/src/tests.rs:970`); CADCraft (`predefined_quit` finds `apps/cadcraft/src/native_menu.rs:61`); `rust_sources` in DesignCraft, PhotoCraft, WordCraft and Craft Anything |
### Feature modules
| Module | Contents | Comes from | First consumers |
|---|---|---|---|
| `image` (`png` 0.18) | RGBA8 and gray views; differing pixels, maximum and mean absolute difference, p99 and PSNR; `psnr(a, b, peak)` for u8 and u16 planes; a tolerance with a neighborhood option; a diff image; a bless variable the caller names; failure images in a folder the caller names; and `assert_similar!`, the one form that fails a test. A missing reference fails the test unless the bless variable is set. | FilmCraft `golden.rs`; AniCraft `crates/engine/tests/golden/mod.rs`; `pdfcraft-oracle` `pixels.rs`; VectorCraft `raster.rs` (comparison only); DesignCraft `crates/render/tests/it/effects.rs:47-61`; EffectCraft `crates/export/tests/it/hevc_encoder.rs:57` (u16 PSNR) | FilmCraft, AniCraft, PdfCraft, VectorCraft, DesignCraft; `psnr` in EffectCraft, LightCraft and craft-libs `video`, `image-codecs` and `raster-codecs` tests |
| `prop` (`proptest`) | `config(cases)`, which pins the seed unless `PROPTEST_RNG_SEED` is set, lets `PROPTEST_CASES` override the count and turns failure persistence off. | VectorCraft `crates/pathops/tests/common/mod.rs:11-18` | VectorCraft (`engine` `import_fuzz` and `plugin_fuzz`, `pathops`), craft-libs, LightCraft, FilmCraft, SoundCraft, PhotoCraft, PdfCraft, WordCraft, FigCraft |
| `corpus` (`sha2`) | `pinned(var, manifest) -> Option<PathBuf>`: the folder a variable names, with every listed file checked against its SHA-256, under the skip-or-fail rule. `Manifest` parses the one manifest format of the family: one tab-separated line per file (`sha256`, path, and optional license and URL columns, as in `corpus.tsv`), with `#` comment lines. `craft-xtask`'s `fetch` reads manifests with the same parser. | craft-libs `crates/affinity/tests/support/corpus.rs:18` | craft-libs `affinity` and `raw`, LightCraft (`crates/raw/tests/it/corpus.rs:1185`), PhotoCraft (`crates/io/tests/it/corpus.rs:430`), CADCraft (`crates/io/src/roundtrip/tests.rs:506`), VectorCraft (`crates/affinity/tests/support/corpus.rs`) |
| `mcp` (`serde_json`) | `McpChild::spawn(path, args, env)`, `initialize(version)`, `notify`, `request(method, params)` matched by id, `call_tool(name, args)` and `close` with the exit status. Each read is bounded by `deadline`, and each line by a length limit. | craft-ai-integrations `crates/ai-mcp/src/apps/child.rs` (`Conn`, `request`, `call_tool`, `MAX_LINE`, deadlines) and its 14 tests in `child_tests.rs`; VectorCraft `apps/vectorcraft-cli/tests/it/mcp_e2e.rs:77-84`; PhotoCraft `apps/photocraft-cli/tests/it/cli.rs:1224-1230` | The 12 repositories in "Helpers copied"; all of them send protocol version `2025-06-18` today. craft-ai-integrations keeps `child.rs`, which is production code, and the `mcp` pull request ports the cases of `child_tests.rs` to `craft-testkit` |
| `log` (`log`) | `warnings(f) -> (T, Vec<String>)` and `records(level, f)`, captured per thread, and `capture_global(level)`, which installs one logger for the whole process and returns a handle whose `drain()` takes the records logged on every thread. `log::set_logger` can be called once per process, so one test binary uses either the per-thread capture or `capture_global`, and the second to be installed returns an error. | `test_log.rs` (WordCraft `crates/doc/src/test_log.rs`, identical in `crates/formats` and craft-libs `docx` and `wordmodel`); SoundCraft `crates/clap-host/tests/editor_main_thread.rs:18-41` (process-wide) | WordCraft, craft-libs `docx` and `wordmodel`, and SoundCraft through `capture_global`: `editor_main_thread.rs` is a `harness = false` binary that installs its own logger (`:41`) and checks a warning logged on a spawned `audio` thread (`:99-101`) |
| `geom` (`craft-geom`, `kurbo`, `proptest`) | Proptest strategies for paths and shapes, and geometry assertions such as Hausdorff closeness. | VectorCraft `crates/testkit/src/strategies.rs` and `crates/testkit/src/geom.rs`; RFC-0030's `crates/testkit` (wdunn001/craft-libs branch `shared-geometry-crates`, `799a7d8604`: `geom.rs` and `strategies.rs`) | VectorCraft and FigCraft, which RFC-0030 names as consumers; the tests of RFC-0030's `craft-geom`, `craft-pathops` and `craft-trace` |
### guards
storytold/craft-libs#139 proposes source guards for three platform rules that several apps broke.
zachshallbetter's storytold/craft-libs#163 implements them as `crates/testkit`, package `craft-testkit`.
storytold/craft-libs#1373 supersedes #163: it keeps his commit with its authorship and adds fixes after
it. The guards are:
- `predefined_quit(files)` lists calls of muda's `PredefinedMenuItem::quit` outside comments
(storytold/designcraft#544, storytold/filmcraft#1943). `craft_quit::QUIT_MENU_ID`
(`crates/quit/src/close.rs:20-26`) replaces the call.
- `wgsl_float_literals` and `wgsl_float_literals_in` list WGSL decimal and hexadecimal float literals
outside `f32`'s finite range, and literals with an `h` suffix outside `f16`'s, from PhotoCraft's
scanner (storytold/photocraft#1982, storytold/photocraft#2023).
- `std_instant(files)` lists lines that name `std::time::Instant` outside comments, with FilmCraft's
rule, and accepts lines under a non-wasm `cfg` (storytold/filmcraft#230). GridCraft enforces the same
rule with clippy (`clippy.toml:9-11`) and keeps that configuration.
- `rust_sources(dir)` lists a crate's `.rs` files without its test files and build output.
Each app calls the guards from one test and keeps its file lists, its exceptions and its clippy
configuration. Rules that ast-grep can express can also run through the craft-common-actions
`actions/ast-grep` action.
### deadline after the LightCraft stack
storytold/lightcraft#3083 adds `crates/testkit/src/deadline.rs` (`time_scale`, `scaled`, `wait_until`,
`wait_until_at_least`, `recv_within`, `LIGHTCRAFT_TIME_SCALE`) and `watchdog.rs`, which prints the tests
still running, exits with code 124 and calls `std::process::abort` 10 seconds later. It has no
`with_deadline`. storytold/lightcraft#3096, #3657, #3722 and #3733 build on it. All four are drafts, and
#3657, #3722 and #3733 conflict with `main`. #3083 adds `deadline.rs` with 243 lines, and at the head of
#3733, which carries the whole stack, the file has 298 lines. After
the stack merges, `deadline` takes `time_scale`, `scaled`, `recv_within` and the watchdog from the
merged result, and `with_deadline` and `wait_until` start scaling their limits by a time-scale variable
the caller names.
### Variables and printed lines
Each function that reads an environment variable takes the variable's name from the caller and has a
`CRAFT_` default. `prop::config` reads proptest's own `PROPTEST_RNG_SEED` and `PROPTEST_CASES`, and
`bin_path!` reads the `NEXTEST_BIN_EXE_<name>` and `CARGO_BIN_EXE_<name>` variables that nextest and
Cargo set. Each app passes the names it uses today, such as `FILMCRAFT_REQUIRE_ORACLES`,
`FILMCRAFT_BLESS`, `FILMCRAFT_HOSTILE_TIMEOUT_SECS`, `PDFCRAFT_ORACLES_REQUIRED`, `UPDATE_GOLDENS`,
`DESIGNCRAFT_BLESS`, `CRAFT_MEDIA_REQUIRE_ORACLES`, `CRAFT_MEDIA_HOSTILE_MULT` and
`CRAFT_TEST_TIMEOUT_SECS`. The printed lines that an xtask reads keep their format: FilmCraft's
`cargo xtask fixtures` reads the `FIXTURE` lines, and LightCraft's `xtask/src/ci_report.rs` reads the
skip log that `lightcraft-testkit` keeps writing on top of `skip`.
A required variable has three readings. Unset or empty means skip. `1` means required, as
`craft-fonts-build` reads `CRAFT_FONTS_REQUIRED` and as `gate.yml` sets it. Any other value fails with a
message that names the variable and the accepted value, so a value such as `true`, `yes` or `0` that a
copy read as required today fails loudly instead of turning into a skip. That reading changes behavior in `pdfcraft-oracle`
and its craft-libs port (any value), `filmcraft-testkit` and `craft-media-testkit` (`1`, `true`, `yes`
or `on`), VectorCraft's Affinity corpus (any value except `0`), Craft Anything's `build.rs` (anything
but empty or `0`), and the `build.rs` readers that test `var_os("CRAFT_FONTS_REQUIRED").is_some()`:
DeckCraft `crates/fonts/build.rs:53`, LightCraft `crates/engine/build.rs:16`, PdfCraft
`crates/fonts/build.rs:21`, VectorCraft `crates/text/build.rs:27`, FigCraft `crates/text/build.rs:25`,
PhotoCraft `crates/text/build.rs:30`, DesignCraft `crates/fonts/build.rs:16`, WordCraft
`crates/fonts/build.rs:23` and `:29`, CADCraft `crates/fonts/build.rs:21` and TextureCraft
`crates/ui-egui/build.rs:35`. Test and xtask code reads variables the same way: `CRAFT_FONTS_REQUIRED`
in PhotoCraft `crates/ui-egui/tests/it/camera_raw_localization.rs:132`, DesignCraft
`crates/fonts/src/fontdb/scoped.rs:462` and `crates/ui-egui/src/canvas/tests.rs:2889`, and LightCraft
`xtask/src/web.rs:56`, and `PHOTOCRAFT_CORPUS_STRICT` in PhotoCraft `crates/io/tests/it/corpus.rs:430`.
FilmCraft's `crates/text/build.rs:23` already reads exactly `1`. Each of these repositories changes its
reading in its own pull request and checks that its workflows set the variable to `1`. The one value that
goes from failing to skipping is an empty one, in the readers that count an empty value as set
(`pdfcraft-oracle` and its port, VectorCraft's Affinity corpus and the `var_os(...).is_some()`
readers), so each such pull request lists every workflow and local setting that sets the variable to an
empty value.
craft-testkit has no helper that changes the process environment. No test in the Craft repositories
calls `std::env::set_var` (the one call, VectorCraft `apps/vectorcraft/src/cursor_theme.rs:142`, is app
code). A test that needs a variable runs the program as a child, and `bin`, `mcp` and `fixtures` take
an environment list for that child.
## UI test support in craft-ui
`craft_ui::testing` holds the test support that needs egui. It gains two modules behind `screen-testing`:
- `input`: `move_to`, `press`, `release`, `click`, `drag(from, to, steps, modifiers)`,
`key(key, modifiers)`, `type_text` and `wheel`, generic over `Harness<State>`. They are filled from
PhotoCraft's `crates/ui-egui/src/canvas/paint_mouse/tests.rs:42` and EffectCraft's
`crates/ui-egui/tests/it/ui_text_edit.rs:33-59`. `DockDriver` drives its own egui `Context` with
`RawInput` and has no `Harness`, so its `window_click` and `window_hold`
(`crates/ui/src/docking/testing.rs:247-256`) stay as they are. First consumers: PhotoCraft and
EffectCraft, then GridCraft.
- `snapshot`: `snapshot_dir(var) -> Option<PathBuf>`, a builder step that turns wgpu on only when a
folder is set, and `save(&mut Harness, dir, name)`. The caller names the variable, and
`CRAFT_UI_SNAPSHOT_DIR` is the default. The module writes screenshots for review and compares
nothing. It takes its code from FilmCraft `crates/ui-egui/tests/it/export_ui.rs:34-40` (the variable
and the wgpu step) and `:110-115` (the save), and from the `snapshots` functions that read
`CRAFT_UI_PANES_SNAPSHOT_DIR` in FilmCraft `crates/ui-egui/tests/it/ui_dock_resize.rs:22`, `:53-57`
and EffectCraft `crates/ui-egui/tests/it/ui_dock_resize.rs:13`, `:42-45` (`e4ab3c6a99`,
`f029bbadb2`). FilmCraft (`FILMCRAFT_UI_SNAPSHOT_DIR` in 25 files) and EffectCraft (`EC_SNAPSHOT_DIR`
and 19 other names) are its first consumers.
Apps switch their `fn preedit` builders to `ime_events` and `compose`, and their dock tests to
`DockDriver`. Every app except PdfCraft, AniCraft and Craft Anything patches egui_kittest to
storytold/egui rev `6d518fc799`. PdfCraft pins rev `725a39fca9` (`Cargo.toml:183`), AniCraft takes
`egui = "0.36"` from crates.io and has no egui_kittest dependency (`Cargo.toml:59`), and Craft Anything
takes `egui = "0.36"` and `egui_kittest = "0.36"` from crates.io with no storytold/egui patch
(`Cargo.toml:40-42`). Each of the three moves to the shared revision before it takes the `input`
module.
More UI test helpers for accessibility follow RFC-0014 (storytold/craft-contrib#21) and
storytold/craft-libs#437 in the same module.
## Test fixtures in the format crates
Every craft-libs crate that exposes test-only fixture writers puts them in `pub mod testing` under
`cfg(any(test, feature = "test-support"))`. Writers that are part of a crate's public API, such as
`craft_tiff::writer`, `craft_psd::builder` and `craft-audio`'s `pcm-encode` exports, keep their paths
and features. The move:
- `craft-pdf` exposes `cos::testkit::Pdf` as `craft_pdf::testing::Pdf` behind `test-support`.
`pdfcraft-testkit` re-exports it and deletes its own builder. VectorCraft's and DesignCraft's
object-level PDF fixtures move to it. Fixtures that need RC4 encryption (VectorCraft `pdf.rs`) or a
broken cross-reference table stay in the apps until the builder has them.
- `craft-psd` renames `testgen`, `craft-heif` renames `testdata` and `craft-pst` renames `test-writer` to
`test-support`. Each keeps the old name as an alias until every repository that enables it has
switched: PhotoCraft enables `craft-psd`'s `testgen` (`crates/automation/Cargo.toml:59`,
`crates/io/Cargo.toml:71`, `crates/ui-egui/Cargo.toml:80`), LightCraft enables `craft-heif`'s
`testdata` (`crates/codecs/Cargo.toml:52`, `crates/engine/Cargo.toml:69`, `crates/meta/Cargo.toml:21`),
craft-libs `crates/psd/Cargo.toml:29` enables `testgen` for the crate's own tests, and no repository
enables `craft-pst`'s `test-writer`. A later pull request per crate removes the alias. Each crate's
tests pass with the old name and with `test-support`. `craft-xlsx`, `craft-ods` and `craft-xls` gate
their `testing` modules (`crates/xlsx/src/lib.rs:63-64`, `crates/ods/src/lib.rs:33-34`,
`crates/xls/src/lib.rs:49-50`) under `cfg(any(test, feature = "test-support"))`, the form
`gridcraft-xlsx` uses (`crates/xlsx/src/lib.rs:35-36`, `crates/xlsx/Cargo.toml:14` at `c2aba7a3f4`).
Their integration tests under `tests/` call `testing` today, so each crate enables the feature for
them through a dev-dependency on itself, as `craft-psd` does for `testgen`. `craft-ui` keeps
`testing` and `screen-testing` as the names for UI drivers.
- A well-formed TIFF or PSD fixture is built with `craft_tiff::writer` or `craft_psd::builder`.
PhotoCraft's orientation and EXIF headers (`apps/photocraft-cli/tests/it/orientation.rs`,
`crates/io/tests/it/orientation.rs`, `crates/engine/tests/it/jpeg_exif_resolution.rs`) and
VectorCraft's `crates/testkit/src/tiff.rs` (except `group3()`, its CCITT Group 3 case) move first.
- A plain PCM WAV fixture calls `craft_audio::pcm_wav_file`, and a float fixture uses
`craft_audio::wav_float_header`, with `pcm-encode` under `[dev-dependencies]`. FilmCraft's
`testkit/src/wav.rs` and the copies in EffectCraft, DeckCraft and SoundCraft move. Writers for
malformed or extensible headers (FilmCraft `crates/interchange/tests/it/wav_extensible.rs`,
EffectCraft `crates/host/tests/it/wav_markers.rs`) stay local.
- A format's pinned corpus list moves to the crate that reads the format: the Affinity list to
`craft-affinity`, which already holds `tests/support/corpus.tsv`; the RAF list to `craft-raw`, which
already holds the same blob as LightCraft (`0fd9572836`); and PngSuite to the PNG decoder's crate.
PhotoCraft's, VectorCraft's and `craft-affinity`'s Affinity lists (60, 53 and 53 entries) and
PhotoCraft's and VectorCraft's PngSuite lists (178 and 177 entries) are merged into one list each. The merged list is the union of the entries. Every list is written in the
`Manifest` format: `corpus.tsv` already has it, and the RAF list (`crates/raw/docs/raf-corpus.sha256`)
and the PngSuite lists (`xtask/pngsuite.sha256`), which use `sha256sum`'s `<sha256> <path>` lines,
are converted by replacing the two spaces with a tab, with their `#` lines kept. An entry whose name
appears with two different SHA-256 values stays out of the list until its source file is checked,
and the pull request lists each such conflict. Before an app switches to a merged list, its corpus
fetch downloads every entry of that list, so a corpus that holds all of the app's current entries is
not reported as incomplete because the union names more files. Each app's switch reports its corpus
tests' pass and skip counts before and after with the merged list.
## craft-xtask
`craft-xtask` is a library. Each app keeps its `xtask` binary, its step list and its app-only commands,
and calls the library with its own policy. Every layers table classifies `craft-xtask` as build
tooling, allowed only as a dependency of `xtask`.
| Module | Contents | Comes from | First consumers |
|---|---|---|---|
| `runner` | `Step { name, run }`, `run_steps` with the shared ok, FAIL and skip summary, `root`, `cargo`, `run(Command, label)` and `nextest_or_test`, which falls back to `cargo test` when nextest is absent. An opt-in lock held across processes and a JSON report are features. On Windows a running `xtask.exe` cannot be replaced while the workspace tests rebuild it (storytold/craft-common-actions#185), so the test steps exclude the `xtask` package from the tested workspace, and a separate step runs the `xtask` package's own tests with a `--target-dir` of their own, which does not replace the running executable. A test checks that the step list never rebuilds the running executable. | DesignCraft `xtask/src/main.rs:69-79`, `:204-247`; LightCraft `xtask/src/ci_lock.rs` and `ci_report.rs` | CADCraft, DeckCraft, DesignCraft, GridCraft, PhotoCraft, VectorCraft, WordCraft, craft-launcher; then MaterialCraft and TextureCraft |
| `layers` | The class-based engine configured by a `Policy` (crate table, same-layer rule `Allowed` or `Ordered`, UI crates and their lowest layer, exceptions, format pairs), and `wasm_set(policy)`. PdfCraft's sideways and standalone exceptions, PhotoCraft's `standalone_exception` and GridCraft's `FORMAT_ALLOWED` become policy fields. | DesignCraft `xtask/src/layers.rs:151` onward (CADCraft differs by 1 line) | CADCraft, DeckCraft, DesignCraft, WordCraft, VectorCraft; then the flat-table repositories with `same_layer: Allowed`; AniCraft, through the small xtask that "Faults in the current copies" adds, which replaces `src/architecture_tests.rs` |
| `version` | `cargo xtask version [set X.Y.Z]`, rejecting numeric parts that overflow u64 and numeric prerelease identifiers with a leading zero, moving the `version` of path dependencies in `[workspace.dependencies]`, and restoring `Cargo.toml` when `cargo update --workspace` fails. | SoundCraft `xtask/src/version.rs:51-121`; PdfCraft `xtask/src/version.rs:31-42`, test `:146` | All 15 repositories with a copy |
| `icon` | `ico::pack`, which refuses empty input, non-square images and sides of 0 or over 256 px; `icns::pack`; `png_size`. The committed-icon test takes the app's icon path. | DeckCraft `xtask/src/ico.rs` (same as CADCraft `:21-31`); craft-launcher `xtask/src/icns.rs` | The 15 repositories with a copy |
| `assets` | Every asset file needs a backticked row in `ASSETS.md`. One extension list (the union of the seven lists, plus `ttc` and `otc`) with a per-app `extra_ext`, and LightCraft's forbidden extensions and names as an option. | VectorCraft or DesignCraft `xtask/src/assets.rs`; LightCraft `xtask/src/assets.rs` | CADCraft, DesignCraft, VectorCraft, WordCraft, DeckCraft, GridCraft, LightCraft |
| `names` | A scanner of production string literals for display names a caller lists, with escapes decoded, plus VectorCraft's extra surfaces (`Cargo.toml` descriptions, `packaging/`, non-Markdown `docs/`, the `brand-ok` marker). Each repository's `display_names.rs` test calls it with its own `BANNED` and `ALLOWED` lists. RFC-0029 (storytold/craft-contrib#43) is the rule it enforces. | CADCraft `crates/ui-egui/tests/display_names.rs:109-115`; VectorCraft `xtask/src/brands.rs` | AniCraft, CADCraft, DeckCraft, FigCraft, GridCraft, LightCraft, PhotoCraft, WordCraft, VectorCraft |
| `fetch` | `fetch_pinned(dest, &[Pin { name, url, sha256, max_bytes }])`, which deletes a file whose hash does not match, bounded archive extraction, and manifests read with `craft_testkit::corpus::Manifest`. It uses `sha2`, and VectorCraft's and PhotoCraft's `sha256.rs` files are deleted. | LightCraft `xtask/src/corpus.rs:71-93`; DesignCraft `xtask/src/main.rs:251-350` (`expands_within`); VectorCraft `xtask/src/pngsuite.rs:10-134` | LightCraft, VectorCraft, PhotoCraft, DesignCraft, WordCraft |
| `stats` | Tests and lines of Rust per crate, without following directory links. Test items used only by the unix symlink test are imported under `cfg(unix)`, and craft-libs `workspace.yml` runs clippy on Windows (`:47-51`). | DesignCraft `xtask/src/stats.rs:21-23` | The 8 repositories with a copy |
| `pins` | `check(metadata, &[Pin { name, version, source, allowed_features, forbidden_packages }])` over `cargo metadata`. Each app keeps its table. | DeckCraft `xtask/src/pdf_deps.rs:10-78` and the other three copies | VectorCraft, DesignCraft, EffectCraft, DeckCraft |
craft-common-actions keeps runner setup, caching, nextest installation, the lockfile check and the
`git-sources` source-prefix check. `craft-xtask` holds what `cargo xtask ci` runs, locally and in
`gate.yml` alike.
## Rules for every crate
- **Required variables.** Each helper that reads a required variable treats an unset or empty value as
skip and `1` as required, and fails with a message naming the variable and the accepted value for any
other value. "Variables and printed lines" lists the copies whose reading changes.
- **Dependency kind.** Apps and craft-libs crates take `craft-testkit`, `craft-ui`'s test features and
the format crates' `test-support` under `[dev-dependencies]`. `craft-media-testkit`, `craft-xtask`'s
`fetch` feature and an app's `xtask` take `craft-testkit` as a normal dependency. `craft-xtask` is a
dependency of `xtask` only. An app with a testkit class in `xtask/src/layers.rs` adds `craft-testkit` to it in its adoption
pull request; GridCraft, FigCraft, MaterialCraft and TextureCraft add the class (or take
`craft_xtask::layers`) in theirs. DesignCraft, DeckCraft, CADCraft and WordCraft keep their testkit
class.
- **Panics.** Setup functions return a `Result`. Failing a test happens only in macros that expand in
the caller (`or_skip!`, `require_ffprobe!`, `assert_similar!`, `bin_path!`) and in `with_deadline`,
`wait_until`, `skip` with a required variable, `skip::craft_fonts` with a required value,
`corpus::pinned`, `fixtures::generate` and `generate_with` under the required rule, and
`hostile::hammer` and `growth::assert_linear` and `assert_linear_with`, each of which carries a documented `#[allow(clippy::panic)]`.
The crate root otherwise copies the `deny` attribute of Rust house rule 1
(`standards/house-rules-rust.md`).
- **Clock.** No helper returns elapsed time for a test to assert on. `deadline` uses the clock only to
stop work that does not finish. Tests of the crates use handshakes, and randomized tests use a fixed
seed.
- **Limits.** Every input read from disk, from a download or from a child process has a size limit that
is a parameter with a documented default: the width, height and byte count of a PNG in `image`, the
line length in `mcp`, the output size in `bin::run` and in `oracle`'s version probe, and `max_bytes`
and the entry count in `fetch`. An input over a limit returns an
error, as `craft_mesh::Limits` does.
- **Network.** No module of `craft-testkit` opens a connection. Downloads are made by `craft-xtask`'s
`fetch`.
- **Lints.** `#![forbid(unsafe_code)]` and `[lints] workspace = true`, as `craft-media-testkit`'s
manifest has.
- **Licenses.** Every dependency is on the house-rules license allowlist as it stands. `tempfile`,
`png`, `proptest`, `sha2`, `serde_json` and `log` are already dependencies of craft-libs crates or of
the apps. `craft-xtask` takes `serde_json` and, through `fetch`, `sha2`, which the apps' `xtask`
manifests already name. The allowlist is the one RFC-0027 (storytold/craft-contrib#41) sets.
- **Admission.** Each module's README row names at least two Craft applications that consume it, as
craft-libs `AGENTS.md:61` requires and as open RFC-0009 (storytold/craft-contrib#10) proposes. Each
crate's README has an Origin table (source repository, path and SHA of each module's code) and a
Migration table (each consumer and the state of its switch), and names a responsible maintainer or
team, agreed in the review of its first craft-libs pull request.
- **One revision.** Each adoption pull request moves all of the repository's craft-libs git
dependencies to the one revision that holds the new code, so `Cargo.lock` holds one copy of each
craft-libs crate. Every git dependency comes from a storytold repository; the `git-sources` job in
craft-common-actions `release.yml` fails on any other git source.
- **CI.** craft-libs `workspace.yml` runs clippy and the tests of every crate with and without
`--all-features` (`:42-53`). A new crate adds no workflow. The parts of `craft-testkit` that the
family table marks native only (`temp`, `skip`, `oracle`, `fixtures`, `serial`, `bin`, `deadline`,
`hostile::hammer`, `guards::rust_sources`, and the `prop`, `log`, `geom`, `corpus` and `mcp`
features) are under
`cfg(not(target_arch = "wasm32"))`. Its wasm32 check is a row in craft-libs `formats.yml` that builds
the default features plus `image`, added by a separate pull request (house rule 11). `craft-xtask`
has no wasm32 row. craft-libs `ui.yml` tests `craft-ui` with `--all-features` (`:55`), which covers
`craft_ui::testing`.
## Faults in the current copies
This list is a non-normative record as of 2026-11-14, like "What exists". The shared code holds the fixed form of each of these. Each repository takes the fix in its own pull
request with a test that fails without it, as item 3 of "How the code moves" says, before or after its
switch.
- 12 of the 15 `version set` copies accept a prerelease that Cargo rejects, such as `1.0.0-01` and
`1.0.0-rc.01` (CADCraft `xtask/src/version.rs:51-52` and the copies with the same blob). Only
VectorCraft (`:146`), PhotoCraft (`:153`) and SoundCraft (`:189`) test it. Open
storytold/pdfcraft#6188 (MMexicann) fixes PdfCraft's copy, and the count becomes 11 of 15 when it
merges. Open storytold/photocraft#10189 (Lucenx9) makes PhotoCraft's copy reject version parts that
overflow. 14 copies leave `Cargo.toml` changed when the following `cargo update --workspace` fails;
SoundCraft (`:114-121`) restores it.
- VectorCraft's and Craft Anything's `ico::pack` accepts non-square images and images with a 0 px side,
and it writes a 0 px width as 0, which the `.ico` format reads as 256 px (VectorCraft
`xtask/src/ico.rs:26-31`).
- The display-name scanners in LightCraft (`crates/ui-egui/tests/display_names.rs:97`), FigCraft
(`crates/mcp/tests/display_names.rs:97`) and PhotoCraft (`crates/ui-egui/tests/display_names.rs:117`)
read the `"` of `'\"'` as the start of a string, so a banned name after such a literal is not seen.
- WordCraft's `cargo xtask corpus --download` fetches PngSuite over plain HTTP and extracts it without a
size limit, an entry limit or a hash check (`xtask/src/main.rs:268-297`). DesignCraft fetches the same
URL with limits and no hash check.
- `cargo xtask stats` follows directory links in PhotoCraft and VectorCraft (`xtask/src/stats.rs:21`)
and GridCraft (`:45`).
- The `stats` tests in WordCraft (`xtask/src/stats.rs:113`) and GridCraft (`:146`) import `walk` and
`Counts` for all targets, while only the unix symlink test uses them, so
`cargo clippy --all-targets -- -D warnings` fails on Windows. Open pull requests fix it one copy at a
time: storytold/wordcraft#6247 (NibrasAz7) and #6235 (dkhlapov), and storytold/gridcraft#1803
(derechopiano), which carries `#[cfg(unix)] use super::{Counts, walk};`. CADCraft fixed the same
import on `main` in storytold/cadcraft#2198, and smacdmac101's open storytold/cadcraft#2288, #2281,
#2277, #2271 and #2231 carry that fix as well.
- LightCraft's `cargo xtask` help says `corpus --download` fetches PngSuite (`xtask/src/main.rs:66-67`),
and `cmd_corpus` downloads only the raw samples and the D750 ColorChecker set
(`xtask/src/corpus.rs:37-66`).
- `holders_take_turns` in PhotoCraft (`crates/testkit/src/gpu.rs`) and DeckCraft
(`crates/ui-egui/src/gpu_lock.rs`) sleeps 2 ms. `craft-media-testkit`'s `hostile::run_one` asserts
each run takes under 5 s (`hostile.rs:27-33`). `serial` and `hostile` replace these with a handshake
and `with_deadline`.
- `pdfcraft-oracle` says its any-value rule matches `CRAFT_FONTS_REQUIRED` (`lib.rs:33-39`), and
`craft-fonts-build` reads only `1` (`lib.rs:12`).
- VectorCraft turns proptest failure persistence off and still has
`crates/pathops/proptest-regressions/planar/tests.txt`. craft-libs has ten committed proptest
regression files, LightCraft has four, SoundCraft has three, and PhotoCraft, DesignCraft, FilmCraft and
PdfCraft have six more. Under `prop`, a failing case becomes a
named regression test, and each adoption pull request turns the repository's committed cases into
tests.
- AniCraft's gate runs `cargo test` and clippy only (`.github/workflows/ci.yml:31`). No AniCraft
workflow runs `cargo fmt --check`, and AniCraft has no `ASSETS.md` while `assets/app-icon/` holds PNG,
SVG and `.ico` files. A small AniCraft xtask on `craft_xtask::runner`, `assets` and `layers` adds these
steps.
## How the code moves
Each move is made in three kinds of pull request:
1. A craft-libs pull request adds the code with the tests of the code it comes from.
2. One pull request per repository switches it to the shared code and deletes its copy. The tests the
repository keeps pass and skip as before, each moved test passes in craft-libs under the same name,
and the pull request lists both sets with their counts. The variable names the repository uses do
not change. An xtask switch shows that `cargo xtask ci` runs the same steps with the same results,
and an `ico` switch compares the written `.ico` with `cmp`.
3. A change of behavior, such as a required variable's reading, CADCraft's `TempDir` (which empties a
leftover folder of the same name; `temp` leaves it in place and makes a new one), DesignCraft's
golden that writes a missing reference and passes, a seeded suite that changes generator, or a fault
listed above, is its own pull request. Each such pull request includes a test that fails without the
change and lists the tests or gate steps whose result changes. A switch of a flat-table repository
to `layers` lists every new violation the shared engine reports, with an exception or a fix for
each. A change to a required variable's reading names each workflow and local setting whose result
changes: each that now fails instead of skipping, each value that now fails with the message about
the accepted value, and each empty value that now skips instead of failing. A switch to the shared `assets` list lists every file that the union list newly flags,
with the `ASSETS.md` row or the exclusion it adds for each. A switch to `prop::config` names each
suite whose seed changes from random to pinned, and keeps a variable or a CI step that still runs
that suite with random seeds. A switch to `names` lists every literal that the shared scanner newly
flags, with the `ALLOWED` entry or the fix for each. A switch to `stats` reports the per-crate counts
before and after.
The craft-libs pull requests go in this order:
1. `craft-testkit` with `guards`, from storytold/craft-libs#1373. It supersedes
storytold/craft-libs#163, which conflicts with `main`, as FredApps noted in a review comment on
2026-11-01. #1373 keeps zachshallbetter's commit from #163 with his authorship.
2. The core modules, one pull request each: `temp`, `skip`, `serial`, `bin`, `deadline` (`with_deadline`
and `wait_until`), `growth`, `oracle`, `fixtures`, `rng`, `hostile`, `fonts`.
3. The feature modules: `image`, `prop`, `log`, `corpus`, `mcp`.
4. `craft_ui::testing::input` and `snapshot`.
5. The format crates' `test-support` renames and `craft-pdf`'s `testing::Pdf`, one crate per pull request.
6. `craft-xtask`, one module per pull request, `runner`, `layers`, `version` and `icon` first.
7. `craft-media-testkit` built on `craft-testkit`, with its public names unchanged and `hostile`
re-exported. This pull request changes code the media reviewers checked in storytold/craft-libs#701,
and its author requests reviews from alehel and FredApps. craft-media, craft-cfb, craft-audio and
craft-video report unchanged pass and skip counts, with `CRAFT_MEDIA_REQUIRE_ORACLES=1` where their
workflow sets it (`media.yml:83`, `audio.yml:162`). Among the testkit folders, the path filters of
`media.yml`, `audio.yml` and `video.yml` name only `crates/media-testkit/**` (`:6`, `:8` in each).
They also match `Cargo.toml` and `Cargo.lock`, so the pull request that adds `crates/testkit`
starts all three, but a later change to `crates/testkit/**` alone does not. A CI-only pull request
(house rule 11) adds `crates/testkit/**` to those path filters.
8. `deadline`'s time scale and watchdog, after the LightCraft stack merges.
9. The `geom` feature, after RFC-0030 (storytold/craft-contrib#46) is accepted.
The repository pull requests start with the near-identical copies: CADCraft's two `TempDir` files, the
repositories with the identical `ci` runner or `version.rs`, and DesignCraft and DeckCraft for
`layers`. FilmCraft's switch also moves `crates/codecs/src/tests.rs:10-28` and
`crates/ui-egui/examples/bench/fixtures.rs:15-18` onto `oracle` and `fixtures`. VectorCraft's switch
includes the two `TempFolder` copies in `crates/mcp/src/tests.rs:51` and
`crates/mcp/tests/common/mod.rs:9-28` and the three `TestDir(tempfile::TempDir)` wrappers. PhotoCraft's
includes `crates/gpu/tests/it/main.rs:5`.
## What stays in the apps
- **App fixtures and models.** VectorCraft's document fixtures, invariants, `render_*` helpers, `ai.rs`,
`ase.rs`, `suitcase_fork` and `group3()`; PhotoCraft's `Sweep`, `perf` and the wgpu instance that
storytold/photocraft#10865 keeps alive; FilmCraft's `cuts.rs` and the golden `.attribution` sidecar;
LightCraft's skip log, its `Need` enum and `crates/ui-egui/src/tests/fixtures.rs`; PdfCraft's XFA
fixtures and the `ScratchFile` of open storytold/pdfcraft#6124; FigCraft's server sessions and
`.sketch` fixtures; EffectCraft's `.aep` helpers and QA harness; AniCraft's `.fla` packer;
WordCraft's `crates/doc/src/work.rs`; SoundCraft's CLAP and VST3 fixture plugins; Craft Anything's
samples; and fixtures that are malformed on purpose.
- **App xtask commands.** The step list of each `cargo xtask ci`, the checklist commands that RFC-0018
(storytold/craft-contrib#30) and RFC-0033 (storytold/craft-contrib#52) cover, `i18n-report`, whose
missing-translation report can move to craft-i18n's `craft-i18n-tests` or craft-libs `i18n`,
LightCraft's `ci --quick`, EffectCraft's `ci --affected` and PdfCraft's license checker.
- **Text snapshots.** `FILMCRAFT_BLESS` text fingerprints, GridCraft's `NUMFMT_BLESS` and PdfCraft's
`UPDATE_SNAPSHOTS` stay in their repositories.
- **Private temporary folders in shipped code.** PdfCraft `crates/ocr/src/tesseract.rs:519` and Craft
Anything `crates/engine/src/tools/java_decompile_tools.rs:58` and `crates/engines/src/ghidra/mod.rs:413`
cannot use a test-support crate. A non-test home for them, such as `craft-atomic`, is a candidate below.
## Candidates for later RFCs
The apps also duplicate runtime code for which craft-libs has no crate. Each item lists its copies
(repository and path, at the SHAs in "What exists"), the copy whose file and test files hold the most
`#[test]` functions, two first consumers, and the open pull requests in its area. Each item can become
its own crate RFC in the shape of this one. This RFC does not decide any of them. Runtime code that
craft-libs already has a crate for is the subject of RFC-0036 (storytold/craft-contrib#56).
| Candidate | Copies | Source (tests) | First consumers |
|---|---|---|---|
| App control channel | `apps/<app>/src/control_server.rs` in VectorCraft, PhotoCraft, DesignCraft, LightCraft, FilmCraft, EffectCraft, GridCraft, WordCraft, DeckCraft, SoundCraft, CADCraft, FigCraft, MaterialCraft and TextureCraft | FilmCraft (22) | WordCraft (19) and CADCraft (13) |
| MCP stdio server | `crates/mcp/src/server.rs` in VectorCraft, DesignCraft, LightCraft, GridCraft, WordCraft, DeckCraft, CADCraft and FigCraft; EffectCraft `crates/automation/src/server.rs`; PdfCraft and SoundCraft `crates/automation/src/mcp.rs`; AniCraft `crates/cli/src/mcp.rs`; Craft Anything `crates/mcp/src/lib.rs`; craft-ai-integrations `crates/ai-mcp/src/mcp.rs` | PdfCraft (6) | SoundCraft and AniCraft |
| Browser downloads in web builds | `web.rs` under `apps/<app>-web/src/` in VectorCraft, PhotoCraft, DesignCraft, LightCraft (also `safety.rs`), GridCraft, WordCraft, DeckCraft, SoundCraft and FigCraft; FilmCraft `apps/filmcraft-web/src/fs.rs`; EffectCraft `apps/effectcraft-web/src/files.rs`; PdfCraft `crates/ui-egui/src/editing/save.rs` and `workflows/web_print.rs`; CADCraft `apps/cadcraft-web/src/download.rs`; AniCraft `src/web.rs`; MaterialCraft and TextureCraft `crates/ui-egui/src/web_files.rs` | MaterialCraft (7) | DeckCraft and SoundCraft |
| macOS open-documents handler | `apps/<app>/src/apple_events.rs` in PhotoCraft, DesignCraft, EffectCraft, PdfCraft, GridCraft, WordCraft, DeckCraft and FigCraft; VectorCraft `apps/vectorcraft/src/open_documents.rs` | FigCraft (1, in `apple_events_tests.rs`) and VectorCraft (1) | PhotoCraft and DesignCraft |
| Single instance | `apps/<app>/src/single_instance.rs` in PdfCraft, PhotoCraft and VectorCraft; craft-launcher `crates/native/src/single_instance.rs` | PhotoCraft (15) | PdfCraft (11) and VectorCraft (10) |
| Window graphics startup | VectorCraft `apps/vectorcraft/src/gpu.rs`; PhotoCraft `apps/photocraft/src/gpu_startup.rs`; DesignCraft `apps/designcraft/src/gpu.rs`; LightCraft `apps/lightcraft/src/window_gpu.rs`; `apps/<app>/src/graphics.rs` in FilmCraft, GridCraft, WordCraft, DeckCraft, SoundCraft, CADCraft and FigCraft; EffectCraft and PdfCraft `apps/<app>/src/main.rs`; AniCraft `src/startup.rs`; TextureCraft `apps/texturecraft/src/gpu.rs`; craft-launcher `apps/artcraft-launcher/src/main.rs`; Craft Anything `apps/craft-anything/src/main.rs` | VectorCraft (39) | CADCraft and DeckCraft |
| Document autosave and recovery | VectorCraft `crates/ui-egui/src/recovery.rs`; PhotoCraft `crates/format/src/autosave.rs`; `crates/engine/src/recovery.rs` in DesignCraft, WordCraft, DeckCraft and AniCraft; `crates/engine/src/autosave.rs` in FilmCraft, SoundCraft and CADCraft; EffectCraft `crates/engine/src/settings/autosave.rs`; PdfCraft `crates/ui-egui/src/persist/recovery.rs`; FigCraft `apps/figcraft/src/recovery.rs`; TextureCraft `crates/formats/src/project_file/recovery.rs` | DesignCraft (84) | DeckCraft and WordCraft |
| WebAssembly plug-in host | VectorCraft and PhotoCraft `crates/plugins`, AniCraft `crates/plugins`, EffectCraft and FigCraft `crates/plugin` | VectorCraft (172) | PhotoCraft and AniCraft |
| Recent files | VectorCraft `crates/ui-egui/src/io/open.rs`; PhotoCraft and DeckCraft `crates/ui-egui/src/app/files.rs`; DesignCraft `crates/engine/src/lib.rs` (`MAX_RECENT_FILES`); FilmCraft `crates/engine/src/settings/schema.rs`; EffectCraft `crates/engine/src/settings/prefs/recent.rs`; PdfCraft `crates/ui-egui/src/state.rs`; GridCraft `crates/ui-egui/src/backstage.rs`; WordCraft `crates/ui-egui/src/lib.rs`; SoundCraft `crates/ui-egui/src/dialogs/recent.rs`; CADCraft `crates/ui-egui/src/lib.rs`; FigCraft `crates/engine/src/cmd/file/open.rs`; AniCraft `crates/engine/src/cmds_recent.rs`; MaterialCraft `crates/ui-egui/src/state/ui_state.rs` | AniCraft (5, in a module of its own) | SoundCraft and FigCraft |
| Display ICC profile | PhotoCraft `apps/photocraft/src/monitor_profile.rs`; VectorCraft `apps/vectorcraft/src/display_profile.rs`; LightCraft `apps/lightcraft/src/screen_profile.rs` and `win_screen_profile.rs` | PhotoCraft (7) | VectorCraft and LightCraft |
| UI clock | `crates/ui-egui/src/clock.rs` in LightCraft and EffectCraft (`AppClock` with a manual override), and in VectorCraft, DesignCraft, GridCraft, WordCraft, DeckCraft and FigCraft (monotonic milliseconds only) | EffectCraft (no tests in the file) | LightCraft and DesignCraft |
| Private temporary folders in shipped code | PdfCraft `crates/ocr/src/tesseract.rs`; Craft Anything `crates/engine/src/tools/java_decompile_tools.rs` and `crates/engines/src/ghidra/mod.rs` | PdfCraft (24) | PdfCraft and Craft Anything |
- **App control channel.** Each copy is a loopback listener the MCP process talks to, with bounded line
reads, a request queue to the UI thread and a reply timeout (228 to 707 lines). Seven authenticate
with a per-run token or key file (CADCraft, FilmCraft, GridCraft, MaterialCraft, PhotoCraft,
TextureCraft, WordCraft), and seven accept any local connection on the port (DesignCraft, EffectCraft,
DeckCraft, FigCraft, LightCraft, SoundCraft, VectorCraft). DesignCraft's and EffectCraft's copies
differ in 15 lines with the same eight tests. craft-libs has no crate. The `crates/ipc` crate of open
storytold/craft-libs#616 (see "Single instance") has a server (`src/server/`), a client
(`src/client.rs`) and `src/auth.rs`.
- **MCP stdio server.** Thirteen apps hand-write initialize with version negotiation, `tools/list` and
`tools/call`; all thirteen support `2025-06-18`, `2025-03-26` and `2024-11-05`. VectorCraft also
negotiates `2026-07-28` in `initialize` (`crates/mcp/src/server.rs:22-23`), and LightCraft
(`crates/mcp/src/server.rs:248`) and EffectCraft (`crates/automation/src/server.rs:281-285`) accept
clients that declare `2026-07-28` per request in `_meta`.
PhotoCraft, FilmCraft, MaterialCraft and TextureCraft use `rmcp`. MaterialCraft's and TextureCraft's
`budgets.rs`, `bridge.rs` and `security.rs` are near copies of PhotoCraft's. craft-ai-integrations
`crates/ai-mcp/src/mcp.rs` (`e8b31cb059`) is a fourteenth hand-written server; it supports
`2025-06-18` and `2025-11-25` (`:13`) and none of the older versions. craft-libs has no crate. Open
storytold/craft-libs#248 (Jeremy8776, draft) plans native MCP readiness for the apps, and open RFC-0016
(storytold/craft-contrib#23) proposes a hosted connector with its own MCP endpoint.
- **Browser downloads in web builds.** Each copy makes a Blob, an object URL, a hidden `<a download>`
and a timed revoke, with revoke delays of 5, 10 or 60 seconds and its own MIME table. DeckCraft's and
SoundCraft's copies differ only in the MIME table. `craft-web-host` has a host-save hook and no
download helper. RFC-0023 (storytold/craft-contrib#39) sets out a web runtime for the apps, and this
candidate is left to it.
- **macOS open-documents handler.** The nine apps queue the files that Finder sends in an
open-documents event.
`craft-platform` has no handler.
- **Single instance.** PdfCraft, PhotoCraft and VectorCraft pass a second launch's files to the running
app, and craft-launcher tells the running copy to show its window (533 to 751 lines each). craft-libs
has no crate. Open storytold/craft-libs#616 (bigwolfeman, CONFLICTING) adds a `crates/ipc` crate with
`src/activate.rs` and `src/auth.rs`, which also bears on the app control channel.
- **Window graphics startup.** Each copy sets up wgpu for the app window. CADCraft's, DeckCraft's and
SoundCraft's `graphics.rs` are near copies. `craft-window` does not use wgpu.
- **Document autosave and recovery.** `craft-settings` `recovery.rs` keeps only damaged settings files.
Open storytold/craft-libs#713 (dooreelko) lets a web host report that it stores saves in place
(`crates/web-host`).
- **WebAssembly plug-in host.** Each copy builds a wasmi 2 host with fuel metering; PhotoCraft's engine
configuration line appears in AniCraft unchanged. None of the five uses the craft-extensions
`craft-ext-core` manifest crate. craft-libs `main` has no host. Open craft-libs pull requests by
bigwolfeman add one, and all of them conflict with `main`: storytold/craft-libs#432
(`craft-plugin-abi`), #454 (`craft-plugin-host` engines: wasmi, with optional wasmtime and browser
engines), #455 (the guest SDK), #613 (the host layer), #615 (`craft-plugin-ui`) and #616 (`craft-cli`,
with `crates/ipc`).
- **Recent files.** The lists have different caps (10 in SoundCraft and AniCraft, 20 in FigCraft, 30 in
VectorCraft, 50 in WordCraft, up to 100 in DesignCraft) and different missing-file checks. craft-libs
has no crate.
- **Display ICC profile.** The copies look up the profile of the display that shows the window.
`craft-cms` has no lookup.
- **UI clock.** `craft-time` holds media time only.
- **Private temporary folders in shipped code.** These are the folders listed under "What stays in the
apps". `craft-atomic` exists and holds file writes only.
The per-app geometry crates are not candidates. MaterialCraft's and TextureCraft's `crates/geom` are
one forked crate, and RFC-0032 (storytold/craft-contrib#50) proposes moving it into `craft-mesh-ops`.
The other twelve apps' `crates/geom` are separate domain models (VectorCraft's and DesignCraft's share
only `snap.rs`) and stay in the apps; a four-point homography solve exists in VectorCraft, LightCraft,
PdfCraft and PhotoCraft.
## Defaults this RFC takes
1. **Names.** RFC-0030 (storytold/craft-contrib#46) proposes a crate also named `craft-testkit` for
geometry assertions and proptest strategies (wdunn001/craft-libs branch `shared-geometry-crates`,
`crates/testkit`, depending on `craft-geom`, `kurbo` and `proptest`). This RFC adds those helpers as a
`geom` module of the same crate behind a `geom` feature. Whichever RFC's crate lands first creates
`craft-testkit`, and the other adds its modules to it. Whichever of RFC-0030 and RFC-0035 lands
first, the geometry code sits behind the `geom` feature, so `craft-testkit`'s default build depends
on no craft-libs crate. `craft-xtask` is the name
storytold/craft-libs#138 uses.
2. **One crate with features.** `craft-testkit` is one crate, and a module with a dependency sits behind
a feature.
3. **craft-media-testkit.** It stays, with its public names. storytold/craft-libs#701 removed an earlier
`craft-testkit` that only wrapped it (alehel,
<https://github.com/storytold/craft-libs/pull/701#issuecomment-6721885995>). Each module of this
`craft-testkit` holds moved code with its tests, and `craft-media-testkit` is rebuilt on it in its own
later pull request.
4. **UI support.** Test helpers that need egui go in `craft_ui::testing`, and `craft-testkit` has no egui
dependency. UI screenshots use egui_kittest's own snapshots or `snapshot`, and `image` adds no second
UI snapshot mechanism.
5. **GPU.** `serial` orders tests on real devices and does not replace `craft-gpu-null`, which RFC-0022
requires every GPU consumer to run against in CI. `craft-testkit` has no wgpu dependency.
6. **Temporary folders.** `temp` wraps `tempfile`, which FilmCraft's testkit and storytold/filmcraft#4681
already use, and adds the mode and owner checks. RFC-0015's `confine` crate keeps its escape tests and
may use `temp` in them.
7. **Required variables.** Unset or empty means skip, `1` means required, and any other value fails
with a message naming the variable and the accepted value.
8. **Testkit layer class.** The class stays in DesignCraft, DeckCraft, CADCraft and WordCraft, and
`craft-testkit` fills it. This settles the question storytold/designcraft#1980 leaves open.
9. **storytold/craft-libs#115.** Its testkit entry names a corpus manifest, large-file fixtures and a
mutation-fuzz helper. They map to `corpus` (from `craft-affinity`'s loader; storytold/filmcraft#429
closed unmerged), `fixtures` and `hostile`.
10. **Host-supplied fonts.** Open RFC-0034 (storytold/craft-contrib#54) asks every build that adopts it
to pass acceptance tests "from shared fixtures", and it changes what "craft-fonts present" means for
wasm32 builds. Its shared font fixtures go in `craft-testkit::fonts` or in a font crate's
`test-support`, and the values that native test runs pass to `skip::craft_fonts` follow it if it is
accepted.
11. **Out of scope.** Font, CFF, Type 1 and ICC builders in open pull requests (storytold/pdfcraft#6733,
#6840, #6977, #7281, #2777, #3028; storytold/deckcraft#874; storytold/cadcraft#1587) wait until one
merges and a second app has a merged copy. The four different `craft-pdf` revisions in the `pins`
tables are for the PDF crate's maintainers to settle.
12. **Other contributors' work.** This RFC changes no open pull request. A switch whose source files an
open pull request changes merges with that pull request or waits for it. The pull request lists in
this item and in item 11 are a non-normative record as of 2026-11-14. storytold/pdfcraft#6124,
#5923, storytold/filmcraft#4681, storytold/photocraft#13266 and storytold/texturecraft#254 make test
folders private, and each repository switches to `temp` after its pull request merges.
storytold/photocraft#10865, storytold/filmcraft#3805 and storytold/lightcraft#3519 change GPU test
serialization or skip logging. storytold/filmcraft#2835 and #1952 change FilmCraft's oracle
code, and FilmCraft's switch merges with them or waits. storytold/filmcraft#1794 stays open as its
author left it. storytold/designcraft#1984 and #2000 are left as they are. The LightCraft stack from
storytold/lightcraft#3083 is the source of `deadline`'s later part.
storytold/craft-libs#504 (el-j, a draft closed without merging) added a `crates/testkit` package
named `craft-testkit` whose `lib.rs` re-exported `craft_media_testkit` and added `skip(what, reason)`,
and a `.github/workflows/testkit.yml` that ran fmt, clippy, the tests and a wasm32 check on Ubuntu
and Windows, with ffmpeg installed on Ubuntu. Its wrapper and `testkit.yml` are not carried forward:
`craft-testkit` comes from storytold/craft-libs#1373 (which supersedes #163) and the modules this
RFC lists.
storytold/photocraft#14595 (davidmann4), merged on 2026-11-15, made `gpu_lock()` keep a wgpu Vulkan
instance on Linux, which adds a wgpu dependency to `photocraft-testkit`; on `main` at `dd768fcd7e`,
`crates/testkit/src/gpu.rs` holds the kept instance and `gpu_lock` is at `:36`. PhotoCraft's switch
keeps the kept instance in `photocraft-testkit` around `serial::gpu_lock`, as it does for
storytold/photocraft#10865. storytold/vectorcraft#7203 (dotCooCoo), merged on 2026-11-14, changed
`crates/testkit/src/strategies.rs`, the source of `geom`. Open app pull requests also change source
files this RFC moves:
- storytold/lightcraft#3710 (THEtheChad, draft) rewrites `xtask/src/ci.rs` (+144/-22), which runs
LightCraft's gate steps with `ci_lock` and `ci_report`, the sources of `runner`'s lock held across
processes and its JSON report.
- storytold/wordcraft#6247 (NibrasAz7) changes `xtask/src/stats.rs`.
- storytold/vectorcraft#1437 (EricKuck) adds `cargo xtask cleanroom` and changes
`xtask/src/brands.rs`, the source of `names`.
- storytold/lightcraft#3086 (THEtheChad, draft) changes `xtask/src/ci.rs`, `xtask/src/test.rs` and
`.config/nextest.toml`, and storytold/lightcraft#3079 (THEtheChad) changes `xtask/src/ci.rs` and
`xtask/src/test.rs`. Both change LightCraft's test caps, which `runner` takes in.
- storytold/filmcraft#4083 (vangel76) takes `NVENC_SERIAL` in every NVENC test, a consumer of
`serial`.
- storytold/designcraft#2549 (ForestParks) changes DesignCraft's MCP test fixtures in
`apps/designcraft-cli/tests/it/cli.rs`, a consumer of `mcp`.
- storytold/pdfcraft#6188 (MMexicann) makes PdfCraft's `xtask/src/version.rs` reject numeric
prerelease identifiers with a leading zero, and storytold/photocraft#10189 (Lucenx9, conflicting)
makes PhotoCraft's reject version parts that overflow. Both are existing fixes for faults that
`version` takes in. storytold/gridcraft#2784 (Harrison-Booth) and storytold/filmcraft#4615
(Neo-DannyDeTour) also change `xtask/src/version.rs`.
- storytold/pdfcraft#4764 (Harrison-Booth, conflicting) changes `crates/oracle/src/lib.rs` and its
README, the source of `oracle`.
- storytold/lightcraft#3099 and #3102 (THEtheChad, drafts) change `xtask/src/ci_lock.rs`, the source
of `runner`'s lock held across processes, and `xtask/src/ci.rs`. storytold/lightcraft#3654
(THEtheChad, draft), #3118 (THEtheChad) and #4167 (dylanmtaylor, conflicting) also change
`xtask/src/ci.rs`.
- storytold/lightcraft#3112 and #3110 (sm18lr88, conflicting) change `xtask/src/corpus.rs`, the source
of `fetch` (`:71-93`).
- storytold/effectcraft#3643, #3646, #3649, #3653 and #3671 (dylanmtaylor, drafts) change
`xtask/src/pdf_deps.rs`, a source of `pins`.
- storytold/vectorcraft#817 (Haven-King) changes `crates/testkit/src/strategies.rs`, the source of
`geom`.
- storytold/wordcraft#6235 (dkhlapov) and storytold/gridcraft#1803 (derechopiano) change the `stats`
tests, as #6247 does.
The `runner`, `stats` and `names` switches in LightCraft, WordCraft and VectorCraft merge with these
pull requests or wait for them, LightCraft's `runner` switch does the same for #3086, #3079, #3099,
#3102, #3654, #3118 and #4167, and `geom` takes `strategies.rs` as it stands on `main`, after #817.
PdfCraft's and PhotoCraft's `version` switches merge with storytold/pdfcraft#6188 and
storytold/photocraft#10189 or wait for them, and the `version` pull request in craft-libs credits
both as the existing fixes. GridCraft's and FilmCraft's `version` switches do the same for #2784 and
#4615, PdfCraft's `oracle` switch for #4764, LightCraft's `fetch` switch for #3112 and #3110,
EffectCraft's `pins` switch for its five `pdf_deps.rs` pull requests, and WordCraft's and
GridCraft's `stats` switches for #6235 and #1803.
storytold/craft-libs#1112 (dylanmtaylor), merged on 2026-11-14, locks the workflow actions in
`media.yml`, `audio.yml`, `video.yml`, `formats.yml` and other workflows through `actions.lock`. The
path filters of `media.yml`, `audio.yml` and `video.yml` are still at `:6` and `:8` (craft-libs
`828b07f3c9`), so the CI-only pull request of step 7 of the craft-libs order is unchanged.
Open craft-libs pull requests also change files that this RFC moves or gates:
- storytold/craft-libs#1309 (regendorf-ux) and #1277 (DesignsByRay) change `crates/pdf/src/cos.rs`,
where `cos::testkit` is declared (`:23-24`).
- storytold/craft-libs#1337, #1330, #1323, #1263 and #1166 (keithcsqueensu) change
`crates/xlsx/src/lib.rs`, whose `testing` module (`:63-64`) this RFC gates.
- storytold/craft-libs#1321 (dylanmtaylor) changes the cfg block of `crates/audio/src/lib.rs` next to
the `pcm-encode` exports.
- storytold/craft-libs#172 (adventurelands) moves `craft-ui` to egui 0.37, while the apps patch
egui_kittest to storytold/egui rev `6d518fc799`.
- storytold/craft-libs#9 (zachshallbetter) adds a root `xtask` package to craft-libs
(`members = ["crates/*", "xtask"]`) with its own `xtask/src/ci.rs` and `cargo xtask compat`.
`craft-xtask` is the library `crates/xtask` (package `craft-xtask`), separate from #9's root
`xtask` binary, and #9's `ci.rs` would call `craft_xtask::runner` once both exist.
- storytold/craft-libs#698 (whatever-industries, conflicting) changes
`crates/audio/tests/codecs/testkit.rs`, which the `fixtures` move rewrites.
Open craft-common-actions pull requests change `gate.yml`, whose lines this RFC cites:
storytold/craft-common-actions#124 (bmh129, conflicting) adds an optional cache for files the gate
downloads, and #220 (dylanmtaylor) locks the workflow actions through a lockfile. The `gate.yml`
line numbers in "What exists" are read again before the `runner` pull request.
The `test-support` pull requests for `craft-pdf` and `craft-xlsx` and the `fixtures` move of `crates/audio/tests/codecs/testkit.rs` merge with these pull requests or wait for
them. The `input` module follows whichever egui revision `craft-ui` has when it lands.
13. **Command-line conventions.** Open RFC-0012 (storytold/craft-contrib#18) has each CLI's `main` pass
its arguments and output streams to a library `run(args, out, err) -> exit code` that tests call
directly. It also has tests pin `--help`, exit codes 0, 1 and 2, and that a protocol subcommand
such as MCP writes nothing else to stdout. If RFC-0012 is accepted, `bin` adds a helper that checks
a child's exit code and streams against those rules, and `mcp` checks that the child writes only
protocol lines on stdout.
## What this RFC decides
- The family: `craft-testkit` and its modules and features, the `craft_ui::testing` additions, the
`test-support` rule for format crates, and `craft-xtask` and its modules.
- The boundaries: the one-way dependencies under "The family", and what stays in the apps.
- "Rules for every crate", including the reading of required variables.
- The three kinds of pull request in "How the code moves".
The inventories, the sources and first consumers of each part, the order of the craft-libs pull
requests and the lists of open pull requests are a record and a plan, not decisions. The new crates
under "Candidates for later RFCs" and the migrations of RFC-0036 (storytold/craft-contrib#56) are not
decided here.
The affected repositories are craft-libs and every Craft application with a copy listed above:
VectorCraft, PhotoCraft, DesignCraft, LightCraft, FilmCraft, EffectCraft, PdfCraft, GridCraft, WordCraft,
DeckCraft, SoundCraft, CADCraft, FigCraft, AniCraft, MaterialCraft, TextureCraft, craft-launcher and
Craft Anything.
Work on the parts after `guards` starts after this RFC is accepted. Per RFC-0000 this is a 3-day
comment period change.