Testing & Diagnostics

Cuttlefish gives you two ways to find problems: run your tests on the real board to catch hardware-specific issues, and get clear error messages that point back at your TypeScript when something goes wrong — instead of leaving you to puzzle over generated C++.

Topics

Two Approaches

Hardware-in-the-Loop (HIL)

Write vitest-style assertions with @typecad/expect that run on the actual microcontroller. The cuttlefish-test CLI transpiles your tests, uploads them, and reports pass/fail over serial. This catches real hardware issues — wrong pin voltages, bus timing, sensor calibration.

Source-Mapped Diagnostics

When C++ compilation fails (type errors, missing symbols, linker issues), source maps translate the error location back to the TypeScript file and line. No more manually correlating generated C++ with your source.

Quick Example: HIL Test

import { describe, done } from '@typecad/expect';
import { A0 } from '@typecad/board';

describe('Analog sensor')
  .it('reads within valid range')
    .expect(A0.readAnalog()).toBeWithinRange(0, 1023)
  .it('is above noise floor')
    .expect(A0.readAnalog()).toBeGreaterThan(10);

done();

Run the tests with the dedicated test binary:

cuttlefish-test --port COM4

Quick Example: Source-Mapped Error

When compilation fails:

cuttlefish build --compile
# Error maps automatically:
# C++ error at out/sketch.ino:42:10
#   -> src/sketch.ts:15:8 (CallExpression: readAnalog)
#   error: 'readAnalog' was not declared

For a detailed report with pin usage, peripheral allocation, and heap estimates:

cuttlefish build --diagnostics
# Generates diagnostics.md and diagnostics.json

Test Workflow

1. Write firmware and tests in TypeScript using @typecad/expect
2. Run cuttlefish-test --port COM4 (transpiles, compiles, uploads, reports)
3. Use cuttlefish build --diagnostics for a full build report

See HIL Testing for the full flow, Expect Assertion API for the matcher reference, and Source-Mapped Diagnostics for source map details.