Testing

Tests are Functions marked @Test, anywhere in a package, beside the code they test, where they see its file’s private names. fb test builds them and runs them in parallel in one process; fb build and fb run leave them out.

Expect

Import std.test brings in Expect, which on failure prints the expression and each side’s value, and lets the test go on to its next check; ExpectThrows<E>, which gives the error a call threw, or fails; Fail; and Skip. A panic or an Assert in a test fails it too.

Import std.core
Import std.test

Function Damage(attack: Int, armor: Int): Int
    If armor >= attack Then Return 1
    Return attack - armor
End Function

Class OutOfAmmo Extends Error
End Class

Function Fire(ammo: Int): Int Throws OutOfAmmo
    If ammo == 0 Then Throw OutOfAmmo("click")
    Return ammo - 1
End Function

@Test
Function DamageIsAtLeastOne()
    Expect(Damage(10, 3) == 7)
    Expect(Damage(3, 10) == 1)
End Function

@Test
Function FiringUsesAmmo() Throws OutOfAmmo
    Expect(Try Fire(3) == 2)
    Local error = ExpectThrows<OutOfAmmo>(Fire(0))
    Expect(error?.Message == "click")
End Function

test main.DamageIsAtLeastOne ... ok
test main.FiringUsesAmmo ... ok

test result: ok. 2 passed; 0 failed; 0 skipped; 0 filtered out

fb test takes a .fb file, a package’s folder, or nothing for the package it’s in, and --filter runs only the tests whose names have its text in them. A test that panics doesn’t stop the rest: fb starts the process again and runs those left. In a debug build, each test’s leaks are reported with it.

A package’s tests/ folder

The .fb files of a package’s tests/ folder are tests that use the package from outside, as another package would: through its Public names only. The package builds without them.

Doc tests

The examples in doc comments are tests too. A code block under a # Examples heading in a /// comment is compiled and run by fb test, named after what it documents, as game.shapes.Circle.Grow (example), so the docs’ examples can’t go stale. A line that starts with # is compiled but not shown, for setup a reader doesn’t need, and a fence marked fb no_run is only compiled.

Import std.core

/// The area of a circle of radius `r`.
///
/// # Examples
///
/// ```
/// Expect(Area(1) > 3.14)
/// Expect(Area(0) == 0)
/// ```
Public Function Area(r: Float): Float => 3.14159 * r * r

Print(Area(2))

fb test std runs the standard library’s own examples, which are its reference’s.