Test — Incan Compiler

Step 1: Determine what changed

Identify which compiler stages are affected by the current changes:

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.