uploaded 2 months ago

A modern, C++-native, test framework for unit-tests, TDD and BDD - using C++14, C++17 and later


# Catch2 unit testing library This component is an ESP-IDF wrapper around [Catch2 unit testing library]( Tests written using this component can be executed both on real hardware and on the host. ## Using Catch2 in ESP-IDF ### Example To get started with Catch2 quickly, use the example provided along with this component: ```bash create-project-from-example "espressif/catch:catch2-test" cd catch2-test set-target esp32 build flash monitor ``` The example can also be used on host (Linux): ```bash --preview set-target linux build monitor ``` ### Writing tests Tests and assertions are written as usual for Catch2, refer to the [official documentation]( for more details. Here is a simple example: ```c++ #include <catch2/catch_test_macros.hpp> TEST_CASE("Test case 1") { REQUIRE(1 == 1); } ``` To ensure the test cases are linked into the application, use `WHOLE_ARCHIVE` argument when calling `idf_component_register()` in CMake. For example: ```cmake idf_component_register(SRCS "test_main.cpp" "test_cases.cpp" INCLUDE_DIRS "." WHOLE_ARCHIVE) ``` ### Enabling C++ exceptions Catch2 relies on C++ exceptions for assertion handling. To get most benefits out of Catch2, it is recommended to have exceptions enabled in the project (`CONFIG_COMPILER_CXX_EXCEPTIONS=y`). ### Stack size Catch2 uses significant amount of stack space — around 8kB, plus the stack space used by the test cases themselves. Therefore it is necessary to increase the stack size of the `main` task using the `CONFIG_ESP_MAIN_TASK_STACK_SIZE` option, or to invoke Catch from a new task with sufficient stack size. It is also recommended to keep `CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK` or `CONFIG_ESP_SYSTEM_HW_STACK_GUARD` options enabled to detect stack overflows. ### Invoking the test runner Catch2 test framework can implement the application entry point (`main(int, char**)`) which calls the test runner. This functionality is typically used via the `CATCH_CONFIG_MAIN` macro. However ESP-IDF applications use `app_main(void)` function as an entry point, so the approach with `CATCH_CONFIG_MAIN` doesn't work. Instead, invoke Catch2 in your `app_main` as follows: ```c++ #include <catch2/catch_session.hpp> extern "C" void app_main(void) { // prepare command line arguments to Catch2 const int argc = 1; const char* argv[2] = {"target_test_main", NULL}; // run the tests int result = Catch::Session().run(argc, argv); // ... handle the result ``` ### Integration with ESP-IDF `console` component This component provides a function to register an ESP-IDF console command to invoke Catch2 test cases: ```c++ esp_err_t register_catch2(const char* cmd_name); ``` This function registers a command with the specified name (for example, "test") with ESP-IDF `console` component. The command passes all the arguments to Catch2 test runner. This makes it possible to invoke tests from an interactive console running on an ESP chip. To try this functionality, use `catch2-console` example: ```bash create-project-from-example "espressif/catch:catch2-console" cd catch2-console set-target esp32 build flash monitor ```

readme of catch2-console example

# Catch2 console example This example shows how to combine Catch2 test framework with ESP-IDF `console` component. In this example, you can execute test cases from an interactive console on an ESP chip. ## Using the example To run the example, build and flash the project as usual. For example, with an ESP32 chip: ```bash set-target esp32 build flash monitor ``` In the console, use `test` command to invoke Catch2. `test` accepts the same command line arguments as Catch2 tests on the host: - `test -h` — prints command line argument reference - `test --list-tests` — lists all the registered tests - `test` — runs all the registered tests - `test <test name|pattern|tags>` — runs specific tests [See Catch2 documentation]( for the complete command line argument reference.

readme of catch2-test example

# Catch2 example This example should help you get started with Catch2 test framework. ## Using the example To run the example on an ESP32, build and flash the project as usual: ```bash set-target esp32 build flash monitor ``` The example can also be used on Linux host: ```bash --preview set-target linux build monitor ``` ## Example structure - [main/idf_component.yml](main/idf_component.yml) adds a dependency on `espressif/catch2` component. - [main/CMakeLists.txt](main/CMakeLists.txt) specifies the source files and registers the `main` component with `WHOLE_ARCHIVE` option enabled. - [main/test_main.cpp](main/test_main.cpp) implements the application entry point which calls the test runner. - [main/test_cases.cpp](main/test_cases.cpp) implements one trivial test case. - [sdkconfig.defaults](sdkconfig.defaults) sets the options required to run the example: enables C++ exceptions and increases the size of the `main` task stack. ## Expected output ``` Randomness seeded to: 3499211612 =============================================================================== All tests passed (1 assertion in 1 test case) Test passed. ```

Supports all targets

License: BSL-1.0

To add this component to your project, run: add-dependency "espressif/catch2^3.4.0~1"

or download archive


  • ESP-IDF >=5.0.0
  • Examples:


    more details


    more details


    • Downloaded in total
      Downloaded in total 6 times
    • Downloaded this version
      This version: 5 times


    espressif/catch2 version: 3.4.0~1 |