`:test_runner`

Configure test runner generation

Warning

Unless you have advanced or unique needs, Unity test runner generation configuration in Ceedling is generally not needed.

Test runner overview

The format of Ceedling test files — the C files that contain unit test cases — is intentionally simple. It’s pure code and all legit C with #include statements, simple functions for test cases, and optional setUp() and tearDown() functions.

To create test executables, we need a main() and a variety of calls to the Unity framework to “hook up” all your test cases into a test suite. You can do this by hand, of course, but it’s tedious and needed updates as code evolves are easily forgotten.

Unity & test runners

Unity provides a script able to generate a test runner in C for you. It relies on Ceedling conventions used in your test files. Ceedling takes this a step further by calling this script for you with all the needed parameters.

Test runner generation is configurable. The :test_runner section of your Ceedling project file allows you to pass options to Unity’s runner generation script. Based on other Ceedling options, Ceedling also sets certain test runner generation configuration values for you.

Test runner configuration options are documented in the Unity project.

`:test_runner` ↳ `:cmdline_args`

Enables command line arguments in generated test runners. Two Ceedling features select test cases through these arguments, and Ceedling enables this option automatically, with a notice, whenever either is in use:

:project ↳ :use_backtrace set to anything other than :none. Backtraces rerun test cases by name.
The command line test case filters --test-case and --exclude_test_case.

Default: FALSE

Environment limitations

Be aware that :cmdline_args works well in desktop, native testing but is generally unsupported by emulators running test executables.

The idea of command line arguments passed to an executable is generally only possible with desktop command line terminals.

`:test_runner` ↳ `:rng_seed`

Seeds the randomization used by :unity ↳ :shuffle_tests to shuffle the Unity runner test case execution order. :rng_seed has no effect unless :shuffle_tests is enabled.

Left at its default of 0, Unity seeds the shuffle from the current time causing a different execution order every time a test runner executes. Set a fixed, nonzero value for a reproducible shuffled order (e.g. to debug an order-dependent failure without test case order moving around run to run).

Default: 0

Example `:test_runner` YAML

:test_runner:
  # Insert additional #include statements in a generated runner
  :includes:
    - Foo.h
    - Bar.h

:test_runner