Skip to content

Ceedling Plugins

Ceedling includes a number of built-in plugins. Each plugin linked below includes full documentation of its capabilities and configuration options.

Need a CI test build report?

Test Suite Report Log Factory provides a handful of popular reports and the ability to create your own.

Have custom needs?

Many find the handy-dandy Command Hooks plugin is often enough as it allows you to connect your own scripts and tools to Ceedling build steps. Alternatively, you can create your own plugins.

See the :plugins configuration reference for how to enable built-in plugins and load custom plugins in your project.

Understanding plugin build duplication

Warning

Build-related plugins intentionally execute duplicated builds.

Plugins including Gcov, Bullseye, Valgrind, and Sanitize recreate test build tasks. That is, the command line build task test:foo also exists as gcov:foo, bullseye:foo, valgrind:foo, and/or sanitize:foo if these plugins are enabled. Each of these triggers a full rebuild of the named test with instrumentation activated. This duplication is intentional and very necessary.

These plugins modify executable code or the environment in which a test suite executable runs. Duplicating and segregating the build tasks addresses several important issues:

  1. Conflicting interactions. Enabling multiple plugins without duplicated tasks (i.e. integrated build tasks) can bring about conflicts and undefined behavior. For instance, Gcov’s instrumentation does not necessarily play nice with Valgrind’s memory-instrumented emulation runtime, and the two should be kept entirely segregated. Likewise, a sanitizer-instrumented test executable cannot run under Valgrind at all.
  2. Unforeseen effects. These plugins can directly alter the functioning of the code under test. For instance, coverage instrumentation inserted into your compiled code can alter its function or timing. As such, it is vital to maintain distinct builds to compare them. Your vanilla test suite build may function slightly differently than the coverage-instrumented build.
  3. Optional instrumentation. The <plugin>: command line task convention also provides a very simple opt-in scheme. Plugins automatically enabled for every build drives the desire to optional disable them. Valgrind testing can require 25-50x the execution time of a test suite, and you likely will want the option to easily disable it. While Ceedling could certainly provide that option at the command line for otherwise always-on plugins, this plugin task namespacing scheme naturally accomplished this along with the needs of (1) and (2).

Note

A duplicated build task is a delta build. Ceedling skips unneeded work in a gcov:, bullseye:, valgrind:, or sanitize: build in the same way it does in a standard test: build.

Each of these plugins maintains its own separate delta build cache, apart from plain test builds and from each other. A file with no role specific to a given plugin will still be rebuilt the first you run that plugin’s build. This happens because each build tracks state in its own dependency cache, not because of the file itself.

Directory

Console Test Results

  • report_tests_pretty_stdout

    The default plugin for printing test results to the console. Produces a well-formatted list of summary statistics, ignored and failed tests, and any extraneous output collected from test fixtures.

  • report_tests_ide_stdout

    Lists failed and ignored tests in the shape of GCC diagnostics, which Eclipse CDT, VS Code, CLion, and other IDEs read as problems that link to each test.

  • report_tests_gtestlike_stdout

    Prints test results to the console in a format that mimics Google Test’s output — both human readable and recognized by a variety of reporting tools, IDEs, and CI servers.

  • report_tests_teamcity_stdout

    Processes test results into TeamCity service messages printed to the console, allowing the CI server to extract build steps and test results from software builds.

Test Results Reports

  • report_tests_log_factory

    Produces any or all of four useful test suite reports in JSON, JUnit XML, CppUnit XML, or HTML format. Also provides a mechanism for custom reports with a small amount of Ruby rather than a full plugin.

  • report_tests_raw_output_log

    Captures extraneous console output generated by test executables — typically for debugging — to log files named after the test executables.

  • report_build_warnings_log

    Scans the output of build tools for console warning notices and collects them in a simple text file and optional SARIF and JSON reports.

Static & Dynamic Analysis

Ceedling includes integrated gdb support

Tracking down weird test failures can require multiple approaches and tools. Diagnosing a bug causing a test executable crash can benefit from either or both of these plugins plus Ceedling’s backtrace feature.

  • cppcheck

    Adds Ceedling tasks to execute static analysis with Cppcheck. Cppcheck helps find bugs related to undefined behavior, dangerous code patterns, and coding style. Cppcheck is even able to analyze non-standard syntax C/C++ code, as is common in embedded projects. The plugin can produce various reports.

  • valgrind

    Adds Ceedling tasks to run test executables under Valgrind memory error detection. Valgrind catches memory leaks, invalid accesses, and use-after-free bugs. The plugin produces per-test log files in the build artifacts directory.

  • sanitize

    Adds Ceedling tasks to build and run test executables with the compiler’s sanitizers. ASan, UBSan, and LeakSanitizer find memory errors, undefined behavior, and leaks as tests run. Findings fail the build and can be written as text, JSON, and SARIF reports.

Code Coverage

  • gcov

    Adds Ceedling tasks to execute tests with GNU code coverage instrumentation. Manages use of gcov, optional Python-based GCovr, and .Net-based ReportGenerator to produce coverage reports in a variety of formats.

  • bullseye

    Adds Ceedling tasks to execute tests with code coverage instrumentation provided by the commercial Bullseye tool, which provides visualization and report generation from the coverage results.

    Note: Bullseye requires a commercial license. It was disabled as of 1.0.0 and is enabled again as of 1.2.0.

Mocking & Test Doubles

Build Integration

  • command_hooks

    Connects Ceedling’s build events to tool entries you define. Easily attach your own scripts or command line utilities to build steps without writing a full custom plugin.

  • compile_commands_json_db

    Creates a JSON Compilation Database — a compile_commands.json file useful to any editor or IDE that implements clangd Language Server Protocol support.

  • beep

    Provides a simple audio notification when a test build completes suite execution or fails due to a build error, intended to support developers running time-consuming test suites locally in the background.

Project & Release Builds

  • module_generator

    Save time in Test-Driven Development by generating a templated triplet of source file, header file, and test file — scaffolded such that they refer to one another — with a variety of options through command line tasks.

  • dependencies

    Manages release build dependencies (e.g. static libraries or built tools) including fetching dependencies, calling a dependency’s build process, and deploying resulting executables and dynamic libraries.