test-driven-univer-development

テスト駆動 Univer 開発

テスト駆動 Univer 開発は、Univer ワークブック向けのパッケージ内 SaC TDD です。変更したパックが univer sac verify を通じてアサーション契約を満たした場合にのみ、動作が完成したとみなします。

これは一般的なコード TDD ではありません。目標は、ソース、ランタイム、アサーションのエビデンスを通じて、Univer パッケージの動作を正しくすることです。スプレッドシートプロジェクトでは、Excel のドメインセマンティクス、範囲の役割、数式、計算値、書式設定、入力規則、保護、保持、負の制約が対象になります。

計画に基づく失敗するアサーションが先にない限り、移行パックを実装してはいけません。

意図したワークブック上で確認できる理由によってアサーションが失敗する前に移行ソースを書いた場合は、次の手順を実行してください。 移行ソースの変更を削除または元に戻し、計画に基づくアサーションゲートからやり直してください。

例外はありません。

• 参照用として残してはいけません。
• アサーションを書きながら変更してはいけません。
• コメントアウトした状態で残してはいけません。
• 計画に基づく失敗するアサーションから新たに実装してください。

使用するタイミング

次のような場合にこのスキルを使用します。

• 新規または変更された Facade Migration Packs
• assertions.ts のカバレッジ
• univer sac apply または univer sac verify による修正ループ
• パッケージ内 SaC ソースにおける、ワークブック上で確認できる動作の変更
• ワークブックの動作を維持しながら SaC ソースをリファクタリングする場合

例外を認めるにはユーザーの明示的な同意が必要であり、引き継ぎ事項に記録しなければなりません。

運用契約

• 複雑なワークブックの動作では、まず writing-univer-plans を使用してください。
• 作成済みの計画に従ってパックごとに進める場合は、executing-univer-plans を使用してください。
• 複雑なワークブックの動作では、アサーションは計画に、計画は success-criteria/<topic>.md にたどれるようにしてください。どちらのソース成果物も迂回してはいけません。
• 重要な変更を加えた各パックについて、assertions.ts をワークブック上で確認できる契約として扱ってください。
• 必要に応じて範囲を限定したブートストラップや読み取り専用プローブを使用できますが、最終的な完了エビデンスとして使用してはいけません。
• univer sac apply の成功だけを根拠に完了を主張してはいけません。
• アサーションがゼロ、すべてスキップ、または変更したパックの verify が未確認である場合、その実行だけを根拠に完了を主張してはいけません。
• パック構成を満たすため、または RED ゲートを装うために、空の Migration Pack や何もしない Migration Pack を作成してはいけません。

テストのアンチパターンに関するリファレンス

アサーションの作成・変更、ワークブックのフィクスチャ作成、読み取り専用プローブをエビデンスとして使用する場合、またはテスト専用の移行メソッドやファサードメソッドを追加しそうな場合は、このリファレンスを読み込んでください。 testing-anti-patterns.md。

このリファレンスでは、移行のエコー、読み取り専用プローブによる完了の主張、不完全なワークブックフィクスチャ、テスト専用の本番サーフェス、正当化、STOP 条件を扱います。

優れたアサーション

品質	優れている例	よくない例
最小限	アサーションごとにワークブックの動作に関する判断が 1 つ	多くのルールを網羅する広範なスナップショット 1 つ
明確	証明するシート、範囲、動作を指定する	assert output is correct
ドメインに基づく	計画のエビデンスから期待値を導く	移行で書き込まれた値をそのままコピーする
ランタイムを考慮	数式が重要な場合は計算値を確認する	数式テキストだけを確認する

順序が重要な理由

移行ソースを書いた後にアサーションを書くと、実装に偏った内容になります。「どのワークブックの動作が存在すべきか」ではなく、「この移行で何が書き込まれたか」に答えるものになってしまいます。

計画に基づく失敗するアサーションがあれば、コードを書く前に Excel のドメインに関する判断を行う必要があります。アサーションが失敗することを確認すれば、そのゲートが動作の欠落を検出できると証明できます。その後にアサーションが成功すれば、Migration Pack がそのワークブック契約を満たしたと証明できます。

手動プレビュー、univer sac apply、読み取り専用プローブは有用なエビデンスですが、再現可能な完了ゲートではありません。再現可能なゲートは、univer sac verify <package.univer> --json と返されたアサーションエビデンスです。

Red-Green-Repair

digraph test_driven_univer_development {
    rankdir=LR;
    red [label="RED\nPlan-derived assertion", shape=box, style=filled, fillcolor="#ffcccc"];
    verify_red [label="Verify fails\nfor right workbook reason", shape=diamond];
    green [label="GREEN\nMinimal Migration Pack", shape=box, style=filled, fillcolor="#ccffcc"];
    verify_green [label="Verify passes\nwith report evidence", shape=diamond];
    repair [label="REPAIR\nSource, assertion, or plan", shape=box, style=filled, fillcolor="#ccccff"];
    next [label="Next pack", shape=ellipse];

    red -> verify_red;
    verify_red -> green [label="yes"];
    verify_red -> red [label="wrong failure"];
    green -> verify_green;
    verify_green -> repair [label="yes"];
    verify_green -> green [label="no"];
    repair -> verify_green [label="stay green"];
    verify_green -> next;
}

