Using parameterized tests¶

Parameterized tests are useful to repeat a specific test logic over a finite set of parameters.

Due to limitations on how generated parameters are passed, parameterized tests can only accept one pointer parameter; however, this is not that much of a problem since you can just pass a structure containing the context you need.

Adding parameterized tests¶

Adding parameterized tests is done by defining the parameterized test function, and the parameter generator function:

#include <criterion/parameterized.h>

ParameterizedTestParameters(suite_name, test_name) {
    void *params;
    size_t nb_params;

    // generate parameter set
    return cr_make_param_array(Type, params, nb_params);
}

ParameterizedTest(Type *param, suite_name, test_name) {
    // contents of the test
}

suite_name and test_name are the identifiers of the test suite and the test, respectively. These identifiers must follow the language identifier format.

Type is the compound type of the generated array. params and nb_params are the pointer and the length of the generated array, respectively.

Passing multiple parameters¶

As said earlier, parameterized tests only take one parameter, so passing multiple parameters is, in the strict sense, not possible. However, one can easily use a struct to hold the context as a workaround:

#include <criterion/parameterized.h>

struct my_params {
    int param0;
    double param1;
    ...
};

ParameterizedTestParameters(suite_name, test_name) {
    struct my_params params[] = {
        // parameter set
    };

    size_t nb_params = sizeof (params) / sizeof (struct my_params);
    return cr_make_param_array(struct my_params, params, nb_params);
}

ParameterizedTest(struct my_params *param, suite_name, test_name) {
    // access param.param0, param.param1, ...
}

C++ users can also use a simpler syntax before returning an array of parameters:

ParameterizedTestParameters(suite_name, test_name) {
    struct my_params params[] = {
        // parameter set
    };

    return criterion_test_params(params);
}

Dynamically allocating parameters¶

Any dynamic memory allocation done from a ParameterizedTestParameter function must be done with cr_malloc, cr_calloc, or cr_realloc.

Any pointer returned by those 3 functions must be passed to cr_free after you have no more use of it.

It is undefined behaviour to use any other allocation function (such as malloc) from the scope of a ParameterizedTestParameter function.

In C++, these methods should not be called explicitely – instead, you should use:

criterion::new_obj<Type>(params...) to allocate an object of type Type and call its constructor taking params.... The function possess the exact same semantics as new Type(params...).
criterion::delete_obj(obj) to destroy an object previously allocated by criterion::new_obj. The function possess the exact same semantics as delete obj.
criterion::new_arr<Type>(size) to allocate an array of objects of type Type and length size. Type is initialized by calling its default constructor. The function possess the exact same semantics as new Type[size].
criterion::delete_arr(array) to destroy an array previously allocated by criterion::new_arr. The function possess the exact same semantics as delete[] array.

Furthermore, the criterion::allocator<T> allocator can be used with STL containers to allocate memory with the functions above.

Freeing dynamically allocated parameter fields¶

One can pass an extra parameter to cr_make_param_array to specify the cleanup function that should be called on the generated parameter context:

#include <criterion/parameterized.h>

struct my_params {
    int *some_int_ptr;
};

void cleanup_params(struct criterion_test_params *ctp) {
    cr_free(((struct my_params *) ctp->params)->some_int_ptr);
}

ParameterizedTestParameters(suite_name, test_name) {
    static my_params params[] = {{
        .some_int_ptr = cr_malloc(sizeof (int));
    }};
    param[0].some_int_ptr = 42;

    return cr_make_param_array(struct my_params, params, 1, cleanup_params);
}

C++ users can use a more convenient approach:

#include <criterion/parameterized.h>

struct my_params {
    std::unique_ptr<int, decltype(criterion::free)> some_int_ptr;

    my_params(int *ptr) : some_int_ptr(ptr, criterion::free) {}
};

ParameterizedTestParameters(suite_name, test_name) {
    static criterion::parameters<my_params> params;
    params.push_back(my_params(criterion::new_obj<int>(42)));

    return params;
}

criterion::parameters<T> is typedef’d as std::vector<T, criterion::allocator<T>>.

Configuring parameterized tests¶

Parameterized tests can optionally recieve configuration parameters to alter their own behaviour, and are applied to each iteration of the parameterized test individually (this means that the initialization and finalization runs once per iteration). Those parameters are the same ones as the ones of the Test macro function (c.f. Configuration reference).