Contributing

Testing

Three ways to run tests:

# Run everything (build + unit tests + integration tests)
pixi run -e dev test

# Unit tests only
pixi run -e dev unit-test

# Integration tests only
pixi run -e dev integration-test

Unit Tests

Unit tests use the Kotatsu testing framework (kota::zest). Located in tests/unit/, the structure mirrors src/:

• tests/unit/common/ -- Tests for shared utilities and option parsing
• tests/unit/catter/ -- Tests for core logic (compiler identification, JS runtime)
• tests/unit/catter-hook/unix/ -- Tests for Unix hook payload

To enable test targets in the build:

pixi run cfg  # or: xmake config --test=y

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.

Integration Tests

Integration tests use the LLVM Lit framework. Located in tests/integration/, they compile and run C++ test programs, using FileCheck for output verification.

# Run integration tests with verbose output
lit ./tests/integration -sav

Commit Message Format

Use conventional commits:

<type>(<scope>): <short description>

Types: feat, fix, refactor, chore, 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-format for C++ formatting
• Use ESLint + Prettier for TypeScript
• Pre-commit hooks are configured (.pre-commit-config.yaml)