All packages Docs Downloads

toast.um

const VERSION

The current version number of the library, formatted as specified by the Semantic Versioning Specification.

const VERSION* = "0.3.0"

type TestFn

The signature of a test function.

TestFn* = fn (ctx: ^Context)

type TestInfo

Information about a test.

TestInfo* = struct {
name: str
func: TestFn
result: std::Err
time: real
funcDepth: uint
}

type Context

The definition of a testing context.

Context* = struct {
// Holds all of the registered tests. You can query this array
// after calling `run()` to see the results and time taken for each test.
tests: []TestInfo

// A weak pointer to the currently processed test.
// It is only valid within the test functions.
current: weak ^TestInfo

// Holds the assertion functions.
assert: Assertions

// Toggles color printing.
printWithColor: bool

// Whether to use the compact or the verbose output.
compactOutput: bool

// The amount of custom assertions called so far.
customAsserts: uint
}

fn newContext

Returns a new, default Context.

Defaults:

  • compactOutput: true
  • printWithColor: false
fn newContext*(): ^Context {

fn (^Context) fail

Marks this test as failed. You should immediately return once calling this.

fn (c: ^Context) fail*(msg: str, code: int = -1) {

fn (^Context) pass

Marks this test as passing. You should immediately return once calling this.

fn (c: ^Context) pass*(msg: str = "") {

fn (^Context) assert.isTrue

Asserts that cond is true. If the resulting bool is false, the caller should return immediately. If msg is not "", prints an extra reason alongside the error.

fn (a: ^Assertions) isTrue*(cond: bool, msg: str = ""): bool {

fn (^Context) assert.isFalse

Asserts that cond is false. Everything else from assert.isTrue applies. (Currently, this is literally just a call to assert.isTrue with the condition inverted.)

fn (a: ^Assertions) isFalse*(cond: bool, msg: str = ""): bool {

fn (^Context) startCustom

Marks the start of a custom assertion. This must be called at the beginning of all custom assertions.

fn (c: ^Context) startCustom*() {

fn (^Context) endCustom

Marks the end of the custom assertion. The intended return boolean must be passed through this function and that must be returned instead: return T.endCustom(returnVal).

fn (c: ^Context) endCustom*(res: bool): bool {

fn (^Context) assert.isOk

Asserts that e's code is 0. If the resulting bool is false, the caller should return immediately. If msg is not "", prints an extra reason alongside the error. If it is, it defaults to e's error message.

fn (a: ^Assertions) isOk*(e: std::Err, msg: str = ""): bool {

fn (^Context) registerTest

Registers a single new test. Will throw a fatal error if the name is already registered with this context.

fn (c: ^Context) registerTest*(name: str, func: TestFn) {

fn (^Context) registerTests

Registers various tests consecutively. Will throw a fatal error if any of the keys are registered as names for tests with this context.

fn (c: ^Context) registerTests*(tests: []TestInfo) {

fn (^Context) run

Runs each of the tests registered to this context, and returns whether any single one of them had an error.

quitIfErr exits the application after every test is run, if any single one of them has any errors.

fn (c: ^Context) run*(quitIfErr: bool = true): bool {

import "std.um"

//~~const VERSION
// The current version number of the library, formatted as specified by
// the [Semantic Versioning Specification](https://semver.org/).
const VERSION* = "0.3.0"
//~~

type (

//~~type TestFn
// The signature of a test function.
TestFn* = fn (ctx: ^Context)
//~~

//~~type TestInfo
// Information about a test.
TestInfo* = struct {
    name: str
    func: TestFn
    result: std::Err
    time: real
    funcDepth: uint
}
//~~

Assertions = struct { ctx: weak ^Context }

//~~type Context
// The definition of a testing context.
Context* = struct {
    // Holds all of the registered tests. You can query this array
    // after calling `run()` to see the results and time taken for each test.
    tests: []TestInfo

    // A weak pointer to the currently processed test.
    // It is only valid within the test functions.
    current: weak ^TestInfo

    // Holds the assertion functions.
    assert: Assertions

    // Toggles color printing.
    printWithColor: bool

    // Whether to use the compact or the verbose output.
    compactOutput: bool

    // The amount of custom assertions called so far.
    customAsserts: uint
}
//~~

)

fn eprintln(text: str = "") { fprintf(std::stderr(), "%s\n", text) }
fn eprint(text: str = "") { fprintf(std::stderr(), text) }

fn (c: ^Context) green(text: str): str { return c.printWithColor ? sprintf("\x1b[32m%s\x1b[m", text) : text }
fn (c: ^Context) red(text: str): str { return c.printWithColor ? sprintf("\x1b[31m%s\x1b[m", text) : text }
fn (c: ^Context) bold(text: str): str { return c.printWithColor ? sprintf("\x1b[1m%s\x1b[m", text) : text }

//~~fn newContext
// Returns a new, default `Context`.
//
// Defaults:
// - `compactOutput`: `true`
// - `printWithColor`: `false`
fn newContext*(): ^Context {
//~~
    c := new(Context)
    c.assert = Assertions { ctx: c }

    c.compactOutput = true
    c.printWithColor = false

    return c
}

//~~fn (^Context) fail
// Marks this test as failed. You should immediately return once calling this.
fn (c: ^Context) fail*(msg: str, code: int = -1) {
//~~
    t := c.current
    std::assert(t != null, "attempt to call fail() outside of a test case")

    s := c.bold("X")
    if !c.compactOutput { s = sprintf("test '%s': %s", t.name, msg) }
    eprint(c.red(s))

    t.funcDepth++
    t.result = std::error(code, msg)
}

//~~fn (^Context) pass
// Marks this test as passing. You should immediately return once calling this.
fn (c: ^Context) pass*(msg: str = "") {
//~~
    t := c.current
    std::assert(t != null, "attempt to call pass() outside of a test case")

    s := "O"
    if !c.compactOutput { s = sprintf("test '%s': %s", t.name, msg) }
    eprint(c.green(s))

    t.funcDepth++
    t.result = std::error(0, msg)
}

//~~ fn (^Context) assert.isTrue
// Asserts that `cond` is true. If the resulting `bool` is false, the caller should return immediately.
// If `msg` is not `""`, prints an extra reason alongside the error.
fn (a: ^Assertions) isTrue*(cond: bool, msg: str = ""): bool {
//~~
    c := a.ctx
    t := c.current
    std::assert(t != null, "attempt to call an assertion outside of a test case")

    if t.result.code == 0 && !cond {
        t.funcDepth++
        s := "assertion failed!"
        if msg != "" { s += sprintf("\nreason: '%s'", msg) }
        c.fail(s)
        return false
    }

    return true
}

//~~ fn (^Context) assert.isFalse
// Asserts that `cond` is false. Everything else from `assert.isTrue` applies.
// (Currently, this is literally just a call to `assert.isTrue` with the condition inverted.)
fn (a: ^Assertions) isFalse*(cond: bool, msg: str = ""): bool {
//~~
    return a.isTrue(!cond, msg)
}

//~~fn (^Context) startCustom
// Marks the start of a custom assertion.
// This must be called at the beginning of all custom assertions.
fn (c: ^Context) startCustom*() {
//~~
    std::assert(c.current != null, "attempt to call startCustom outside of a test suite")
    c.customAsserts++
    c.current.funcDepth += 2 // one more for this very function
}

//~~fn (^Context) endCustom
// Marks the end of the custom assertion.
// The intended return boolean must be passed through this
// function and that must be returned instead:
// `return T.endCustom(returnVal)`.
fn (c: ^Context) endCustom*(res: bool): bool {
//~~
    std::assert(
        c.current != null && c.customAsserts != 0,
        "attempt to call endCustom outside a custom assertion"
    )

    c.customAsserts--
    c.current.funcDepth--
    // returning from this function decrements once more
    return res
}

//~~fn (^Context) assert.isOk
// Asserts that `e`'s code is 0. If the resulting `bool` is false, the caller should return immediately.
// If `msg` is not `""`, prints an extra reason alongside the error. If it is, it defaults to `e`'s error message.
fn (a: ^Assertions) isOk*(e: std::Err, msg: str = ""): bool {
//~~
    c := a.ctx
    t := c.current
    std::assert(t != null, "attempt to call an assertion outside of a test case")

    if t.result.code == 0 && e.code != 0 {
        t.funcDepth++
        s := sprintf("error code is not std::StdErr.ok (%i)", e.code)
        s += sprintf("\nreason: '%s'", msg != "" ? msg : e.msg)
        c.fail(s, e.code)
        return false
    }

    return true
}

//~~fn (^Context) registerTest
// Registers a single new test.
// Will throw a fatal error if the name is already registered with this context.
fn (c: ^Context) registerTest*(name: str, func: TestFn) {
//~~
    e := sprintf("test '%s' already registered", name)
    for _, t^ in c.tests { std::assert(name != t.name, e) }
    c.tests = append(c.tests, TestInfo{ name: name, func: func })
}

//~~fn (^Context) registerTests
// Registers various tests consecutively.
// Will throw a fatal error if any of the keys are registered as names for tests with this context.
fn (c: ^Context) registerTests*(tests: []TestInfo) {
//~~
    for _, t in tests {
        // in case it was set, since it's checked for later
        t.result.msg = ""

        n := t.name
        e := sprintf("test '%s' already registered", n)
        for _, u^ in c.tests { std::assert(n != u.name, e) }

        c.tests = append(c.tests, t)
    }
}

//~~fn (^Context) run
// Runs each of the tests registered to this context, and returns whether any single one of them had an error.
//
// `quitIfErr` exits the application after every test is run, if any single one of them has any errors.
fn (c: ^Context) run*(quitIfErr: bool = true): bool {
//~~
    didFail := false
    passedTests := 0

    if c.compactOutput { eprint("results: ") }

    for _, t^ in c.tests {
        c.current = t

        time := std::clock()
        t.func(c)
        t.time = std::clock() - time

        if t.result.code != 0 {
            didFail = true
            if !c.compactOutput {
                pos := t.result.trace[t.funcDepth]
                eprint(sprintf("\nat file %s\nline %i", pos.file, pos.line))
            }
        } else {
            if t.result.msg == "" { c.pass("passed") }
            passedTests++
        }

        if !c.compactOutput { eprintln(sprintf("\ntook %fms\n", t.time * 1000)) }
    }

    if c.compactOutput {
        eprintln("\n")
        if didFail {
            eprintln(c.red(c.bold("failed tests:\n")))

            // TODO: should loop through all tests again?
            for _, t^ in c.tests {
                if t.result.code == 0 { continue }

                msg := sprintf(
                    "test '%s': %s",
                    t.name, t.result.msg
                )

                pos := t.result.trace[t.funcDepth]

                eprintln(sprintf(
                    "%s\nat file %s\nline %i, took %fms\n",
                    c.red(msg), pos.file, pos.line, t.time * 1000
                ))
            }
        }
    }

    l := len(c.tests)
    text := sprintf("%i of %i tests passed", passedTests, l)

    text = passedTests == l ? c.green(text) : c.red(text)
    eprintln(c.bold(text))

    c.current = null
    if quitIfErr && didFail { exit(-1) }
    return didFail
}