RED - アサーションを先に記述する

計画に基づいてアサーションを導き出します。ユーザーの意図、ベースラインの証拠、範囲の役割、最終レイアウトの根拠、Contract Decision Evidence を考慮します。

移行によって実際に書き込まれた内容からアサーションを導き出してはいけません。

アサーションには、次の内容を含めてください。

• ワークブック上で確認できる最終状態：シート、使用範囲、ヘッダー、代表値、数式、計算値
• Excel のドメインセマンティクス：符号、カテゴリ、期間の境界、テキストの大文字・小文字、空白とゼロの区別、空白とエラーのプレースホルダーの区別、単数形・複数形のラベルの維持、保存される値の型、表示上重要な値、数式の動作
• 範囲の役割の維持：ソースデータ、ヘルパー／制御入力、ルックアップ／参照、例／デモ、既存の出力、維持のみの範囲
• 境界条件と否定的制約：余分な見出しがないこと、ヘルパーシートがないこと、末尾がクリアされていること、意図しない上書きがないこと、望ましくない書式変更がないこと
• スタイル／エクスポートの安全性：有効な #RRGGBB または文書化された色文字列、想定される数値形式、スタイルまたは数式が関わる場合にエクスポートと互換性のあるワークブック上の値
• ワークブックの動作に関する契約上の判断：出力形状、並べ替え、グループ化、マッピング、値／数式のセマンティクス、書式／表示、操作／検証／保護、維持、否定的制約
• 意味のあるケース：関連する場合は、最初、中間、最後、空白、ゼロ、日付境界、テキスト境界、グループ化境界の行

アサーションは小さく、決定性のあるものにしてください。ワークブック全体のスナップショットより、代表的な範囲を優先してください。

RED を検証する - 失敗を確認する

univer sac verify <package.univer> --json は、適用済みパックを検証します。アサーションをテストするためだけに、保留中のソースを適用することはありません。新規の保留中パックでは、実装前に計画に基づくアサーションを記述し、ワークブック上で確認できるベースラインの証拠によって、対象の動作がまだ存在しないことを確認することで RED ゲートを確立します。

RED のために verify を実行するのは、対象のパックがすでに適用されている場合、または適用済みパックを修正していて、そのアサーションが失敗すると予想される場合に限ります。verify を実行したら、次の点を確認してください。

• 変更したパックが JSON サマリーで実際にチェックされている
• アサーションが失敗している
• 失敗の原因が、意図したワークブック上で確認できる動作である
• 失敗の原因が、タイプミス、フィクスチャの欠落、セットアップエラー、古い apply 状態、パックのスキップ、または無効なアサーションではない

次のものは、有効な RED ゲートではありません。

• SAC_EMPTY_MIGRATION_PACK
• SAC_PACK_FILE_INVALID
• checkedPacks: 0、checkedPackCount: 0、またはすべてスキップされた実行
• 未適用のためパックがスキップされる、変更のないシート移行
• 変更したパックのアサーションをチェックしない verify の合格

verify で変更したパックをまだチェックできない場合、verify を実行させるためだけに空または変更のないパックを追加してはいけません。次の GREEN ステップでは、アサーションファイルが存在し、ベースラインの証拠によって対象の動作が欠けていることを確認した後に限り、最小限の実際の移行ソースを作成できます。

verify が実際にチェックした変更済みパックのアサーションに、すぐ合格するものがある場合、新しい動作を検証するゲートとしては役に立ちません。アサーションを強化するか、計画から次に欠けている動作を選んでください。

GREEN - 最小限のパック変更を実装する

該当する RED ゲートが確立されてから、Migration Pack を編集します。適用済みパックの場合は意図した理由でアサーションが失敗していること、新規の保留中パックの場合は計画に基づくアサーションが存在し、ベースラインの証拠によって対象の動作が欠けていることを確認してください。

現在のパックとアサーションが必要とするものだけを実装します。無関係なシート、ヘルパー範囲、広範な書式設定、または将来の動作を追加してはいけません。

GREEN を確認する - レポートを使用する

該当するマイグレーションがまだ適用されていない場合は apply を実行し、その後、確認します。

univer sac apply <package.univer>
univer sac verify <package.univer> --json

JSON の概要と返されたアサーションの証拠を読みます。

変更されたパックがチェック済みで、少なくとも 1 つのアサーションが合格していることを確認します。アサーションが 0 件、すべてスキップ、または変更されたパックが未チェックの実行は GREEN ではありません。

