ApexTrace Guide
ApexTrace records the execution path of a Usecase and turns that record into the thing your tests assert on. A line you wrote for the production debug log becomes the assertion that answers "did this Usecase really take that path?".
It is organised as usage guides you can read in order, starting from how to instrument a Usecase, plus a deep dive into the internals and the gotchas.
📦 To install ApexTrace (unlocked package or git submodule), see Installing Apex Stem.
Usage guides
Read them in order: instrument the log, pin the path in a test, then pin governor usage.
Trace's four lifecycle methods
The basic shape of instrumenting a Usecase: why the Trace is created once in an instance field, how start / log / skip / abort / finish divide the work, and the three exit paths that separate "completed", "exited without doing anything" and "did not complete".
Verifying execution paths with TraceFlow
How to pin a void Usecase along two axes, side effects and path. Covers telling paths apart with isLastFinish / isLastSkip / isLastAbort, when to reach for contains over lastHistoryContains, and aligning the observation window with discardArrange().
Pinning governor usage with TraceUsage
A loose ceiling that insures against N+1 slipping into bulk. Covers the governor IT built on ApexBlueprint times(), usageOf versus usagesOf, asserts with a reason string, and the misuses that now raise.
Deep Dives
A closer look at nesting behaviour and the two modes that differ between test and production.
What to read next
- Test strategy: how path verification divides between unit and integration tests
- Handler-Usecase Architecture: the design of the Usecase layer where
Tracelives - The ApexTrace GitHub repository: source code and the latest updates