RFC-011: Testing Framework

1. Abstract

This RFC specifies Aura’s built-in testing support: discovery via @test, assertions, async tests, unit vs integration layout, filtering, and coverage hooks. Tests run through aura test using the same compiler and runtime as production code.

Toolchain today (2026-07-28, S2/C22): aura test discovers @test functions in files and packages; builtins assert / assert_eq cover Int/String/Bool, and std.assert supports package-mode assertions. The test path is included in the S2 acceptance gate, supports forwarded process arguments after --, substring name filters, and structured JSON reports with skipped cases. aura race reuses the test workflow with runtime race tracking. std.test also provides deterministic benchmark, snapshot, and property hooks. Async test conventions, tags, integration-test conventions, JUnit/LCOV output, and coverage hooks remain open.

2. Motivation

2.1 Problem statement

Testing bolted on via external-only frameworks fragments DX. First-party discovery and runner make TDD and CI default paths.

2.2 Why now

Language attributes (RFC-009) and CLI (RFC-012) need a concrete test model for Ship MVP.

2.3 Success metrics

Metric	Target
Discovery	Zero-config `@test` in package
Async	`async @test` works with runtime
CI	JUnit-like / JSON report optional

3. Goals

Attribute-based discovery.
Rich asserts with good failure messages.
Parallel test execution by default where safe.
Integration test directory convention.
Coverage hooks (LLVM/source-based).

4. Non-goals

Full browser/e2e product testing.
Mandatory mocking framework in core (ecosystem).
Property-based testing in MVP (later).

5. Prior art & alternatives

System	Notes	Take
Rust `#[test]`	Simple	Inspiration
JUnit	Ecosystem	Report formats
Go `testing`	Table tests	Style
pytest	Fixtures power	Later ecosystem

6. Design

6.1 Overview

code

@test functions → compile test harness → run in process(es) → report

6.2 Discovery

aura

@test
fun adds() {
  assertEqual(1 + 1, 2)
}

@test
async fun fetches() {
  val v = await load()
  assertTrue(v > 0)
}

Package-private @test functions are discovered (no need for pub).
Ignore: @test(ignore) or @ignore.
Tags: @test(tag = "slow") + --tag filter.

6.3 Layout

Kind	Location
Unit	Same package, `*_test.aura` or inline
Integration	`tests/*.aura` as separate crates linking lib

Exact filename convention freeze later; document both.

6.4 Assertions (`std.test`)

aura

assertTrue(cond)
assertEqual(actual, expected)
assertNotNull(x)
assertFails { throw ... }

Failure captures file/line and pretty-prints values (Debug derive).

6.5 Runner

aura test builds test targets and executes.
Default: parallel by test function with isolation (process-per-test optional flag).
Filter: --test-name pattern, file path args.
Fail fast option.

6.6 Async & concurrency

Async tests run on runtime scheduler.
Timeouts per test configurable.
Race detector can enable under aura test --race when available.

6.7 Coverage

--coverage produces LCOV/HTML via instrumentation (LLVM).
Not required for MVP exit; design hooks reserved.

6.8 Reports

Human terminal default.
--format json / junit xml for CI.

6.9 Examples