Skip to content

Applications and tests

Build the application struct’s Context field in boot from Context.root(), or derive a tighter one there (spec §15 Scoped application fields; tour: App Fields, Defer & Context):

pub struct Config
    port:    Int = 8080
    context: Context
end

pub fn boot() -> Result<Config, String>
    Ok(Config{context: Context.root()})
end

A boot’s error is the error of what it calls. When its steps fail with one error type, such as a database’s sql.Error, make that the E of Result<App, E> and end each step with ?. A boot whose steps fail with different types returns an error type of its own with a From impl for each, so each ? converts (spec §11 Propagating with ?). A boot that cannot fail says Result<App, String> and returns Ok(...).

Boot with no startup input when the tests need none. A boot that reads no startup input declares no parameter, fn boot() -> Result<App, E>, and its groups write boot server.boot(). A boot that reads startup takes startup: Startup. When most of its tests need no input, default the parameter, fn boot(startup: Startup = Startup{}) -> Result<App, E>, so those groups write boot server.boot() and only the groups that test the inputs build a Startup. The runtime still passes the real Startup to main’s boot, so the default changes nothing outside tests. Leave the parameter required when every test must decide its inputs, such as a boot that fails without a database URL. Configuration helpers that build the whole application take startup as a parameter too.

Put with lines at the top of the block they govern where practical, so the reader sees the replaced fields before the code that runs under them:

fn import_quietly()
    with Config.logger = Silent
    with Config.store = FakeStore{}

    run_import()
end

A with lasts to the end of its block. When only part of a function should run under it, move that part into a helper function and put the with lines at the top of the helper. Use a bare block statement only when a helper would be ceremony.

39. Write tests as ordinary code with direct assertions

Section titled “39. Write tests as ordinary code with direct assertions”

Prefer _test.nomi files with explicit test "..." blocks for behavior checks (spec §17 Tests; tour: Testing). A test should read like ordinary Nomi code with a small number of direct assertions:

test "result values can be asserted directly"
    assert parse_id("42") == Ok(42)
    assert parse_id("nope") == Err("expected a numeric id")
end

Put the tests of shapes.nomi in shapes_test.nomi beside it. That file is its partner test and reads its private declarations (spec §14 Visibility), so a private helper is tested as it is: don’t make a declaration pub only so a test can reach it.

Use unique full test names within a file. The enclosing group is part of the full name, so repeated leaf names are fine in different groups.

A group is for tests that share a clock, boot or setup, or for several tests that belong under one heading. Don’t wrap a single test in a group to name it: name the test.

test "a new clock wraps past midnight"
    assert "${Clock.new(25, 0)}" == "01:00"
end

Keep tests focused. A test name should carry the intent, so avoid comments that restate the next line. Split unrelated rules into separate tests instead of collecting a tour of a feature in one block.

A compact example that belongs to one declaration is an attached test (§49), especially a stdlib reference example. Keep broader workflows and multi-case behavior in named test and group blocks.

Use assert for the positive shape and refute when the thing under test is already a predicate (spec §17 Assertions; tour: Testing). Don’t wrap simple value checks in io.inspect or string interpolation to produce output; assert the value itself. Don’t introduce a pipeline for a simple call-and-compare; direct equality is clearer:

assert String.to_decimal("1.50") == Some(1.50d)

Write the value under test on the left of == and the expected value on the right. A failed comparison of multi-line Strings prints a diff that reads the right operand as expected and the left as actual.

assert and refute may stand alone as statements, since the check is the reason the expression is there. Use a pattern assertion when a payload matters:

assert parse_id("42")

assert Err(message) = parse_id("wat")

assert "numeric" in message

Use ? for fallible setup when the happy-path value is what the rest of the test needs. Use a pattern assertion when the returned shape is itself under test:

t = Time.parse("09:30:00")?

assert Time.to_string(t) == "09:30:00"

assert Err(Error.InvalidFormat(_)) = Time.parse("bad")

When the value under test comes from a pipeline and the intermediate meaning is useful, bind the pipeline result and assert the binding. The failure report then shows a named expression:

found =
    [1, 2, 3, 4, 5]
    |> Iter.find(fn x -> x == 3)

assert found == Some(3)

For one-shot checks where a binding would only name the plumbing, let the pipeline compute the assertion subject and put assert or refute at the head. Prefer an existing predicate or equality function (String.contains, String.equal, Result.is_ok) over a throwaway lambda. When a predicate has semantic weight or several conditions, give it a predicate’s name (§4) and assert that instead; keep then stages for tiny local transformations. Indent the stages under the asserted operand, which distinguishes it from a statement-level pipeline:

assert "  ADA LOVELACE  "
    |> String.trim()
    |> String.lowercase()
    |> String.equal("ada lovelace")

assert values
    |> Iter.map(normalize)
    |> Iter.all_match(is_valid)

Use subtests (spec §17 Subtests; tour: Testing) when one claim is checked over a table of inputs: the same assertions, rows that differ only in data. Each row then reports on its own, and a failure names the row. Write the rows as a table of tuples or structs, pipe it into subtests, and bind each row with a pattern that names each column:

test "parses ids"
    [("42", Ok(42)), ("007", Ok(7)), ("nope", Err("expected a numeric id"))]
    |> subtests (text, expected)
        assert parse_id(text) == expected
    end
end

Pipe a literal table used once. Bind the table to a name, and write subtests cases, (text, expected), when the test uses it again or when it needs a type annotation.

When the data alone does not say what a row checks, give each row a description column and name the row with it, so a failure reads as the case it is:

test "leap years"
    [
        ("year divisible by 400 is leap year",                         2000, True),
        ("year divisible by 100, not divisible by 400 in common year", 1900, False),
    ]
    |> subtests (description, year, expected), description
        assert is_leap_year(year) == expected
    end
end

Name rows with a column rather than a string built from the other columns when the table already carries one, and leave the name out when the rendered row says enough.

When the table’s type needs one variant or struct name to settle, write the name in the first row that needs it and leave the other rows bare, rather than annotating the table:

cases = [
    ("single bit one to decimal", 2, [1],                 10, Ok([1])),
    ("input base is one",         1, [0],                 10, Err(Error.InvalidInputBase)),
    ("input base is zero",        0, [],                  10, Err(.InvalidInputBase)),
    ("negative digit",            2, [1, -1, 1, 0, 1, 0], 10, Err(.InvalidDigit)),
]

Annotate the table when a column is an anonymous struct, which has no name to write, or when several columns would each need a name.

Write separate tests instead when the rows need different setup or different assertions: a subtests body that branches on its row is several tests in one. Keep a table to one claim, and split a long one into tests by what the rows have in common.

42. Keep expected values the tests share in a once

Section titled “42. Keep expected values the tests share in a once”

When several tests check against the same expected values (a song’s verses, a board, a tree), write them once as a once in the test file (spec §6 once Bindings; tour: Bindings & Expressions) and have each test take what it needs. One test runs subtests over the table (§41), and the others build their expectations from it:

once verses = [
    (1, "On the first day of Christmas my true love gave to me: a Partridge."),
    (2, "On the second day of Christmas my true love gave to me: two Doves."),
]

test "each verse"
    subtests verses, (number, expected)
        assert recite(number, number) == [expected]
    end
end

test "two verses together"
    expected =
        verses
        |> Iter.map(fn (_number, verse) -> verse)
        |> Iter.to_list()

    assert recite(1, 2) == expected
end

A value is then written once, and a fix to it reaches every test that uses it. Keep a value one test uses in that test.

43. Test an interactive program with io.replay

Section titled “43. Test an interactive program with io.replay”

Test an interactive program, one that prompts and reads in turn, with assert io.replay(script, main) (std::io; tour: Testing) and a """ script, not with io.capture(input, main) and separate input and output strings. The script shows each answer next to the prompt it answers, so the reader follows one conversation instead of matching two lists. Keep io.capture for a program that reads its input in one go, or when the value main returns matters. A program that reads nothing is checked with io.replay too, with a script of its output alone.

Write the output at the closing """’s column, so the literal keeps only the indentation that is part of the output. Indent each input line four columns past it and put one space after its >. Write a prompt the program writes with io.write as its own output line, without its trailing space, and the answer on the input line under it.

test "deposit money"
    assert io.replay(
        """
        What is the starting balance?
            > 500
        deposit:
            > 25
        new balance is 525
        """,
        main,
    )
end

io.replay gives the script’s rules, such as how to write output that would read as input.

A script with no input is its output, written the same way:

test "prints the table"
    assert io.replay(
        """
        -10.0 C |   14.0 F
         -5.0 C |   23.0 F
        """,
        main,
    )
end

44. Share a group’s boot and fakes through a helper file

Section titled “44. Share a group’s boot and fakes through a helper file”

Put the fakes a project’s tests install, and the Startup they boot with when they need one (spec §17 Groups; tour: Testing), in a test helper file such as test_support.nomi. It exports the fake types and, when tests need startup input, pub fn startup() -> Startup. A group passes test_support.startup() to its boot line and installs fakes with with lines in setup, so every test in the group runs against them. Build the Startup with only the fields it sets; the rest default to empty:

// test_support.nomi
import server.Mailer

pub fn startup() -> Startup
    Startup{env: {"SENDER" => "test@example.com"}}
end

pub type FakeMailer

impl Mailer for FakeMailer
    fn send(_mailer: FakeMailer, to: String) -> Result<Unit, String>
        if to == "" then Err("no address") else Ok(Unit)
    end
end
// signup_test.nomi
import
    server
    server.App
    test_support
    test_support.FakeMailer
end

group "signup"
    boot server.boot(test_support.startup())

    setup begin
        with App.mailer = FakeMailer
        "ada@example.com"
    end

    test "sends a welcome", to
        assert server.welcome(to)
    end
end

A test that needs a different startup builds it from the shared one: {..test_support.startup(), args: ["--dry-run"]}. Groups do not nest; write sibling groups, and share setup between them through a function.

Put a group’s setup at its top, after clock and boot, where a reader looks for it.