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:
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');
}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:
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');
}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:
- TypeScript
- Python
- Rust
const doc = await StofDoc.new(source, 'stof', 'test');
await doc.run('test'); // throws if a test fails
doc = Doc()
doc.parse(source, profile='test')
doc.run('test') # raises if a test fails
let mut graph = Graph::default();
graph.parse_stof_src(source, None, Profile::test())?;
let tests: stof::rustc_hash::FxHashSet<String> = ["test".to_string()].into_iter().collect();
let result = Runtime::run_attribute_functions(&mut graph, None, &Some(tests), true); // an Err 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.