Contributing
Testing
Two kinds of tests: C++ unit tests, and the cases, which run the built catter on small projects and compare every output with a snapshot.
# Run everything: build, unit tests and cases (RelWithDebInfo, or Debug)
pixi run -e dev test
# Unit tests only, on a build
pixi run -e dev unit-test
# Cases only, against the Debug build
pixi run -e dev cases-test DebugUnit Tests
Unit tests use the Kotatsu testing framework (kotatsu::zest). Located in unittests/, the structure mirrors src/:
unittests/command/-- Tests for command analysis (compiler identification, argument parsing, the option tables)unittests/protocol/,unittests/feature/-- Tests for the handler protocol and the built-insunittests/hook/-- Tests for the hook payloads
They build into unittests, and the hook payload's unittests-hook-unix or unittests-hook-windows, of the platform the build is for.
Each test binary runs its tests on a pool of worker processes, several at once, with a 60 second limit per test. A suite that uses a fixed file or directory name must run alone: mark it with ZEST_SUITE_ATTRS(serial = true);. To debug a test, run it in the binary's own process with --no-isolation --test-filter=<suite>.<test>; --help lists the other options.
Cases
Every test of catter's behavior is a case under tests/<topic>/<subtopic>/NN_name/: the inputs of a small project, an optional test.ts saying what to run, and a snap.toml holding every output the case pins. The runner (tools/testing/, TypeScript on vitest) runs the catter of a build, so the cases hold whatever builds catter and whatever language it is written in. tests/README.md is the contract: writing a case, the placeholders paths are normalized to, platform differences and known bugs.
# The cases under a path
CATTER_CASES=builds/make pixi run -e dev cases-test
# Accept the new outputs of the cases that changed; review the diff of snap.toml
UPDATE_SNAPSHOTS=1 pixi run -e dev cases-test
# Another catter than a build's
CATTER_EXECUTABLE=/path/to/catter pixi run -e dev pnpm --dir tests run casesCommit Message Format
Use conventional commits:
<type>(<scope>): <short description>Types: feat, fix, refactor, chore, build, docs, ci, test, perf, style, revert
Scopes should match source directories or feature names. Keep the subject line under 70 characters.
Code Style
- C++23 standard
- Use
.clang-formatfor C++ formatting - Use ESLint + Prettier for TypeScript
pixi run -e format formatformats every source file; CI fails on any change it makes
