diff --git a/docs/test-macros.rst b/docs/test-macros.rst index 1bcf5fa7d..b9ceca85f 100644 --- a/docs/test-macros.rst +++ b/docs/test-macros.rst @@ -73,6 +73,41 @@ documenting known bugs that cannot yet be fixed. CHECK_EQUAL(expected, buggy_function()); // currently produces wrong result } +Parameterized Tests +-------------------- + +Write a test body once, then run it against several cases without repeating +it. Each case still becomes its own ordinary test - independently named, +filterable, and reported on failure - so a failing case never hides its +siblings. + +``PARAMETERIZED_TEST(group, name, ParamsType)`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:c:macro:`PARAMETERIZED_TEST` defines the shared body, taking a ``params`` +value of ``ParamsType``. Write this before the +:c:macro:`PARAMETERIZED_TEST_CASE` lines that use it. + +``PARAMETERIZED_TEST_CASE(group, name, id, expr)`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:c:macro:`PARAMETERIZED_TEST_CASE` registers one case as +``TEST(group, name_id)``, calling the shared body with the value of +``expr``. + +.. literalinclude:: ../examples/tests/ParameterizedTest.test.cpp + :language: cpp + :lines: 1-37 + +To reuse the same set of cases across several checks - for example, running +an interface-conformance suite against every implementation of an interface - +write a small local macro that expands to one +:c:macro:`PARAMETERIZED_TEST_CASE` per case and invoke it after each body: + +.. literalinclude:: ../examples/tests/ParameterizedTest.test.cpp + :language: cpp + :lines: 39-103 + Metadata -------- @@ -171,6 +206,8 @@ These bridge C test files into the C++ test runner. See - Same as above but expected to fail * - :c:macro:`TEST_ORDERED_C_WRAPPER(group, name, level) ` - Wires a C test function into a :c:macro:`TEST_ORDERED` + * - :c:macro:`PARAMETERIZED_TEST_CASE_C_WRAPPER(group, name, id, ParamsType, expr) ` + - Wires one case into a C :c:macro:`PARAMETERIZED_TEST` body Examples -------- @@ -187,3 +224,5 @@ Examples - C-wrapper two-file pattern with :c:macro:`TEST_GROUP_SETUP`, :c:macro:`TEST`, and :c:macro:`TEST_C_WRAPPER` * - :source:`OrderedTest.test.cpp ` - :c:macro:`TEST_ORDERED` alongside regular :c:macro:`TEST` + * - :source:`ParameterizedTest.test.cpp ` + - :c:macro:`PARAMETERIZED_TEST` and :c:macro:`PARAMETERIZED_TEST_CASE`, including reusing one case list across several checks diff --git a/examples/tests/CMakeLists.txt b/examples/tests/CMakeLists.txt index 109b8e06c..7e02bc66b 100644 --- a/examples/tests/CMakeLists.txt +++ b/examples/tests/CMakeLists.txt @@ -29,6 +29,7 @@ add_executable(ExampleTests MockDocumentation.test.c MockDocumentation.test.cpp OrderedTest.test.cpp + ParameterizedTest.test.cpp Printer.test.cpp TeamCityOutputPlugin.cpp TeamCityTestOutput.test.cpp diff --git a/examples/tests/ParameterizedTest.test.cpp b/examples/tests/ParameterizedTest.test.cpp new file mode 100644 index 000000000..26c68a0d5 --- /dev/null +++ b/examples/tests/ParameterizedTest.test.cpp @@ -0,0 +1,103 @@ +#include "mu/tiny/test.hpp" + +// --- 1. Plain data-driven table, the classic pytest.mark.parametrize case --- + +namespace { +struct SquareCase +{ + int input; + int expected; +}; +} // namespace + +TEST_GROUP(NumberChecks) +{}; + +PARAMETERIZED_TEST(NumberChecks, square_matches_expected, SquareCase) +{ + CHECK_EQUAL(params.expected, params.input * params.input); +} +PARAMETERIZED_TEST_CASE( + NumberChecks, + square_matches_expected, + two, + (SquareCase{ 2, 4 }) +) +PARAMETERIZED_TEST_CASE( + NumberChecks, + square_matches_expected, + three, + (SquareCase{ 3, 9 }) +) +PARAMETERIZED_TEST_CASE( + NumberChecks, + square_matches_expected, + negative_four, + (SquareCase{ -4, 16 }) +) + +namespace { + +class FooInterface +{ +public: + virtual const char* class_name() const = 0; + virtual int foo(int value) const = 0; + virtual ~FooInterface() = default; +}; + +class ImplA : public FooInterface +{ +public: + const char* class_name() const override { return "ImplA"; } + int foo(int value) const override { return value + 1; } +}; + +class ImplB : public FooInterface +{ +public: + const char* class_name() const override { return "ImplB"; } + int foo(int value) const override { return value + 10; } +}; + +struct FooParams +{ + FooInterface* sut; + const char* expected_name; +}; + +// One persistent instance per implementation, handed out by address. A +// fresh-per-test SUT is also possible - construct it directly in the case +// expression instead of taking the address of a static. +FooParams impl_a_params() +{ + static ImplA impl; + return { &impl, "ImplA" }; +} + +FooParams impl_b_params() +{ + static ImplB impl; + return { &impl, "ImplB" }; +} + +} // namespace + +#define FOO_CASES(testName) \ + PARAMETERIZED_TEST_CASE(FooContract, testName, ImplA, (impl_a_params())) \ + PARAMETERIZED_TEST_CASE(FooContract, testName, ImplB, (impl_b_params())) + +TEST_GROUP(FooContract) +{}; + +PARAMETERIZED_TEST(FooContract, class_name_matches, FooParams) +{ + STRCMP_EQUAL(params.expected_name, params.sut->class_name()); +} +FOO_CASES(class_name_matches) + +PARAMETERIZED_TEST(FooContract, foo_returns_greater_value, FooParams) +{ + CHECK(params.sut->foo(1) > 1); +} +FOO_CASES(foo_returns_greater_value) diff --git a/include/mu/tiny/test.h b/include/mu/tiny/test.h index 0377a8050..0d3a018ac 100644 --- a/include/mu/tiny/test.h +++ b/include/mu/tiny/test.h @@ -324,6 +324,24 @@ extern "C" #define XFAIL_TEST(group_name, test_name) \ extern void expect_fail_##group_name##_##test_name##_wrapper_c(void); \ void expect_fail_##group_name##_##test_name##_wrapper_c(void) + +/** + * @brief Define the C body of a parameterized test. + * + * The function stub is called once per case by the corresponding + * @c PARAMETERIZED_TEST_CASE_C_WRAPPER macro (mu/tiny/test.hpp) in the C++ + * bridge file. @p ParamsType must be a type visible to both this file and + * the bridge file - typically a plain struct declared in a shared header. + * + * @param group_name Test group. + * @param test_name Base test name, shared by every case. + * @param ParamsType Type received by value as @c params. + */ +#define PARAMETERIZED_TEST(group_name, test_name, ParamsType) \ + extern void parameterized_##group_name##_##test_name##_wrapper_c( \ + ParamsType \ + ); \ + void parameterized_##group_name##_##test_name##_wrapper_c(ParamsType params) #endif /** diff --git a/include/mu/tiny/test.hpp b/include/mu/tiny/test.hpp index 09fab8135..8cd503434 100644 --- a/include/mu/tiny/test.hpp +++ b/include/mu/tiny/test.hpp @@ -183,6 +183,56 @@ } /* namespace */ \ void EXPECT_FAIL##testGroup##_##testName##_Test::test_body() +/** + * @brief Define the shared body of a parameterized test. + * + * Write the body once, then list each case with @ref PARAMETERIZED_TEST_CASE. + * Every case expands to an ordinary @ref TEST() named "testName_id" - + * independently registered, filterable by name, and reported on failure like + * any other test. A case failing does not affect its siblings. + * + * @param testGroup An already-declared @ref TEST_GROUP. + * @param testName Base name; each case run as "testName_id". + * @param ParamsType Type passed by value to the body as @c params. + * + * @code{.cpp} + * struct SquareCase { int input; int expected; }; + * + * PARAMETERIZED_TEST(NumberChecks, square_matches_expected, SquareCase) + * { + * CHECK_EQUAL(params.expected, params.input * params.input); + * } + * PARAMETERIZED_TEST_CASE(NumberChecks, square_matches_expected, two, + * (SquareCase{2, 4})) + * PARAMETERIZED_TEST_CASE(NumberChecks, square_matches_expected, three, + * (SquareCase{3, 9})) + * @endcode + * + * @see PARAMETERIZED_TEST_CASE + */ +#define PARAMETERIZED_TEST(testGroup, testName, ParamsType) \ + void testGroup##_##testName##_body(ParamsType params) + +/** + * @brief Register one case of a parameterized test. + * + * Must follow the matching @ref PARAMETERIZED_TEST definition in the same + * translation unit. + * + * @param testGroup Same group passed to the matching @ref PARAMETERIZED_TEST. + * @param testName Same name passed to the matching @ref PARAMETERIZED_TEST. + * @param id Short, unique-within-testName identifier for this case; + * becomes the "_id" suffix of the generated test name. + * @param expr Expression producing a ParamsType value for this case. + * + * @see PARAMETERIZED_TEST + */ +#define PARAMETERIZED_TEST_CASE(testGroup, testName, id, expr) \ + TEST(testGroup, testName##_##id) \ + { \ + testGroup##_##testName##_body(expr); \ + } + /** * @brief Attach a key/value property to the currently running test. * @@ -281,4 +331,27 @@ expect_fail_##group_name##_##test_name##_wrapper_c(); \ } +/** + * @brief Bridge a C-defined parameterized test body into one case. + * + * @p ParamsType must match the type used in the corresponding C-side @ref + * PARAMETERIZED_TEST definition (mu/tiny/test.h). + * + * @param testGroup Test group. + * @param testName Base name, matching the C-side @ref PARAMETERIZED_TEST. + * @param id Short, unique-within-testName identifier for this case. + * @param ParamsType Type passed by value to the C body. + * @param expr Expression producing a ParamsType value for this case. + */ +#define PARAMETERIZED_TEST_CASE_C_WRAPPER( \ + testGroup, testName, id, ParamsType, expr \ +) \ + extern "C" void parameterized_##testGroup##_##testName##_wrapper_c( \ + ParamsType \ + ); \ + TEST(testGroup, testName##_##id) \ + { \ + parameterized_##testGroup##_##testName##_wrapper_c(expr); \ + } + #endif diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt index 67341a2cf..9e08c5db3 100644 --- a/tests/CMakeLists.txt +++ b/tests/CMakeLists.txt @@ -27,6 +27,9 @@ add_executable(mutiny_test src/OrderedTestC.test.c src/Ordered.test.cpp src/OrderedTestC.test.cpp + src/ParameterizedTest.test.cpp + src/ParameterizedTestC.test.c + src/ParameterizedTestC.test.cpp src/Preprocessor.test.cpp src/SetPointerPlugin.test.cpp src/String.test.cpp diff --git a/tests/src/ParameterizedTest.h b/tests/src/ParameterizedTest.h new file mode 100644 index 000000000..9007b458a --- /dev/null +++ b/tests/src/ParameterizedTest.h @@ -0,0 +1,19 @@ +#ifndef INCLUDED_PARAMETERIZEDTEST_H +#define INCLUDED_PARAMETERIZEDTEST_H + +#ifdef __cplusplus +extern "C" +{ +#endif + + typedef struct + { + int input; + int expected; + } SquareCase; + +#ifdef __cplusplus +} +#endif + +#endif /* INCLUDED_PARAMETERIZEDTEST_H */ diff --git a/tests/src/ParameterizedTest.test.cpp b/tests/src/ParameterizedTest.test.cpp new file mode 100644 index 000000000..e434eefd4 --- /dev/null +++ b/tests/src/ParameterizedTest.test.cpp @@ -0,0 +1,96 @@ +#include "mu/tiny/test/Shell.hpp" + +#include "mu/tiny/test.hpp" + +TEST_GROUP(ParameterizedTest) +{}; + +// Each case runs as its own TEST(), named "testName_id". +PARAMETERIZED_TEST( + ParameterizedTest, + generated_test_is_named_correctly, + const char* +) +{ + STRCMP_EQUAL(params, mu::tiny::test::Shell::get_current()->get_name()); +} +PARAMETERIZED_TEST_CASE( + ParameterizedTest, + generated_test_is_named_correctly, + alpha, + ("generated_test_is_named_correctly_alpha") +) +PARAMETERIZED_TEST_CASE( + ParameterizedTest, + generated_test_is_named_correctly, + beta, + ("generated_test_is_named_correctly_beta") +) + +// Each case's expression is evaluated fresh when its TEST() runs, and the +// resulting value reaches the shared body unchanged. +namespace { +struct SquareCase +{ + int input; + int expected; +}; +} // namespace + +PARAMETERIZED_TEST(ParameterizedTest, delivers_case_value, SquareCase) +{ + CHECK_EQUAL(params.expected, params.input * params.input); +} +PARAMETERIZED_TEST_CASE( + ParameterizedTest, + delivers_case_value, + two, + (SquareCase{ 2, 4 }) +) +PARAMETERIZED_TEST_CASE( + ParameterizedTest, + delivers_case_value, + three, + (SquareCase{ 3, 9 }) +) +PARAMETERIZED_TEST_CASE( + ParameterizedTest, + delivers_case_value, + negative_four, + (SquareCase{ -4, 16 }) +) + +// The same case list can be reused across several PARAMETERIZED_TEST bodies +// by writing a small local macro that expands to one PARAMETERIZED_TEST_CASE +// per case - the pattern an interface-conformance suite relies on to apply +// its checks to every implementation under test. +namespace { +int implementation_a_value() +{ + return 1; +} +int implementation_b_value() +{ + return 2; +} +} // namespace + +#define REUSED_CASES(testName) \ + PARAMETERIZED_TEST_CASE( \ + ParameterizedTest, testName, ImplA, (implementation_a_value()) \ + ) \ + PARAMETERIZED_TEST_CASE( \ + ParameterizedTest, testName, ImplB, (implementation_b_value()) \ + ) + +PARAMETERIZED_TEST(ParameterizedTest, reused_cases_are_positive, int) +{ + CHECK(params > 0); +} +REUSED_CASES(reused_cases_are_positive) + +PARAMETERIZED_TEST(ParameterizedTest, reused_cases_are_under_ten, int) +{ + CHECK(params < 10); +} +REUSED_CASES(reused_cases_are_under_ten) diff --git a/tests/src/ParameterizedTestC.test.c b/tests/src/ParameterizedTestC.test.c new file mode 100644 index 000000000..136d3c044 --- /dev/null +++ b/tests/src/ParameterizedTestC.test.c @@ -0,0 +1,8 @@ +#include "ParameterizedTest.h" + +#include "mu/tiny/test.h" + +PARAMETERIZED_TEST(ParameterizedTestC, square_matches_expected, SquareCase) +{ + CHECK_EQUAL_INT(params.expected, params.input * params.input); +} diff --git a/tests/src/ParameterizedTestC.test.cpp b/tests/src/ParameterizedTestC.test.cpp new file mode 100644 index 000000000..ef095855b --- /dev/null +++ b/tests/src/ParameterizedTestC.test.cpp @@ -0,0 +1,21 @@ +#include "ParameterizedTest.h" + +#include "mu/tiny/test.hpp" + +TEST_GROUP(ParameterizedTestC) +{}; + +PARAMETERIZED_TEST_CASE_C_WRAPPER( + ParameterizedTestC, + square_matches_expected, + two, + SquareCase, + (SquareCase{ 2, 4 }) +) +PARAMETERIZED_TEST_CASE_C_WRAPPER( + ParameterizedTestC, + square_matches_expected, + three, + SquareCase, + (SquareCase{ 3, 9 }) +)