Skip to content

Getting Started

The extension brings a Ceedling project’s tests into VS Code’s built-in Testing view, and most projects need no configuration at all. This page covers what the extension requires, how to install it, what it does when it opens a project, and how it runs Ceedling. The first-run guide walks through the same steps for a typical project.

Requirements

The extension needs a recent VS Code and Ceedling 1.0.0 or later.

  • VS Code 1.88.0 or later. That release added the test coverage views that Run with Coverage uses.
  • Ceedling 1.0.0 or later. Ceedling 1.0.0 through 1.2.2 are supported. The Ceedling documentation covers installing it.
  • Code coverage also needs one of Ceedling’s coverage plugins: gcov, with a report tool, or Bullseye, with a licensed installation. See Code Coverage.
  • Debugging needs a debugger extension, such as Microsoft’s C/C++ extension, and a launch.json configuration. See Debugging.

Installing

Install the extension from the Visual Studio Marketplace. Search the Extensions view for “Ceedling”, or open the Marketplace page. Its identifier is throw-the-switch.vscode-ceedling.

Opening a project

Open the folder or workspace containing your Ceedling project, then open the Testing view, the flask icon in the Activity Bar. The view lists every test file, test function, and parametrized test case. Run and debug tests from it, or from the icons beside each test in the editor.

Two settings cover most projects that don’t work straight away.

A workspace with several folders lists each folder’s projects under an entry of its own, labeled Ceedling (folder). A folder without a Ceedling project adds no entry.

How the extension reads a project

The extension asks Ceedling itself for each project’s configuration, so it sees exactly what a real build sees. Discovering a project takes three Ceedling commands, run in the project’s directory.

  1. ceedling version checks that Ceedling runs and is 1.0.0 or later. It honors a Ceedling vendored in the project’s vendor/ceedling, or named by WHICH_CEEDLING. From Ceedling 1.2.2, it runs again with the project’s own project file and mixins, which may select another installation through :project ↳ :which_ceedling. The version decides which of Ceedling’s features the extension uses, such as running a test file by its path from Ceedling 1.2.0.
  2. ceedling dumpconfig resolves the project’s configuration, with its mixins and plugin defaults applied.
  3. ceedling files:test lists the project’s test files. The extension then reads each one to find its test functions and parametrized cases.

The extension applies a mixin of its own to every command that reads or runs the project. It enables the report_tests_log_factory plugin’s cppunit report, which is where the extension reads test results. No plugin setup is needed in project.yml. Configuration explains how it combines with your own mixins.

How the extension runs Ceedling

The extension runs every Ceedling command itself, in the project’s directory, through a shell. Three settings shape how it does so.

  • The shell. Commands run in the operating system’s default shell. ceedlingExplorer.shellPath names another, such as MSYS2’s or Git Bash’s bash.exe on Windows.
  • The command. Each command starts with ceedling. ceedlingExplorer.ceedlingCommand replaces it, e.g. with bundle exec ceedling or a path to a Ceedling of your own.
  • The output. The extension removes ANSI escape sequences, such as terminal colors, from Ceedling’s output before it reads or shows it. ceedlingExplorer.ansiEscapeSequencesRemoved set to false leaves them in.

Run the Ceedling You Use sets these up for common installations.

Keeping the test list current

The Testing view keeps itself current as the project changes.

  • Editing a test file updates its tests as you type, even before you save.
  • Adding or removing a test file rediscovers the project.
  • Changing project.yml, a mixin file, or the Ceedling in vendor/ceedling rediscovers it too.
  • Changing a setting that affects discovery, such as ceedlingExplorer.projects, rediscovers every project in the folder.

The Testing view’s refresh button rediscovers on demand, for example after upgrading the installed Ceedling gem.

Migrating from Ceedling Test Explorer

This extension continues the original Ceedling Test Explorer extension, and most of its settings carry over unchanged.

  • The tests appear in VS Code’s own Testing view, not the third-party Test Explorer view. The Test Explorer UI extension is no longer needed.
  • The ceedlingExplorer.debugConfiguration setting no longer exists. Name each project’s launch configuration in ceedlingExplorer.projects[].debugLaunchConfig instead.
  • launch.json configurations using ${command:ceedlingExplorer.debugTestExecutable} work unchanged.

The Breaking Changes document describes the changes that need action when upgrading.