spectral
Fluent test assertions for Rust.
Influenced by Google Truth and other fluent assertion frameworks.
Usage
Add this to your Cargo.toml
:
[]
= "0.6.0"
Then add this to your crate:
extern crate spectral
To quickly start using assertions, simply use the prelude
module in your test module:
use *;
Overview
Spectral allows you to write your assertions in a fluent manner by seperating out what you are testing with, what you are testing against and how you are asserting.
Simple asserts
For example, to test that a produced value is equal to an expected value, you would write:
assert_that.is_equal_to;
Or that a Vec contains a certain number of elements:
let test_vec = vec!;
assert_that.has_length;
The methods avaliable for asserting depend upon the type under test and what traits are implemented.
As described below, it's recommended to use the macro form of assert_that!
to provide correct file and line numbers for failing assertions.
Failure messages
For failing assertions, the usual panic message follows the following format:
expected: <2>
but was: <1>
To add additional clarification to the panic message, you can also deliberately state what you are asserting by calling the asserting(...)
function rather than assert_that(...)
:
asserting.that.is_equal_to;
Which will produce:
test condition:
expected: <2>
but was: <1>
Using the macro form of assert_that!
will provide you with the file and line of the failing assertion as well:
expected: vec to have length <2>
but was: <1>
at location: tests/parser.rs:112
Named Subjects
To make it more obvious what your subject actually is, you can call .named(...)
after assert_that
(or asserting(...).that(...)
), which will print out the provided &str
as the subject name if the assertion fails.
assert_that(&thing.attributes).named(&"thing attributes").has_length(2);
On failure, this will display:
for subject [thing attributes]
expected: vec to have length <2>
but was: <1>
Mapping values
If you want to assert against a value contained within a struct, you can call map(...)
with a closure, which will create a new Spec
based upon the return value of the closure. You can then call any applicable assertions against the mapped value.
let test_struct = TestStruct ;
assert_that.map.is_equal_to;
Macros
If you add #[macro_use]
to the extern crate
declaration, you can also use the macro form of assert_that
and asserting
.
assert_that!.has_length
This allows you to pass through a subject to test without needing to deliberately turn it into a reference. However, for consistency, you can also use a deliberate reference in the macro as well.
assert_that!.has_length
Additionally, this will provide you with the file and line number of the failing assertion (rather than just the internal spectral panic location).
Assertions (Basic)
Note: Descriptions and examples for each of the assertions are further down in this readme.
General
is_equal_to
is_not_equal_to
matches
Booleans
is_true
is_false
Numbers
is_less_than
is_less_than_or_equal_to
is_greater_than
is_greater_than_or_equal_to
Floats (optional)
is_close_to
Options
is_some -> (returns a new Spec with the Option value)
is_none
contains_value
Paths
exists
does_not_exist
is_a_file
is_a_directory
has_file_name
Results
is_ok -> (returns a new Spec with the Ok value)
is_err -> (returns a new Spec with the Err value)
is_ok_containing
is_err_containing
Strings
starts_with
ends_with
contains
Vectors
has_length
is_empty
HashMaps
has_length
is_empty
contains_key -> (returns a new Spec with the key value)
does_not_contain_key
contains_entry
does_not_contain_entry
IntoIterator/Iterator
contains
does_not_contain
contains_all_of
mapped_contains
equals_iterator
IntoIterator
matching_contains
Optional Features
Num Crate
The num
crate is used for Float
assertions. This feature will be enabled by default, but if you don't want the dependency on num
, then simply disable it.
Assertions (Detailed)
As a general note, any type under test will usually need to implement at least Debug
. Other assertions will have varying bounds attached to them.
General
is_equal_to
Asserts that the subject and the expected value are equal. The subject type must implement PartialEq
.
Example
assert_that.is_equal_to;
Failure Message
is_not_equal_to
Asserts that the subject and the expected value are not equal. The subject type must implement PartialEq
.
Example
assert_that.is_not_equal_to;
Failure Message
matches
Accepts a function accepting the subject type which returns a bool. Returning false will cause the assertion to fail.
NOTE: The resultant panic message will only state the actual value. It's recommended that you write your own assertions rather than relying upon this.
Example
assert_that.matches;
Failure Message
Booleans
is_true
Asserts that the subject is true. The subject type must be bool
.
Example
assert_that.is_true;
Failure Message
is_false
Asserts that the subject is false. The subject type must be bool
.
Example
assert_that.is_false;
Failure Message
Numbers
is_less_than
Asserts that the subject value is less than the expected value. The subject type must implement PartialOrd
.
Example
assert_that.is_less_than;
Failure Message
is_less_than_or_equal_to
Asserts that the subject is less than or equal to the expected value. The subject type must implement PartialOrd
.
Example
assert_that.is_less_than_or_equal_to;
Failure Message
is_greater_than
Asserts that the subject is greater than the expected value. The subject type must implement PartialOrd
.
Example
assert_that.is_greater_than;
Failure Message
is_greater_than_or_equal_to
Asserts that the subject is greater than or equal to the expected value. The subject type must implement PartialOrd
.
Example
assert_that.is_greater_than_or_equal_to;
Failure Message
Floats (optional)
is_close_to
Asserts that the subject is close to the expected value by the specified tolerance. The subject type must implement Float
and Debug
.
Example
assert_that.is_close_to;
Failure Message
)
Options
is_some -> (returns a new Spec with the Option value)
Asserts that the subject is Some
. The subject type must be an Option
.
This will return a new Spec
containing the unwrapped value if it is Some
.
Example
assert_that.is_some;
Chaining
assert_that.is_some.is_equal_to;
Failure Message
is_none
Asserts that the subject is None
. The value type must be an Option
.
Example
assert_that.is_none;
Failure Message
contains_value
Asserts that the subject is a Some
containing the expected value. The subject type must be an Option
.
Example
assert_that.contains_value;
Failure Message
Paths
exists
Asserts that the subject Path
or PathBuf
refers to an existing location.
Example
assert_that.exists;
Failure Message
does_not_exist
Asserts that the subject Path
or PathBuf
does not refer to an existing location.
Example
assert_that.does_not_exist;
Failure Message
is_a_file
Asserts that the subject Path
or PathBuf
refers to an existing file.
Example
assert_that.is_a_file;
Failure Message
is_a_directory
Asserts that the subject Path
or PathBuf
refers to an existing directory.
Example
assert_that.is_a_directory;
Failure Message
has_file_name
Asserts that the subject Path
or PathBuf
has the expected file name.
Example
assert_that.has_file_name;
Failure Message
Results
is_ok -> (returns a new Spec with the Ok value)
Asserts that the subject is Ok
. The value type must be a Result
.
This will return a new Spec
containing the unwrapped value if it is Ok
.
Example
assert_that.is_ok;
Chaining
let result: = Ok;
assert_that.is_ok.is_equal_to;
Failure Message
is_err -> (returns a new Spec with the Err value)
Asserts that the subject is Err
. The value type must be a Result
.
This will return a new Spec
containing the unwrapped value if it is Err
.
Note: This used to be called is_error
, but has been renamed to match standard Rust naming.
Example
assert_that.is_err;
Chaining
let result: = Err;
assert_that.is_err.is_equal_to;
Failure Message
is_ok_containing
Asserts that the subject is an Ok
Result containing the expected value. The subject type must be a Result
.
Example
assert_that.is_ok_containing;
Failure Message
is_err_containing
Asserts that the subject is an Err
Result containing the expected value. The subject type must be a Result
.
Example
assert_that.is_err_containing;
Failure Message
Strings
starts_with
Asserts that the subject &str
or String
starts with the provided &str
.
Example
assert_that.starts_with;
Failure Message
ends_with
Asserts that the subject &str
or String
ends with the provided &str
.
Example
assert_that.ends_with;
Failure Message
contains
Asserts that the subject &str
or String
contains the provided &str
.
Example
assert_that.contains;
Failure Message
Vectors
has_length
Asserts that the length of the subject vector is equal to the provided length. The subject type must be of Vec
.
Example
assert_that.has_length;
Failure Message
is_empty
Asserts that the subject vector is empty. The subject type must be of Vec
.
Example
let test_vec: = vec!;
assert_that.is_empty;
Failure Message
HashMaps
has_length
Asserts that the length of the subject hashmap is equal to the provided length. The subject type must be of HashMap
.
Example
let mut test_map = new;
test_map.insert;
test_map.insert;
assert_that.has_length;
Failure Message
is_empty
Asserts that the subject hashmap is empty. The subject type must be of HashMap
.
Example
let test_map: = new;
assert_that.is_empty;
Failure Message
contains_key -> (returns a new Spec with the key value)
Asserts that the subject hashmap contains the expected key. The subject type must be of HashMap
.
This will return a new Spec
containing the associated value if the key is present.
Example
let mut test_map = new;
test_map.insert;
assert_that.contains_key;
Chaining
let mut test_map = new;
test_map.insert;
assert_that.contains_key.is_equal_to;
Failure Message
does_not_contain_key
Asserts that the subject hashmap does not contain the provided key. The subject type must be of HashMap
.
Example
let mut test_map = new;
test_map.insert;
assert_that.does_not_contain_key;
Failure Message
contains_entry
Asserts that the subject hashmap contains the expected key with the expected value. The subject type must be of HashMap
.
Example
let mut test_map = new;
test_map.insert;
assert_that.contains_entry;
Failure Message
does_not_contain_entry
Asserts that the subject hashmap does not contain the provided key and value. The subject type must be of HashMap
.
Example
let mut test_map = new;
test_map.insert;
assert_that.does_not_contain_entry;
Failure Message
IntoIterator/Iterator
contains
Asserts that the subject contains the provided value. The subject must implement IntoIterator
or Iterator
, and the contained type must implement PartialEq
and Debug
.
Example
let test_vec = vec!;
assert_that.contains;
Failure Message
does_not_contain
Asserts that the subject does not contain the provided value. The subject must implement IntoIterator
or Iterator
, and the contained type must implement PartialEq
and Debug
.
Example
let test_vec = vec!;
assert_that.does_not_contain;
Failure Message
contains_all_of
Asserts that the subject contains all of the provided values. The subject must implement IntoIterator
or Iterator
, and the contained type must implement PartialEq
and Debug
.
Example
let test_vec = vec!;
assert_that.contains_all_of;
Failure Message
mapped_contains
Maps the values of the subject before asserting that the mapped subject contains the provided value. The subject must implement IntoIterator, and the type of the mapped value must implement PartialEq
.
NOTE: The panic message will refer to the mapped values rather than the values present in the original subject.
Example
...
assert_that.mapped_contains;
Failure Message
equals_iterator
Asserts that the subject is equal to provided iterator. The subject must implement IntoIterator
or Iterator
, the contained type must implement PartialEq
and Debug
and the expected value must implement Iterator and Clone.
Example
let expected_vec = vec!;
let test_vec = vec!;
assert_that.equals_iterator;
Failure Message
)
)
IntoIterator
matching_contains
Asserts that the subject contains a matching item by using the provided function. The subject must implement IntoIterator
, and the contained type must implement Debug
.
Example
let mut test_into_iter = new;
test_into_iter.push_back;
test_into_iter.push_back;
test_into_iter.push_back;
assert_that.matching_contains;
Failure Message
How it works
The Spec
struct implements a number of different bounded traits which provide assertions based upon the bound type.
As a single example, length assertions are provided by the VecAssertions
trait:
Which is then implemented by Spec:
Naturally traits need to be included with a use
before they apply, but to avoid an excessive number of use
statements there is a prelude
module which re-exports commonly used assertion traits.
Creating your own
To create your own assertions, simply create a new trait containing your assertion methods and implement Spec against it.
To fail an assertion, create a new AssertionFailure
struct using from_spec(...)
within your assertion method and pass in self
.
AssertionFailure
also implements builder methods with_expected(...)
, with_actual(...)
and fail(...)
, which provides the necessary functionality to fail the test with the usual message format. If you need greater control of the failure message, you can call fail_with_message(...)
which will directly print the provided message.
In either case, any description provided using asserting(...)
will always be prepended to the panic message.
For example, to create an assertion that the length of a Vec
is at least a certain value: