ApexTrace ガイド

ApexTrace は、Usecase の処理経路を記録し、その記録をそのままテストの検証項目にする OSS です。本番のデバッグログのために書いた 1 行が、「この Usecase は本当にその経路を通ったのか」を確かめるアサーションになります。

Usecase への仕込み方から順に読める 使い方ガイド と、内部の仕組みと注意点を扱う Deep Dive で構成しています。

📦 ApexTrace の導入 (unlocked package / git submodule) は Installing Apex Stem を参照してください。

使い方ガイド

ログを仕込む → 経路をテストで縛る → ガバナ消費を縛る、という順に読むと迷いません。

Usecase に Trace を仕込む基本形。instance field で 1 回だけ生成する理由、start / log / skip / abort / finish の使い分け、そして「正常完了 / 何もせず抜けた / 完遂しなかった」を分ける 3 つの終了パスを解説します。

戻り値が void の Usecase を「副作用」と「経路」の 2 軸で縛る方法。isLastFinish / isLastSkip / isLastAbort による経路の区別と、lastHistoryContains と contains の使い分けを実例で解説します。

バルクで N+1 が混入していないことを緩い上限で縛る保険。ApexBlueprint の times() と組むガバナ IT の形、usageOf と usagesOf の使い分け、reason つきアサート、そして v1.3.0 で例外になった誤用を扱います。

ネスト時の挙動と、テストと本番で挙動が変わる 2 つのモードを掘り下げます。

Usecase が Usecase を呼ぶときの LIFO 順序ルールと、テスト時に自動で有効になる Strict モード / 本番の Relaxed モードの違い。テストを Trace で包む理由と、その文字列に検証内容を自由に書ける利点も扱います。