Expand description

Fluent test assertions in Rust

Speculoos is a testing framework designed to make your assertions read like plain English. This allows you to more easily expose the intent of your test, rather than having it shrouded by assertions which work, but are opaque on their meaning.

Methods available to assert with are dependent upon the type of the subject under test. Assertions are available for some basic types, but there is still a great deal missing from the standard library.

Usage

Add the dependency to your Cargo.toml:

[dependencies]
speculoos = "0.6.0"

Then add this to your crate:

extern crate speculoos;

If you want macro support, include #[macro_use] to the declaration:

#[macro_use]
extern crate speculoos;

To quickly start using assertions, use the prelude module:

use speculoos::prelude::*;

Example

We’re going to make a few assertions on a String we create. Normally you would want to assert on the output of something, but we’ll just pretend that something created it.

First, we’ll create a new test with our String.

#[test]
pub fn should_be_the_correct_string() {
    let subject = "Hello World!";
}

Note that it is good practice to make sure that you name your test in a way that actually explains what it is trying to test. When you have a number of tests, and one of them fails, something like this is easier to understand:

#[test]
pub fn should_return_false_if_condition_does_not_hold() {
    // ...
}

Rather than if you have a test like this:

#[test]
pub fn should_work() {
    // ...
}

Unfortunately, our test isn’t named very well at the moment, but given the lack of context, it’ll have to do for now.

Now that we have something to test, we need to actually start asserting on it. The first part to that is to provide it to the assert_that function. Note that we need to provide it as a reference.

#[test]
pub fn should_be_the_correct_string() {
    let subject = "Hello World!";
    assert_that(&subject);
}

If we run that with cargo test, we’ll see the following output:

running 1 test
test should_be_the_correct_string ... ok

Our test compiles and passes, but we still haven’t made any assertions. Let’s make a simple one to start with. We’ll check to see that it starts with the letter ‘H’.

#[test]
pub fn should_be_the_correct_string() {
    let subject = "Hello World!";
    assert_that(&subject).starts_with(&"H");
}

Once you run this, you’ll notice that the test still passes. That’s because we’ve just proven something that was already true. Usually you’ll want to start with a failing test, and then change your code to make it pass, rather than writing the test after the implementation.

But for the purpose of exploration, let’s break the actual value. We’ll change “Hello World!” to be “ello World!”.

#[test]
pub fn should_be_the_correct_string() {
    let subject = "ello World!";
    assert_that(&subject).starts_with(&"H");
}

This time, we see that the test fails, and we also get some output from our assertion to tell us what it was, and what it was expected to be:

running 1 test
test should_be_the_correct_string ... FAILED

failures:

---- should_be_the_correct_string stdout ----
    thread 'should_be_the_correct_string' panicked at 'expected string starting with <"H"> but
    was <"ello World!">', src/lib.rs:204

Great! So we’ve just encountered a failing test. This particular case is quite easy to fix up (just add the letter ‘H’ back to the start of the String), but we can also see that the panic message tells us enough information to work that out as well.

Now, this was just a simple example, and there’s a number of features not demonstrated, but hopefully it’s enough to start you off with writing assertions in your tests using Speculoos.

Modules

Macros

Structs

A failed assertion.

An assertion.

A description for an assertion.

Traits

Functions

Wraps a subject in a Spec to provide assertions against it.

Describes an assertion.