The tests have brought their own notebook

The tests have arrived with a notebook. They would like the compiler to remember exactly which promise it broke, rather than announcing that something somewhere was unfortunate.

Give the example a name

Put test declarations in a file ending in .spec.pooka, such as test/main.spec.pooka:

module main_test

test "two numbers can share an answer" {
  assert 20 + 22 == 42
}

test "division keeps a fractional answer" {
  assert 7 / 2 == 3.5
}

The names explain the intended behaviour. The assertions contain concrete observations the runner can check. Production source files do not accept test declarations, which keeps the boundary between shipped code and test code explicit.

A skipped page is still part of the book

A test can be kept without being executed:

module main_test

test skip "a future visitor can be greeted" {
  assert 1 + 1 == 2
}

The skipped body is still type-checked. A test waiting for a feature should not become an abandoned pocket of syntax the compiler never reads.

That also means test skip is not a way to hide an unresolved name or an invalid call. It changes execution, not the language rules inside the body.

Choose the amount of conversation

pooka test
pooka test --compact
pooka test --verbose

The ordinary view groups named tests by module. The compact view concentrates on failures and totals. The verbose view is useful when more detail is needed.

When an equality assertion fails, showing the expected and actual values gives the reader something to compare. A location tells them where the expectation was written. Neither requires printing the entire compiler diagnostic treatment around every ordinary failed assertion.

The process exit status matters too: a failing suite must tell CI it failed. A beautiful green summary printed before returning success for a broken assertion would be an exceptionally well-dressed lie.

Tests are small executable explanations. Their notebook is most useful when the next reader can understand both the promise and the evidence without interviewing the author.

— Peregrine Finch