From 681dae457c3ae908c68bca556594cae452675ece Mon Sep 17 00:00:00 2001
From: opaopa6969 <opaopa6969@gmail.com>
Date: Wed, 5 Aug 2026 22:31:44 +0900
Subject: [PATCH] =?UTF-8?q?docs:=20test-baseline=20=E9=81=8B=E7=94=A8?=
 =?UTF-8?q?=E3=82=92=20docs/=20=E3=81=A8=20README=20=E3=81=AB=E8=A8=98?=
 =?UTF-8?q?=E8=BC=89=20(#63)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

test-baseline.txt と tools/ci/check-test-baseline.sh は CI が依存する
仕組みだが README/AGENTS.md/docs に説明がなく、新規参加者が役割を
理解しにくかった。

- docs/test-baseline.md: 役割・動作・baseline 更新手順・運用方針
- docs/INDEX.md / INDEX.ja.md: Analysis セクションに追記
- README.md / README.en.md: 開発セクションに1行リンク追記

Closes #63
---
 README.en.md          |  2 ++
 README.md             |  2 ++
 docs/INDEX.ja.md      |  1 +
 docs/INDEX.md         |  1 +
 docs/test-baseline.md | 47 +++++++++++++++++++++++++++++++++++++++++++
 5 files changed, 53 insertions(+)
 create mode 100644 docs/test-baseline.md

diff --git a/README.en.md b/README.en.md
index da56af06..987dddbb 100644
--- a/README.en.md
+++ b/README.en.md
@@ -276,4 +276,6 @@ External repository: [tinyexpression-group/tinyexpression-ide](https://github.co
 mvn -q test
 ```
 
+CI manages known failures via `test-baseline.txt` and fails on new ones. See [docs/test-baseline.md](docs/test-baseline.md) for the workflow and update procedure.
+
 Document index: [docs/INDEX.md](docs/INDEX.md)
diff --git a/README.md b/README.md
index d7f81201..4fc8fabc 100644
--- a/README.md
+++ b/README.md
@@ -276,4 +276,6 @@ VS Code 拡張 [tinyexpression-p4-lsp-vscode](tools/tinyexpression-p4-lsp-vscode
 mvn -q test
 ```
 
+CI は `test-baseline.txt` で既知の失敗を管理し、新規失敗で落とす。運用と更新手順は [docs/test-baseline.md](docs/test-baseline.md) 参照。
+
 ドキュメント一覧: [docs/INDEX.ja.md](docs/INDEX.ja.md)
diff --git a/docs/INDEX.ja.md b/docs/INDEX.ja.md
index b3a46224..77d585bf 100644
--- a/docs/INDEX.ja.md
+++ b/docs/INDEX.ja.md
@@ -34,6 +34,7 @@
 |-------------|------|
 | [backend-coverage-matrix.md](./backend-coverage-matrix.md) | 5つの実行バックエンドのカバレッジマトリクス |
 | [feature-parity-diff.md](./feature-parity-diff.md) | 手書きパスと UBNF (P4) パスの機能パリティ差分 |
+| [test-baseline.md](./test-baseline.md) | `test-baseline.txt` / `check-test-baseline.sh` の運用（既知の失敗の管理と更新手順） |
 
 ## その他のドキュメント
 
diff --git a/docs/INDEX.md b/docs/INDEX.md
index 88dfc1d6..ecf672e4 100644
--- a/docs/INDEX.md
+++ b/docs/INDEX.md
@@ -34,6 +34,7 @@
 |----------|-------------|
 | [backend-coverage-matrix.md](./backend-coverage-matrix.md) | Backend coverage matrix for the 5 execution backends |
 | [feature-parity-diff.md](./feature-parity-diff.md) | Feature parity diff between hand-written path and UBNF (P4) path |
+| [test-baseline.md](./test-baseline.md) | `test-baseline.txt` / `check-test-baseline.sh` の運用（既知の失敗の管理と更新手順） |
 
 ## Other Documentation
 
diff --git a/docs/test-baseline.md b/docs/test-baseline.md
new file mode 100644
index 00000000..40dcaf70
--- /dev/null
+++ b/docs/test-baseline.md
@@ -0,0 +1,47 @@
+# Test Baseline 運用
+
+CI は `test-baseline.txt` と `tools/ci/check-test-baseline.sh` で「既知の失敗」を管理し、新規失敗の混入を検出する。
+
+## 役割
+
+| 要素 | 役割 |
+|------|------|
+| `test-baseline.txt` | 既知の失敗テスト一覧（`Class#method` 形式、1行1件）。空ファイル = 既知の失敗ゼロ件。 |
+| `tools/ci/check-test-baseline.sh` | surefire の失敗をベースラインと比較するゲートスクリプト。 |
+
+## `check-test-baseline.sh` の動作
+
+前提: `mvn verify -Dmaven.test.failure.ignore=true` 実行後（`target/surefire-reports/` に結果があること）。
+
+- **ベースラインに無い新規失敗** → `::error` を出し **exit 1** で CI を落とす。
+- **ベースラインに有るが今回は通った** → `::notice` で警告のみ（ベースライン縮小を促す）。
+- **新規失敗なし** → `OK: 新規失敗なし` を出し exit 0。
+
+## baseline 更新手順
+
+```bash
+# 1. フルテストを実行（失敗を止めず最後まで走らせる）
+mvn verify -Dmaven.test.failure.ignore=true \
+  -Dtinyexpression.skipRailroad=true -Dgpg.skip=true \
+  -Dmaven.javadoc.skip=true -Dspotbugs.skip=true -Derrorprone.skip=true
+
+# 2. ベースラインを生成（target/surefire-reports から失敗を収集）
+bash tools/ci/check-test-baseline.sh --write-baseline
+
+# 3. 内容を確認してコミット
+git diff test-baseline.txt
+git add test-baseline.txt && git commit -m "test: update baseline"
+```
+
+`--write-baseline` は `target/surefire-reports/TEST-*.xml` から `failure` / `error` を持つ `testcase` を集計し `Class#method` 形式で書き出す。
+
+## 運用方針
+
+- **新規失敗は許容しない**。ベースライン未登録の失敗が出たら CI を落とし、修正するかベースラインに登録する（登録は人間判断）。
+- **ベースラインの縮小は推奨**。ベースラインに有るテストが通ったら `::notice` で知らせるので、整理して縮小を図る。
+- **ベースラインが空の場合**、既知の失敗ゼロ件を意味する。#58 のような「baseline に登録して運用する」想定の issue と実態が不整合にならないよう注意。
+
+## 関連 issue
+
+- #58: TernaryExpressionTest 失敗と baseline 運用の不整合
+- #38: 指数バックトラックに起因するテスト失敗（#58 の前身）