ステータスが failed の場合は、パック ID、アサーションの種類、対象、期待値、実際の値、および差分がある場合はその最初の箇所を調べます。どちらかを変更する前に、マイグレーションのソースとアサーションの期待値のどちらが誤っているかを判断します。

ステータスが error の場合は、ワークブックの動作を評価する前に、セットアップ、設定、対象の欠落、ソースの検証、バンドル、またはランタイムのセットアップを修正します。

パックがすでに適用されていて、その後に動作の変更が必要になった場合は、ハッシュ不一致のループに陥るまで適用済みのパックを編集し続けないでください。動作を修正し、独自のアサーションを備えた新しい後続の Migration Pack を作成することを優先します。

REPAIR - コントラクトを正確に保つ

inspect、pipe out、または読み取り専用のランタイムコマンドなどの読み取り専用プローブは、失敗のデバッグに役立つ場合があります。有用なプローブの結果を計画、マイグレーションのソース、またはアサーションに反映してから、univer sac verify に戻ります。

検証によって期待される動作が変わる場合は、ソースやアサーションを修正する前、または修正と同時に計画を更新します。

アサーションのカバレッジルール

計画の Contract Decision Evidence テーブルに記録された、リスクの高い各判断について、選択したルールと、妥当そうに見える誤ったルールとを区別できるアサーションまたは読み取り専用プローブを少なくとも 1 つ追加します。

例：

• 並べ替え／グループ化／切り捨ての判断：出力容量に上限がある場合は、先頭、中間、末尾、および最初に除外される候補を検証します
• マッピングの判断：関連する場合は、カテゴリ、符号、空白／ゼロ、または境界のマッピングの各側につき 1 行を含め、代表的なソースからターゲットへの座標を検証します
• テキストの判断：大文字・小文字、空白、略語、単数形／複数形の表記、保存されている値の型を正確に検証します
• 構造上の判断：最終的なレイアウトが確定した後に、セクション見出し、セグメントの境界、先頭行と末尾行を検証します
• 空白／エラーの判断：実際の空白と #N/A、n/a、スペース、NBSP、またはゼロを区別できる、該当なしまたはデータ欠落の行を少なくとも 1 つ検証します
• 日付範囲の判断：最初に計算される行、境界の前後の行、中間の行 1 つ、最後の行を検証します
• 古い例／ターゲットの判断：既存のターゲット値が古い例や部分的な出力である可能性がある場合、それらの値を誤って保持すると失敗する反例を少なくとも 1 つ検証します
• スタイルの判断：リクエストに無効または曖昧な色トークンが含まれる場合は、正規化された色文字列と、エクスポートされたワークブックとの互換性を検証します

基礎となる意味上の判断が曖昧な場合、マイグレーションの出力をそのまま反映するだけの合格アサーションでは不十分です。同じアサーションが妥当そうに見える誤ったルールでも合格するなら、そのアサーションを強化するか、読み取り専用プローブを追加してから、パックを GREEN と判断します。

既存のターゲット値がコピーされたことを確認するだけで、指示から導かれるワークブックの動作と一致することを証明しないアサーションは、合格しても GREEN とみなさないでください。

正確な値に関する判断では、アサーションによって、実装が望ましいと考える正規化ではなく、ワークブック上で確認できるコントラクトを証明する必要があります。大文字・小文字、空白、句読点、識別子、保存されている値の型、日付、ブール値、空白、ゼロ、エラーのプレースホルダーが表示される場合、またはリスクの高い判断に含まれていた場合は、それぞれをカバーします。

アサーションによって、特定されていない仮定をワークブックで証明された事実に変えることはできません。計画で判断が underdetermined assumption とされている場合、アサーションでは、実装が宣言された仮定を一貫して適用していることを検証します。また、最終的な引き継ぎでは、決定的なワークブックの証拠として示すのではなく、その不確実性を残します。

合格条件

重要な SaC TDD の引き継ぎでは、次の条件を満たす必要があります。

• 最新の関連する univer sac verify <package.univer> --json のステータスが passed であること
• タスク用に作成または変更したすべてのパックをチェックすること。ただし、アサーションがないことが明示されている場合を除きます
• 変更した各パックに、少なくとも 1 つの合格したアサーションがあること
• 該当する場合は、スキップしたパックに言及すること
• アサーションが 0 件の実行や、すべてスキップされた実行は完了の根拠になりません

最終引き継ぎ

外部ハーネスから納品または停止の条件が提示された場合、最新の関連する検証が合格した後は、そのハーネスに従ってください。必要な引き継ぎ成果物が作成された後、補助的な証拠の収集を続けないでください。

最終的な引き継ぎには、次の内容を含める必要があります。

• 計画の結果とパックの順序
• 検証コマンド
• 最終ステータス
• 変更したパックのアサーションの証拠
• 該当する場合は、スキップしたパック
• 使用した補助的な確認があれば、その内容と完了の証拠にならない理由