Writing and running tests

The test fn declaration, the expect assertion vocabulary, grouping and hooks.

vlatest

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