Test — Incan Compiler

Step 1: Determine what changed

Identify which compiler stages are affected by the current changes:

Change area	Stages affected
New syntax or keyword	Parser, Typechecker, Lowering, Emission
New semantic rule or validation	Typechecker
New or changed codegen output	Lowering, Emission
Stdlib addition	Typechecker (loader), Emission, possibly Runtime
CLI behavior	Integration tests
Formatter change	Property tests, integration tests

For non-trivial changes, do a quick pattern intake before writing or changing tests:

• Identify the active area and downstream stages the behavior must survive.
• Read 2-3 nearby tests or fixtures that already cover a similar behavior shape.
• Name the source-of-truth boundary, such as the RFC, diagnostics catalog, stdlib registry, ownership policy, CLI reference, or docs contract.
• Pick the narrowest failing test first, then the downstream verification that proves the behavior reaches the right stage.

Step 2: Pick the right tests to write

Decision tree

Did you change the parser?
  → Add a test to the subject's module under loaves/kernel/incan_syntax/src/parser/tests/ (shared helpers live in helpers.rs)

Did you change the typechecker?
  → Add a test to the subject's module under loaves/compiler/incan_frontend/src/typechecker/tests/ (shared helpers live in helpers.rs)

Did you change lowering or emission (codegen output)?
  → Add a .incn file in loaves/compiler/incan_emit/tests/codegen_snapshots/
  → Add a test function in loaves/compiler/incan_emit/tests/codegen_snapshot_tests.rs
  → Run: INSTA_UPDATE=1 cargo test -p incan_emit --test codegen_snapshot_tests

Did you change end-to-end behavior (CLI, build, multi-file)?
  → Add a test in loaves/toolchain/incan-cli/tests/integration_tests.rs

Did you change the formatter?
  → Property tests in loaves/compiler/incan_format/tests/property_tests.rs verify idempotency
  → Also add a codegen snapshot if formatting affects output

Did you add a diagnostic?
  → Add a fixture in loaves/compiler/incan_test_support/fixtures/invalid/ that triggers it
  → Add an integration test that asserts the diagnostic message

What to always do

For any pipeline feature (parser through emission), write both:

1. A unit test at the stage you changed (parser or typechecker)
2. A codegen snapshot test that exercises the feature in expressions, not just declarations

Step 3: Write the tests

Parser test pattern

Directory: loaves/kernel/incan_syntax/src/parser/tests/ — one module per subject (for example expressions.rs, patterns_and_matching.rs, modules_and_imports.rs); a module starts with use super::*;, which brings in the parser namespace and crate imports from mod.rs and the shared helpers from helpers.rs (a module whose tests spell everything as crate:: paths omits it). Add a test to the module whose subject it belongs to, and keep every module under the inventory's 1,500-line split threshold.

#[test]
fn test_parse_my_feature() -> Result<(), Vec<CompileError>> {
    let source = r#"
model Example:
    field: str
"#;
    let program = parse_str(source)?;
    assert_eq!(program.declarations.len(), 1);
    Ok(())
}

Helpers available from helpers.rs: parse_str(source), parse_str_err(source, context), require_source_span(source, needle, occurrence) and the require_*_decl accessors; parse_str_with_module_path(source, path) is private to modules_and_imports.rs.

Typechecker test pattern

Directory: loaves/compiler/incan_frontend/src/typechecker/tests/ — one module per subject (for example traits.rs, narrowing_and_matching.rs, rust_imports_and_types.rs); every module starts with use super::*;, which brings in the crate imports from mod.rs and the shared helpers from helpers.rs. Add a test to the module whose subject it belongs to, and keep every module under the inventory's 1,500-line split threshold.

#[test]
fn test_my_feature_valid() {
    assert_check_ok(r#"
def example() -> str:
    return "hello"
"#);
}

#[test]
fn test_my_feature_invalid() {
    let result = check_str(r#"
def example() -> int:
    return "hello"
"#);
    assert!(result.is_err());
    let errs = result.unwrap_err();
    assert!(errs.iter().any(|e| e.message.contains("expected")));
}

Helpers available: check_str(source), assert_check_ok(source), check_str_with_library_index(source, index).

Important: test functions that do fallible work must return Result and use ?. Never use .unwrap() or .expect().

Codegen snapshot test pattern

1. Create loaves/compiler/incan_emit/tests/codegen_snapshots/my_feature.incn:

def example() -> str:
    return "hello"

2. Add to loaves/compiler/incan_emit/tests/codegen_snapshot_tests.rs:

#[test]
fn test_my_feature_codegen() {
    let source = load_test_file("my_feature");
    let rust_code = generate_rust(&source);
    insta::assert_snapshot!("my_feature", rust_code);
}

3. Generate the snapshot:

INSTA_UPDATE=1 cargo test -p incan_emit --test codegen_snapshot_tests -- test_my_feature_codegen

4. Review: cargo insta review or check loaves/compiler/incan_emit/tests/snapshots/codegen_snapshot_tests__my_feature.snap.

Helpers available: load_test_file(name) (loads from loaves/compiler/incan_emit/tests/codegen_snapshots/<name>.incn), generate_rust(source), generate_rust_with_widgets_manifest(source) (for library import tests).

Integration test pattern

File: loaves/toolchain/incan-cli/tests/integration_tests.rs

#[test]
fn test_my_feature_compiles() -> Result<(), Vec<String>> {
    compile_source(r#"
def main():
    let x: str = "hello"
    print(x)
"#)
}

Helpers available: compile_source(source), compile_file(path).

Invalid fixture pattern

1. Create loaves/compiler/incan_test_support/fixtures/invalid/my_error_case.incn with code that should fail.
2. Add an integration test that asserts the expected diagnostic.

Step 4: Run the tests

During development (targeted)

# Run a specific test
cargo test -p incan_emit --test codegen_snapshot_tests -- test_my_feature

# Run all typechecker tests
cargo test -p incan_frontend --lib typechecker::tests

# Run all parser tests
cargo test -p incan_syntax --lib parser::tests

# Run integration tests
cargo test -p incan-cli --test integration_tests

Before finishing (full suite)

# Full test suite
make test

# Full pre-commit gate (full checks + smoke-test-fast)
make pre-commit

# Update all snapshots if codegen changed
INSTA_UPDATE=1 cargo test -p incan_emit --test codegen_snapshot_tests

Step 5: Verify

After tests pass, check:

• No .unwrap() or .expect() in test code (clippy will reject them)
• Test functions that do fallible work return Result
• Codegen snapshots are updated (no pending cargo insta review)
• Both valid and invalid cases are covered for new diagnostics

Rust compiler error workflow

When the task is to debug a Rust compiler error, collect the full context before changing code:

• exact command that failed;
• full diagnostic text, including error code, notes, help text, and secondary spans;
• active features or build mode, especially default build vs. rust-metadata;
• relevant function signature and nearby type definitions;
• local precedent files or tests that show the intended pattern.

Classify the root cause before proposing a fix: lifetime/borrow across an await or compiler boundary, missing trait bound, feature-gate/build-mode mismatch, orphan/coherence rule, missing import, or incomplete parser/typechecker/lowering/emission wiring. Prefer fixing the owning boundary over adding local conversion or clone workarounds.