tui-testing-debugging

スナップショット、PTY、仮想端末、ConPTYを使用したTUIのテストとデバッグ

TUIに信頼性の高いテストが必要な場合や、対話型端末のバグを実際の端末セッション外で再現する必要がある場合に、このスキルを使用してください。

4層のテスト戦略

1. 純粋な状態テスト。 端末を使わずに、リデューサー、更新関数、フォーカス遷移、検証、並べ替え、フィルタリング、コマンドのスケジューリングをテストします。
2. コンポーネント／レンダリングのスナップショット。 幅、高さ、テーマ、カラー対応レベル、ロケール、時刻を固定してウィジェットをレンダリングします。安定したテキストまたはセルグリッドと比較します。
3. 仮想端末テスト。 ANSI出力を端末エミュレーターに入力し、最終的なセル、カーソル、スタイル、スクロールバック、クリーンアップを検証します。
4. PTY統合テスト。 実際のプログラムを起動し、キー入力／貼り付け／サイズ変更を送信して、画面上の動作と終了ステータスを検証します。

スナップショットの安定化

次の項目を固定または正規化します。

• 端末サイズ。
• テーマとカラー対応。
• 時刻、ランダムID、ネットワークデータ、スピナー、カーソルの点滅。
• Unicodeモードと曖昧幅の前提。
• テストを複数のプラットフォームで実行する場合のファイルパス。
• 進捗率と非同期スケジューリング。

動作の検証にはセマンティックアサーションを優先し、安定した視覚的な仕様にはスナップショットを使用します。

デバッグのワークフロー

1. 最小の端末サイズと入力シーケンスで再現します。
2. プロトコルの動作が疑われる場合は、入力と出力の生バイト列を取得します。
3. 標準出力、標準エラー、ログ、代替画面の出力を分離します。
4. アニメーションと色を無効にして、スタイルとレイアウトを切り分けます。
5. 関連する場合は、tmux/screen/SSHの外側と内側の両方でテストします。
6. Windows対応を謳う場合は、WindowsでConPTYを介してテストします。

CIのルール

• CIに実際のTTYがあると想定しないでください。
• 統合テストで端末の動作が必要な場合は、PTYラッパーを使用します。
• 端末エミュレーター固有のテストを明示します。
• スナップショットを決定論的でレビューしやすい状態に保ちます。
• 失敗時にはログと最終的な端末フレームをアーティファクトとして保存します。

失敗パターン

症状	考えられる原因	対処法
スナップショットが不安定	時刻、スピナー、ランダムデータ、端末幅	入力を固定して出力を正規化する
手動では動作するが、CIでは失敗する	TTYがない、またはTERMが異なる	PTYを作成するか、非TUIモードを使用する
Windowsのテストだけ失敗する	UnixのPTYに関する前提	ConPTY経由でテストし、改行を考慮する
生バイト列は異なるが、画面は同じ	最終セルではなくシーケンスをテストしている	仮想端末の状態を検証する
デバッグログでUIが乱れる	ログが制御対象の画面に書き込まれている	ログをファイルまたはパネルに出力する

参考ファイル

• references/test-strategy.md - テスト層、ツール、エコシステムごとのアサーション。
• references/debugging-playbook.md - バイト列の取得、端末のリセット、CI、Windows、フレークの切り分け。