Module nalgebra::proptest[−][src]

proptest-related features for nalgebra data structures.

This module is only available when the proptest-support feature is enabled in nalgebra.

proptest is a library for property-based testing. While similar to QuickCheck, which may be more familiar to some users, it has a more sophisticated design that provides users with automatic invariant-preserving shrinking. This means that when using proptest, you rarely need to write your own shrinkers - which is usually very difficult - and can instead get this “for free”. Moreover, proptest does not rely on a canonical Arbitrary trait implementation like QuickCheck, though it does also provide this. For more information, check out the proptest docs and the proptest book.

This module provides users of nalgebra with tools to work with nalgebra types in proptest tests. At present, this integration is at an early stage, and only provides tools for generating matrices and vectors, and not any of the geometry types. There are essentially two ways of using this functionality:

Using the matrix function to generate matrices with constraints on dimensions and elements.
Relying on the Arbitrary implementation of MatrixMN.

The first variant is almost always preferred in practice. Read on to discover why.

Using free function strategies

In proptest, it is usually preferable to have free functions that generate strategies. Currently, the matrix function fills this role. The analogous function for column vectors is vector. Let’s take a quick look at how it may be used:

use nalgebra::proptest::matrix;
use proptest::prelude::*;

proptest! {
    #[test]
    fn my_test(a in matrix(-5 ..= 5, 2 ..= 4, 1..=4)) {
        // Generates matrices with elements in the range -5 ..= 5, rows in 2..=4 and
        // columns in 1..=4.
    }
}

In the above example, we generate matrices with constraints on the elements, as well as the on the allowed dimensions. When a failing example is found, the resulting shrinking process will preserve these invariants. We can use this to compose more advanced strategies. For example, let’s consider a toy example where we need to generate pairs of matrices with exactly 3 rows fixed at compile-time and the same number of columns, but we want the number of columns to vary. One way to do this is to use proptest combinators in combination with matrix as follows:

use nalgebra::{Dynamic, MatrixMN, U3};
use nalgebra::proptest::matrix;
use proptest::prelude::*;

type MyMatrix = MatrixMN<i32, U3, Dynamic>;

/// Returns a strategy for pairs of matrices with `U3` rows and the same number of
/// columns.
fn matrix_pairs() -> impl Strategy<Value=(MyMatrix, MyMatrix)> {
    matrix(-5 ..= 5, U3, 0 ..= 10)
        // We first generate the initial matrix `a`, and then depending on the concrete
        // instances of `a`, we pick a second matrix with the same number of columns
        .prop_flat_map(|a| {
            let b = matrix(-5 .. 5, U3, a.ncols());
            // This returns a new tuple strategy where we keep `a` fixed while
            // the second item is a strategy that generates instances with the same
            // dimensions as `a`
            (Just(a), b)
        })
}

proptest! {
    #[test]
    fn my_test((a, b) in matrix_pairs()) {
        // Let's double-check that the two matrices do indeed have the same number of
        // columns
        prop_assert_eq!(a.ncols(), b.ncols());
    }
}

The `Arbitrary` implementation

If you don’t care about the dimensions of matrices, you can write tests like these:

use nalgebra::{DMatrix, DVector, Dynamic, Matrix3, MatrixMN, Vector3, U3};
use proptest::prelude::*;

proptest! {
    #[test]
    fn test_dynamic(matrix: DMatrix<i32>) {
        // This will generate arbitrary instances of `DMatrix` and also attempt
        // to shrink/simplify them when test failures are encountered.
    }

    #[test]
    fn test_static_and_mixed(matrix: Matrix3<i32>, matrix2: MatrixMN<i32, U3, Dynamic>) {
        // Test some property involving these matrices
    }

    #[test]
    fn test_vectors(fixed_size_vector: Vector3<i32>, dyn_vector: DVector<i32>) {
        // Test some property involving these vectors
    }
}

While this may be convenient, the default strategies for built-in types in proptest can generate any number, including integers large enough to easily lead to overflow when used in matrix operations, or even infinity or NaN values for floating-point types. Therefore Arbitrary is rarely the method of choice for writing property-based tests.

Notes on shrinking

Due to some limitations of the current implementation, shrinking takes place by first shrinking the matrix elements before trying to shrink the dimensions of the matrix. This unfortunately often leads to the fact that a large number of shrinking iterations are necessary to find a (nearly) minimal failing test case. As a workaround for this, you can increase the maximum number of shrinking iterations when debugging. To do this, simply set the PROPTEST_MAX_SHRINK_ITERS variable to a high number. For example:

PROPTEST_MAX_SHRINK_ITERS=100000 cargo test my_failing_test

Structs

DimRange	A range of allowed dimensions for use in generation of matrices.
MatrixParameters	Parameters for arbitrary matrix generation.
MatrixStrategy	A strategy for generating matrices.
MatrixValueTree	A value tree for matrices.

Functions