Skip to content

Start Testing in Your Project

This guide takes a typical Ceedling project from opening it in VS Code to running its first test. Most projects need no configuration, so it usually takes a minute. At the end, the Testing view lists every test, and runs any of them.

What you need

  • VS Code 1.88.0 or later.
  • Ceedling 1.0.0 or later, which runs in a terminal. ceedling version should print its version.
  • A Ceedling project, with its project.yml, or ceedling.yml from Ceedling 1.2.0.

Steps

  1. Install the extension. Search VS Code’s Extensions view for “Ceedling”, and install Ceedling by Throw The Switch.
  2. Open the project. Open the folder holding the project file, with File ↳ Open Folder….
  3. Open the Testing view. Choose the flask icon in the Activity Bar. After a few seconds, the view lists the project’s test files, each with its test functions.
  4. Run a test. Choose the run button beside a test function. Its result appears beside it, and a failure shows its message at the failing line in the editor.
  5. Run them all. Choose Run Tests at the top of the view, to run every test file.

The editor’s gutter shows run and debug buttons beside each test function too.

When no tests appear

The extension looks for the project file at the folder’s root. Two settings cover most projects where it isn’t found, or where Ceedling won’t run.

A project in a subdirectory needs its path in ceedlingExplorer.projects. Add it to the folder’s .vscode/settings.json.

{
    "ceedlingExplorer.projects": [
        { "path": "firmware" }
    ]
}

A Ceedling that runs only in a particular shell needs that shell in ceedlingExplorer.shellPath. That is common on Windows, where Ceedling may run only in an MSYS2 or Git Bash shell. Run the Ceedling You Use shows each setup.

Any other problem shows a notification. Troubleshooting matches each message to its fix.

What happens when the folder opens

The extension asks Ceedling itself about the project, so it sees exactly what a real build sees. It runs ceedling version, then ceedling dumpconfig and ceedling files:test, in the project’s directory. It then reads each test file for its test functions. Getting Started explains each step.

The test list keeps itself current from then on. Editing a test file updates its tests as you type. Adding a test file, or changing project.yml, rediscovers the project.

Next steps