Vyperling

Inline pass/fail annotations and native debugging for vyperling embedded-C unit tests, built on the native VS Code Test Explorer API.

What it does

• Discovers test files in your project's test_dir and lists each test function in the Test Explorer. Honors your forge.yml conventions: both default snake_case (test_uart.c → void test_*(void)) and Ceedling-style (test_prefix: "Test" + test_naming: "camelCase" → TestUart.c → void testFoo(void)).
• Run a test unit → invokes vpl test --output json and maps results back to the editor: green/red gutter icons, failing assertions peek their message inline at file:line, ignored tests show as skipped.
• Debug a test unit → rebuilds it with debug symbols (vpl test --debug) and launches the native binary under gdb (via the C/C++ extension), so breakpoints in both the test file and the source-under-test hit.

Requirements

• The vpl (or vyperling) CLI on your PATH — install with pip install vyperling or poetry install in the tool repo.
• A forge.yml at (or above) your workspace root. Activation triggers on workspaceContains:**/forge.yml.
• ms-vscode.cpptools (declared as an extension dependency) for debugging.
• gcc + gdb for the native target.

Settings

Why a shell?

GUI-launched VS Code does not inherit your login-shell PATH, so a bare vpl would fail to resolve when it lives under nvm, poetry, or a virtualenv. The extension runs the CLI through your shell (default $SHELL -lic) so the same PATH you have in a terminal is used. Verify with your-shell -lc 'which vpl'.

Debugging

Native (target == native) only in this version. The Debug profile first runs vpl test --debug -k <unit>, which builds with -g -O0 into build/native-debug/ (a separate dir so the optimised/coverage build cache is untouched), then launches a cppdbg session on that binary. Breakpoints in the test_*.c and the source-under-test bind because the debug build has DWARF symbols.

If you prefer a manual config, build once with vpl test --debug and add this to your project's .vscode/launch.json:

{
  "type": "cppdbg",
  "request": "launch",
  "name": "Debug <unit>",
  "program": "${workspaceFolder}/build/native-debug/<unit>",
  "MIMode": "gdb",
  "cwd": "${workspaceFolder}"
}

Cross-target debugging (QEMU -g <port> + gdb attach) is a planned follow-up.

Troubleshooting

Open View → Output → "Vyperling" for the exact command, working directory, exit code, and vpl stdout/stderr of every run.

Developing the extension

Uses Yarn Berry (pinned via packageManager in package.json). corepack ships with Node ≥ 16 and resolves the right Yarn version automatically:

cd editors/vscode
corepack enable        # one-time: lets `yarn` use the pinned version
yarn install
yarn build             # bundle src -> dist/extension.js via esbuild
yarn typecheck         # tsc --noEmit
yarn test              # vitest unit tests (pure logic; no vscode needed)
yarn test:cov          # tests + coverage report (text + html)

Unit tests

Pure, vscode-free logic lives in src/discovery.ts (convention matcher ported from runnergen.py), src/paths.ts, and src/forgeConfig.ts, and is covered by vitest suites under test/. The vscode-coupled modules (testController.ts, runner.ts, debug.ts) are verified manually via the F5 dev host — the tests never import vscode, so no API mock is required.

Then open editors/vscode in VS Code and press F5 ("Run Extension") to launch an Extension Development Host. Open a vyperling project (e.g. the temp_sensor example) inside it and exercise the Test Explorer. Set breakpoints in src/*.ts in the main window to step through the extension itself.

The JSON contract is produced by vpl test --output json — see write_results_json in vyperling/reporter.py. Keep src/types.ts in sync with its schema version.