Dice Testing Guide

Dice bundles several test layers to cover interceptors, pubsub behaviour, and module integration. Use this guide to run the relevant subsets and understand how to extend them.

Test Layout

  • test/ (default target): unit-style checks for core components such as pubsub, mempool, and TLS helpers.
  • test/interpose/: autogenerated harness that verifies each interceptor calls the real function and publishes the expected events. Function signatures live in interposed.h.in, and the generator produces one .c per module.
  • test/traces/: integration scenarios that run small programs under Dice and assert specific events or ordering constraints using the trace_checker subscriber.
  • test/order/: exercises module constructor/destructor ordering and link-time combinations to guard against regressions in preload behaviour.
  • test/cxx/: some C++ specific tests, e.g., involving the lifetime of __thread global variables.
  • Sanitizer-specific builds (ThreadSanitizer, AddressSanitizer) reuse the same source files but run with -DDICE_SANITIZER=<tool> to catch data races or memory bugs introduced by interceptors.

Running Tests

cmake -B build
cmake --build build
ctest --test-dir build

Focus on a Subset

  • Interpose suite: ctest --test-dir build -R interpose
  • Trace scenarios: ctest --test-dir build -R trace_
  • Order/linking checks: ctest --test-dir build -R order

Testing with sanitizers

cmake -B build-tsan -DDICE_SANITIZER=<thread|address|undefined>
cmake --build build-tsan
ctest --test-dir build-tsan

NOTE: That sanitizer tests do not work in all configurations.

Extending Tests

  • Interpose tests: add the new function signature to test/interpose/interposed.h.in (define MM_RETURN_<name>, MM_PARAMS_<name>, MM_ARGS_<name>). The generator will create a matching test that publishes events and compares payloads.
  • Trace tests: add a new program under test/traces/ and register it in test/traces/CMakeLists.txt. Use scripts/dice in the test command to load the required modules.
  • Order tests: expand the scenarios in test/order/ to cover additional link combinations or slots when you introduce new modules.

Refer back to doc/contributing.md for the checklist that reviewers expect when new behaviours are added.