🌱 Ceedling Visual Studio Code Extension

Ceedling is a handy-dandy build system for C projects. This Visual Studio Code extension runs your Ceedling test suite using VS Code’s built-in Testing view.

Supporting this work

Ceedling and its complementary ThrowTheSwitch pieces and parts are and always will be freely available and open source.

💼 Ceedling Suite is a growing collection of paid products and services built around Ceedling to help you do even more. Ceedling Assist for support contracts and training is now available.

🙏🏻 Please consider supporting Ceedling and this extension as a Github Sponsor

Features

• Displays all detected tests and suites with their state in VS Code’s built-in Test Explorer (the Testing view).
• Adds gutter run/debug icons and CodeLens-style affordances to your test files, generated automatically from each test’s location.
• Shows a failed test’s message and failing line directly in the Test Explorer and the editor.
• Runs a single test function in isolation, without running the rest of its file.
• Can be configured to report compiler and linker problems inline in the editor and in the Problems panel.

Requirements

VS Code

Requires VS Code 1.71.0 or later.

Ceedling

Requires Ceedling 1.0.0 or later. Ceedling 1.0.0 and 1.1.0 are both supported.

Ceedling documentation

Parameterized Unity test cases

Parametrized tests using Unity’s TEST_CASE() / TEST_RANGE() require :unity ↳ :use_param_tests: ⇒ true in your project configuration.

Ceedling 1.0.0 also requires test-file preprocessing disabled (:project ↳ :use_test_preprocessor ⇒ :none (default) or :mocks). Ceedling 1.0.0 cannot preserve these macros through preprocessing, but Ceedling 1.1.0 supports parametrized tests with or without preprocessing.

Getting started

• Install the extension and restart VS Code.
• Open the workspace or folder containing your Ceedling project.
• Configure your Ceedling project configuration filepath in VS Code’s settings if required see below.
• Configure the shell path where Ceedling is installed in VS Code’s settings if required (Windows) see below.
• Enable and configure the report_tests_log_factory Ceedling plugin with the cppunit option in your Ceedling project configuration. This generates an XML test report on which this extension depends.
• Open the Testing view.
• Run your tests using the run/debug icons in VS Code’s Testing view or in your test file’s gutter.

Running and debugging tests

Run and debug tests from the Testing view, or from the gutter next to a test in the editor.

The Testing view’s toolbar also has Clean and Clobber buttons. They run ceedling clean and ceedling clobber against the current project.

Configuration

Options

This table of options should be read as ceedlingExplorer.<property>.

ceedlingExplorer Property	Description
.projects	An array of objects with the path to the Ceedling project (or yml-file) to use (relative to the workspace folder). See below for its path, debugLaunchConfig, and name properties.
.shellPath	The path to the shell where Ceedling is installed. By default (or if this option is set to null), it uses the OS default shell.
.prettyTestLabel	Shortens the test label in the Testing explorer by dropping its leading prefix (e.g. inactive test_BlinkTaskShouldToggleLed vs. active BlinkTaskShouldToggleLed). Inactive: Active:
.prettyTestFileLabel	Shortens the test file label in the Testing explorer by dropping its path, leading prefix, and file type (e.g. inactive test/LEDs/test_BlinkTask.c vs. active BlinkTask). Inactive: Active:
.testCommandArgs	The command line arguments used to run Ceedling tests. The first argument has to literally contain the ${TEST_ID} tag. The value ["test:${TEST_ID}"] is used by default. For example, the arguments "test:${TEST_ID}", "gcov:${TEST_ID}", "utils:gcov" can be used to run tests and generate a gcov report.
.problemMatching	Configuration of compiler/linker problem matching. See the Problem matching section for details.
.testCaseMacroAliases	An array of aliases for Unity’s parameterized test TEST_CASE macro. By default it is ["TEST_CASE"].
.testRangeMacroAliases	An array of aliases for Unity’s parameterized test TEST_RANGE macro. By default it is ["TEST_RANGE"].
.ansiEscapeSequencesRemoved	Whether ANSI escape sequences are removed from Ceedling $stdout and $stderr. By default it is true.

ceedlingExplorer.projects properties

• path: can point either to a directory containing a "project.yml" file or directly to another .yml file (with the respective project.yml in the same directory). This path should be relative to the workspace root directory.
• debugLaunchConfig: must be the name property of the launch config (launch.json) that is used for this project. The ${command:ceedlingExplorer.debugTestExecutable} must still be used.
• name (optional): used as the name for the folder containing the tests in the test explorer.

Problem matching

Problem matching is the mechanism that scans Ceedling output text for known error/warning/info strings and reports these inline in the editor and in the Problems panel. It mimics VS Code’s Tasks problemMatchers mechanism.

