Native Testing Framework

Flame features an integrated, zero-cost testing runner driven by PascalCase annotations. Run tests with flame test.

Built-in Testing Annotations

Annotation	Description
`@Test`	Marks a function as an executable test case.
`@Setup`	Runs before each individual test in the file.
`@Cleanup`	Runs after each individual test in the file.
`@BeforeAll`	Runs once before the entire test suite starts.
`@AfterAll`	Runs once after all tests in the file complete.
`@Parameterized`	Executes the test across a matrix of input arguments.

Example Test Suite

@Setup
fn init_test_env() {
    print("Setting up test sandbox...")
}

@Test(timeout: 3000)
fn test_math_operations() {
    let result = 10 * 5
    assertEq(result, 50, "Multiplication should equal 50")
}

@Parameterized([
    [2, 3, 5],
    [10, 15, 25],
    [-5, 5, 0]
])
fn test_addition(a: Int, b: Int, expected: Int) {
    assertEq(a + b, expected)
}

@Cleanup
fn tear_down() {
    print("Test finished.")
}

Built-in Test Assertions & Mock Helpers

assert(condition, message = "assertion failed")
assertTrue(condition, message = "assertion failed")
assertFalse(condition, message = "assertion failed")
assertEq(actual, expected, message = "")
assertNe(actual, unexpected, message = "")
mockData(schema: String) -> Formula
mockApi(url: String, body: String = "{\"status\": \"ok\"}", status: Int = 200) -> Formula
mockFunction(function_name: String, return_value: Any)

@Test
fn test_mocking() {
    let user = mockData("user")
    assertEq(user.id, 1001)

    let api_res = mockApi("/v1/health")
    assertTrue(api_res.ok)
}

Explicit Test Failures & Invariants (`panic`)

When writing complex integration tests for robotics control loops or validating edge-case state transitions, standard equality assertions (assertEq) may not express custom branching failure logic clearly.

You can invoke the built-in panic(message: String) function directly within any @Test case to explicitly fail the test with an exact diagnostic message and line trace:

@Test
fn test_logical_operators_and_safety_interlocks() {
    let isOnline = true
    let isFaulted = false

    // Explicit invariant validation using panic
    if isOnline and isFaulted {
        panic("Expected safety interlock: system cannot be online while in a faulted state")
    }

    if not (isOnline or isFaulted) {
        panic("Expected system to be responsive (online or faulted)")
    }

    let motorSpeed: Int? = 1200
    if motorSpeed == nil {
        panic("Motor telemetry dropped unexpectedly during active test cycle")
    }
}

Benchmarking Framework (`@Benchmark`)

Flame provides a built-in, first-class performance benchmarking framework. Simply decorate functions with @Benchmark and execute them via flame bench.

@Benchmark(warmup: 10, iterations: 100, group: "crypto", name: "SHA-256 Hashing")
fn benchmark_sha256() {
    let hash = crypto.sha256("benchmark-payload")
}

Configuration Parameters

Parameter	Type	Default	Description
`warmup`	`Int`	`10`	Unmeasured iterations to warm CPU caches and JIT paths.
`iterations`	`Int`	`100`	Timed iterations measured for statistical profiling.
`group`	`String`	`""`	Tag for generating comparative performance ranking tables.
`name`	`String`	Function Name	Display name in benchmark reports.

Running Benchmarks

# Run all benchmarks across tests/, benchmarks/, and src/
flame bench

# Run a specific benchmark file
flame bench tests/crypto_bench.fm

Statistical Metrics & Comparative Reports

Each benchmark generates:

Total Time & Average Time / Op (with microsecond / nanosecond precision)
Min & Max Latency
Percentiles: p50 (median), p95, p99
Throughput: Calculated ops/sec
Memory Allocation: Total bytes and bytes per op (using OS page RSS tracking)
Group Comparison Tables: Automatically ranks benchmarks sharing a group and computes the relative percentage improvement!