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-16): aura test discovers @test functions; builtins assert / assert_eq (Int/String/Bool); std.assert package for package-mode asserts (C3d, C4h). No async tests, tags/filters, or coverage hooks yet.

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