Skip to main content

Testing

Tests live in the document next to what they test. A function marked #[test] is a test, and stof test runs them all. A test passes unless it throws.

Writing Tests​

The assert functions throw when a check fails:

tests.stofPlayground ↗
rate: 2

fn total(units: int) -> float {
  units * self.rate
}

#[test]
fn totals() {
  assert_eq(self.total(3), 6);
  assert_neq(self.total(1), 0);
  assert(self.total(0) == 0);
  assert_null(self.discount);
  pln('all passed');
}
Output

This example's Run button calls the test function directly. On your machine, stof test finds and runs every test. The asserts are assert, assert_not, assert_eq, assert_neq, assert_null, and assert_not_null, in the Standard Library.

Expected Values and Errors​

#[test(value)] passes when the function returns that value. #[errors] passes when the function throws, for checking that bad input is rejected:

#[test(10)]
fn five_units() -> float {
self.total(5)
}

#[test]
#[errors]
fn rejects_missing_units() {
self.total();
}

Running Tests​

$ stof test pricing.stof
running 3 tests ...
test root totals ... ok
test root five_units ... ok
test root rejects_missing_units ... ok

test result: ok. 3 passed; 0 failed; finished in 0s

A failing test shows what failed and where:

failed: root @ totals ...
error: assertion failed: '6' does not equal '7'
--> pricing.stof:9:5
|
9 | assert_eq(self.total(3), 7);
| ^
at root.totals (pricing.stof:9:5)

stof test exits with an error code when a test fails, so it fits in CI. Give it a directory to test a whole package.

Checking for Leaks​

stof test --leaks runs tests one at a time and also fails any test that leaves objects behind in the document:

leaked: root @ build_order ... 1 object never dropped
1 on root (drop it, or declare it with `using`)

That matters for documents that live a long time, like a policy that runs on every request. See Memory Management.

Keep Tests Independent​

Tests run at the same time, as processes on one shared document. Two tests that change the same field can interfere with each other. Give each test its own data, with new { ... } (declared with using so it's cleaned up), and treat shared fields as read-only:

independent.stofPlayground ↗
fn apply_discount(order: obj) {
  order.total = order.total * 0.9;
}

#[test]
fn applies_discount() {
  using order = new { total: 100 };
  self.apply_discount(order);
  assert_eq(order.total, 90);
  pln('passed');
}
Output

Tests and Production​

Tests are part of the document, but they cost nothing in production. When an app loads a document normally, test functions are left out. To run them from an app, load the document with the test profile and run the test attribute:

const doc = await StofDoc.new(source, 'stof', 'test');
await doc.run('test'); // throws if a test fails

That's a good way to check logic a model wrote: ask it to include tests, and run them before trusting the rest. Next, Memory Management.