Writing and running tests
The test fn declaration, the expect assertion vocabulary, grouping and hooks.
PickleScript has a built-in test runner. Tests are ordinary declarations marked
with test, and they are discovered and executed by pickle test.
Declaring a test
fn add(a: int, b: int) -> int {
return a + b
}
test fn add_returns_the_sum() {
expect(add(2, 3)).toBe(5)
}
test fn name() { ... } is the form. The runner collects every test fn in the
module and runs them.
The assertion vocabulary
expect(value) starts a chain. The complete set of matchers is:
| Matcher | Passes when |
|---|---|
.toBe(expected) |
Strict equality |
.toEqual(expected) |
Structural equality |
.toBeTruthy() |
The value is truthy |
.toBeFalsy() |
The value is falsy |
.toBeNull() |
The value is none |
.toExist() |
The value is a present some |
.toHaveLength(n) |
A string, list or map has length n |
.toContain(needle) |
A string contains a substring, or a collection contains an element |
.toBeGreaterThan(n) |
Ordering comparison |
.toBeLessThan(n) |
Ordering comparison |
Negate any matcher with .not(), which is a call rather than a property:
expect(add(2, 3)).not().toBe(6)
test fn matchers() {
expect(2 + 2).toBe(4)
expect("abc").toContain("b")
expect([1, 2, 3]).toHaveLength(3)
expect("hello").toHaveLength(5)
expect(5).toBeGreaterThan(4)
expect(5).toBeLessThan(6)
expect(true).toBeTruthy()
expect(false).toBeFalsy()
expect(none).toBeNull()
expect(1).not().toBe(2)
}
expect is only available inside a test fn. It is a compile-time construct
rather than an ordinary function, so the type checker handles the chain directly.
A failing test looks like this
running 2 test(s) from main.pkl
test fails ... FAILED (Expected:
2
Received:
1
)
test passes ... ok
test result: 1 passed; 1 failed
The process exit code is 1 when any test fails.
Testing optional values
Because none is the language's only absence, asserting on optionals is a
normal part of a test suite. expect(...).toBeNull() and .toExist() cover the
two cases directly:
fn findFirst(xs: List<int>) -> int? {
for (x in xs) {
return x
}
return none
}
test fn optional_results() {
expect(findFirst([1])).toExist()
expect(findFirst([1]) ?? -1).toBe(1)
let seeded = [0]
let head = findFirst(seeded)
if (let some(v) = head) {
expect(v).toBe(0)
} else {
expect(true).toBe(false)
}
}
To assert on a payload, bind it with match:
import { Stack } from std.collections.stack
test fn empty_stack_has_no_front() {
let s = Stack<int>(0)
match (s.pop()) {
case some(v) -> { expect(false).toBe(true) }
case none -> {}
}
}
case some(v) -> ... binds the payload to v; case none -> ... matches
absence. An empty arm body is written {}.
Grouping and hooks
describe and it nest related tests. Both take a description and a block,
separated by a comma:
fn double(n: int) -> int {
return n * 2
}
describe("maths", {
it("doubles", {
expect(double(2)).toBe(4)
})
it("doubles three", {
expect(double(3)).toBe(6)
})
})
A bare test("description", { ... }) is the ungrouped form of it. Four hooks
may appear at the top level:
beforeAll({ ... })
beforeEach({ ... })
afterEach({ ... })
afterAll({ ... })
pickle-cli test stdlib/collections/set_test.pkl
running 3 test(s) from stdlib/collections/set_test.pkl
describe maths
test doubles ... ok
test doubles three ... ok
test result: 3 passed; 0 failed
File layout
The runner picks up two naming conventions from a directory:
*_test.pkl*.test.pkl
This is how the standard library is organised, each module has a matching test file:
stdlib/collections/set.pkl
stdlib/collections/set_test.pkl
A file that is not a test can still be run directly, which is convenient while iterating:
pickle-cli test stdlib/collections/set_test.pkl
Selecting tests
# By name substring
pickle-cli test --filter fib
# By tag, repeatable
pickle-cli test --tag fast --tag unit
--filter and --tag combine with AND semantics: a test must match the filter
and carry at least one of the requested tags.
Next steps
- Builtin functions: the functions available inside tests.
- Pattern matching: the
match/casesyntax in depth.