Problem matching configuration options

Example configuration which is sufficient in most cases:

"ceedlingExplorer.problemMatching": {
	"mode": "gcc"
}

Problem matching pattern options

Example pattern object (GCC compiler warnings):

{
    "severity": "warning",
    "filePrefix": "${projectPath}",
    "regexp": "^(.*):(\\d+):(\\d+):\\s+warning:\\s+(.*)$",
    "message": 4,
    "file": 1,
    "line": 2,
    "column": 3
}

Commands

The following commands are available in VS Code’s command palette. Use the ID to add them to your keyboard shortcuts. Both also appear as toolbar buttons in the Testing view. Running, debugging, and reloading tests are done from VS Code’s built-in Testing view (or its toolbar/gutter icons) rather than extension-specific commands.

Debugging

To set up debugging, create a Debug Configuration in launch.json and reference its name as the debugLaunchConfig property of the corresponding entry in ceedlingExplorer.projects (see Options). If ceedlingExplorer.projects isn’t configured at all, the extension falls back to a single default project expecting a launch configuration literally named ceedling.

Migrating from the original Ceedling Test Explorer extension? Its flat ceedlingExplorer.debugConfiguration string setting no longer exists. Use ceedlingExplorer.projects[].debugLaunchConfig instead, as above.

${command:ceedlingExplorer.debugTestExecutable} can be used in the program property to reference the test executable being debugged. Depending on your Ceedling configuration, it is found under projectPath/build/test/out/.

This looks like a VS Code command variable. The extension substitutes it directly with the resolved executable path before starting the debug session. That substitution only happens when debugging starts from a test’s own debug icon in the Testing view.

Starting the same launch configuration from F5 or the Run and Debug panel skips that substitution entirely. A guard shows a clear error in that case, instead of a confusing “path does not exist” failure. Always start debugging from a test’s debug icon, not F5 or the Run and Debug panel.

Note: Individual test debugging is not supported — clicking “debug” on a single parametrized test case still runs and debugs its entire containing test file, since Ceedling always compiles and runs a whole test file’s executable at a time. Set or skip breakpoints accordingly.

Example configuration with Native Debug (webfreak.debug):

{
    "name": "Ceedling Test Explorer Debug",
    "type": "cppdbg",
    "request": "launch",
    "program": "${workspaceFolder}/build/test/out/${command:ceedlingExplorer.debugTestExecutable}",
    "args": [],
    "stopAtEntry": false,
    "cwd": "${workspaceFolder}",
    "environment": [],
    "externalConsole": false,
    "MIMode": "gdb",
    "miDebuggerPath": "C:/MinGW/bin/gdb.exe",
    "setupCommands": [
        {
            "description": "Enable pretty-printing for gdb",
            "text": "-enable-pretty-printing",
            "ignoreFailures": true
        }
    ]
}

Crashes and :use_backtrace

A crashing test doesn’t need the debugger to be caught. Ceedling’s own :use_backtrace project setting, documented here, reports a crash as a normal failed test, at the exact crashing line, instead of a bare timeout or a silently stopped run. This extension shows that result the same way it shows any other failed test. No extra configuration is needed.

It defaults to :simple. :simple reruns each test case individually to isolate which one crashed. It needs no gdb. It works with a simulator-based test fixture, not just native hardware.

:gdb additionally identifies the exact crashing line and, on Ceedling 1.1.0 and later, a per-test-case gdb log file. This extension turns a reference to that log into a clickable link in the failing test’s message. :gdb needs gdb installed. It only supports the native build platform, not a cross-compiled or simulator-based test fixture. Stay on :simple if either applies.

Troubleshooting

If you think you’ve found a bug, please check Known Issues and, if it’s not there, file a bug report.

Documentation

• Changelog — a terse, itemized record of what changed in each release.
• Release Notes — the narrative version, highlights worth reading before upgrading.
• Known Issues — currently open issues, by version.
• Breaking Changes — what to expect when upgrading across a compatibility boundary.
• Development — the workflow for working on this extension itself.

Contributing

Want to work on this extension itself? See docs/Development.md for the development workflow, local debugging, and the development environment sidecar.

Acknowledgments

This VS Code extension is a fork of the original Ceedling Test Explorer extension [Github, Marketplace] authored by Kin Numaru and taken over by the ThrowTheSwitch community, the authors and maintainers of Ceedling itself. Kin gave their blessing to taking up this work.

Ceedling 1.0.0 compatibility was added to the original extension project by merging a PR authored by @simeon-s1.

Thank you to Kin, @simeon-s1, and all those who contributed to the original repository.