---
title: "Unit tests"
---

# Unit tests

Host unit tests with CTest and Unity in the Testing view, Unity tests of an IAR test configuration on the C-SPY simulator or the target, and IAR C-RUN runtime analysis with messages in Problems and a report for the safety record.

## Host unit tests with CTest and Unity

CTest tests, including Unity cases, appear in the Testing view under **Embedded Unit Tests**, one entry per test, and can be rerun one at a time. A failure shows at its line. The module reads CTest's JSON and JUnit XML.

![CTest and Unity cases in the Testing view, with a failed assertion shown at its line.](https://neuralinverse.com/docs-images/modules/embedded/ctest-unity-tests.webp)

For a project laid out like the reference firmware:

```bash
cmake --preset host-tests && cmake --build --preset host-tests && ctest --preset host-tests --output-on-failure
```

- Verified: unit tests on CTest JSON and JUnit XML fixtures.
- Not verified: any CTest version in a real run; Windows (the integration test skips there).

## Unity tests on IAR's C-SPY simulator or the target

For IAR projects, each test configuration of the `.ewp` (such as `UnitTest` or `HardwareInLoop`) appears in the Testing view under **IAR C-SPY Tests**, with its Unity cases.

1. Run a configuration from the Testing view.
2. The module builds it with `iarbuild` first, then runs the test image with IAR's `cspybat`.
3. On the **C-SPY simulator** the run starts directly. On the **target**, a confirmation first names the target, the probe and its C-SPY driver, the image with its size and SHA-256, and the flash loader, and says that C-SPY programs the flash and runs the tests until they end or the time-out passes.
4. Results appear per test: passed, failed with the expected and actual values at the assertion's line, or ignored with its message.

The `cspybat` command line comes from the configuration's `settings/*.xcl` files, which Embedded Workbench writes, or, for the simulator, from files composed from the project's `.ewd` and `.ewp`. Each run runs the whole test image; continuous runs are not offered.

State: unit-tested on Linux on Embedded Workbench 7.4, 8.1 and 8.3 files from public projects, and on the command forms in IAR's CMake tutorial. **Not yet run against `cspybat`** on any operating system, simulator or probe (kit iar-keil-build). Runs on a probe need the `.xcl` files Embedded Workbench writes.

## IAR C-RUN runtime analysis

With an IAR C-RUN licence, the C-SPY test runs can check the code at run time for arithmetic errors, bounds errors and heap errors.

1. Run **Configure IAR C-RUN Runtime Checking...**. A list shows each C-RUN check of the test configuration, as stored in the project's `.ewt` file (`RuntimeChecking`), with IAR's name for it: C-RUN runtime checking, integer overflow, integer conversion, integer shift overflow, unhandled switch case, division by zero (and their unsigned and explicit-cast variants), bounds checking, and the checked heap.
2. Choose the checks. A confirmation names the file and each change, repeats IAR's advice where it applies (for example not to use bounds checking and the checked heap together), and says that only these values change and that the next build instruments the code.
3. Run the tests. C-RUN messages go to Problems at their line, with the call stack below each message, under the source **IAR C-RUN**.

![The C-RUN Runtime Checking list of the UnitTest configuration with the checks that are on, and two C-RUN heap errors in Problems with their call stacks.](https://neuralinverse.com/docs-images/modules/embedded/crun-options.webp)

| Command | What it does |
|---|---|
| **Filter IAR C-RUN Messages...** | Shows only messages of chosen kinds, or containing a text |
| **Clear IAR C-RUN Messages** | Removes them from Problems |
| **Read IAR C-RUN Messages from Log...** | Reads a saved log of `cspybat` or IAR C-SPY with C-RUN messages |
| **Export IAR C-RUN Report...** | Writes a Markdown report for the safety record: where the messages were read from, the project, configuration, image and its SHA-256, the C-SPY driver and command line, the C-RUN options as stored, and the messages by kind. The report says it lists what C-RUN found and is not a verdict on the code |

![IAR C-RUN heap errors in Problems with their call stacks, after a unit test run.](https://neuralinverse.com/docs-images/modules/embedded/iar-crun-problems.webp)

State: verified on Linux on IAR's own C-RUN evaluation projects for reading and changing the options (one state changed; an unchanged save byte-identical); the message reader on output in the form of IAR's published `cspybat` V9.5.3 output; Electron rendering; the running app with stand-in `iarbuild` and `cspybat`. **Not yet run against `cspybat` or Embedded Workbench with a C-RUN licence** (kit iar-keil-build). The `--rtc_enable` option is unverified, message names other than "Heap usage error" and "Out of heap space" have not been seen, and five `.ewt` options are read-only.

## Agents

Agents can list and run C-SPY tests (**List IAR C-SPY Tests**, **Run IAR C-SPY Tests**), and read and change C-RUN options, read C-RUN messages and export the report. Running tests and changing options run only after you confirm; a run on the target names the probe that programs its flash.