Test Scripts

Writing and organizing Elle test scripts.

Elle test scripts

Elle test scripts live in tests/elle/ — one .lisp file per feature area. Each file is a self-contained test that imports examples/assertions.lisp and exits non-zero on failure.

Structure

(defn assert-eq [a b msg]
  (when (not= a b)
    (error {:error :assertion :message msg})))

# Description of what this file tests

(assert-eq (+ 1 2) 3 "basic addition")
(assert-eq (- 10 3) 7 "basic subtraction")

Assertion library

Elle test scripts use examples/assertions.lisp which provides: assert-eq, assert-true, assert-false, assert-list-eq, assert-not-nil, assert-string-eq.

For runtime error checking, use protect:

(def [ok? err] (protect (/ 1 0)))
(assert-eq (not ok?) true "division by zero should error")
(assert-eq (get err :error) :division-by-zero "error kind")

Naming

Files are named for the feature they test: core.lisp, booleans.lisp, destructuring.lisp, blocks.lisp, closures.lisp, etc.

Granularity

One file should cover a coherent feature area. A file can contain hundreds of assertions. The overhead is one pipeline initialization per file instead of one per assertion.

Relationship to examples/

examples/ files are curated documentation that happens to be tested. tests/elle/ files are test suites that happen to be readable. Different audiences, different goals:

• examples/ — teaches the language, shows idiomatic patterns, includes

display/print output, organized as themed demonstrations

• tests/elle/ — verifies behavior, maximizes coverage, no output noise,

organized by feature area

Do not merge test scripts into examples or vice versa.

What NOT to put in Elle scripts

• Tests that require Rust type inspection (see decision tree)
• Compile-time rejection tests
• Tests for the Rust API surface (Value methods, SymbolTable API)

Note: Property-based tests belong in tests/property/ only if random input generation genuinely finds bugs. If you're testing a fixed set of known-good examples, write Elle test scripts instead — they're faster and clearer.

Property tests

Property tests use proptest to verify invariants across generated inputs. They live in tests/property/ and answer: "Does this invariant hold for all valid inputs?"

Use property tests only when random input generation genuinely finds bugs. If you're testing a fixed set of known-good examples, write Elle test scripts instead — they're faster and clearer. Property testing is the wrong tool for concrete cases.

The PROPTEST_CASES environment variable

All proptest! blocks use the proptest_cases() helper from tests/common/mod.rs:

proptest! {
    #![proptest_config(crate::common::proptest_cases(200))]

    #[test]
    fn my_property(n in -1000i64..1000) {
        // ...
    }
}

The default parameter (200 in this example) is the per-test tuning. Do NOT change hardcoded case counts in test files. Instead, use the PROPTEST_CASES environment variable to override all tests uniformly:

# Fast smoke during development (8 cases per test)
PROPTEST_CASES=8 cargo test property::

# Full run with per-test defaults (CI)
cargo test property::

# Targeted run with custom case count
PROPTEST_CASES=50 cargo test property::fibers

When PROPTEST_CASES is set, it overrides the hardcoded default in every proptest_cases(N) call. This allows CI and local development to control case counts uniformly without modifying test files.

Case count guidelines

Running property tests

# Fast smoke (development, CI fast tier)
PROPTEST_CASES=8 cargo test property::

# Default case counts (CI thorough tier, pre-merge)
cargo test property::

# Targeted
cargo test property::arithmetic

What stays in Rust

These tests cannot be expressed in Elle and must remain in Rust:

Test helpers

common/mod.rs

eval_source(input: &str) -> Result<Value, String> — The canonical test eval. Evaluates Elle source through the full pipeline with stdlib. Use this for any test that needs to run Elle code.

use crate::common::eval_source;
let result = eval_source("(+ 1 2)").unwrap();
assert_eq!(result, Value::int(3));

eval_source_bare(input: &str) -> Result<Value, String> — Same as eval_source but skips stdlib initialization. Use this for tests that never call stdlib functions. Prelude macros are still available.

setup() -> (SymbolTable, VM) — Returns an initialized pair with primitives and stdlib registered. Use this when you need direct access to the VM or symbol table (e.g., calling analyze() or compile() directly).

proptest_cases(default: u32) -> ProptestConfig — Create a proptest config that respects the PROPTEST_CASES environment variable. When set, it overrides the given default uniformly across all tests.

property/strategies.rs

8 public strategies for generating Elle values and FFI types:

Naming conventions

• Test files: lowercase, hyphenated concepts joined with underscores

(e.g., closures_and_lambdas.rs, signal_enforcement.rs)

• Test functions: test_ prefix for example-based, descriptive name for

property tests (e.g., fn int_roundtrip(...), fn add_commutative(...))

• Property test names describe the invariant, not the implementation

Fixtures

tests/fixtures/ contains static data files used by tests:

• naming-good.lisp — Elle source with correct kebab-case naming
• naming-bad.lisp — Elle source with camelCase/PascalCase/snake_case naming

Used by integration/lint.rs to test the linter against real files.

See also

• Analysis index