Ceedling: a Ruby driven build and unit test harness for C

Ceedling is the glue layer over Unity, CMock and CException

Ceedling is best understood as an orchestrator rather than a testing framework in its own right. The project calls itself a build system for C projects, and describes itself as the glue for bringing together two other open source projects: Unity, an xUnit style test framework, and CMock, a code generating kit for function mocking and stubbing.

That division of labour explains most of Ceedling's design decisions. You do not hand-write Unity assertions in every test file and then hand-maintain a mock library; you write the test in the Unity style, declare which modules to mock, and Ceedling generates the mock code, compiles everything, runs the tests and reports the results. The CException project appears in the project links as a third member of the family.

There is also an alternative path. Through a plugin, Ceedling supports FFF for fake functions as an alternative to CMock's mocks and stubs, so a team that has standardised on that approach is not forced to adopt CMock's generator. Both mocking styles sit behind the same plugin mechanism.

The practical audience is anyone writing C with a test suite they have to keep rebuilding. The README is explicit that Ceedling is especially adept at building unit test suites for C projects, including in tricky embedded systems, and that it handles the rebuild mechanics so the loop between editing code and seeing a red or green result stays short.

A project configuration this short still drives the whole test loop

The configuration file is the part that makes Ceedling approachable. For a test suite project using the default gcc toolchain, the project description shows a YAML file with a build root and three path globs, and that is enough to run the tests.

:project:
  :build_root: project/build/

:paths:
  :test:
    - tests/**
  :source:
    - source/**
  :include:
    - inc/**

The structure is a Ruby symbol-keyed hierarchy: :project: holds project level settings, :paths: declares where tests, sources and headers live, and each entry is a glob. From that, Ceedling knows what to compile and what to feed to the mock generator.

Running the suite is a single command.

ceedling test:all

The task naming is colon separated, which is the pattern used across the tool: test:all for the whole suite, and the plugin documentation links show the same scheme for tools such as gcov, valgrind and cppcheck. Configuration is layered on top of this. Mixins let a project share configuration fragments, and 1.1.x added an option for inline YAML at the command line, so a variation can be expressed on the spot rather than in a file.

The repository keeps a config directory at the top level alongside lib, plugins, examples, spec and docs, and ships three example projects, examples/cipher_quest, examples/temp_sensor and examples/wondrous_forest.

Installing Ceedling means installing a Ruby gem, or pulling a Docker image

Official releases follow SemVer numbering with the pattern major.minor.patch, and the README states plainly that production systems and automated tooling should rely on official releases and not prereleases. The current state of the repository matches that guidance: 1.1.10 is the newest official release, tagged on 2026-10-08, while v1.2.0-pre.10 tagged on 2026-10-19 is a prerelease.

There are two distribution paths.

gem install ceedling --no-document

That installs the prepackaged gem from the public RubyGems repository. The no-document flag suppresses the README generation that RubyGems does by default, which keeps the install quiet and quick.

The second path is a ready-to-run Docker image published on Docker Hub under the throwtheswitch account, for teams that would rather not install Ruby and a toolchain on the build machine. The Docker images are listed alongside the gem as the official release artefacts, so a CI pipeline can pin either one to the same version number.

The project also maintains a support policy that matters for planning. The latest major.minor version receives support, with only limited support for earlier minor releases, and if you have adopted a major.minor release you are expected to move on to its bug fix patches. The Getting Started section covers installation details for both official releases and prereleases, and the repository itself is structured as a Ruby gem with a gemspec, a Rakefile, a Gemfile and a spec directory for its own tests.

Partials let one test mix mocked and real functions

The feature that changes how you structure tests is called a Partial. It allows a test file to mix mocked and real functions from the same source module, and it makes it possible to test static and inline functions without modifying the source under test.

That last part deserves emphasis. In plain C, static and inline functions are invisible to a linker, so a mocking framework cannot replace them. Working around that usually means editing production headers, adding test hooks, or accepting that those functions stay untested. The Partial mechanism sidesteps the edit, which matters most in embedded code where you cannot restructure the module casually.

The second capability in the same 1.1.x series is the documentation site, which is searchable and available both online and as a local bundle exported from the command line. The local bundle matters in regulated or air-gapped environments where a developer cannot reach the web for reference text. Support also moved to a Discourse community forum, replacing an older Google Group.

Other additions in the 1.1.x line include stock plugins for Valgrind memory checking and Cppcheck static analysis, a GCov plugin that now supports coverage reports for all sources and adds Modified Condition and Decision Coverage, and the return of compatibility between Ceedling's test preprocessing and Unity's parameterized test cases, which had been dropped with 1.0.0.

Ceedling drives external tools, so the toolchain is part of your configuration

The architecture is plugin-based and it is where most of the practical behaviour comes from. Ceedling ships built-in plugins for code coverage, test suite report generation, Continuous Integration features, IDE integration, release library builds and dependency management. The Valgrind and Cppcheck plugins are named as new stock additions in 1.1.x.

Because the plugins invoke command line tools, the assumption is that those tools exist on the machine running the tests. The default toolchain is gcc, and a project that wants Valgrind coverage or Cppcheck findings has to have those binaries installed and on the path. The README's own description of the tool is that it drives code generation and command line tools for you, and that all generated and framework code is easy to see and understand.

That design has a pleasant side effect for debugging. The documentation points to backtrace debugging options for finding the source of crashing code exercised by unit tests, and because the framework source lands in your build tree rather than inside a hidden package, you can read it and step through it. For a team that distrusts opaque test harnesses, that visibility is often the deciding factor.

The tool is also entirely command line driven, with a Visual Studio Code extension available separately in the marketplace for people who want editor integration around it.

Where Ceedling is the wrong tool

The first wrong-tool case is a project that is happy with its current build. If a team already has a Makefile or CMake setup that compiles, links and runs its C tests, adopting Ceedling means adding Ruby, a gem install and a second configuration model to a workflow that works. The overhead is real, and Ceedling's own claim is that it handles rebuild mechanics and mocking, which only pays off if you were going to build that part yourself anyway.

The second case is a project that cannot add a Ruby dependency. Some regulated or embedded pipelines are locked to a compiler binary and a make invocation, with no interpreter allowed on the build host. The Docker image addresses the toolchain side of this problem but not the dependency side, since it still brings Ruby inside the container.

The third case is a team that has adopted the newest features. A prerelease such as v1.2.0-pre.10 will move, and the README's own guidance is that automated tooling should stay on official releases. Chasing the prerelease buys early access and pays for it in upgrade churn.

On cost, the licence is MIT and the tools it drives, Unity, CMock and CException, are open source. The commercial side of the project is separate: the README points to a paid Ceedling Suite of products and to Ceedling Assist for support contracts and training, both from the same maintainers. You do not need either to run the tool, but if your organisation wants a support contract around it, that is the commercial path rather than a community channel.

Editorial conclusion

Ceedling suits embedded and general C teams that want mocking, coverage and CI integration without hand-rolling a build script, and the whole configuration for a small project is a dozen lines of YAML. It does not suit a project that already has a working Make or CMake harness for which adding Ruby is unwelcome, and it does not suit a team that needs the very latest features, since v1.2.0-pre.10 is a prerelease while 1.1.10 is the newest official release. Before adopting, run ceedling test:all on the examples/temp_sensor project, then check that your gcc toolchain, your memory checker and your CI runner all resolve from the same machine, because the tool drives external commands rather than bundling them.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. ThrowTheSwitch/Ceedling on GitHub