Skip to content

encero-systems/incan / .agents/skills/test

Run and write tests for the Incan compiler. Use when the user asks to test changes, add tests, run the test suite, verify a feature, or says /test. Guides test selection, provides correct patterns, and runs the right commands.

Test — Incan Compiler

Step 1: Determine what changed

Identify which compiler stages are affected by the current changes:

Change areaStages affected
New syntax or keywordParser, Typechecker, Lowering, Emission
New semantic rule or validationTypechecker
New or changed codegen outputLowering, Emission
Stdlib additionTypechecker (loader), Emission, possibly Runtime
CLI behaviorIntegration tests
Formatter changeProperty 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"
  1. 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);
}
  1. Generate the snapshot:
INSTA_UPDATE=1 cargo test -p incan_emit --test codegen_snapshot_tests -- test_my_feature_codegen
  1. 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.

finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 319kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 319kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 319kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 196kUpdated Claude CodeCodexVerifiedInstall