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.

FileKindSize
SKILL.mdskill md7.9 KB
---
name: test
description: 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 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

```text
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.

```rust
#[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.

```rust
#[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`:

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

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

```rust
#[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:

```bash
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`

```rust
#[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)

```bash
# 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)

```bash
# 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: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated 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: 198kUpdated Claude CodeCodexVerifiedInstall