Testing
The Karkain test suite validates the compiler, runtime, standard library and
toolchain on two engines — the Go front end and the self-hosted kcc
engine — with deterministic, reproducible results. This page explains the
structure and how to run each layer.
Go unit tests
Every pkg/*/... package has *_test.go files that run in-process
without invoking the compiler subprocess. Run the core packages with:
go test ./pkg/lexer/... ./pkg/parser/... ./pkg/codegen/... ./pkg/pm/... -count=1
go test ./pkg/ir/ssa/... ./pkg/sema/... ./pkg/source/... -count=1
On the documented 4 GB host, run single packages sequentially:
GOMAXPROCS=1 GOGC=60 go test ./pkg/lexer/... -count=1
GOMAXPROCS=1 GOGC=60 go test ./pkg/codegen/... -count=1
Conformance corpus
conformance/ contains 11 test files with 59 func test_*
functions:
001_arithmetic_test.kark
002_control_flow_test.kark
003_functions_test.kark
004_strings_test.kark
005_arrays_test.kark
006_structs_test.kark
007_maps_test.kark
008_algorithms_test.kark
009_phase81_regression_test.kark
010_array_returns_test.kark
011_namespace_test.kark
These run through the real front end + C runtime on both engines. The test driver ensures byte-identical stdout and exit codes on both engines.
E2E CLI tests
pkg/cli/*_test.go exercises the real CLI subprocess — karkain check,
karkain build, karkain run, karkain test, karkain fmt,
karkain lint, karkain debug, karkain prof, karkain target,
karkain lsp, karkain pkg. Every command is validated end-to-end
through actual process invocations.
Run the full CLI suite (large, allocate dedicated time):
go test ./pkg/cli/... -count=1
Phase-specific gate tests
Each major phase has a phase*_test.go gate that pins the behavior it
introduced. Examples:
pkg/cli/phase95_parity_test.go # kcc engine parity (Go + kcc goldens)
pkg/cli/phase100_runtime_test.go # runtime error model (parity)
pkg/cli/phase107_concurrency_test.go # concurrency runtime (E2E)
pkg/cli/phase108_cli_test.go # wasm32-wasi (E2E through wasmtime)
pkg/cli/phase123_cli_test.go # enum ADT parity + WASI boundary gate
pkg/cli/phase109_stdlib_test.go # standard library v2 (multi-module)
pkg/cli/phase110_profiling_test.go # karkain prof (text/json/folded)
pkg/cli/phase111_cross_compile_test.go # cross-compilation triples
All gate tests must pass before merging.
Memory constraints (documented)
On the documented ~4 GB host, running the full go test ./pkg/... tree
in parallel causes stalls and OOMs. Mitigations:
GOMAXPROCS=1 GOGC=60for individual packages.Single-package runs only for focused development.
Bootstrap stage-2 builds may OOM/SEGFAULT with the full
src/compilertree — this is a documented environmental limitation, not a defect.karkain check(low-memory path) still passes.
Note
If tests stall on your machine, run them in isolation rather than as a single parallel invocation.
See also
Contributing — how to run the suite before committing. Implemented — conformance corpus and parity gates.