Skill: F Prime Unit Testing

Step-by-step procedure for writing high-quality unit tests for an F Prime component. The full reference for scaffolding, assertion macros, helper functions, TestMain structure, and CMakeLists registration is in the unit testing guide. Follow the guide for implementation details; this skill adds the workflow order and quality criteria.

0 — Prerequisites

1 — Scaffold, implement, register, run

1. Scaffold: fprime-util impl --ut — rename .template files, delete auto-generated *Ac.* / *GTestBase.*.
2. Tester class: inherit <Component>GTestBase, add test methods and helper functions. See Tester class structure and helper functions.
3. TestMain: TEST() macros with COMMENT(...) / REQUIREMENT(...), seed STest::Random. See TestMain.
4. CMakeLists.txt: register_fprime_ut(...) with UT_AUTO_HELPERS and DEPENDS STest. See CMakeLists.txt registration.
5. Build & run: fprime-util build --ut, fprime-util check, fprime-util check --coverage.
6. Consolidate: once the new tests pass, re-read the test diff as a reviewer would and refactor before opening the PR:
   • fold repeated invoke → assert sequences shared by two or more tests into a Tester helper, or into an existing rule when the component already has test/ut/Rules/;
   • reuse existing helpers and rules before adding new ones;
   • drop tests that do not verify the behavior the task added or changed (note remaining coverage gaps as future work);
   • re-run fprime-util check to confirm nothing regressed.

2 — Key patterns to enforce

• clearHistory() at the start of every test action.
• component.doDispatch() after every async invocation on active/queued components.
• Helper functions for all port invocations and assertion groups — no raw invoke_to_* + ASSERT_* in test methods.
• STest::Pick::any() for port numbers, IDs, sizes where the specific value does not matter.

3 — Rules-based testing (preferred for complex components)

Core constructs (all from TestUtils/RuleBasedTesting.hpp):

• FW_RBT_DEFINE_RULE(TesterClass, Group, Rule) — declares a precondition/action pair and a rule struct on the Tester.
• Shadow state — a Tester member mirroring observable component state; queried in preconditions, updated in actions.
• Scenarios — RandomScenario (picks applicable rule at random), BoundedScenario (wraps another, stops after N steps), SequenceScenario (fixed order).

Scaffold with fprime-util new --rule-based-test. For file layout, implementation patterns, and full examples see the rules-based testing guide and the Svc/Ccsds/ApidManager exemplar.

Build note: add every Rules/<GroupName>.cpp and TestState/TestState.cpp to the SOURCES list in CMakeLists.txt and include DEPENDS STest.

4 — Quality checklist

• Every input port has at least one test
• Every command has nominal + error-path tests
• Every event asserted (emitted and not-emitted)
• Every telemetry channel asserted after its update action
• clearHistory() at start of each test action
• doDispatch() after every async invocation on active/queued components
• Helper functions used — no raw invoke_to_* + ASSERT_* in test methods
• STest::Pick for port numbers, IDs, sizes where specific value doesn't matter
• Boundary values tested (min/max buffer size, port index 0 and max)
• Rules-based testing for stateful / multi-port components (≥ 1000 random steps)
• No dynamic memory after construction
• REQUIREMENT("...") and COMMENT("...") macros present
• Consolidation pass done: shared sequences folded into helpers or rules, off-task tests removed
• fprime-util check passes