From 695c95835a0f936d70c316525ce361f85a14e13e Mon Sep 17 00:00:00 2001 From: kiyotis Date: Fri, 26 Jun 2026 09:53:39 +0900 Subject: [PATCH 01/15] =?UTF-8?q?chore:=20start=20session=20=E2=80=94=20nt?= =?UTF-8?q?f-yaml-support?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Sonnet 4.6 --- .rn/ntf-yaml-support/input/ntf-doc-terms.md | 538 ++++++++++++++ .../input/ntf-testdata-doc-examples-file.md | 308 ++++++++ .../ntf-testdata-doc-examples-messaging.md | 197 +++++ .../ntf-testdata-doc-examples-overview.md | 194 +++++ .../ntf-testdata-doc-examples-special.md | 321 ++++++++ .../input/ntf-testdata-doc-examples-table.md | 182 +++++ .../ntf-testdata-doc-examples-testshots.md | 287 +++++++ .../input/ntf-testdata-doc.md | 699 ++++++++++++++++++ .../input/ntf-testdata-loading.md | 263 +++++++ .../input/testdata-converter-design.md | 363 +++++++++ .rn/ntf-yaml-support/steering.md | 124 ++++ 11 files changed, 3476 insertions(+) create mode 100644 .rn/ntf-yaml-support/input/ntf-doc-terms.md create mode 100644 .rn/ntf-yaml-support/input/ntf-testdata-doc-examples-file.md create mode 100644 .rn/ntf-yaml-support/input/ntf-testdata-doc-examples-messaging.md create mode 100644 .rn/ntf-yaml-support/input/ntf-testdata-doc-examples-overview.md create mode 100644 .rn/ntf-yaml-support/input/ntf-testdata-doc-examples-special.md create mode 100644 .rn/ntf-yaml-support/input/ntf-testdata-doc-examples-table.md create mode 100644 .rn/ntf-yaml-support/input/ntf-testdata-doc-examples-testshots.md create mode 100644 .rn/ntf-yaml-support/input/ntf-testdata-doc.md create mode 100644 .rn/ntf-yaml-support/input/ntf-testdata-loading.md create mode 100644 .rn/ntf-yaml-support/input/testdata-converter-design.md create mode 100644 .rn/ntf-yaml-support/steering.md diff --git a/.rn/ntf-yaml-support/input/ntf-doc-terms.md b/.rn/ntf-yaml-support/input/ntf-doc-terms.md new file mode 100644 index 00000000..91b67147 --- /dev/null +++ b/.rn/ntf-yaml-support/input/ntf-doc-terms.md @@ -0,0 +1,538 @@ +# NTF 解説書（v6）用語リファレンス + +NTF（自動テストフレームワーク）解説書から抽出した用語の引き表。`ntf-testdata-doc.md` の見直しで、解説書の正式な用語名・表記・仕様を引くために使う。 + +取得元の解説書 URL ベース: +`https://nablarch.github.io/docs/LATEST/doc/development_tools/testing_framework/guide/development_guide/` + +取得対象は `06_TestFWGuide/` 配下、補足参照は `05_UnitTestGuide/` 配下。各用語の出典ページは見出し直下に示す。 + +--- + +## 用語ドメインの全体像 + +```mermaid +flowchart TB + DT[データタイプ
Excel 1行目のキーワード] + SHEET[シート・行・列・セル
テストデータの物理構造] + GID[グループID
同シート内データの識別標識] + TS[testShots / requestParams
テストケース一覧] + FILE[ファイルデータ
固定長・可変長のフィールド定義] + MSG[メッセージング
電文・FW制御ヘッダ] + FORMAT[特殊記法・コメント・マーカーカラム
セル値の解釈規則] + + SHEET --> DT + DT --> GID + DT --> TS + DT --> FILE + DT --> MSG + SHEET --> FORMAT +``` + +データタイプが解析の起点（Excel 1 行目の `データタイプ=値`）で、グループ ID・testShots・ファイルデータ・メッセージングはいずれもデータタイプに紐づく。特殊記法・コメント・マーカーカラムはセル値の解釈規則として全データタイプに横断的にかかる。 + +--- + +## データタイプ（Data Types） + +出典: `06_TestFWGuide/01_Abstract.html` + +フレームワークが認識する固定キーワード。データ 1 行目に `データタイプ=値` の形式で記載する。 + +| データタイプ | 設定値 | 用途 | +|---|---|---| +| `SETUP_TABLE` | テーブル名 | テスト前に DB へ登録する準備データ | +| `EXPECTED_TABLE` | テーブル名 | テスト後の DB 期待値（省略カラムは比較対象外） | +| `EXPECTED_COMPLETE_TABLE` | テーブル名 | テスト後の DB 期待値（省略カラムにはデフォルト値を適用して比較） | +| `LIST_MAP` | 一意の ID | `List>` 形式で取得するデータ | +| `SETUP_FIXED` | ファイルパス | 固定長ファイルの事前準備データ | +| `EXPECTED_FIXED` | ファイルパス | 固定長ファイルの期待値 | +| `SETUP_VARIABLE` | ファイルパス | 可変長ファイルの事前準備データ | +| `EXPECTED_VARIABLE` | ファイルパス | 可変長ファイルの期待値 | +| `EXPECTED_REQUEST_HEADER_MESSAGES` | リクエスト ID | 要求電文（ヘッダ）の期待値（固定長ファイル形式） | +| `EXPECTED_REQUEST_BODY_MESSAGES` | リクエスト ID | 要求電文（本文）の期待値（固定長ファイル形式） | +| `RESPONSE_HEADER_MESSAGES` | リクエスト ID | 応答電文（ヘッダ）データ（固定長ファイル形式） | +| `RESPONSE_BODY_MESSAGES` | リクエスト ID | 応答電文（本文）データ（固定長ファイル形式） | + +`MESSAGE` 系データタイプには、固定 ID として `setUpMessages`／`expectedMessages` も使う（メッセージング処理テスト）。 + +--- + +## シート・行・列・セル + +出典: `06_TestFWGuide/01_Abstract.html` + +| 用語 | 定義 | +|---|---| +| ファイル名 | テストクラス名と同一（拡張子のみ `.xlsx`） | +| シート名 | テストメソッド名と同一 | +| setUpDb シート | テストクラス共通の DB 初期値を記載する特殊シート名（テストメソッド実行前に自動投入） | +| 1 行目（データタイプ行） | `データタイプ=値` を記述する行 | +| 2 行目（ヘッダ行） | カラム名（Map のキー）を記述する行 | +| 3 行目以降（データ行） | 実データ・レコードを記述する行 | +| カラム | Excel の列に対応する概念（フィールド名） | +| セル | 個々の入力値の単位。書式は全て文字列として記述する | + +2 行目以降の具体構造はデータタイプごとに異なる（後述「データタイプ別の行構造」）。 + +--- + +## セル値の解釈規則（特殊記法・マーカーカラム・コメント） + +出典: `06_TestFWGuide/01_Abstract.html` + +### 特殊記法 + +| 記述 | 変換内容 | +|---|---| +| `null` | null 値 | +| `"null"` | 文字列 `null`（前後のダブルクォートを除去） | +| `""` | 空文字列 | +| `${systemTime}` | システム日時（実行時に挿入） | +| `${setUpTime}` | コンポーネント設定ファイルで定めた固定タイムスタンプ | +| `${文字種,文字数}` | 指定文字種・文字数で生成（例: `${半角英字,5}`） | +| `${binaryFile:パス}` | 指定パスのバイナリファイル内容（BLOB 列用） | +| `\\r` | CR 改行コード | +| `\\n` | LF 改行コード | + +### マーカーカラム + +カラム名を半角角括弧で囲む（例: `[no]`）と、そのカラムはテスト実行時に読み込まれない。Excel 上の可読性向上（行番号表示など）に使う視覚的マーカー。 + +### コメント + +セル値の `//` 以降はフレームワークが読み込まない（ドキュメント注釈用途）。 + +### 日付記述フォーマット + +`yyyyMMddHHmmssSSS` または `yyyy-MM-dd HH:mm:ss.SSS`。ミリ秒・時刻部分は省略可能。 + +### 設計原則（用語として登場する概念） + +- テスト独立性: テストメソッドの実行順序に依存しない設計 +- データ集約: テストデータは全て Excel に記述 +- データタイプまとめ記述: 複数データタイプ使用時は種類ごとにまとめる（混在するとデータ読み込みが途中で終了する） + +--- + +## グループ ID + +出典: `06_TestFWGuide/02_RequestUnitTest.html` + +同じシート内に記載したデータを識別する標識。`setUpTable`・`expectedSearch`・`expectedTable` などのカラムでグループ ID を参照し、対応するデータセットを紐付ける。 + +- 書式: `データタイプ[グループID]=値`（例: `SETUP_TABLE[case_001]=EMPLOYEE_TABLE`） +- `default`: デフォルトグループ ID（省略時に使用される） + +--- + +## データタイプ別の行構造 + +### DB 系（SETUP_TABLE / EXPECTED_TABLE / EXPECTED_COMPLETE_TABLE / LIST_MAP） + +出典: `06_TestFWGuide/02_DbAccessTest.html` + +いずれも 1 行目に `データタイプ=値`、2 行目にカラム名（Map のキー）、3 行目以降にデータ行を置く。 + +| データタイプ | 2 行目 | 3 行目以降 | +|---|---|---| +| `SETUP_TABLE=テーブル名` | カラム名（複数列） | 登録レコード | +| `LIST_MAP=任意のID` | Map のキー（SELECT 句で指定したカラム名） | 期待結果（SELECT 対象カラムは全て記述必須） | +| `EXPECTED_TABLE=テーブル名` | カラム名 | 期待値（省略カラムは比較対象外） | +| `EXPECTED_COMPLETE_TABLE=テーブル名` | カラム名 | 期待値（省略カラムにはデフォルト値が格納されているものとして比較） | + +#### デフォルト値 + +| データ型 | デフォルト値 | +|---|---| +| 数値型 | `0` | +| 文字列型 | 半角スペース | +| 日付型 | `1970-01-01 00:00:00.0` | + +カスタマイズは `BasicDefaultValues` クラスで設定。 + +#### カラム省略の制約 + +- 主キーカラムは省略不可。 +- 省略カラムへのデフォルト値適用は `EXPECTED_COMPLETE_TABLE` のみ（`EXPECTED_TABLE` では省略カラムを比較対象外とする）。 + +#### タイムスタンプ形式 + +`java.sql.Timestamp` 型: `yyyy-mm-dd hh:mm:ss.fffffffff`（f は 9 桁ナノ秒） + +#### マスタデータ復旧機能 + +外部キー設定テーブルの親子関係データを扱う際に利用する機能。読み取り専用マスタを共通ファイルで再利用する場合にも用いる。 + +### 固定長ファイル（SETUP_FIXED / EXPECTED_FIXED） + +出典: `06_TestFWGuide/RequestUnitTest_batch.html`、`05_UnitTestGuide/02_RequestUnitTest/batch.html` + +``` +SETUP_FIXED[グループID]=ファイルパス + +[ディレクティブ行] ← text-encoding, record-separator 等 +[レコード種別行] +[フィールド名称行] +[データ型行] ← 日本語表記（例: 半角英字） +[フィールド長行] +[データ行] +``` + +- バイナリデータは 16 進数形式（例: `0x4AD`）で記述。`0x` プレフィックスがない場合は文字列として解釈。 +- 指定したフィールド長に対してデータのバイト長が短い場合、フィールドのデータ型に応じたパディングが行われる。 + +### 可変長ファイル（SETUP_VARIABLE / EXPECTED_VARIABLE） + +出典: `06_TestFWGuide/RequestUnitTest_batch.html`、`05_UnitTestGuide/02_RequestUnitTest/batch.html` + +``` +SETUP_VARIABLE[グループID]=ファイルパス + +[ディレクティブ行] +[レコード種別行] +[フィールド名称行] +[データ型行] +（フィールド長行は存在しない） +[データ行] +``` + +固定長との違いはフィールド長を記載しない点。 + +### ファイルデータのフィールド定義用語 + +| 用語 | 定義 | +|---|---| +| レコード種別行 | ファイルデータのレコード種別を示す行 | +| フィールド名称行 | 各フィールド名称を並べた行 | +| データ型行 | フィールドのデータ型を示す行（日本語表記例: 「半角英字」） | +| フィールド長行 | 各フィールドのバイト長を示す行（固定長のみ存在） | +| データ行 | 実データを並べた行 | +| パディング | フィールド長に対してデータのバイト長が短い場合に自動補完される処理 | + +### ディレクティブ + +出典: `06_TestFWGuide/RequestUnitTest_batch.html` + +ファイル／電文フォーマット定義の設定行。コンポーネント設定でデフォルト値を map 形式で指定可能。 + +| ディレクティブキー | 対象 | 説明 | +|---|---|---| +| `text-encoding` | 共通 | 文字エンコーディング（例: `Windows-31J`） | +| `record-separator` | 共通 | レコード区切り文字（例: `CRLF`） | +| `quoting-delimiter` | 可変長 | 引用符区切り文字 | +| `file-type` | メッセージ | 電文全体を文字列として扱うか項目単位で分割するかの制御（`Fixed` / `XML` / `JSON` 等） | +| `record-length` | 固定長 | レコード長。フィールド長から自動計算のため記載不要な場合あり | + +デフォルト値設定のコンポーネントプロパティ: +- `defaultDirectives`（共通） +- `fixedLengthDirectives`（固定長専用） +- `variableLengthDirectives`（可変長専用） + +--- + +## testShots / requestParams（テストケース一覧） + +`LIST_MAP` データタイプで定義するテストケース一覧。固定 ID `testShots` と `requestParams` を持ち、カラム構成はテスト種別ごとに異なる。 + +| 用語 | 定義 | +|---|---| +| `testShots` | テストケース一覧の `LIST_MAP` ID（固定値） | +| `TestShot` | テストケース 1 件分の情報を格納・実行するクラス | +| `requestParams` | リクエストパラメータの `LIST_MAP` ID（固定値） | +| 行単位の関連付け | testShots と requestParams は同じ行番号で対応する | + +### testShots カラム一覧（ウェブアプリケーション） + +出典: `06_TestFWGuide/02_RequestUnitTest.html`、`05_UnitTestGuide/02_RequestUnitTest/index.html` + +| カラム名 | 必須 | 説明 | +|---|---|---| +| `no` | ✓ | テストケース番号（1 からの連番） | +| `description` | ✓ | テストケースの説明。HTML ダンプファイル名に使用される | +| `context` | ✓ | リクエスト ID・ユーザ・HTTP メソッドを記載 | +| `cookie` | - | Cookie 情報 | +| `queryParams` | - | クエリパラメータ情報 | +| `isValidToken` | - | トークン設定の要否（`true` / `false`） | +| `setUpTable` | - | テストケース実行前の DB 登録用グループ ID | +| `expectedStatusCode` | ✓ | 期待する HTTP ステータスコード | +| `expectedMessageId` | - | 期待するメッセージ ID（複数の場合はカンマ区切り） | +| `expectedSearch` | - | 期待する検索結果のグループ ID（`SqlResultSet` 型、リクエストスコープキー `searchResult`） | +| `expectedTable` | - | 期待するテーブル状態のグループ ID | +| `forwardUri` | - | 期待するフォワード先 URI | +| `expectedContentLength` | - | ダウンロード時のコンテンツレングス期待値 | +| `expectedContentType` | - | ダウンロード時のコンテンツタイプ期待値 | +| `expectedContentFileName` | - | ダウンロード時のファイル名期待値 | +| `expectedMessage` | - | メッセージ同期送信時の要求電文グループ ID | +| `responseMessage` | - | メッセージ同期送信時の応答電文グループ ID | +| `expectedMessageByClient` | - | HTTP メッセージ同期送信時の要求電文グループ ID | +| `responseMessageByClient` | - | HTTP メッセージ同期送信時の応答電文グループ ID | + +#### requestParams の仕様 + +- `LIST_MAP=requestParams` として定義。HTTP リクエストパラメータを表す。 +- パラメータが不要なテストケースでもダミー行の定義が必須。 +- 1 つのキーに複数の値を指定する場合はカンマ区切り。カンマ自体を含める場合は `\\` でエスケープ。 + +### testShots カラム一覧（バッチ処理） + +出典: `06_TestFWGuide/RequestUnitTest_batch.html`、`05_UnitTestGuide/02_RequestUnitTest/batch.html` + +| カラム名 | 必須 | 説明 | +|---|---|---| +| `no` | ✓ | テストケース番号（1 からの連番） | +| `description` | ✓ | テストケースの説明 | +| `expectedStatusCode` | ✓ | 期待するステータスコード | +| `diConfig` | ✓ | バッチ実行時のコンポーネント設定ファイルへのパス | +| `requestPath` | ✓ | バッチ実行時のリクエストパス | +| `userId` | ✓ | バッチ実行ユーザ ID | +| `setUpTable` | - | テスト前の DB 登録用グループ ID | +| `setUpFile` | - | 入力用ファイル作成時に参照するデータのグループ ID | +| `expectedTable` | - | 期待する DB 状態のグループ ID | +| `expectedFile` | - | 出力ファイルの期待値データのグループ ID | +| `expectedLog` | - | 期待するログメッセージを記載した `LIST_MAP` の ID | +| `args[n]` | - | コマンドライン引数（n は 0 以上の整数、連続した添字が必要） | + +### testShots カラム一覧（メッセージング受信） + +出典: `06_TestFWGuide/RequestUnitTest_real.html`、`05_UnitTestGuide/02_RequestUnitTest/real.html` + +| カラム名 | 必須 | 説明 | +|---|---|---| +| `no` | ✓ | テストケース番号（1 からの連番） | +| `description` | ✓ | テストケースの説明 | +| `expectedStatusCode` | ✓ | 期待するステータスコード | +| `diConfig` | ✓ | コンポーネント設定ファイルパス | +| `requestPath` | ✓ | リクエストパス（常駐バッチ） | +| `userId` | ✓ | 実行ユーザ ID | +| `setUpTable` | - | テスト前の DB 初期化用グループ ID | +| `expectedTable` | - | 期待する DB 状態のグループ ID | +| `expectedLog` | - | 期待するログメッセージ ID | + +### ログ検証（expectedLog） + +出典: `06_TestFWGuide/RequestUnitTest_batch.html` + +`LIST_MAP=expectedLogMessages` として定義し、以下のカラムを含む（AND 条件で評価）。 + +| カラム名 | 説明 | +|---|---| +| `logLevel` | 期待するログレベル | +| `message1` | 期待するログに含まれる文言（複数設定可: `message1`, `message2`, ...） | + +--- + +## メッセージング + +### 基本用語 + +| 用語 | 定義 | +|---|---| +| 電文 | メッセージング処理のメッセージ | +| 要求電文 | 送信するメッセージ（リクエスト） | +| 応答電文 | 受信するメッセージ（レスポンス） | +| 電文種別 | 要求電文／応答電文の分類 | +| フレームワーク制御ヘッダ | メッセージに付与される制御情報（`requestId` 等） | +| メッセージボディ | フレームワーク制御ヘッダ以降の実データ部分 | +| `setUpMessages` | メッセージング受信テストにおける要求電文 ID（固定値） | +| `expectedMessages` | メッセージング受信テストにおける応答電文期待値 ID（固定値） | +| `no`（電文側） | 複数電文送信時の連番・送信順序を示す電文内フィールド | + +### メッセージデータ構造（受信: setUpMessages / expectedMessages） + +出典: `06_TestFWGuide/RequestUnitTest_real.html`、`05_UnitTestGuide/02_RequestUnitTest/real.html` + +`MESSAGE=setUpMessages` または `MESSAGE=expectedMessages` として定義。 + +セクション 1 ─ ディレクティブ行: +- `text-encoding`（文字エンコーディング） +- `record-separator`（レコード区切り） +- `requestId`（フレームワーク制御ヘッダ: リクエスト識別子） +- `file-type`（電文種別の解釈方式） + +セクション 2 ─ メッセージボディ: +- 1 行目: フィールド名称（先頭セルは `no`） +- 2 行目: データ型（先頭セルは空白） +- 3 行目: フィールド長（先頭セルは空白） +- 4 行目以降: 実データ（先頭セルは通番） + +#### `FwHeaderDefinition` / `fwHeaderDefinition` + +- `FwHeaderDefinition` 実装クラスが `fwHeaderDefinition` という名前でコンポーネント登録されていることが前提。 +- 異なる名称の場合は `getFwHeaderDefinitionName()` メソッドをオーバーライドする。 + +### メッセージデータタイプ（同期応答メッセージ送信） + +出典: `06_TestFWGuide/RequestUnitTest_send_sync.html`、`05_UnitTestGuide/02_RequestUnitTest/send_sync.html` + +| データタイプ | 設定値 | 用途 | +|---|---|---| +| `EXPECTED_REQUEST_HEADER_MESSAGES` | リクエスト ID | 要求電文ヘッダの期待値 | +| `EXPECTED_REQUEST_BODY_MESSAGES` | リクエスト ID | 要求電文本文の期待値 | +| `RESPONSE_HEADER_MESSAGES` | リクエスト ID | 応答電文ヘッダデータ | +| `RESPONSE_BODY_MESSAGES` | リクエスト ID | 応答電文本文データ | + +グループ ID 付き書式例: `EXPECTED_REQUEST_BODY_MESSAGES[グループID]=リクエストID` + +電文データの行構造: `no` カラム（複数電文送信時の連番・送信順序） → フィールド名称行 → データ型行（日本語表記例: 「半角英字」） → フィールド長行 → データ行。 + +ディレクティブの記載不要項目: +- `file-type`（テスティングフレームワークが固定長のみ対応） +- `record-length`（フィールド長から自動計算） + +### 障害系テスト用特殊値 + +応答電文の最初のフィールド（`no` 除く）に設定する。 + +| 設定値 | 発生する例外 | +|---|---| +| `errorMode:timeout` | `MessageSendSyncTimeoutException`（タイムアウトシミュレート） | +| `errorMode:msgException` | `MessagingException`（メッセージ受信エラーシミュレート） | + +### 制約事項（同期応答メッセージ送信） + +- フィールド名称に重複は許容されない。 +- 複数レコード電文の場合「ヘッダ → 本文」を交互に記載する必要がある。 +- `expectedMessage` および `responseMessage` が空欄で送信が行われた場合、テストは失敗する。 + +### HTTP 同期応答メッセージ送信の用語読み替え + +出典: `06_TestFWGuide/RequestUnitTest_http_send_sync.html` + +「同期応答メッセージ送信処理テスト」との差分のみ。基本は同期応答メッセージ送信を参照。 + +| 標準用語（同期応答メッセージ送信） | HTTP 版の対応用語 | +|---|---| +| 同期応答メッセージ送信 | HTTP 同期応答メッセージ送信 | +| `MockMessagingContext` | `MockMessagingClient` | +| `RequestTestingMessagingProvider` | `RequestTestingMessagingClient` | + +--- + +## テスト種別と主要クラス + +### テスト種別の正式名称 + +| 正式名称 | 内容 | +|---|---| +| クラス単体テスト | Action/Component の単体テスト | +| リクエスト単体テスト（ウェブアプリケーション） | HTTP リクエスト 1 件単位のテスト（シンクライアント型）。Ajax 等のリッチクライアントは未対応 | +| リクエスト単体テスト（RESTful ウェブサービス） | REST API の 1 リクエスト単位テスト | +| リクエスト単体テスト（バッチ処理） | バッチ処理の 1 バッチ起動単位テスト | +| リクエスト単体テスト（メッセージ受信処理） | 電文受信 1 件単位テスト | +| リクエスト単体テスト（同期応答メッセージ送信処理） | 同期応答電文送信の 1 リクエスト単位テスト | +| リクエスト単体テスト（HTTP 同期応答メッセージ送信処理） | HTTP 同期応答電文送信の 1 リクエスト単位テスト | +| 取引単体テスト | 複数リクエストをまたぐ業務取引単位のテスト | + +### DB アクセステスト + +出典: `06_TestFWGuide/02_DbAccessTest.html` + +| 分類 | 操作 | 検証・要件 | +|---|---|---| +| 参照系テスト | SELECT | `setUpDb` で準備データを投入し、`assertSqlResultSetEquals` で検証。コミット処理は不要 | +| 更新系テスト | INSERT / UPDATE / DELETE | 実行後に `commitTransactions()` が必須。`assertTableEquals` で検証 | + +| メソッド | 用途 | +|---|---| +| `setUpDb(String sheetName)` | シート内の全 SETUP_TABLE を処理して準備データを投入 | +| `assertSqlResultSetEquals(sheetName, mapId, SqlResultSet)` | 参照結果を LIST_MAP と比較（レコード順序を厳密に比較） | +| `assertTableEquals(sheetName)` | 更新後 DB を EXPECTED_TABLE と比較（主キーで照合、順序不問） | +| `commitTransactions()` | トランザクションをコミット（更新系テストで必須） | + +### リクエスト単体テスト（ウェブアプリケーション）の主要クラス + +出典: `06_TestFWGuide/02_RequestUnitTest.html`、`05_UnitTestGuide/02_RequestUnitTest/index.html` + +| クラス名 | 役割 | +|---|---| +| `DbAccessTestSupport` | DB 関連の準備データ投入・検証機能 | +| `HttpServer` | 内蔵サーブレットコンテナ（内蔵サーバ） | +| `HttpRequestTestSupport` | リクエスト単体テスト用アサート提供 | +| `BasicHttpRequestTestTemplate` | テストソース記述量を削減するテンプレートクラス | +| `TestCaseInfo` | データシートに定義されたテストケース情報を格納するクラス | + +シート構成: `setUpDb` シート（テストクラス共通 DB 初期値）、`testShots` シート（テストケース一覧、`LIST_MAP` ID は `testShots`）、`requestParams` シート（HTTP リクエストパラメータ、`LIST_MAP` ID は `requestParams`）。 + +#### HTML ダンプ出力 + +- デフォルト出力先: `./tmp/html_dump` +- ディレクトリ構造: テストクラスごとのディレクトリ／テストケース説明と同名の HTML ファイル +- CSS・画像等のリソースも同ディレクトリに出力。 + +#### コンポーネント設定の主要項目 + +| 項目名 | デフォルト値 | 説明 | +|---|---|---| +| `htmlDumpDir` | `./tmp/html_dump` | HTML ダンプの出力先 | +| `webBaseDir` | `../main/web` | ウェブアプリケーションルート | +| `userIdSessionKey` | `user.id` | ユーザ ID を格納するセッションキー | +| `dumpVariableItem` | `false` | JSESSIONID・トークンのダンプ出力制御 | +| `checkHtml` | `true` | HTML チェック実施フラグ | + +### リクエスト単体テスト（RESTful ウェブサービス） + +出典: `06_TestFWGuide/RequestUnitTest_rest.html` + +| クラス名 | 役割 | +|---|---| +| `RestTestSupport` | DB 機能を含む完全版スーパクラス | +| `SimpleRestTestSupport` | DB 不要な場合の簡略版スーパクラス | +| `RestMockHttpRequest` | リクエスト構築に使用するオブジェクト | + +- リクエスト構築（流れるようなインターフェース）: `get` / `post` / `put` / `patch` / `delete` および汎用の `newRequest` で `RestMockHttpRequest` を生成。 +- 結果検証: `assertStatusCode`（HTTP ステータスコード）、`readTextResource`（ファイルベースの期待値読み込み）。レスポンスボディは JSONAssert・json-path-assert・XMLUnit 等の外部ライブラリを推奨。 +- 必須モジュール: `nablarch-testing-rest`・`nablarch-testing-default-configuration`・`nablarch-testing-jetty12`。 + +### リクエスト単体テスト（バッチ処理） + +出典: `06_TestFWGuide/RequestUnitTest_batch.html`、`05_UnitTestGuide/02_RequestUnitTest/batch.html` + +| クラス名 | 役割 | +|---|---| +| `StandaloneTestSupportTemplate` | コンテナ外処理のテスト環境を提供 | +| `BatchRequestTestSupport` | テスト準備・アサート提供 | +| `TestShot` | テストケース 1 件分の情報を格納・実行するクラス | +| `MainForRequestTesting` | テスト用メインクラス | + +常駐バッチテスト時のハンドラ変更: `RequestThreadLoopHandler` を `OneShotLoopHandler` に変更する（セットアップした要求データ全件処理後にバッチ実行が終了するため）。 + +### リクエスト単体テスト（メッセージ受信処理） + +出典: `06_TestFWGuide/RequestUnitTest_real.html`、`05_UnitTestGuide/02_RequestUnitTest/real.html` + +| クラス名 | 役割 | +|---|---| +| `StandaloneTestSupportTemplate` | コンテナ外処理のテスト環境を提供 | +| `TestShot` | テストケース 1 件分の情報を格納・実行するクラス | +| `MessagingRequestTestSupport` | 同期応答メッセージ用スーパクラス | +| `MessagingReceiveTestSupport` | 応答不要メッセージ用スーパクラス | + +### リクエスト単体テスト（同期応答メッセージ送信処理） + +出典: `06_TestFWGuide/RequestUnitTest_send_sync.html`、`05_UnitTestGuide/02_RequestUnitTest/send_sync.html` + +| クラス名 | 役割 | +|---|---| +| `StandaloneTestSupportTemplate` | Action 実行後に `MockMessagingContext` で要求メッセージを検証 | +| `AbstractHttpRequestTestTemplate` | HTTP ベース処理用スーパクラス | +| `RequestTestingMessagingProvider` | 要求メッセージ検証・応答メッセージ生成 | +| `MessageSender` | 同期応答メッセージ送信処理コンポーネント | +| `TestDataConvertor` | Excel から読み込んだテストデータの編集インターフェース | +| `MockMessagingContext` | モックメッセージングコンテキスト | + +--- + +## その他のフレームワーク固有用語 + +| 用語 | 定義 | +|---|---| +| 内蔵サーバ | テスト時に使用するサーブレットコンテナ（`HttpServer`） | +| リクエストスコープ | HTTP リクエスト単位のスコープ（例: 検索結果格納キー `searchResult`） | +| `BasicDefaultValues` | デフォルト値設定をカスタマイズするクラス | +| `FixedSystemTimeProvider` | システム日時を固定値に設定するコンポーネント（形式: `yyyyMMddHHmmss`） | +| `FastTableIdGenerator` | シーケンスオブジェクト採番をテーブル採番に置き換えるコンポーネント | +| `nablarch.test.resource-root` | テストデータ読み込みディレクトリの設定キー（セミコロン区切りで複数指定可） | +| `BasicAdvice` | `execute(Advice advice)` で使用するコールバック実装クラス | +| `beforeExecute()` | リクエスト送信前コールバック | +| `afterExecute()` | リクエスト送信後コールバック | diff --git a/.rn/ntf-yaml-support/input/ntf-testdata-doc-examples-file.md b/.rn/ntf-yaml-support/input/ntf-testdata-doc-examples-file.md new file mode 100644 index 00000000..17f11f6a --- /dev/null +++ b/.rn/ntf-yaml-support/input/ntf-testdata-doc-examples-file.md @@ -0,0 +1,308 @@ +# NTF テストデータ解説書 — 記述例（ファイルデータ） + +ファイルデータ（固定長／可変長）のテストデータを Excel と YAML で書くための記述例集です。該当するシナリオの節を引いて、Excel 表と YAML を写して使います。 + +## 全体像 + +各形式は同じ NTF 仕様上の意味を別の記法で表します。中核要素の対応は次のとおり。 + +```mermaid +flowchart LR + subgraph Excel + E1[SETUP_FIXED=パス / 区切り行] + E2[レコード種別+フィールド名称行] + E3[データ型行 / フィールド長行] + E4[データ行 先頭セル空] + end + subgraph YAML + Y1[path / type / group_id] + Y2[record_type] + Y3["fields: name/type/length"] + Y4["rows: 値配列"] + end + E1 --- Y1 + E2 --- Y2 + E3 --- Y3 + E4 --- Y4 +``` + +| 節 | シナリオ | 引くきっかけ | +|---|---|---| +| [6.1](#61-固定長ファイル) | 固定長ファイル | 入出力とも固定長の基本形 | +| [6.2](#62-エンコーディング指定付き固定長ファイル) | エンコーディング指定 | `text-encoding` 等のディレクティブを付ける | +| [6.3](#63-groupid-付き固定長ファイル) | groupId 付き | ケースごとに入力ファイルを使い分ける | +| [6.4](#64-可変長ファイル) | 可変長ファイル | CSV など区切り文字形式 | +| [6.5](#65-複数レコードレイアウト) | 複数レコードレイアウト | 1 ファイルに HEADER と DATA が混在 | +| [6.6](#66-空ファイル) | 空ファイル | 0 バイトのファイルを生成 | + +形式間で共通する記法規則: + +- フィールドは Excel では「レコード種別+フィールド名称行・データ型行・フィールド長行」の 3 行、YAML では `fields:` 配列の 1 要素（`name`／`type`／`length`）で定義します。 +- データ値はパディングなしで記述します。フレームワークが自動付与します。 +- YAML の `rows:` 各配列は `fields:` と**完全に同じ順序・件数**で値を並べます。 +- Excel のデータ行は先頭セルを必ず空にします（Excel 固有の制約）。YAML に先頭要素を空にする制約はありません。 + +各節の YAML キーは上記を前提に、節固有の差分（ディレクティブ・groupId・レコード数）だけを示します。 + +--- + + + +## 6.1 固定長ファイル + +注文データのバッチ処理テスト。固定長の入力ファイルを読み込んで処理し、結果を固定長の出力ファイルに書き出すことを確認するケース。 + +### Excel + +| SETUP_FIXED=work/input.txt | | | | | +|---|---|---|---|---| +| データ | ID | COUNTER | MESSAGE | | +| | 半角 | 数値 | 半角 | | +| | 5 | 5 | 10 | | +| | 10001 | 10 | hello | | +| | 10002 | 20 | good bye. | | + +| EXPECTED_FIXED=work/output.txt | | | | | +|---|---|---|---|---| +| データ | ID | COUNTER | MESSAGE | | +| | 半角 | 数値 | 半角 | | +| | 5 | 5 | 10 | | +| | 10001 | 11 | HELLO | | +| | 10002 | 21 | GOOD BYE. | | + +### YAML + +```yaml +setup_files: + - path: work/input.txt + type: fixed + records: + - record_type: データ + fields: + - {name: ID, type: 半角, length: 5} + - {name: COUNTER, type: 数値, length: 5} + - {name: MESSAGE, type: 半角, length: 10} + rows: + - ["10001", "10", "hello"] + - ["10002", "20", "good bye."] + +expected_files: + - path: work/output.txt + type: fixed + records: + - record_type: データ + fields: + - {name: ID, type: 半角, length: 5} + - {name: COUNTER, type: 数値, length: 5} + - {name: MESSAGE, type: 半角, length: 10} + rows: + - ["10001", "11", "HELLO"] + - ["10002", "21", "GOOD BYE."] +``` + +--- + +## 6.2 エンコーディング指定付き固定長ファイル + +MS932 エンコーディングで顧客データファイルを読み込むケース。ディレクティブでエンコーディングを明示指定します。 + +### Excel + +| SETUP_FIXED=input/data.dat | | | | +|---|---|---|---| +| text-encoding | MS932 | | | +| DATA | USER_ID | USER_NAME | AMOUNT | +| | X | N | Z | +| | 10 | 20 | 10 | +| | 001 | 山田太郎 | 5000 | +| | 002 | 鈴木花子 | 3000 | + +- ディレクティブ行はレコード定義より前に記述します（「キー | 値」の 2 セル構成）。 + +### YAML + +```yaml +setup_files: + - path: input/data.dat + type: fixed + directives: + text-encoding: MS932 + records: + - record_type: DATA + fields: + - {name: USER_ID, type: 半角, length: 10} + - {name: USER_NAME, type: 全角, length: 20} + - {name: AMOUNT, type: 数値, length: 10} + rows: + - ["001", "山田太郎", "5000"] + - ["002", "鈴木花子", "3000"] +``` + +- ディレクティブは `directives:` オブジェクトの `key: value` 形式で記述します。 + +--- + +## 6.3 groupId 付き固定長ファイル + +テストケースごとに異なる入力ファイルを使い分けるケース。groupId なしがデフォルトの 1 件処理、`case2` が追加データありの複数件処理に対応します。 + +### Excel + +| SETUP_FIXED=work/input.txt | | | | | +|---|---|---|---|---| +| データ | ID | COUNTER | MESSAGE | | +| | 半角 | 数値 | 半角 | | +| | 5 | 5 | 10 | | +| | 10001 | 10 | hello | | + +| SETUP_FIXED[case2]=work/input.txt | | | | | +|---|---|---|---|---| +| データ | ID | COUNTER | MESSAGE | | +| | 半角 | 数値 | 半角 | | +| | 5 | 5 | 10 | | +| | 20001 | 30 | morning | | + +- groupId は `SETUP_FIXED[case2]=パス` のように指定します。 + +### YAML + +```yaml +setup_files: + - path: work/input.txt + type: fixed + records: + - record_type: データ + fields: + - {name: ID, type: 半角, length: 5} + - {name: COUNTER, type: 数値, length: 5} + - {name: MESSAGE, type: 半角, length: 10} + rows: + - ["10001", "10", "hello"] + - group_id: case2 + path: work/input.txt + type: fixed + records: + - record_type: データ + fields: + - {name: ID, type: 半角, length: 5} + - {name: COUNTER, type: 数値, length: 5} + - {name: MESSAGE, type: 半角, length: 10} + rows: + - ["20001", "30", "morning"] +``` + +- groupId は `group_id:` フィールドで指定します。省略するとグループ ID なし（デフォルトグループ）扱いです。 +- groupId なしと `group_id: case2` の 2 エントリが同一 `setup_files:` リストに並びます。 + +--- + +## 6.4 可変長ファイル + +CSV 形式の顧客データファイルを入力として使うケース。フィールド区切り文字をディレクティブで指定します。 + +### Excel + +| SETUP_VARIABLE=input/data.csv | | | | +|---|---|---|---| +| field-separator | , | | | +| DATA | USER_ID | USER_NAME | AMOUNT | +| | X | N | X | +| | 001 | 山田太郎 | 5000 | +| | 002 | 鈴木花子 | 3000 | + +### YAML + +```yaml +setup_files: + - path: input/data.csv + type: variable + directives: + field-separator: "," + records: + - record_type: DATA + fields: + - {name: USER_ID, type: X} + - {name: USER_NAME, type: N} + - {name: AMOUNT, type: X} + rows: + - ["001", "山田太郎", "5000"] + - ["002", "鈴木花子", "3000"] +``` + +- 固定長との差異は `type: fixed` / `type: variable` と `length` の有無だけです。可変長では `fields:` の各要素から `length` を省略します。 + +--- + + + +## 6.5 複数レコードレイアウト + +1 ファイルに HEADER レコードと DATA レコードが混在する振込依頼ファイルを扱うケース。 + +### Excel + +| SETUP_FIXED=input/multi.dat | | | | +|---|---|---|---| +| HEADER | SEQ | TYPE | | +| | X | X | | +| | 4 | 2 | | +| | H001 | 01 | | +| DATA | USER_ID | AMOUNT | NOTE | +| | X | Z | N | +| | 10 | 10 | 20 | +| | 001 | 5000 | 備考 | + +- 同一セクション内でレコード種別+フィールド名称行を続けて書くと、複数レコードレイアウトになります。 + +### YAML + +```yaml +setup_files: + - path: input/multi.dat + type: fixed + records: + - record_type: HEADER + fields: + - {name: SEQ, type: X, length: 4} + - {name: TYPE, type: X, length: 2} + rows: + - ["H001", "01"] + - record_type: DATA + fields: + - {name: USER_ID, type: X, length: 10} + - {name: AMOUNT, type: Z, length: 10} + - {name: NOTE, type: N, length: 20} + rows: + - ["001", "5000", "備考"] +``` + +- `records:` 配列に複数のレコードレイアウトを並べます。 + +--- + + + +## 6.6 空ファイル + +出力ファイルがゼロ件のときに 0 バイトの空ファイルを生成することを確認するケース。 + +### Excel + +| SETUP_FIXED=input/empty.dat | | +|---|---| +| text-encoding | MS932 | + +- ディレクティブ行のみ記述してレコード定義以降を省略します。 + +### YAML + +```yaml +setup_files: + - path: input/empty.dat + type: fixed + directives: + text-encoding: MS932 + records: [] +``` + +- レコードは `records: []` と空配列で記述します。 diff --git a/.rn/ntf-yaml-support/input/ntf-testdata-doc-examples-messaging.md b/.rn/ntf-yaml-support/input/ntf-testdata-doc-examples-messaging.md new file mode 100644 index 00000000..73dee960 --- /dev/null +++ b/.rn/ntf-yaml-support/input/ntf-testdata-doc-examples-messaging.md @@ -0,0 +1,197 @@ +# NTF テストデータ解説書 — 記述例（メッセージングテストデータ） + + + +メッセージング系データブロック（MESSAGE / SendSync 期待値 / sendSyncTestData 配置 / ステータスコードデフォルト）の Excel・YAML 記法をケースごとに引く。各ケースとも Excel と YAML の対応例を並べ、末尾に制約・補足を示す。 + +## 7.1 MESSAGE セクション（メッセージ送受信） + +受信電文と応答電文を定義するケース。実物のデータは `MessageParserTest.xls` の `testParse` シートを参照。 + +### Excel + +| MESSAGE=requestMessages | | | | +|---|---|---|---| +| text-encoding | Windows-31J | | | +| requestId | hoge | | | +| userId | moge | | | +| | ユーザ名 | 備考 | FILLER | +| | 全角 | 全角 | 半角 | +| | 50 | 200 | 252 | +| 1 | 電文太郎 | 特筆なし | | +| 2 | | ユーザ名が空欄なのでエラーが発生します。 | | + +| MESSAGE=responseMessages | | | | +|---|---|---|---| +| no | 処理結果コード | 会員ID | FILLER | +| | X | X | X | +| | 2 | 10 | 490 | +| 1 | 00 | 1234567890 | | +| 2 | 01 | | | + +### YAML + +```yaml +messages: + - id: requestMessages + directives: + text-encoding: Windows-31J # ディレクティブ + fw_header: # FW制御ヘッダ（任意キーのマップ） + requestId: hoge + userId: moge + records: + - record_type: default + fields: + - {name: ユーザ名, type: 全角, length: 50} + - {name: 備考, type: 全角, length: 200} + - {name: FILLER, type: 半角, length: 252} + rows: + - ["電文太郎", "特筆なし", ""] + - ["", "ユーザ名が空欄なのでエラーが発生します。", ""] + - id: responseMessages + records: + - record_type: default + fields: + - {name: 処理結果コード, type: 半角, length: 2} + - {name: 会員ID, type: 半角, length: 10} + - {name: FILLER, type: 半角, length: 490} + rows: + - ["00", "1234567890", ""] + - ["01", "", ""] +``` + +### 制約・補足 + +- ディレクティブ行（`text-encoding` など）はフィールド定義より前に記述する +- Excel のフィールド名称行の先頭セルは空にする（Excel 固有） +- `no` 列（先頭列）はフレームワークが除去する。データとして保存されない +- `record_type` の値はフレームワーク内部で `"default"` に置き換えられる。任意の値を記述できる（`FW_HEADER` のような予約値はない。FW制御ヘッダは `fw_header:` マップに記述する） + +--- + +## 7.2 要求電文・応答電文の期待値（SendSync メッセージング） + +バッチリクエスト単体テストで電文の送受信をテストするケース。実物のデータは `RequestTestingSendSyncSupportTest.xls` を参照。 + +### Excel + +| LIST_MAP=testShots | | | | | | | | | | | +|---|---|---|---|---|---|---|---|---|---|---| +| no | description | expectedStatusCode | setUpTable | expectedTable | expectedLog | diConfig | requestPath | userId | expectedMessage | responseMessage | +| 1 | 電文送受信テスト | 0 | | | | batch-test-component-configuration.xml | BM21AA0106 | batch_user | case1 | res_case1 | + +| EXPECTED_REQUEST_HEADER_MESSAGES[case1]=RM21AA0104_01 | | | | +|---|---|---|---| +| text-encoding | ms932 | | | +| no | requestId | | | +| | 半角 | | | +| | 20 | | | +| 1 | RM21AA0104_01 | | | + +### YAML + +```yaml +list_maps: + - id: testShots + rows: + - no: "1" + description: "電文送受信テスト" + expectedStatusCode: "0" + setUpTable: "" + expectedTable: "" + expectedLog: "" + diConfig: "batch-test-component-configuration.xml" + requestPath: "BM21AA0106" + userId: "batch_user" + expectedMessage: "case1" + responseMessage: "res_case1" + +expected_request_header_messages: + - group_id: case1 + id: RM21AA0104_01 + directives: + text-encoding: ms932 + records: + - record_type: default + fields: + - {name: requestId, type: 半角, length: 20} + rows: + - ["RM21AA0104_01"] +``` + +### 制約・補足 + +- `expectedMessage` カラムには要求電文の groupId、`responseMessage` カラムには応答電文の groupId を指定する +- YAML では `expected_request_header_messages:` の `group_id:` が `testShots` の `expectedMessage` カラムに対応する +- `id:` はリクエスト ID（フォーマット定義ファイルの解決に使われる） +- ヘッダとボディのエントリ数（rows 合計）は一致が必須 + +--- + +## 7.3 sendSyncTestData の配置規則 + +テストデータファイルを `sendSyncTestData/{requestId}/message` に配置するケース。 + +### Excel + +| MESSAGE=sendSyncTestData/REQ001/message | | | | +|---|---|---|---| +| no | errorMode | field1 | field2 | +| 1 | | value1 | value2 | +| 2 | | value3 | value4 | + +### YAML + +```yaml +messages: + - id: sendSyncTestData/REQ001/message + records: + - record_type: DATA + fields: + - {name: no, type: 半角, length: 2} + - {name: errorMode, type: 半角, length: 10} + - {name: field1, type: 半角, length: 10} + - {name: field2, type: 半角, length: 10} + rows: + - ["1", "", "value1", "value2"] + - ["2", "", "value3", "value4"] +``` + +### 制約・補足 + +- `MESSAGE=sendSyncTestData/{requestId}/message` というパスで配置する +- `no` 列の値は送信順序と一致させる +- `errorMode` に `errorMode:timeout` を指定するとタイムアウトエラー、`errorMode:msgException` を指定すると例外エラーのシミュレーションになる。どちらを指定した場合も他フィールドはパース対象外になる +- N 回送信する場合はヘッダ件数とボディ件数をともに N 件ずつ記述する + +--- + +## 7.4 ステータスコードのデフォルト値 + +HTTP 同期応答テストでステータスコードカラムを省略するケース。 + +### Excel + +| RESPONSE_BODY_MESSAGES=REQ001 | | | +|---|---|---| +| no | body | | +| | 半角 | | +| | 10 | | +| 1 | RESULT_OK | | + +### YAML + +```yaml +response_body_messages: + - id: REQ001 + records: + - record_type: DATA + fields: + - {name: body, type: 半角, length: 10} + rows: + - ["RESULT_OK"] +``` + +### 制約・補足 + +- ステータスコード列がない場合、実行時にデフォルト値 `"200"` が使用される diff --git a/.rn/ntf-yaml-support/input/ntf-testdata-doc-examples-overview.md b/.rn/ntf-yaml-support/input/ntf-testdata-doc-examples-overview.md new file mode 100644 index 00000000..2c07be9e --- /dev/null +++ b/.rn/ntf-yaml-support/input/ntf-testdata-doc-examples-overview.md @@ -0,0 +1,194 @@ +# NTF テストデータ解説書 — 記述例（概要・groupId） + + + +## 1. NTF テストデータ + +リクエスト単体テスト（バッチ処理）の例。1 ファイルにテストケース・セットアップ・検証が共存する。 + +### Excel + +| LIST_MAP=testShots | | | | | | | | | | | +|---|---|---|---|---|---|---|---|---|---|---| +| no | description | expectedStatusCode | setUpTable | expectedTable | setUpFile | expectedFile | diConfig | requestPath | userId | expectedLog | +| 1 | 注文カウンタが正しくインクリメントされます | 0 | default | default | | | nablarch/test/core/batch/BatchSample.xml | DBtoDBBatchSample | test | expectedLog | + +| SETUP_TABLE=ORDER_HEADER | | | | +|---|---|---|---| +| ORDER_ID | ITEM_COUNT | REMARKS | | +| 10001 | 10 | 通常注文 | | +| 10002 | 20 | まとめ買い | | + +| EXPECTED_TABLE=ORDER_HEADER | | | | +|---|---|---|---| +| ORDER_ID | ITEM_COUNT | REMARKS | UPDATE_DATE | +| 10001 | 11 | 通常注文 | 2010-09-13 12:34:56.0 | +| 10002 | 21 | まとめ買い | 2010-09-13 12:34:56.0 | + +| LIST_MAP=expectedLog | | | +|---|---|---| +| message | logLevel | | +| 注文ID[10001] | INFO | | +| 注文ID[10002] | INFO | | + +- 種別はブロック先頭のラベルで決まる：`LIST_MAP=testShots` がテストケース定義、`SETUP_TABLE` がセットアップ、`EXPECTED_TABLE` が検証、`LIST_MAP=expectedLog` が期待ログ + +### YAML + +```yaml +list_maps: + - id: testShots + rows: + - no: "1" + description: "正しく更新されます" + expectedStatusCode: "0" + setUpTable: "default" + expectedTable: "default" + setUpFile: "" + expectedFile: "" + diConfig: "nablarch/test/core/batch/BatchSample.xml" + requestPath: "DBtoDBBatchSample" + userId: "test" + expectedLog: "expectedLog" + - id: expectedLog + rows: + - message: "注文ID[10001]" + logLevel: "INFO" + - message: "注文ID[10002]" + logLevel: "INFO" + +setup_tables: + - table: ORDER_HEADER + rows: + - ORDER_ID: "10001" + ITEM_COUNT: "10" + REMARKS: "通常注文" + - ORDER_ID: "10002" + ITEM_COUNT: "20" + REMARKS: "まとめ買い" + +expected_tables: + - table: ORDER_HEADER + rows: + - ORDER_ID: "10001" + ITEM_COUNT: "11" + REMARKS: "通常注文" + UPDATE_DATE: "2010-09-13 12:34:56.0" + - ORDER_ID: "10002" + ITEM_COUNT: "21" + REMARKS: "まとめ買い" + UPDATE_DATE: "2010-09-13 12:34:56.0" +``` + +- 種別はトップレベルキーで決まる：`list_maps:` の `id: testShots` がテストケース定義、`setup_tables:` がセットアップ、`expected_tables:` が検証 +- `id: expectedLog` のような任意 ID の `list_maps:` エントリも同一ファイルに共存できる +- 同一の `list_maps:` キーには複数エントリをリストとして並べる（YAML はトップレベルキーの重複不可のため） + +> [要確認] `description` カラムが Excel 例（注文カウンタが正しくインクリメントされます）と YAML 例（正しく更新されます）で食い違う。両形式は同一データを表すべきなのでどちらかが誤り。正しい文言を確認のうえ揃える。 + +--- + + + +## 4.3 セクションのグループ化（groupId） + +テストケースごとに異なるセットアップ／検証データを使い分けるシナリオ。`testShots` の `setUpTable`／`expectedTable` カラムに書いた値が groupId となり、その groupId が付いたセクションだけが対象になる。 + +| ケース | setUpTable | 投入されるセクション | +|---|---|---| +| ケース1（正常注文） | `case01` | `SETUP_TABLE[case01]` | +| ケース2（大量注文） | `case02` | `SETUP_TABLE[case02]` | + +`expectedTable` も同様に、書いた値の groupId が付いた `EXPECTED_TABLE[...]` セクションが検証に使われる。groupId を省略したセクションは `setUpTable` が空のケースで使われる（groupId なし = デフォルトグループ）。 + +### Excel + +groupId はセクションラベルの `[...]` で表す。 + +| LIST_MAP=testShots | | | | | +|---|---|---|---|---| +| no | description | expectedStatusCode | setUpTable | expectedTable | +| 1 | 正常注文 | 0 | case01 | case01 | +| 2 | 大量注文 | 0 | case02 | case02 | + +| SETUP_TABLE[case01]=ORDER_DETAIL | | | | | +|---|---|---|---|---| +| ORDER_ID | PRODUCT_CODE | QUANTITY | UNIT_PRICE | | +| 1001 | P-001 | 5 | 1500 | | + +| EXPECTED_TABLE[case01]=ORDER_DETAIL | | | | | +|---|---|---|---|---| +| ORDER_ID | PRODUCT_CODE | QUANTITY | UNIT_PRICE | | +| 1001 | P-001 | 5 | 1500 | | + +| SETUP_TABLE[case02]=ORDER_DETAIL | | | | | +|---|---|---|---|---| +| ORDER_ID | PRODUCT_CODE | QUANTITY | UNIT_PRICE | | +| 2001 | P-003 | 100 | 500 | | +| 2001 | P-004 | 200 | 300 | | + +| EXPECTED_TABLE[case02]=ORDER_DETAIL | | | | | +|---|---|---|---|---| +| ORDER_ID | PRODUCT_CODE | QUANTITY | UNIT_PRICE | | +| 2001 | P-003 | 100 | 500 | | +| 2001 | P-004 | 200 | 300 | | + +### YAML + +groupId は各セクションの `group_id` キーで表す。 + +```yaml +list_maps: + - id: testShots + rows: + - no: "1" + description: "正常注文" + expectedStatusCode: "0" + setUpTable: "case01" + expectedTable: "case01" + - no: "2" + description: "大量注文" + expectedStatusCode: "0" + setUpTable: "case02" + expectedTable: "case02" + +setup_tables: + - group_id: case01 + table: ORDER_DETAIL + rows: + - ORDER_ID: "1001" + PRODUCT_CODE: "P-001" + QUANTITY: "5" + UNIT_PRICE: "1500" + - group_id: case02 + table: ORDER_DETAIL + rows: + - ORDER_ID: "2001" + PRODUCT_CODE: "P-003" + QUANTITY: "100" + UNIT_PRICE: "500" + - ORDER_ID: "2001" + PRODUCT_CODE: "P-004" + QUANTITY: "200" + UNIT_PRICE: "300" + +expected_tables: + - group_id: case01 + table: ORDER_DETAIL + rows: + - ORDER_ID: "1001" + PRODUCT_CODE: "P-001" + QUANTITY: "5" + UNIT_PRICE: "1500" + - group_id: case02 + table: ORDER_DETAIL + rows: + - ORDER_ID: "2001" + PRODUCT_CODE: "P-003" + QUANTITY: "100" + UNIT_PRICE: "500" + - ORDER_ID: "2001" + PRODUCT_CODE: "P-004" + QUANTITY: "200" + UNIT_PRICE: "300" +``` diff --git a/.rn/ntf-yaml-support/input/ntf-testdata-doc-examples-special.md b/.rn/ntf-yaml-support/input/ntf-testdata-doc-examples-special.md new file mode 100644 index 00000000..6c3a299d --- /dev/null +++ b/.rn/ntf-yaml-support/input/ntf-testdata-doc-examples-special.md @@ -0,0 +1,321 @@ +# NTF テストデータ解説書 — 記述例（特殊値・ディレクティブ・ヘッダ） + +特殊値・インタープリタ、ファイルディレクティブ、ヘッダ／コメント／空エントリの Excel・YAML 記法を項目ごとに引く。各項目とも Excel と YAML の対応例を並べ、末尾に制約を示す。 + + + +## 8. 特殊値・インタープリタ + +### 8.1 日付型・Timestamp・特殊値 + +`EXPECTED_TABLE` で日付・タイムスタンプ・NULL・システム日時を使うケース。実物のデータは `BasicTestDataParserTest.xls` の `convertedValues` シートを参照。 + +#### Excel + +| EXPECTED_TABLE=SCHEDULE | | | | +|---|---|---|---| +| ID | EVENT_NAME | START_DATE | CREATED_AT | +| 1 | 会議 | 2024-01-15 | 2024-01-01 09:00:00.0 | +| 2 | NULLテスト | NULL | NULL | +| 3 | システム時刻 | ${systemTime} | ${systemTime} | +| 4 | 更新時刻 | ${updateTime} | ${setUpTime} | + +#### YAML + +```yaml +expected_tables: + - table: SCHEDULE + rows: + - ID: "1" + EVENT_NAME: "会議" + START_DATE: "2024-01-15" + CREATED_AT: "2024-01-01 09:00:00.0" + - ID: "2" + EVENT_NAME: "NULLテスト" + START_DATE: null + CREATED_AT: null + - ID: "3" + EVENT_NAME: "システム時刻" + START_DATE: "${systemTime}" + CREATED_AT: "${systemTime}" + - ID: "4" + EVENT_NAME: "更新時刻" + START_DATE: "${updateTime}" + CREATED_AT: "${setUpTime}" +``` + +#### 制約 + +- `NULL` 文字列は `NullInterpreter` が Java null に変換する。大文字小文字不問（`null`・`Null` も同様）。YAML ではアンクォートの `null` で記述し、`"null"` とクォートすると文字列として格納される +- `${systemTime}` は完全一致のみ変換される。文字列中に埋め込むには `CompositeInterpreter` との組み合わせが必要 +- `java.sql.Timestamp` 型カラムの期待値は末尾 `.0` が必須（`"2024-01-01 09:00:00.0"`）。末尾 `.0` がないとアサートが失敗する + +> [要確認] `${updateTime}`・`${setUpTime}`（行 4）が解決する値の定義が本ファイルにない。`${systemTime}` との違いと対応するインタープリタを確認のうえ補う。 + +--- + +### 8.2 QuotationTrimmer によるスペース値明示記法 + +空白値やダブルクォート文字を明示して記述するケース。 + +#### Excel + +| EXPECTED_TABLE=ITEM | | | +|---|---|---| +| ID | NAME | MEMO | +| 1 | " " | """ | + +#### YAML + +```yaml +expected_tables: + - table: ITEM + rows: + - ID: "1" + NAME: " " + MEMO: "\"" +``` + +#### 制約 + +- Excel: `" "` → 半角スペース1文字、`"""` → ダブルクォート1文字。半角または全角ダブルクォートで前後が囲まれた場合のみ外側1層を除去する +- YAML: `" "` でスペース1文字。ダブルクォート文字は `"\""` または `'"'` で記述する + +--- + +### 8.3 バイナリデータ + +BLOB カラムにバイナリデータを記述するケース。 + +#### Excel + +| SETUP_TABLE=FILE_TABLE | | | +|---|---|---| +| FILE_ID | FILE_DATA | | +| 001 | 0xCAFEBABE | | +| 002 | ${binaryFile:testdata.bin} | | + +#### YAML + +```yaml +setup_tables: + - table: FILE_TABLE + rows: + - FILE_ID: "001" + FILE_DATA: "0xCAFEBABE" + - FILE_ID: "002" + FILE_DATA: "${binaryFile:testdata.bin}" +``` + +#### 制約 + +- `0x` プレフィクス付き16進数でバイナリ値を記述する。`0x` がない場合は文字列としてエンコードされる +- `${binaryFile:パス}` でファイル内容をバイナリ読み込みして HexString に変換する + +--- + + + +## 9. ディレクティブ + +### 9.1 固定長ファイルのディレクティブ + +エンコーディングとゾーン10進数の符号ニブルを指定するケース。 + +#### Excel + +| SETUP_FIXED=input/data.dat | | | +|---|---|---| +| text-encoding | MS932 | | +| positive-zone-sign-nibble | C | | +| DATA | USER_ID | AMOUNT | +| | X | Z | +| | 10 | 10 | +| | 001 | 5000 | + +#### YAML + +```yaml +setup_files: + - path: input/data.dat + type: fixed + directives: + text-encoding: MS932 + positive-zone-sign-nibble: C + records: + - record_type: DATA + fields: + - {name: USER_ID, type: X, length: 10} + - {name: AMOUNT, type: Z, length: 10} + rows: + - ["001", "5000"] +``` + +#### 制約 + +- Excel のディレクティブ行は「キー | 値」の2セルで記述する。YAML は `directives:` オブジェクトの `key: value` 形式 +- `file-type` と `record-length` はフレームワークが自動設定するため通常は記述不要 +- 無効なディレクティブキーを指定すると `IllegalArgumentException` がスローされる + +--- + +### 9.2 可変長ファイルのディレクティブ + +タブ区切り・CRLF 改行のファイルを扱うケース。 + +#### Excel + +| SETUP_VARIABLE=input/data.tsv | | | +|---|---|---| +| field-separator | \t | | +| record-separator | CRLF | | +| DATA | FIELD1 | FIELD2 | +| | X | X | +| | value1 | value2 | + +#### YAML + +```yaml +setup_files: + - path: input/data.tsv + type: variable + directives: + field-separator: "\\t" + record-separator: CRLF + records: + - record_type: DATA + fields: + - {name: FIELD1, type: X} + - {name: FIELD2, type: X} + rows: + - ["value1", "value2"] +``` + +#### 制約 + +- タブ文字の記法が形式で異なる。Excel セルには `\t`（バックスラッシュ + t の2文字）を入力し、フレームワークがタブ文字（0x09）に変換する。YAML は `"\\t"` と記述する（YAML の `\t` は実際のタブ文字になるためバックスラッシュをエスケープする） +- `record-separator` には `NONE` / `CR` / `LF` / `CRLF` または任意リテラル文字列が有効 +- `field-separator` は1文字のみ有効。2文字以上は `IllegalArgumentException` がスローされる + +--- + + + +## 10. ヘッダ・コメント・空エントリ + +### 10.1 コメントとマーカーカラム + +#### Excel + +| SETUP_TABLE=TEST_TABLE | | | | | +|---|---|---|---|---| +| // この行はコメントです | | | | | +| [no] | PK_COL1 | PK_COL2 | NUMBER_COL | [desc] | +| 1 | 0000000001 | AB | 100 | テスト1 | +| // この行もスキップされます | | | | | +| 2 | 0000000002 | CD | 200 | テスト2 | + +#### YAML + +```yaml +setup_tables: + - table: TEST_TABLE + rows: + # この行はコメントです（YAML の # 構文） + - "[no]": "1" + PK_COL1: "0000000001" + PK_COL2: "AB" + NUMBER_COL: "100" + "[desc]": "テスト1" + - "[no]": "2" + PK_COL1: "0000000002" + PK_COL2: "CD" + NUMBER_COL: "200" + "[desc]": "テスト2" +``` + +#### 制約 + +- Excel: `//` で始まる行は丸ごとスキップされる（テスト実行に影響しない）。**行内コメント**は先頭以外の要素が `//` で始まる場合にその要素以降が切り捨てられる（Excel 固有） +- YAML: 標準のコメント構文（`#`）を使う。行末コメントも可（`NUMBER_COL: "100" # 数値カラム`） +- `[no]`・`[desc]` のように角括弧で囲んだカラムはマーカーカラムで、DB 操作から除外される。YAML ではダブルクォートで囲む（`"[no]"`） + +--- + +### 10.2 空エントリのスキップ + +全要素が null または空文字のエントリは読み飛ばされる。 + +#### Excel + +| SETUP_TABLE=USER | | | +|---|---|---| +| USER_ID | NAME | | +| 001 | 山田太郎 | | +| | | | +| 002 | 鈴木花子 | | + +#### YAML + +```yaml +setup_tables: + - table: USER + rows: + - USER_ID: "001" + NAME: "山田太郎" + # 空行はここには書かない（YAML にはそもそも空エントリの概念がない） + - USER_ID: "002" + NAME: "鈴木花子" +``` + +#### 制約 + +- Excel: 全セルが空の行は自動的にスキップされる +- YAML: キーを省略するだけのため空エントリを記述する機会はほとんどない。空行を挿入しても無視される + +--- + + + +## 11. DB アサート + +> テーブルアサートの記法・省略カラムの扱い・主キー突合は [ntf-testdata-doc-examples-table.md](ntf-testdata-doc-examples-table.md#table-data) と本体仕様（[ntf-testdata-doc.md](ntf-testdata-doc.md) 5.4）に詳しい。ここでは DB アサート固有の挙動だけを示す。 + +### 11.1 テーブルアサート（順序不問・主キー突合） + +`EXPECTED_TABLE` は記述順と DB の格納順が違っても、主キーで突合して比較する。下記は順序が違っても成功するケース。 + +#### Excel + +| EXPECTED_TABLE=USER | | | +|---|---|---| +| USER_ID | NAME | | +| 001 | 山田太郎 | | +| 002 | 鈴木花子 | | + +#### YAML + +```yaml +expected_tables: + - table: USER + rows: + - USER_ID: "001" + NAME: "山田太郎" + - USER_ID: "002" + NAME: "鈴木花子" +``` + +### 11.2 EXPECTED_COMPLETE_TABLE（省略カラムにデフォルト値補完） + +省略したカラムにデフォルト値を補完してから比較する。 + +#### YAML + +```yaml +expected_complete_tables: + - table: USER + rows: + - USER_ID: "001" + NAME: "山田太郎" + # AGE など省略したカラムはデフォルト値（数値型なら "0"）で補完される +``` diff --git a/.rn/ntf-yaml-support/input/ntf-testdata-doc-examples-table.md b/.rn/ntf-yaml-support/input/ntf-testdata-doc-examples-table.md new file mode 100644 index 00000000..4622e079 --- /dev/null +++ b/.rn/ntf-yaml-support/input/ntf-testdata-doc-examples-table.md @@ -0,0 +1,182 @@ +# NTF テストデータ解説書 — 記述例（テーブルデータ） + + + +テーブル系データブロック（SETUP_TABLE / EXPECTED_TABLE / EXPECTED_COMPLETE_TABLE / LIST_MAP）の Excel・YAML 記法を種別ごとに引く。各種別とも Excel と YAML の対応例を並べ、末尾に制約を示す。 + +## 5.1 テーブルデータの基本形式 + + + +### SETUP_TABLE + +会員テーブルへ初期データを INSERT するケース。 + +#### Excel + +| SETUP_TABLE=MEMBER | | | | | | | +|---|---|---|---|---|---|---| +| MEMBER_ID | NAME | RANK | SCORE | RATE | PROFILE | PHOTO | +| 0000000101 | 山田太郎 | 1 | 85000 | 1.5 | ゴールド会員です | ${binaryFile:testdata.txt} | +| 0000000102 | 鈴木花子 | 2 | Null | 2.25 | シルバー会員 | ${binaryFile:member_photo.jpg} | + +- 1 行目にカラム名、2 行目以降にデータ +- `//` で始まる行はコメント（型情報・桁数などの注記に使う） + +#### YAML + +```yaml +setup_tables: + - table: MEMBER + rows: + - MEMBER_ID: "0000000101" + NAME: "山田太郎" + RANK: "1" + SCORE: "85000" + RATE: "1.5" + PROFILE: "ゴールド会員です" + PHOTO: "${binaryFile:testdata.txt}" + - MEMBER_ID: "0000000102" + NAME: "鈴木花子" + RANK: "2" + SCORE: null + RATE: "2.25" + PROFILE: "シルバー会員" + PHOTO: "${binaryFile:member_photo.jpg}" +``` + +- 1 行が 1 オブジェクト、カラム名がキー +- 値は文字列で記述（`"0000000101"` のようにクォート） +- NULL 値はアンクォートの `null`。`"null"` とクォートすると文字列として格納される + +#### 制約 + +- **主キーカラムは省略不可**。省略すると `"0"` やスペースのデフォルト値が INSERT される +- `NULL` 文字列は `NullInterpreter` により Java null に変換される（YAML ではアンクォート `null`） +- `${binaryFile:パス}` はファイル内容をバイナリ読み込みして HexString に変換する + +--- + + + +### EXPECTED_TABLE と EXPECTED_COMPLETE_TABLE + +バッチ処理後の会員スコアと注文カウンタを検証するケース。 + +#### Excel + +| EXPECTED_TABLE=MEMBER | | | | | +|---|---|---|---|---| +| MEMBER_ID | NAME | RANK | SCORE | UPDATED_DATE | +| 0000000101 | 山田太郎 | 1 | 87500 | 2024-04-01 09:00:00.0 | +| 0000000102 | 鈴木花子 | 2 | 42000 | 2024-04-01 09:00:00.0 | + +| EXPECTED_COMPLETE_TABLE=ORDER_HEADER | | | | +|---|---|---|---| +| ORDER_ID | ITEM_COUNT | STATUS | UPDATE_DATE | +| 10001 | 3 | 1 | 2024-04-01 12:30:00.0 | +| 10002 | 5 | 1 | | + +#### YAML + +```yaml +expected_tables: + - table: MEMBER + rows: + - MEMBER_ID: "0000000101" + NAME: "山田太郎" + RANK: "1" + SCORE: "87500" + UPDATED_DATE: "2024-04-01 09:00:00.0" + - MEMBER_ID: "0000000102" + NAME: "鈴木花子" + RANK: "2" + SCORE: "42000" + UPDATED_DATE: "2024-04-01 09:00:00.0" + +expected_complete_tables: + - table: ORDER_HEADER + rows: + - ORDER_ID: "10001" + ITEM_COUNT: "3" + STATUS: "1" + UPDATE_DATE: "2024-04-01 12:30:00.0" + - ORDER_ID: "10002" + ITEM_COUNT: "5" + STATUS: "1" + # UPDATE_DATE を省略 → BasicDefaultValues のデフォルト値で補完されて比較 +``` + +#### 省略カラムの扱い + +| キーワード | 省略カラムの扱い | YAML での省略 | +|---|---|---| +| `EXPECTED_TABLE` / `expected_tables:` | 比較対象外。検証したいカラムだけ列挙できる | キーを書かない | +| `EXPECTED_COMPLETE_TABLE` / `expected_complete_tables:` | `BasicDefaultValues` のデフォルト値を補完してから比較 | キーを書かない | + +#### 制約 + +- **Excel は混在禁止**: 同一ファイル内で `EXPECTED_TABLE` と `EXPECTED_COMPLETE_TABLE` を混在させると後半のデータが読み込まれない +- **YAML は混在可**: `expected_tables:` と `expected_complete_tables:` は別キーのため、YAML パーサーが両方を独立に読み込んでマージする + +--- + + + +### LIST_MAP + +キーバリュー形式の汎用データ。マーカーカラム・期待ログ・リクエストパラメータ等に使う。 + +#### Excel — リクエストパラメータ（マーカーカラム付き） + +注文検索画面の HTTP リクエストパラメータを定義するケース。 + +| LIST_MAP=searchParams | | | | | | +|---|---|---|---|---|---| +| [no] | memberId | orderStatus | fromDate | toDate | [desc] | +| 1 | 0000000101 | 1 | 2024-04-01 | 2024-04-30 | 4月注文検索 | +| 2 | 0000000102 | | 2024-01-01 | | 全件検索 | + +#### Excel — 期待ログ + +| LIST_MAP=expectedLog | | | +|---|---|---| +| message | logLevel | | +| 会員ID[0000000101]の注文を処理しました | INFO | | +| 会員ID[0000000102]の注文を処理しました | INFO | | + +#### YAML + +```yaml +list_maps: + - id: searchParams + rows: + - "[no]": "1" + memberId: "0000000101" + orderStatus: "1" + fromDate: "2024-04-01" + toDate: "2024-04-30" + "[desc]": "4月注文検索" + - "[no]": "2" + memberId: "0000000102" + orderStatus: "" + fromDate: "2024-01-01" + toDate: "" + "[desc]": "全件検索" + - id: expectedLog + rows: + - message: "会員ID[0000000101]の注文を処理しました" + logLevel: "INFO" + - message: "会員ID[0000000102]の注文を処理しました" + logLevel: "INFO" +``` + +#### マーカーカラム + +- 角括弧で囲んだカラム（`[no]`・`[desc]`）はマーカーカラム。DB 操作から除外される（Excel 上の見やすさのために使うことが多い） +- YAML ではダブルクォートで囲む（`"[no]"`）。YAML の角括弧構文との衝突を避けるため + +#### 制約 + +- `testShots` は予約 ID。フレームワークがテストケース定義として自動読み込みする +- ID は完全一致で検索される。同一 ID の重複エントリは先着一致で、2 件目以降は無視される diff --git a/.rn/ntf-yaml-support/input/ntf-testdata-doc-examples-testshots.md b/.rn/ntf-yaml-support/input/ntf-testdata-doc-examples-testshots.md new file mode 100644 index 00000000..cb65b18f --- /dev/null +++ b/.rn/ntf-yaml-support/input/ntf-testdata-doc-examples-testshots.md @@ -0,0 +1,287 @@ +# NTF テストデータ解説書 — testShots カラム一覧 + +処理方式ごとの `testShots` カラムを引くためのリファレンス。どの処理方式でも `testShots` は `LIST_MAP` として記述する。 + +- [全体像](#overview) +- [共通カラム](#common) +- [ウェブアプリケーション](#web) +- [バッチ処理](#batch) +- [メッセージング](#messaging) +- [エンティティバリデーション](#entity) + +--- + + + +## 全体像 + +`testShots` の 1 行が 1 テストケース。カラムには値を直接書くものと、別セクション（`LIST_MAP` や各種テーブル／ファイル／電文セクション）の groupId・名前を指す参照型がある。処理方式ごとに必須カラムとオプションカラムが定まる。 + +```mermaid +flowchart LR + TS["testShots（LIST_MAP）
1行=1テストケース"] + REQ[必須カラム] + OPT[オプションカラム] + REF["別セクション
LIST_MAP / テーブル / ファイル / 電文"] + TS --> REQ + TS --> OPT + OPT -.参照型は名前/groupIdで指す.-> REF +``` + +各処理方式の対応クラス: + +| 処理方式 | 対応クラス | +|---|---| +| ウェブアプリケーション | `HttpRequestTestSupport` | +| バッチ処理 | `BatchRequestTestSupport` | +| メッセージング | `MessagingRequestTestSupport` | +| エンティティバリデーション | `EntityTestSupport` | + +--- + + + +## 共通カラム + +ウェブ・バッチ・メッセージングで共通の必須カラム。エンティティバリデーションは別体系（[該当節](#entity)を参照）。 + +| カラム名 | 説明 | +|---|---| +| `no` | テストケース番号。空の場合はエラー | +| `description` | テストケースの説明（旧名 `case` も可）。`description` も `case` も未定義の場合はエラー | +| `expectedStatusCode` | 期待するステータスコード（ウェブは HTTP ステータスコード） | + +以降の各処理方式の表では、固有カラムを示す。 + +--- + + + +## ウェブアプリケーション（HttpRequestTestSupport） + +### 必須カラム + +[共通カラム](#common)（`no`／`description`／`expectedStatusCode`）に加えて: + +| カラム名 | 説明 | +|---|---| +| `isValidToken` | CSRF トークン制御フラグ（`1`: あり、`0`: なし） | +| `forwardUri` | 期待するフォワード先 URI | +| `context` | リクエスト ID・ユーザ・HTTP メソッドを記載した `LIST_MAP` 名。1エントリのみ有効。`REQUEST_ID` が空の場合は例外がスロー | + +### オプションカラム + +| カラム名 | 説明 | 空の場合 | +|---|---|---| +| `setUpDb` | この値と同じ名前の `LIST_MAP` を持つシートの全 `SETUP_TABLE` を、テストメソッド開始前に1回だけ INSERT | スキップ | +| `setUpTable` | この値と同じ groupId を持つ `SETUP_TABLE` セクションを収集して INSERT | スキップ | +| `expectedTable` | この値と同じ groupId を持つ `EXPECTED_TABLE`/`EXPECTED_COMPLETE_TABLE` セクションで DB を検証 | スキップ | +| `expectedSearch` | 検索結果期待値の groupId（対応する `LIST_MAP` セクションを収集） | スキップ | +| `expectedMessageId` | 期待するメッセージ ID（カンマ区切りで複数指定可） | スキップ | +| `requestParams` | HTTP リクエストパラメータの `LIST_MAP` 名。指定した LIST_MAP の行数がテストケース番号より少ない場合はエラー | — | +| `responseResult` | HTTP レスポンス（リクエストスコープ）期待値の `LIST_MAP` 名 | スキップ | +| `cookie` | Cookie 値の `LIST_MAP` 名。指定した LIST_MAP が空の場合はエラー | Cookie なし | +| `queryParams` | クエリパラメータの `LIST_MAP` 名。指定した LIST_MAP が空の場合はエラー | パラメータなし | +| `HTTP_METHOD` | HTTP メソッド | `"POST"` | +| `expectedContentLength` | 期待する Content-Length | スキップ | +| `expectedContentType` | 期待する Content-Type | スキップ | +| `expectedContentFileName` | 期待する Content-Disposition ファイル名 | スキップ | +| `expectedMessage` | この値と同じ groupId を持つ要求電文セクション（`EXPECTED_REQUEST_HEADER/BODY_MESSAGES`）で検証 | スキップ | +| `responseMessage` | この値と同じ groupId を持つ応答電文セクション（`RESPONSE_HEADER/BODY_MESSAGES`）をレスポンスとして返す | スキップ | +| `expectedMessageByClient` | HTTP 同期応答メッセージ送信の要求電文グループ ID | スキップ | +| `responseMessageByClient` | HTTP 同期応答メッセージ送信の応答電文グループ ID | スキップ | + +### 記述例 + +#### Excel + +| LIST_MAP=testShots | | | | | | +|---|---|---|---|---|---| +| no | description | isValidToken | expectedStatusCode | forwardUri | context | +| 1 | 正常ケース | 0 | 200 | /success | context001 | +| 2 | 認証エラー | 0 | 400 | /error | context002 | + +| LIST_MAP=context001 | | | +|---|---|---| +| REQUEST_ID | USER_ID | HTTP_METHOD | +| REQ_001 | user001 | POST | + +#### YAML + +```yaml +list_maps: + - id: testShots + rows: + - no: "1" + description: "正常ケース" + isValidToken: "0" + expectedStatusCode: "200" + forwardUri: "/success" + context: "context001" + - no: "2" + description: "認証エラー" + isValidToken: "0" + expectedStatusCode: "400" + forwardUri: "/error" + context: "context002" + - id: context001 + rows: + - REQUEST_ID: "REQ_001" + USER_ID: "user001" + HTTP_METHOD: "POST" +``` + +--- + + + +## バッチ処理（BatchRequestTestSupport） + +### 必須カラム + +[共通カラム](#common)（`no`／`description`／`expectedStatusCode`）に加えて: + +| カラム名 | 説明 | +|---|---| +| `diConfig` | DI コンポーネント設定ファイルパス | +| `requestPath` | リクエストパス | +| `userId` | 実行ユーザ ID | + +### オプションカラム + +| カラム名 | 説明 | 空の場合 | +|---|---|---| +| `setUpDb` | この値と同じ名前の `LIST_MAP` を持つシートの全 `SETUP_TABLE` を、テストメソッド開始前に1回だけ INSERT | スキップ | +| `setUpTable` | この値と同じ groupId を持つ `SETUP_TABLE` セクションを収集して INSERT | スキップ | +| `expectedTable` | この値と同じ groupId を持つ `EXPECTED_TABLE`/`EXPECTED_COMPLETE_TABLE` セクションで DB を検証 | スキップ | +| `setUpFile` | この値と同じ groupId を持つ `SETUP_FIXED`/`SETUP_VARIABLE` セクションを入力ファイルとして配置 | スキップ | +| `expectedFile` | この値と同じ groupId を持つ `EXPECTED_FIXED`/`EXPECTED_VARIABLE` セクションで出力ファイルを検証 | スキップ | +| `expectedLog` | 期待ログの `LIST_MAP` 名。指定した LIST_MAP が空の場合はエラー | スキップ | +| `args[0]`, `args[1]`, ... | コマンドライン引数 | — | +| その他任意カラム | コマンドラインオプション | — | + +### 記述例 + +#### Excel + +| LIST_MAP=testShots | | | | | | | +|---|---|---|---|---|---|---| +| no | description | expectedStatusCode | diConfig | requestPath | userId | setUpFile | +| 1 | 正しく更新されます | 0 | nablarch/test/core/batch/BatchSample.xml | DBtoDBBatchSample | test | | +| 2 | 入力ファイルあり | 0 | nablarch/test/core/batch/BatchSample.xml | FileToFileBatchSample | test | case2 | + +#### YAML + +```yaml +list_maps: + - id: testShots + rows: + - no: "1" + description: "正しく更新されます" + expectedStatusCode: "0" + diConfig: "nablarch/test/core/batch/BatchSample.xml" + requestPath: "DBtoDBBatchSample" + userId: "test" + setUpFile: "" + - no: "2" + description: "入力ファイルあり" + expectedStatusCode: "0" + diConfig: "nablarch/test/core/batch/BatchSample.xml" + requestPath: "FileToFileBatchSample" + userId: "test" + setUpFile: "case2" +``` + +--- + + + +## メッセージング（MessagingRequestTestSupport） + +### 必須カラム + +[共通カラム](#common)（`no`／`description`／`expectedStatusCode`）に加えて: + +| カラム名 | 説明 | +|---|---| +| `diConfig` | DI コンポーネント設定ファイルパス | +| `requestPath` | リクエストパス | +| `userId` | 実行ユーザ ID | + +### オプションカラム + +| カラム名 | 説明 | 空の場合 | +|---|---|---| +| `setUpDb` | この値と同じ名前の `LIST_MAP` を持つシートの全 `SETUP_TABLE` を、テストメソッド開始前に1回だけ INSERT | スキップ | +| `setUpTable` | この値と同じ groupId を持つ `SETUP_TABLE` セクションを収集して INSERT | スキップ | +| `expectedTable` | この値と同じ groupId を持つ `EXPECTED_TABLE`/`EXPECTED_COMPLETE_TABLE` セクションで DB を検証 | スキップ | +| `expectedMessage` | この値と同じ groupId を持つ要求電文セクション（`EXPECTED_REQUEST_HEADER/BODY_MESSAGES`）で検証 | スキップ | +| `responseMessage` | この値と同じ groupId を持つ応答電文セクション（`RESPONSE_HEADER/BODY_MESSAGES`）をレスポンスとして返す | スキップ | +| `expectedLog` | 期待ログの `LIST_MAP` 名。指定した LIST_MAP が空の場合はエラー | スキップ | + +### 記述例 + +#### Excel + +| LIST_MAP=testShots | | | | | | | | +|---|---|---|---|---|---|---|---| +| no | description | expectedStatusCode | diConfig | requestPath | userId | expectedMessage | responseMessage | +| 1 | 電文送受信テスト | 0 | batch-test-component-configuration.xml | BM21AA0106 | batch_user | case1 | res_case1 | + +#### YAML + +```yaml +list_maps: + - id: testShots + rows: + - no: "1" + description: "電文送受信テスト" + expectedStatusCode: "0" + diConfig: "batch-test-component-configuration.xml" + requestPath: "BM21AA0106" + userId: "batch_user" + expectedMessage: "case1" + responseMessage: "res_case1" +``` + +--- + + + +## エンティティバリデーション（EntityTestSupport） + +[共通カラム](#common)とは別体系。`no`／`description`／`expectedStatusCode` は使わない。 + +### 必須カラム + +| カラム名 | 説明 | +|---|---| +| `title` | テストケースの説明 | +| `expectedMessageId1` | 期待するバリデーションメッセージ ID（複数ある場合は `expectedMessageId2`, `expectedMessageId3`, ... と連番で追加） | +| `propertyName1` | バリデーション対象プロパティ名（同上、連番で追加可能） | + +### 関連予約 ID + +| 予約 ID | 説明 | +|---|---| +| `params` | 入力パラメータ定義。`testShots` の行数と一致が必須 | + +### 記述例 + +#### Excel + +| LIST_MAP=testShots | | | | +|---|---|---|---| +| title | expectedMessageId1 | propertyName1 | | +| 必須チェック | errors.required | userName | | + +#### YAML + +```yaml +list_maps: + - id: testShots + rows: + - title: "必須チェック" + expectedMessageId1: "errors.required" + propertyName1: "userName" +``` diff --git a/.rn/ntf-yaml-support/input/ntf-testdata-doc.md b/.rn/ntf-yaml-support/input/ntf-testdata-doc.md new file mode 100644 index 00000000..9a1a424c --- /dev/null +++ b/.rn/ntf-yaml-support/input/ntf-testdata-doc.md @@ -0,0 +1,699 @@ +# NTF テストデータ リファレンス + +Nablarch Testing Framework（NTF）が読み込むテストデータの記述仕様。Excel・YAML のどちらで書く場合にも共通して適用される。各節末尾のリンクから Excel 表と YAML コードブロックの対比例を参照できる。 + +--- + +## 目次 + +1. [全体像](#1-全体像) +2. [テストデータの基本構造](#2-テストデータの基本構造) +3. [データブロック識別](#3-データブロック識別) +4. [テストケース定義](#4-テストケース定義) +5. [テーブルデータ](#5-テーブルデータ) +6. [ファイルデータ](#6-ファイルデータ) +7. [メッセージングテストデータ](#7-メッセージングテストデータ) +8. [値の書き方](#8-値の書き方) +9. [ディレクティブ](#9-ディレクティブ) +10. [ヘッダ・コメント・空エントリ](#10-ヘッダコメント空エントリ) + +--- + +## 1. 全体像 + +テストコード（Java）がテストデータファイルを読み込み、DB へのデータ投入・入力ファイルの配置・期待値との比較を行う。テストデータには **テストケース**・**セットアップ**・**検証** の3用途のデータを記述し、いずれも **データブロック** 単位で管理する。 + +| 用途 | 内容 | 主なデータブロック | +|---|---|---| +| テストケース | 1エントリ1ケースの実行条件（ウェブ:「ユーザ ID・期待ステータスコード・期待フォワード先 URI」、バッチ:「リクエストパス・ユーザ ID・DI コンフィグ・期待ステータスコード」など） | `LIST_MAP=testShots` | +| セットアップ | テスト前に投入するデータ（DB INSERT、固定長・可変長ファイルの入力） | `SETUP_TABLE` / `SETUP_FIXED` / `SETUP_VARIABLE` | +| 検証 | テスト後の期待値（DB・出力ファイル・電文・ログ・検索結果） | `EXPECTED_*` / `RESPONSE_*` | + +データの格納階層は次のとおり。テストクラス1つ分のデータが読み込み単位（Excel は1シート／YAML は1ファイル）に分かれ、その中に複数のデータブロックが共存する。 + +```mermaid +flowchart TD + TC[テストクラス
Excel: 1ブック / YAML: 1ディレクトリ] --> U1[読み込み単位
Excel: 1シート / YAML: 1ファイル] + TC --> U2[読み込み単位] + U1 --> B1[データブロック
種別 + 識別子] + U1 --> B2[データブロック] + B1 --> F[レコード定義 / フィールド / データ] +``` + +データブロックは **種別**（`SETUP_TABLE` など14種）と **識別子の値**（テーブル名・ファイルパス・ID など）の組み合わせで区別する。詳細は [3章](#3-データブロック識別)。 + +→ [Excel / YAML Example](ntf-testdata-doc-examples-overview.md#overview) + +--- + +## 2. テストデータの基本構造 + +テストデータはテストクラスと1対1で対応する。 + +| 形式 | テストクラス対応 | 読み込み単位 | +|---|---|---| +| Excel | 同名の1ブック（`.xls`） | 1シート | +| YAML | 同名のディレクトリ | 1ファイル（Excel の1シートに相当） | + +``` +【Excel】 【YAML】 +src/test/java/com/example/ src/test/java/com/example/ + FooTest.xls FooTest/ + ├── case01 ← シート ├── case01.yaml ← ファイル + └── case02 ← シート └── case02.yaml ← ファイル +``` + +1読み込み単位の中に、テストケース・セットアップ・検証の複数データブロックを共存させて記述する。 + +YAML ファイルは **YAML 1.2** に準拠する。YAML 1.1 との主な違いとして、`yes` / `no` / `on` / `off` は真偽値ではなく文字列として扱われる。 + +### ファイルの読み込みルール + +| 項目 | Excel | YAML | +|---|---|---| +| ファイルなし時 | エラー | ファイルが存在しない、またはパース失敗時はエラー | +| 空ファイル時 | 空シートは存在しないシート扱い | 空ファイル（0バイト）は空データ扱い（エラーにならない） | +| 値の書き方 | セルは必ず**文字列書式**。数値・日付書式の動作は保証しない | 値は必ず**ダブルクォートで囲む** | + +--- + +## 3. データブロック識別 + +### 3.1 識別の構成要素 + +各データブロックは **データブロック種別**（[3.2](#32-データブロック種別の一覧) の14種）と **識別子の値**（テーブル名・ファイルパス・ID など）の2要素で識別される。 + +| 形式 | 記述方法 | +|---|---| +| Excel | データブロック先頭セルに `データブロック種別=識別子の値`。種別名で始まれば合致（前方一致）。例: `SETUP_TABLE=USER_MASTER` | +| YAML | 種別ごとの専用トップレベルキー（下表）。完全一致のため前方一致は発生しない | + +YAML のトップレベルキー対応: + +| データブロック種別 | YAML キー | +|---|---| +| `SETUP_TABLE` | `setup_tables` | +| `EXPECTED_TABLE` | `expected_tables` | +| `EXPECTED_COMPLETE_TABLE` | `expected_complete_tables` | +| `LIST_MAP` | `list_maps` | +| `SETUP_FIXED` / `SETUP_VARIABLE` | `setup_files` | +| `EXPECTED_FIXED` / `EXPECTED_VARIABLE` | `expected_files` | +| `MESSAGE` | `messages` | +| `EXPECTED_REQUEST_HEADER_MESSAGES` | `expected_request_header_messages` | +| `EXPECTED_REQUEST_BODY_MESSAGES` | `expected_request_body_messages` | +| `RESPONSE_HEADER_MESSAGES` | `response_header_messages` | +| `RESPONSE_BODY_MESSAGES` | `response_body_messages` | + +```yaml +setup_tables: + - table: USER_MASTER + rows: ... +``` + +**同種データブロックの記述ルール**: + +- YAML: 同一ファイル内のトップレベルキーの重複は禁止。同種データは同一キーにリストとして並べる（重複時はエラー） +- Excel: 同一シート内に同種データブロックを複数記述できる。DataType により全件収集または先着一致で収集される（[3.3](#33-同一ファイルシート内に複数のデータブロックを書く場合の注意) 参照） + +### 3.2 データブロック種別の一覧 + +使用できる種別は以下の14種。 + +| データブロック種別 | 用途 | 同一 ID が複数ある場合 | +|---|---|---| +| `SETUP_TABLE` | INSERT 用テーブルデータ | 同じグループのものをすべて収集 | +| `EXPECTED_TABLE` | 比較用テーブルデータ（省略カラムは比較対象外） | 同じグループのものをすべて収集 | +| `EXPECTED_COMPLETE_TABLE` | 比較用テーブルデータ（省略カラムにデフォルト値補完） | 同じグループのものをすべて収集 | +| `LIST_MAP` | キーバリュー形式の汎用データ（テストケース定義・期待値等） | 最初の1件のみ有効（2件目以降は無視） | +| `SETUP_FIXED` | 固定長ファイルの入力データ | 同じグループのものをすべて収集 | +| `EXPECTED_FIXED` | 固定長ファイルの期待値データ | 同じグループのものをすべて収集 | +| `SETUP_VARIABLE` | 可変長ファイルの入力データ | 同じグループのものをすべて収集 | +| `EXPECTED_VARIABLE` | 可変長ファイルの期待値データ | 同じグループのものをすべて収集 | +| `MESSAGE` | メッセージング電文データ | 最初の1件のみ有効（2件目以降は無視） | +| `EXPECTED_REQUEST_HEADER_MESSAGES` | 要求電文ヘッダの期待値 | groupId 指定時は全件収集、ID 直接指定時は最初の1件 | +| `EXPECTED_REQUEST_BODY_MESSAGES` | 要求電文ボディの期待値 | groupId 指定時は全件収集、ID 直接指定時は最初の1件 | +| `RESPONSE_HEADER_MESSAGES` | 応答電文ヘッダデータ | groupId 指定時は全件収集、ID 直接指定時は最初の1件 | +| `RESPONSE_BODY_MESSAGES` | 応答電文ボディデータ | groupId 指定時は全件収集、ID 直接指定時は最初の1件 | +| `DEFAULT` | フレームワーク内部用（通常使用しない） | — | + +### 3.3 同一ファイル（シート）内に複数のデータブロックを書く場合の注意 + +- **複数テーブルの INSERT**: `setup_tables` などの全件収集タイプは同一 groupId のものをすべて収集する。複数テーブルデータを並べて記述できる +- **データタイプの混在順序（YAML）**: YAML はトップレベルのセクションキー（`expected_tables` / `expected_complete_tables` 等）ごとに独立して取得する。記述順序や異なるセクションの交互記述に関わらず正しく読み込まれる +- **`LIST_MAP` / `MESSAGE` の重複 ID**: 同一 ID が複数ある場合は最初の1件のみ有効。2件目以降は無視 + +> **Excel との違い**: Excel（旧形式）は行を順に読む方式のため、同一シート内で別のデータタイプを挟むと後半が読み込まれない制約があった（解説書の旧 Doc-4）。YAML はセクションキーで構造化されるためこの制約はなく、移行時にデータタイプごとにまとめ直す必要はない。 + +グループの指定方法（groupId）は [4.3](#43-データブロックのグループ化groupid) を参照。 + +--- + +## 4. テストケース定義 + +### 4.1 testShots + +`testShots` はテストケース定義の予約 ID。フレームワークがこの ID を自動的に読み込み、各エントリを1テストケースとして実行する。旧称 `testCases` も動作するが、新規作成では `testShots` を使う。 + +- テスト実行には `testShots` に1件以上のエントリが必要（0件はエラー） +- **Excel**: `LIST_MAP=testShots` データブロックに記述 +- **YAML**: `list_maps:` 下の `id: testShots` エントリに記述 + +### 4.2 testShots のカラム仕様 + +カラムは処理方式によって異なる。各処理方式の詳細は以下を参照。 + +- [ウェブアプリケーション（HttpRequestTestSupport）](ntf-testdata-doc-examples-testshots.md#web) +- [バッチ処理（BatchRequestTestSupport）](ntf-testdata-doc-examples-testshots.md#batch) +- [メッセージング（MessagingRequestTestSupport）](ntf-testdata-doc-examples-testshots.md#messaging) +- [エンティティバリデーション（EntityTestSupport）](ntf-testdata-doc-examples-testshots.md#entity) + +### 4.3 データブロックのグループ化（groupId） + +複数のテストケースで異なるセットアップデータや期待値を使い分けたい場合、データブロックに **groupId** を付加してグループ化する。`testShots` の各カラム（`setUpTable` / `expectedTable` / `setUpFile` / `expectedFile` 等）に groupId の値を指定すると、そのテストケースでは対応する groupId を持つデータブロックだけが収集される。 + +| 形式 | 記述方法 | +|---|---| +| Excel | DataType 名の直後に `[groupId]`。例: `SETUP_TABLE[case01]=USER_MASTER` | +| YAML | `group_id:` フィールド | + +```yaml +setup_tables: + - group_id: case01 + table: USER_MASTER + rows: ... +``` + +**制約**: + +- `testShots` の各カラムで groupId を省略すると、groupId なしのデータブロック（デフォルトグループ）が収集される +- バッチ固有の動作として groupId に `"default"` を指定すると groupId なし扱いと同等になる（HTTP テスト・メッセージングテストでは適用されない） + +→ [Excel / YAML Example](ntf-testdata-doc-examples-overview.md#groupid) + +--- + +## 5. テーブルデータ + +### 5.1 データの形式 + +各エントリはカラム名と値の組み合わせで記述する。省略したカラムには INSERT 時にデフォルト値が補完される。 + +**Excel**: 1行目にカラム名、2行目以降にデータ。 + +``` +| SETUP_TABLE=テーブル名 | | | +| カラム1 | カラム2 | カラム3 | +| 値1 | 値2 | 値3 | +``` + +**YAML**: `rows:` 配列に各行をオブジェクトで記述。 + +```yaml +setup_tables: + - table: テーブル名 + rows: + - カラム1: "値1" + カラム2: "値2" + カラム3: "値3" +``` + +**YAML 必須キー**: `setup_tables` / `expected_tables` / `expected_complete_tables` の各エントリには `table` キーが必須（省略時エラー）。 + +→ [Excel / YAML Example](ntf-testdata-doc-examples-table.md#table-data) + +### 5.2 SETUP_TABLE + +DB への INSERT 用データ。 + +- 各エントリのカラム名と値を記述する +- **主キーカラムは省略しない**。省略すると型に応じたデフォルト値（数値型は `"0"`、文字型はスペース等）が INSERT される + +**null 値・空文字の動作**: + +| 値の指定 | Excel | YAML | +|---|---|---| +| null（Java null） | セルに `null`（大文字小文字不問） | アンクォートの `null`（`"null"` でも同結果） | +| 空文字 | セルを空にする | `""` | +| 日付型カラムの空文字 | セルを空にする → `null` 扱い | `""` → `null` 扱い | + +→ [Excel / YAML Example](ntf-testdata-doc-examples-table.md#setup-table) + +### 5.3 EXPECTED_TABLE + +テスト後の DB 状態と比較するデータ。 + +- **省略したカラムは比較対象外**。検証したいカラムだけを列挙できる + +→ [Excel / YAML Example](ntf-testdata-doc-examples-table.md#expected-complete-table) + +### 5.4 EXPECTED_COMPLETE_TABLE + +省略カラムにデフォルト値を補完してから比較するデータ。 + +| カラム型 | デフォルト値 | +|---|---| +| 数値型 | `"0"` | +| 固定長文字列型（CHAR, NCHAR） | 半角スペース × カラム長 | +| 可変長文字列型（VARCHAR 等） | `" "`（半角スペース1文字） | +| 日付型 | epoch 起点（JVM タイムゾーン依存。JST 環境では `"1970-01-01 09:00:00.0"`） | +| バイナリ型 | 10バイトのゼロバイト列の HexString | +| Boolean 型 | `"false"` | + +**注意**: DATE カラムのデフォルト値は JVM のタイムゾーン設定に依存する。JST 環境と UTC 環境では値が異なる。 + +**Excel 混在禁止**: Excel では `EXPECTED_TABLE` と `EXPECTED_COMPLETE_TABLE` を同一シート内で混在させると後半のデータが読み込まれない。同じ種別をまとめて記述する。YAML では `expected_tables` と `expected_complete_tables` は別キーのため混在可能。 + +→ [Excel / YAML Example](ntf-testdata-doc-examples-table.md#expected-complete-table) + +### 5.5 LIST_MAP + +キーバリュー形式の汎用データ。テストケース定義（`testShots`）・リクエストパラメータ・期待値オブジェクト・期待ログなど様々な用途で使う。 + +**Excel**: + +``` +| LIST_MAP=testShots | | | +| no | description | status | +| 1 | 正常系 | active | +| 2 | 異常系 | error | +``` + +**YAML**: + +```yaml +list_maps: + - id: testShots + rows: + - no: "1" + description: "正常系" + status: "active" + - no: "2" + description: "異常系" + status: "error" +``` + +- ID は完全一致で検索される +- 同一ファイル内で同一 ID の重複エントリは先着一致、2件目以降は無視 +- 指定 ID のエントリが存在しない場合は空データ扱い（エラーにならない） + +主な予約 ID は [4章](#4-テストケース定義) を参照。 + +→ [Excel / YAML Example](ntf-testdata-doc-examples-table.md#list-map) + +--- + +## 6. ファイルデータ + +### 6.1 固定長・可変長の統合 + +セットアップ用ファイルデータ（`SETUP_FIXED` / `SETUP_VARIABLE`）は固定長・可変長の区別なくまとめて収集される。期待値ファイル（`EXPECTED_FIXED` / `EXPECTED_VARIABLE`）も同様。固定長か可変長かはデータブロック内の記述で区別される。 + +**YAML 必須キー**: `setup_files` / `expected_files` の各エントリには `path` キーが必須（省略時エラー。`table` キーと同様）。 + +### 6.2 ファイルデータブロックの構造 + +ファイルデータブロックは次の順序で記述する。 + +```mermaid +flowchart TD + D["ディレクティブ（0件以上）
エンコーディング等のファイル属性"] --> N["レコード種別 + フィールド名称
先頭要素=レコード種別、以降=フィールド名称"] + N --> T["データ型（各フィールドの型記号）"] + T --> L["フィールド長（固定長のみ）
各フィールドのバイト長"] + L --> R["データ（1件以上）"] +``` + +**Excel 固有の制約**: データの先頭要素は必ず空（null または空文字）にする。YAML にこの制約はない。 + +**Excel の記述例**（各セルを `|` で区切って表示）: + +``` +行1: SETUP_FIXED=work/input.txt [空] [空] +行2: text-encoding MS932 [空] +行3: DATA USER_ID AMOUNT +行4: [空] 半角 数値 +行5: [空] 10 10 +行6: [空] 001 5000 +``` + +**YAML の記述例**: + +```yaml +setup_files: + - path: work/input.txt + type: fixed + directives: + text-encoding: MS932 + records: + - record_type: DATA + fields: + - {name: USER_ID, type: 半角, length: 10} + - {name: AMOUNT, type: 数値, length: 10} + rows: + - ["001", "5000"] +``` + +- `fields:` の各要素は `{name: フィールド名, type: データ型, length: バイト長}` の形式 +- **`type` は日本語型名称（`半角`, `全角`, `数値` 等）で記述する**（[8.10](#810-データ型マッピング) 参照）。Excel と同じ表記であり、変換ツールも Excel の型名称をそのまま出力する +- `length` は整数（`length: 10`）または文字列（`length: "10"`）どちらでも有効。変換ツールが生成した YAML は文字列形式（`"10"`） +- `rows:` の各行は配列形式で、`fields:` と**同じ順序・同じ件数**で値を並べる +- `rows:` 内の値はダブルクォートで囲む（[8章](#8-値の書き方) 参照） + +→ [Excel / YAML Example](ntf-testdata-doc-examples-file.md#file-data) + +### 6.3 固定長ファイル固有の仕様 + +- フィールド名称・データ型・フィールド長の3リストが同サイズで必須 +- 1ファイルデータブロック内の全レコード定義は同一レコード長でなければならない（違反時エラー） +- フィールド値がフィールド長を超えた場合はエラー + +### 6.4 可変長ファイル固有の仕様 + +- フィールド名称・データ型の2リストが同サイズで必須。フィールド長は不要 +- **空エントリの動作**: ファイルデータの空エントリ（先頭フィールドが空の行）はデータ行として扱われる。可変長は全フィールドが `""` のレコードとして保持され、固定長はスペースパディングされた定長レコードとして書き出される（テーブルデータの空行スキップとは異なる。[10.5](#105-空エントリのスキップ) 参照） + +### 6.5 複数レコードレイアウト + +1ファイルデータブロック内に複数のレコードレイアウトを連続して記述できる。データの後ろに新たなレコード種別とフィールド名称を書くと、新しいレコードレイアウトとして扱われる。 + +→ [Excel / YAML Example](ntf-testdata-doc-examples-file.md#multi-record) + +### 6.6 空ファイル + +0バイトの空ファイルを表現するには、ディレクティブのみを記述してレコード定義を省略する。 + +→ [Excel / YAML Example](ntf-testdata-doc-examples-file.md#empty-file) + +### 6.7 `"-"` 長フィールド + +フィールド長に `"-"` を指定すると、追加された全レコードの最大バイト長に自動拡張される。値は改行コードと前後空白が除去される。 + +### 6.8 エラーになるケース + +- 同一レコード種別内でフィールド名称が重複している +- フィールド名称リストまたはデータ型リストが未指定または空 +- フィールド名称・データ型・フィールド長リストのサイズが一致していない +- 存在しないフィールド名称を指定している +- データ要素数が不正 +- ディレクティブまたはレコード種別/フィールド名称定義の要素数が2未満 +- ファイルの読み込みに失敗した（IO エラー） +- 日付型カラムの値が日付として解析できない + +--- + +## 7. メッセージングテストデータ + +### 7.1 sendSyncTestData の配置規則 + +テストデータファイルは `sendSyncTestData/{requestId}/message` というパスに配置する（末尾の `message` は固定のパスセグメント）。 + +- **Excel**: `MESSAGE=sendSyncTestData/{requestId}/message` をデータブロック識別子として記述 +- **YAML**: `messages:` の `id:` に `sendSyncTestData/{requestId}/message` を指定 + +### 7.2 FW 制御ヘッダフィールド + +> **適用範囲**: `fw_header:` マップは `messages`（MESSAGE: MockMessaging 経路の要求/応答電文）でのみ使用する。`expected_request_header_messages` / `expected_request_body_messages` / `response_header_messages` / `response_body_messages` の4種では使用しない。これらは `requestId` 等のヘッダフィールドも含めて `records` の `fields:`/`rows:` にフィールド単位（型・長さつき）で記述する（[7.x EXPECTED/RESPONSE 系の記述](#) 参照）。両者はテスト手法が異なる（値の指定 か フィールド単位の検証/生成 か）ため表現も異なる。 + +FW 制御ヘッダのフィールド名は**プロジェクトごとに異なる**。フレームワーク標準では4種が既定値だが固定ではなく、`SystemRepository` の `reader.fwHeaderfields` キーでプロジェクトが任意の名前に変更できる（例: `reader.fwHeaderfields=requestId,addHeader`）。 + +- 既定値の例: `requestId`, `userId`, `resendFlag`, `resultCode` + +| 形式 | 記述方法 | +|---|---| +| Excel | フィールド名称行（`no` 行）より前に `| フィールド名 | 値 |`（ディレクティブと同じ「名前｜値」形式） | +| YAML | `fw_header:` マップ（キー: 値）。キー名は固定でなく任意（`reader.fwHeaderfields` 設定に合わせる） | + +```yaml +messages: + - id: requestMessages + directives: + text-encoding: Windows-31J # ディレクティブはここに書く + fw_header: # FW制御ヘッダは名前: 値のマップ（キーは任意） + requestId: hoge + userId: moge + records: + - record_type: default # MessageParser は record_type を無視する（7.10 参照） + fields: + - {name: ユーザ名, type: 全角, length: 50} + - {name: 備考, type: 全角, length: 200} + - {name: FILLER, type: 半角, length: 252} + rows: + - ["電文太郎", "特筆なし", ""] +``` + +- **`directives:`（`text-encoding` 等）と `fw_header:`（`requestId` 等）は別キー。** Excel ではどちらも「名前｜値」の行だが、FW 制御ヘッダはフレームワークが電文ヘッダとして分離して扱うため YAML では区別する +- **`fw_header:` のキーはすべて FW 制御ヘッダとして扱われる。** ランタイムは `fw_header:` マップをそのまま FW ヘッダとして使い、`reader.fwHeaderfields` でフィルタリングして取り捨てることはしない（記述したものが黙って消えない） +- 電文ボディのフィールドは従来どおり `records:` の `fields:`/`rows:` に記述する + +### 7.3 HEADER / BODY MESSAGES の構造と件数制約 + +- `EXPECTED_REQUEST_HEADER_MESSAGES` と `EXPECTED_REQUEST_BODY_MESSAGES` のエントリ数（rows 合計）は一致が必須（不一致時エラー） +- HTTP 同期応答メッセージ（`response_body_messages`）の各データエントリは文字列長が同一である必要がある + +### 7.4 no 行（フィールド名称行）と errorMode + +**電文の行構造**: ディレクティブ群・FW 制御ヘッダの後、`no` で始まる行がフィールド名称行。以降、データ型行・フィールド長行・データ行が続く（公式仕様の電文表書式に準拠）。 + +- **Excel**: フィールド名称行の先頭セルに `no` を記述。データ行の先頭セル（`no` カラム）はフレームワークが除去しデータとして保存しない +- **YAML**: フィールド名称は `fields:`、データは `rows:` に記述（`no` カラム自体は YAML の構造に現れない） + +**errorMode（RESPONSE 系・MockMessaging 経路のみ）**: + +- `response_header_messages` / `response_body_messages` で、データ行の先頭値が `errorMode:timeout` または `errorMode:msgException` の場合、そのエントリは送受信エラーをシミュレートするマーカーとして扱われる +- errorMode 行は `fw_header:` の分離とは独立した別の仕組み。`fw_header:` を分離した後も errorMode 行はそのまま機能する +- `RequestTestingSendSyncSupport` 経路（GroupMessageParser）では errorMode は使用されない + +### 7.5 複数回送信 + +N 回送信する場合は、ヘッダ件数とボディ件数をともに N 件ずつ記述する。同一リクエスト ID で複数回送信する場合は `no` 値を変えて連続記述し、送信順序と `no` 値を一致させる。 + +### 7.6 メッセージの groupId 収集 + +同一 groupId を持つ複数のメッセージプールを収集する。識別子の値をリクエスト ID として使用する。 + +### 7.7 ステータスコード + +ステータスコードカラムがない場合はデフォルト値 `"200"` が使用される。Excel・YAML 両方で共通。 + +### 7.8 フォーマット定義ファイルの命名規則 + +- 応答電文: `{requestId}_RECEIVE` +- 要求電文: `{requestId}_SEND` + +### 7.9 アサート方式の切り替え + +`SystemRepository` の `messaging.assertAsMapFileType` キーの設定値に応じてアサート方式が切り替わる。未設定時のデフォルトは `"Fixed"` 形式（項目単位アサート）。 + +### 7.10 record_type の扱い + +`messages` / `expected_request_*_messages` / `response_*_messages` の `record_type` 値は、フレームワーク内部で常に `"default"` に置き換えられる。 + +- **Excel**: フィールド名称行の先頭セルに任意の値を記述できる（装飾的なメタデータ扱い） +- **YAML**: `record_type:` に任意の値を記述できる（可読性のためだけで実行時挙動に影響しない） + +> **注意**: 旧版では FW 制御ヘッダを `record_type: FW_HEADER` のレコードとして表していたが、本仕様では FW 制御ヘッダは `fw_header:` マップで記述する（[7.2](#72-fw-制御ヘッダフィールド) 参照）。`record_type` に特別な予約値はない。 + +→ [Excel / YAML Example](ntf-testdata-doc-examples-messaging.md#messaging) + +--- + +## 8. 値の書き方 + +### 8.1 値の種類と Excel / YAML 対比 + +| 値の種類 | Excel での記述 | YAML での記述 | 備考 | +|---|---|---|---| +| 通常の文字列 | `abc` | `"abc"` | YAML はクォート必須（型変換防止） | +| null（DB に null を格納） | `null`（大文字小文字不問） | `null`（クォートなし） | YAML の `"null"`（クォートあり）も同結果 | +| 空文字 | 空セル | `""` | | +| 先頭ゼロ付き数値 | `001` | `"001"` | YAML でクォートなしだと `1` に型変換される | +| `true` / `false`（文字列） | `true` | `"true"` | YAML でクォートなしだと真偽値に型変換される | +| 半角スペース1文字 | `" "`（セルに `"` space `"` と入力） | `" "` | 外側クォートが除去されてスペースになる | +| ダブルクォート1文字 | `"""`（セルに `"` `"` `"` と入力） | `'"'`（YAML シングルクォート） | | +| 日時プレースホルダ | `${systemTime}` | `"${systemTime}"` | 完全一致のみ変換。[8.4](#84-datetimeinterpreter-の完全一致制約) 参照 | +| バイナリファイル参照 | `${binaryFile:path}` | `"${binaryFile:path}"` | パスはどちらもデータファイルのディレクトリ基準。[8.6](#86-binaryfileinterpreter-のパス基準) 参照 | +| 文字種生成 | `${半角英字,10}` | `"${半角英字,10}"` | [8.5](#85-文字種生成の有効文字種) 参照 | +| 改行文字（CR） | `\\r` | `"\\r"` | LineSeparatorInterpreter が変換（デフォルト設定は CR のみ） | + +**YAML のクォートルール**: + +- `rows:` 内のすべてのデータ値は**必ずダブルクォートで囲む**。クォートなしだと SnakeYAML が数値・真偽値に型変換する +- `null` のみクォートなしで記述（ただし `"null"` でも同じく Java null になる） +- `type:`, `record_type:`, `path:` 等のスキーマ構造値はクォート不要 + +**Excel のセル書式**: セルは必ず**文字列書式**で記述する。数値・日付書式の動作は保証されない。 + +### 8.2 インタープリタチェーンの仕組み + +テストデータの値はパース時にインタープリタチェーンを通過して変換される。DI 設定で注入されたインタープリタが順番に適用される。 + +### 8.3 インタープリタ一覧 + +| インタープリタ | 変換内容 | +|---|---| +| `NullInterpreter` | `null` / `NULL` / `Null`（大文字小文字不問）→ Java null | +| `QuotationTrimmer` | 半角または全角ダブルクォートで前後が囲まれた場合のみ外側1層を除去 | +| `DateTimeInterpreter` | `${systemTime}` / `${updateTime}` / `${setUpTime}` の完全一致のみ変換 | +| `LineSeparatorInterpreter` | `\\r` → CR（0x0D）に変換（デフォルト設定）。`setMatchPattern` / `setLineSeparator` で変換対象・変換後の改行コードを変更可能 | +| `BinaryFileInterpreter` | `${binaryFile:パス}` でファイル内容をバイナリ読み込みし HexString に変換。パスはデータファイル（Excel / YAML）のディレクトリからの相対パス | +| `BasicJapaneseCharacterInterpreter` | `${文字種,文字数}` 形式で文字列生成 | +| `CompositeInterpreter` | 文字列中の `${...}` 要素を個別解釈して置換 | + +### 8.4 DateTimeInterpreter の完全一致制約 + +`DateTimeInterpreter` は完全一致のみ変換する。部分文字列は変換されない。文字列中の `${...}` を置換するには `CompositeInterpreter` との組み合わせが必要。 + +### 8.5 文字種生成の有効文字種 + +14種類の文字種が使用できる: 半角英字 / 半角数字 / 半角記号 / 半角カナ / 全角英字 / 全角数字 / 全角ひらがな / 全角カタカナ / 全角漢字 / 全角記号その他 / 中国語 / サロゲートペア / 改行 / 外字。 + +上記以外の文字種を指定するとエラーになる。 + +### 8.6 BinaryFileInterpreter のパス基準 + +`${binaryFile:パス}` のパスは**テストデータファイルのディレクトリ**からの相対パス。Excel・YAML 両方で同じ動作。 + +| 形式 | 基準ディレクトリ | +|---|---| +| Excel | Excel ファイル（`.xls` / `.xlsx`）が置かれているディレクトリ | +| YAML | YAML ファイル（`.yaml`）が置かれているディレクトリ | + +### 8.7 日付型カラムの記述形式と境界値 + +有効な記述形式: + +- `yyyyMMddHHmmssSSS`（17文字） +- 後置0埋め短縮形 +- JDBC タイムスタンプエスケープ形式（5文字目が `-`） + +`java.sql.Timestamp` 型カラムの期待値は末尾 `.0` が必須（例: `"2010-01-01 12:34:56.0"`）。末尾 `.0` がないとアサートが失敗する。 + +→ [Excel / YAML Example](ntf-testdata-doc-examples-special.md#datetime) + +### 8.8 バイナリデータの記述 + +`0x` プレフィクス付き16進数で記述できる。`0x` がない場合は文字列としてエンコードされる。 + +### 8.9 X9/SX9 型フィールドの記述 + +パディング文字・符号を含めた実際のバイト列表現（固定長フォーマットの実値）をそのまま記述する。 + +### 8.10 データ型マッピング + +フィールドのデータ型は以下の日本語型名称で指定する。使用できない型名称を指定するとエラーになる。 + +| 型名称 | 型記号 | 用途 | +|---|---|---| +| `半角英字` / `半角数字` / `半角記号` / `半角カナ` / `半角英数字` / `半角英数字記号` / `半角` | `X` | 半角文字 | +| `全角英字` / `全角数字` / `全角ひらがな` / `全角カタカナ` / `全角漢字` / `全角` | `N` | 全角文字 | +| `全半角` | `XN` | 全角・半角混在 | +| `数値` / `符号無ゾーン10進数` | `Z` | ゾーン10進数（符号なし） | +| `符号付ゾーン10進数` | `SZ` | ゾーン10進数（符号あり） | +| `符号無パック10進数` | `P` | パック10進数（符号なし） | +| `符号付パック10進数` | `SP` | パック10進数（符号あり） | +| `符号無数値` | `X9` | バイナリ表現の数値（符号なし） | +| `符号付数値` | `SX9` | バイナリ表現の数値（符号あり） | +| `バイナリ` | `B` | バイナリデータ | + +`TEST_{型名称}` という名前のデータ型を定義すると、同名の基底型より優先して使用される（テスト専用の型定義に使う）。 + +--- + +## 9. ディレクティブ + +### 9.1 ディレクティブの構成 + +ディレクティブは「キー名・値」の2要素で記述する（最低2要素必要）。 + +- **Excel**: ファイルデータブロックの先頭（レコード定義より前）に `| キー名 | 値 |` の形で記述 +- **YAML**: `directives:` オブジェクトに `key: value` 形式で記述 + +### 9.2 固定長ファイルのディレクティブ + +有効なキーは以下に限定される。無効なキーを指定するとエラーになる。 + +| ディレクティブキー | 説明 | +|---|---| +| `file-type` | 自動設定（`"Fixed"`）。通常は記述不要 | +| `text-encoding` | ファイルの文字エンコーディング | +| `record-length` | フィールド長合計から自動計算。通常は記述不要 | +| `record-separator` | レコード区切り文字 | +| `positive-zone-sign-nibble` | ゾーン10進数の正符号ニブル | +| `negative-zone-sign-nibble` | ゾーン10進数の負符号ニブル | +| `positive-pack-sign-nibble` | パック10進数の正符号ニブル | +| `negative-pack-sign-nibble` | パック10進数の負符号ニブル | +| `required-decimal-point` | 小数点を必須とするか（`true` / `false`） | +| `fixed-sign-position` | 符号を固定位置に置くか（`true` / `false`） | +| `required-plus-sign` | 正符号を出力するか（`true` / `false`） | + +→ [Excel / YAML Example](ntf-testdata-doc-examples-file.md#file-data) + +### 9.3 可変長ファイルのディレクティブ + +有効なキーは以下に限定される。無効なキーを指定するとエラーになる。 + +| ディレクティブキー | 説明 | +|---|---| +| `file-type` | 自動設定（`"Variable"`）。通常は記述不要 | +| `text-encoding` | ファイルの文字エンコーディング | +| `record-separator` | レコード区切り。`NONE` / `CR` / `LF` / `CRLF` または任意リテラル文字列が有効 | +| `field-separator` | フィールド区切り文字。デフォルトは `","`。`"\\t"` 指定でタブ文字。**1文字のみ有効**（2文字以上はエラー） | +| `quoting-delimiter` | クォート文字 | +| `ignore-blank-lines` | 空行を無視するか | +| `requires-title` | タイトル行の有無 | +| `max-record-length` | レコードの最大長 | +| `title-record-type-name` | タイトルレコードの種別名 | + +→ [Excel / YAML Example](ntf-testdata-doc-examples-file.md#file-data) + +### 9.4 デフォルトディレクティブの DI 設定 + +`SystemRepository` への DI 設定で、全ファイル共通または種別専用のデフォルトディレクティブを一括設定できる。 + +| DI キー | 適用対象 | +|---|---| +| `defaultDirectives` | 全ファイル共通のデフォルト | +| `fixedLengthDirectives` | 固定長ファイル専用。`defaultDirectives` より後に上書き適用される | +| `variableLengthDirectives` | 可変長ファイル専用 | + +→ [Excel / YAML Example](ntf-testdata-doc-examples-special.md#directive) + +--- + +## 10. ヘッダ・コメント・空エントリ + +### 10.1 ヘッダの構造 + +ヘッダにはカラム名を列挙する。 + +- ヘッダ末尾の空カラムは除去される（末尾カラムの省略が可能） +- データエントリがヘッダより少ない場合、不足分は空文字 `""` で補完される + +### 10.2 マーカーカラム + +カラム名が `[カラム名]` 形式（角括弧で囲まれた名前）のカラムはマーカーカラムとして扱われ、DB 操作から除外される。 + +| 形式 | 除外対象 | +|---|---| +| Excel | `SETUP_TABLE` / `EXPECTED_TABLE` / `LIST_MAP` すべて | +| YAML | `setup_tables` / `expected_tables` / `list_maps` すべて | + +### 10.3 エントリ単位のコメント + +エントリをコメントとしてマークすると、そのエントリ全体がスキップされる。 + +- **Excel**: 先頭要素が `//` で始まる行はスキップされる +- **YAML**: `#` がコメント記号（行頭・行末どちらにも使える） + +### 10.4 要素途中からのコメント（Excel 固有） + +- **Excel**: 先頭以外の要素が `//` で始まる場合、その要素以降が切り捨てられる +- **YAML**: `#` を行末に書いて同等の記述ができる（例: `NUMBER_COL: "100" # 数値カラム`） + +### 10.5 空エントリのスキップ + +全要素が null または空文字のエントリは読み飛ばされる。 + +- **Excel**: 行の全セルが空の場合にスキップされる +- **YAML**: `rows:` 内の要素が空マッピング（`{}`）またはすべての値が空文字の場合にスキップされる + +→ [Excel / YAML Example](ntf-testdata-doc-examples-special.md#header-comment) diff --git a/.rn/ntf-yaml-support/input/ntf-testdata-loading.md b/.rn/ntf-yaml-support/input/ntf-testdata-loading.md new file mode 100644 index 00000000..5ddc9b6b --- /dev/null +++ b/.rn/ntf-yaml-support/input/ntf-testdata-loading.md @@ -0,0 +1,263 @@ +# NTF テストデータ読み込み機構 + +NTF 本体が Excel のテストデータを読み解き、構造化オブジェクトへ変換するまでを解説します。 +利用者向けの「テストデータの書き方」（`ntf-testdata-doc.md`）が表側だとすれば、本書はその裏側──本体がどう動くか──です。読み終えると、**どの段階で何が変換・整形され、どこから元の値に戻せなくなるか**を追えるようになります。 + +- **用語**：NTF 解説書（`ntf-doc-terms.md`）に準拠（データタイプ、ヘッダ行、データ行、ディレクティブ、電文 など） +- **対象範囲**：NTF 本体（`nablarch.test.core.reader`）の読み込み経路。変換ツール・YAML 経路は対象外 + +--- + +## 1. 読み込みの4段階 + +Excel の1シートは、4つの段階を経て構造化オブジェクトになる。 + +```mermaid +flowchart LR + A["① 読む
PoiXlsReader

シートを
文字列の表に"] --> B["② 掃除する
TestDataParsingTemplate

コメント・
空行を除去"] --> C["③ 変換する
各 Interpreter

特殊記法を
実値へ"] --> D["④ 組み立てる
各データタイプのパーサ

構造化
オブジェクトへ"] + style A fill:#e8f0fe + style B fill:#e8f0fe + style C fill:#e8f0fe + style D fill:#ede7f6 +``` + +利用者は入口インタフェース `TestDataParser` 経由でデータを取得する。各段階を束ねるクラスの関係は次のとおり。 + +```mermaid +classDiagram + class TestDataParser { + <> + } + class BasicTestDataParser + class TestDataParsingTemplate + class TestDataReader { + <> + } + class PoiXlsReader + class Interpreter + class データタイプ別パーサ + + TestDataParser <|.. BasicTestDataParser + TestDataReader <|.. PoiXlsReader + TestDataParsingTemplate <|-- データタイプ別パーサ + BasicTestDataParser ..> データタイプ別パーサ : 生成しparseを委譲 + BasicTestDataParser --> TestDataReader : 保持 + TestDataParsingTemplate --> TestDataReader : 保持 + TestDataParsingTemplate --> Interpreter : 保持 +``` + +図の各クラスと、4段階での役割の対応は次のとおり。 + +| 段 | 担当クラス | 役割 | +|---|---|---| +| 入口 | `TestDataParser` | 利用者の窓口 | +| ① 読む | `PoiXlsReader` | Excel シートを1行ずつ文字列のリストにする | +| ② 掃除する | `TestDataParsingTemplate` | コメント・空行を除いて意味のある行だけ残す | +| ③ 変換する | 各 `Interpreter` | 特殊記法を実値へ変換する | +| ④ 組み立てる | データタイプ別パーサ（次章）| 構造化オブジェクトへ組み立てる | + +押さえるべき勘所は3点。 + +- **①〜③はすべてのデータタイプで共通**。同じ経路を必ず通る。 +- **分岐するのは④だけ**。データタイプ（`データタイプ=値` の1行目）を見て、対応する組み立て方を選ぶ。 +- **③の変換は④より前にセル単位で完了している**（詳細は3章）。④へ渡るのは実値へ変換済みのデータである。 + +--- + +## 2. データタイプと組み立て方の対応 + +④で分岐する先は、データタイプごとに異なる。ただし**組み立て方は実質2系統に集約される**。 + +④を担当するパーサは、共通の `TestDataParsingTemplate` を頂点とする継承ツリーを成す。 +データブロックの選び方（Single / Group、7章）で枝が分かれ、その先に各データタイプのパーサが位置する。 + +```mermaid +classDiagram + class TestDataParsingTemplate + class SingleDataParsingTemplate + class GroupDataParsingTemplate + class DataFileParser + class FixedLengthFileParser + class VariableLengthFileParser + class MessageParser + class SendSyncMessageParser + class GroupMessageParser + class TableDataParser + class ListMapParser + + TestDataParsingTemplate <|-- SingleDataParsingTemplate + TestDataParsingTemplate <|-- GroupDataParsingTemplate + GroupDataParsingTemplate <|-- DataFileParser + DataFileParser <|-- FixedLengthFileParser + DataFileParser <|-- VariableLengthFileParser + GroupDataParsingTemplate <|-- TableDataParser + GroupDataParsingTemplate <|-- GroupMessageParser + SingleDataParsingTemplate <|-- MessageParser + SingleDataParsingTemplate <|-- ListMapParser + MessageParser <|-- SendSyncMessageParser + MessageParser ..> FixedLengthFileParser : 委譲 + GroupMessageParser ..> MessageParser : 委譲 +``` + +| データタイプ | 構造化オブジェクト | 組み立て方 | 担当パーサ | +|---|---|---|---| +| `SETUP_FIXED` / `EXPECTED_FIXED` | 固定長ファイル | 状態機械 | `FixedLengthFileParser` | +| `SETUP_VARIABLE` / `EXPECTED_VARIABLE` | 可変長ファイル | 状態機械 | `VariableLengthFileParser` | +| `MESSAGE` / `*_MESSAGES`（電文各種） | メッセージ | 状態機械（ファイルデータを内部再利用）| `MessageParser` 系 | +| `SETUP_TABLE` / `EXPECTED_TABLE` / `EXPECTED_COMPLETE_TABLE` | テーブルデータ | ヘッダ行＋データ行 | `TableDataParser` | +| `LIST_MAP` | `List` | ヘッダ行＋データ行 | `ListMapParser` | + +図から読み取れる、構造上の勘所は次の2つ。 + +- **固定長と可変長の違いは、フィールド長行の有無だけ**（4章）。共通の親が組み立ての大半を担う。 +- **メッセージは独自の組み立てを持たず、固定長ファイルの仕組みを再利用している**。電文のボディを固定長ファイルとして読み込み、フレームワーク制御ヘッダを添えて包み直すだけである。種別ごとに追うと別物に見えるが、実体はファイルデータの組み立てに集約されている。 + +--- + +## 3. 値の変換と整形 + +入力ファイルの値は、**そのまま構造化オブジェクトに渡るものと、変換・整形されるものがある**。 +変換には、全データタイプ共通のもの（③）と、組み立て時にデータタイプごとに行われるもの（④）の2種類がある。 + +### ③ 共通変換：特殊記法を実値へ（全データタイプ共通） + +`TestDataParsingTemplate` が、掃除後の各セルを順に `Interpreter` のチェーンへ通す。 +**特殊記法に該当するセルだけが変換され、それ以外のセルはそのまま通る**（どの `Interpreter` にもマッチしなければ素通りする）。 + +| 記法の例 | 変換結果 | +|---|---| +| `null` | null 値 | +| `${systemTime}` ほか日時記法 | システム時刻などの実日時 | +| `${文字種,文字数}`（例 `${全角英字,10}`）| 条件に合う文字列 | +| `${半角数字,4}-${半角数字,4}` | 各記法を変換し連結した文字列 | +| `"..."`（ダブルクォート囲み）| 引用符を除いた中身 | +| （改行コード記法）| Excel で書けない改行コードに補正 | +| （ファイル参照記法）| 参照先のファイルデータ | + +### ④ 個別整形：組み立て時にデータタイプごとに（値の整形・補完） + +③が「人間用記法→実値」の意味変換であるのに対し、④は**行・セルの構造的な整形や、省略値の補完**であり、性質が異なる。 + +| 対象 | 整形・補完の内容 | +|---|---| +| ファイル・メッセージ | 行末の空セルを取り除く | +| メッセージ | レコード種別が空欄の行に、既定のレコード種別を補う | +| テーブル | マーカーカラムを除外する（5章）| +| テーブル | DB 登録時、値が省略されたカラムにデフォルト値を補完する | + +### ③は不可逆、④は非破壊 + +③と④では、元の値の残り方が異なる。 + +- **③（共通変換）は不可逆**。変換後の値だけがキャッシュ（8章）に保持され、変換前の生の値を残す仕組みはない。一度変換すると、変換前には戻せない。 +- **④（個別整形）は非破壊**。整形は③変換後のデータの**コピー**に対して行われ、入力側（キャッシュ上の③変換後データ）は書き換えられない。同じシートを取得し直せば、整形前（③変換後）の状態から組み立てをやり直せる。 + +つまり「整形前」に戻せるのは④までで、さかのぼれるのは③変換後の状態まで。③変換前の生の値には、どちらの場合も戻せない。 + +--- + +## 4. 状態機械による組み立て（ファイル・メッセージ） + +ファイルデータと電文は、1レコードレイアウトを次の順序で読み進めて組み立てる。 + +```mermaid +flowchart TD + DIR["ディレクティブ行"] --> NAME["フィールド名称行"] + NAME --> TYPE["データ型行"] + TYPE --> LEN["フィールド長行"] + LEN --> DATA["データ行"] + DATA -->|先頭セルが空| DATA + DATA -->|先頭セルに値| NAME +``` + +勘所となるのは次の2点。 + +- **データ行かどうかは「先頭セルが空か」で決まる**。先頭セルに値があれば、それは次のレコードレイアウトのフィールド名称行とみなされる。 +- **可変長はフィールド長行を持たない**。データ型行の次に、フィールド長行を飛ばしてデータ行へ進む。固定長との差はこの一点のみ。 + +電文の場合は、上記で組み立てたボディから、フレームワーク制御ヘッダに該当するフィールドを分離して保持する。 + +### 組み立て先のデータモデル（ファイル・メッセージ） + +状態機械が積み上げた結果は、入れ子の構造化オブジェクトに保持される。 +ファイルデータが最も階層が深く、メッセージはこれを内部に抱える。 + +```mermaid +flowchart TD + DF["ファイルデータ
DataFile"] -->|複数保持| FR["レコードレイアウト
DataFileFragment"] + DF -.->|ファイル全体に適用| DIR["ディレクティブ"] + FR --> META["フィールド名称・データ型・フィールド長"] + FR --> VAL["データ
List<Map<名→値>>"] + MSG["メッセージ
MessagePool"] -->|内部に保持| DF2["ファイルデータ（ボディ）
FixedLengthFile"] + MSG -.-> FWH["フレームワーク制御ヘッダ"] +``` + +| 保持先 | 何を持つか | 対応クラス | +|---|---|---| +| ファイルデータ | 複数のレコードレイアウト ＋ ディレクティブ（ファイル全体の書式設定）＋ ファイルパス | `DataFile`（`FixedLengthFile` / `VariableLengthFile` が継承）| +| レコードレイアウト | レコード種別 ＋ フィールド名称・データ型・フィールド長 ＋ データ（行の並び）| `DataFileFragment` | +| データ（1行） | フィールド名称をキー、変換済みの実値を値とする対応 | `Map`（`Fragment` 内に行数分）| +| メッセージ | ボディ（ファイルデータそのもの）＋ フレームワーク制御ヘッダ（分離して保持）| `MessagePool`（`FixedLengthFile` を内包）| + +勘所は、**1ファイルが複数のレコードレイアウトを持てる**こと。 +ヘッダ・データ・トレーラのように種別の異なるレコードが混在するファイルは、種別ごとに1レコードレイアウトとして分かれて保持される。 +状態機械が「先頭セルに値のある行＝次のレコードレイアウトの始まり」と判定するのは、この複数レイアウトを切り分けるためである。 + +--- + +## 5. ヘッダ行＋データ行による組み立て（テーブル・LIST_MAP） + +テーブルデータと `LIST_MAP` は、先頭のヘッダ行を押さえ、以降の各行をヘッダと対応づける。 + +- **マーカーカラム**（ヘッダ行で `[...]` と半角角括弧で囲んだ列）は、組み立て時に読み込み対象から除外される。Excel 上の見た目のためだけに存在する列を、構造化オブジェクトに含めないための仕組み。 + +### 組み立て先のデータモデル（テーブル・LIST_MAP） + +| データタイプ | 保持先 | 何を持つか | 対応クラス | +|---|---|---|---| +| テーブル | テーブルデータ | テーブル名 ＋ カラム名 ＋ 行の並び | `TableData` | +| `LIST_MAP` | `List` | 1行 = フィールド名→値の対応。これを行数分並べたもの | `List>` | + +ファイルデータが「レコードレイアウトの入れ子」を持つのに対し、こちらは**フラットな行の並び**である。 +データタイプによって保持モデルの形が異なる点が、両系統の構造上の違いである。 + +--- + +## 6. 入口 API がまとめる単位 + +利用者が呼ぶ入口の API（`TestDataParser`）は、複数のデータタイプを1つの結果にまとめて返すことがある。 +ここはデータタイプと API が1対1ではないため、実装を追わないと気づきにくい。 + +- **準備ファイルの取得**（`getSetupFile`）：固定長（`SETUP_FIXED`）と可変長（`SETUP_VARIABLE`）を**まとめて**1つのファイルデータのリストとして返す。 +- **テーブル期待値の取得**（`getExpectedTableData`）：`EXPECTED_TABLE` と `EXPECTED_COMPLETE_TABLE` を**マージして**返す。後者は、省略カラムにデフォルト値を補完してから統合される。 + +--- + +## 7. データブロックの選び方（Single / Group） + +④では、目的のデータブロックをシートから選び出す。選び方は2方式あり、データタイプごとに決まっている。 + +| 方式 | 選び方 | 該当データタイプ | +|---|---|---| +| Single | データタイプとIDが完全一致する**最初の1ブロック**を取得 | `LIST_MAP`、`MESSAGE` 等 | +| Group | `データタイプ + groupId + '='` で前方一致する**複数ブロック**を収集 | テーブル、ファイル 等 | + +> 補足：解説書の「複数のデータタイプを使用する場合は種類ごとにまとめて記述する」という規約は、 +> この選び方に由来する。混在して書くと、読み込みが途中で打ち切られるデータタイプがある。 + +--- + +## 8. 再解析を避けるキャッシュ + +①〜③（読む・掃除・変換）を終えた結果は、`ファイル名/シート名` をキーにキャッシュされる。 +同じシートから複数のデータブロックを取得する場合でも、Excel の読み込みと特殊記法変換は1回で済む。 + +--- + +## さいごに + +要点は3つ。**①〜③は全データタイプ共通で、分岐するのは④だけ**。**組み立て方は実質2系統**（状態機械＝ファイル・メッセージ／ヘッダ行＋データ行＝テーブル・LIST_MAP）に集約され、メッセージも独自の組み立てを持たず固定長ファイルを再利用する。そして**③（特殊記法変換）は不可逆、④（個別整形）は非破壊**で、戻せるのは③変換後までという境界がある。 + +この境界が本書の肝である（③を通すと記法のまま戻せなくなる）。境界をどう扱うかは変換ツール設計（[testdata-converter-design.md](testdata-converter-design.md)）を参照。 + +限界として、本書は NTF 本体（`nablarch.test.core.reader`）の **Excel 読み込み経路のみ**を扱う。変換ツール・YAML 経路、各データタイプの記法そのもの（`ntf-testdata-doc.md`）は対象外。 diff --git a/.rn/ntf-yaml-support/input/testdata-converter-design.md b/.rn/ntf-yaml-support/input/testdata-converter-design.md new file mode 100644 index 00000000..45b6260d --- /dev/null +++ b/.rn/ntf-yaml-support/input/testdata-converter-design.md @@ -0,0 +1,363 @@ +# NTF テストデータ変換ツール 設計書 + +NTF のテストデータを Excel と YAML で相互変換するツールの設計です。 +中核の設計判断は一つ──**読み込みロジックを NTF 本体と共有し、変換ツールと本体で解釈がズレないことを保証する**こと。ズレれば、変換ツールが妥当とみなしたデータを本体が別物として読む不整合が起きます。この一点から、以下の構造・再利用方針・品質担保がすべて導かれます。 + +本体の読み込み機構は [ntf-testdata-loading.md](ntf-testdata-loading.md) を参照。 + +--- + +## 1. 何を作るか（背景と決定） + +### 解くべき課題 + +Excel で書かれてきた NTF テストデータを、AI エージェントが扱える YAML にも対応させる。そのため両形式を相互変換するツールを作る。難所は前述のとおり、変換ツールと本体で構造解釈をズラさないことにある。 + +### 基準は「形式」ではなく「NTF 仕様上の意味」 + +中間モデルを置き、Excel と YAML はその意味を各形式の記法で表したものとして扱う。どちらの形式も基準としない。 + +```mermaid +flowchart LR + XLS[Excel] <--> MID[中間モデル
NTF仕様上の意味] <--> YAML[YAML] +``` + +**可逆性**：ある形式 → 中間モデル → 同じ形式 と往復したとき、NTF 仕様上の意味が変わらないこと。形式に固有で意味を持たない情報（Excel の色・書式・結合セル、YAML のコメント等）は中間モデルに乗らず、可逆性の対象外とする。 + +**中間モデルが満たす状態**： + +- 構造は解析済み（レコードレイアウトの区切り、各行の役割、フィールド名と値の対応を保持） +- 値は未変換（`${systemTime}` 等の特殊記法を解決せず文字列のまま保持） +- 意図ある情報は無損失（マーカーカラム、空エントリ、空欄のレコード種別を保持） +- 無意味な情報は持たない（コメント、完全な空行、行末の空セルを除去） + +### 保持するか捨てるかの判断基準 + +迷う情報は一つの基準で割り切る。**その情報がテスト作成者の意図を持つなら保持し、持たない（本体が機械的に補う／捨てる）なら本体に従う。** + +本体の読み込み（①読む→②掃除→③特殊記法変換→④組み立て）の各処理を、変換ツールが実行するかどうかは、この基準で決まる。 + +| 段 | 処理 | 変換ツール | 理由 | +|---|---|---|---| +| ① | 読む（形式→行・セル）| 実行 | 変換ツールも各形式を読む | +| ② | コメント行・行内コメント除去 | 実行 | 注釈用途。中間モデルに位置づける先がない | +| ② | 空行除去（完全な空行）| 実行 | 全セル空は無意味。仕様上もスキップ対象 | +| ③ | 特殊記法変換（`null`・`${...}`・`""`・`\r` 等）| **実行しない** | 不可逆。記法のまま保持しないと本体の挙動が壊れる | +| ④ | 構造解析（名前/型/長さ/データの読み解き）| 実行 | 中間モデルの組み立てに必須 | +| ④ | マーカーカラム除外 | **実行しない** | `[...]` を外せば意味あるカラム名。作成者の意図を持つ | +| ④ | 行末空セル除去 | 実行 | 末尾の無意味な余白。意図を持たない | +| ④ | レコード種別の default 補完 | **実行しない** | 元データにない値。補完は本体の責務 | +| ④ | デフォルト値補完（DB 登録時）| **実行しない** | DB 登録時の処理。読み込み構造化の対象外 | + +補足が要るのは 2 点。**空行の区別**──「先頭フィールドのみ空」の空エントリは完全な空行ではなく、ファイルデータではデータ行として意味を持つため保持する。**補完の一貫性**──default 補完・DB デフォルト値補完は中間モデルでは行わず空欄のまま保持し、復元時も補完しない。最終的に本体が読む際に補うので結果は変わらず、補完の責務を本体に一貫させられる。 + +### 制約 + +- **既存 NTF 本体（Excel 読み込み）**：観測可能な挙動の維持が必達。挙動を変えないリファクタリングは可。明確なバグの修正は、観測挙動の維持を破らないため許容する。 +- **YAML 対応・変換ツール**：新規開発につき変更可。 +- 機能追加対象は最新バージョン **v6 のみ**。実装完了後、YAML 対応と変換ツールは別リポジトリへ分割する（他バージョンをフォークで作りやすくするため）。 + +--- + +## 2. どう作るか（設計判断） + +冒頭の「本体と解釈をズラさない」を、**本体の構造解析を変換ツールが再利用する**ことで満たす。本体と同じ器（`DataFile`／`TableData`／`MessagePool`）に行き着けば、構造解釈は 1 箇所に集約されズレない。 + +再利用する処理としない処理の線引きは、1 章の表のとおり。①読む・④構造解析は再利用し、③特殊記法変換・④破壊的整形（本体 getter が被せる加工）は持ち込まない。 + +ここで設計判断が分かれるのは、**本体に Excel と YAML の 2 系統があり、再利用の取り回しが違う**点。経路ごとに判断を示す。 + +### 判断 A：Excel 経路 — アダプタで再利用 + +**検討した選択肢と却下理由** + +本体の `BasicTestDataParser` の公開 API（`getSetupFile`／`getExpectedTableData` 等）をそのまま呼ぶ案は却下した。これらは結果を返す前に不要な加工を被せるため──`getSetupFile` は `BinaryFileInterpreter` を必ず先頭に積み `${binaryFile:...}` を解決し、`getExpectedTableData` は `fillDefaultValues`（DB 全カラム補完）と種別マージを行う。1 章の「記法のまま・無損失」に反する。 + +**決定** + +公開 API を経由せず、配線役の責務だけを薄いアダプタが肩代わりする。`BasicTestDataParser` は各 Parser へ `reader`・`interpreters`（・テーブル系は `dbInfo`）を渡して生成しデータタイプで振り分ける配線役にすぎない。アダプタが同じ配線を、**空の `interpreters`** で行い、`parse → getResult` で生の器を取り出す。 + +これで `null`・`${...}`・`""` 等は解釈されず、補完・マージも起きない。特殊記法は記法のまま中間モデルへ運ばれ、本体がテストとして読む際に解釈される。 + +> 1 章で「実行する」と定めた整形（行末空セル除去など）は外さない。外すのは③特殊記法変換のみ。 + +**残る課題と対応**：本体の非公開メンバ（Parser の `getResult`・一部コンストラクタ、`DataFileFragment` の `names`/`types`/`lengths`/`values`）は、変換ツールの正しいパッケージから直接呼べない。これを越えるため、本体の非公開メンバを同一パッケージから読み plain で返す薄い**抽出アダプタ**を、器のパッケージごとに 1 枚ずつ置く。 + +| アダプタ | 相乗り先 | 役割 | +|---|---|---| +| `TestCoreReaderAdapter` | `nablarch.test.core.reader` | Parser を空 `interpreters` で `parse → getResult` し、生の器を取り出す。`readFiles`/`readTables`/`readListMap`/`readMessage`/`readSendSyncMessages`/`readHeaders`/`readBlockBodyLines` を提供。MESSAGE 本文は `MessageParser.getDelegate()` から `FixedLengthFile` を取る | +| `TestCoreFileAdapter` | `nablarch.test.core.file` | `DataFileFragment` の `names`/`types`/`lengths`/`values` を読んで plain で返す | + +いずれも構造を組み立てず、読み取った値を plain で返すだけ。相乗りはこの 2 枚に閉じる。これにより本体の getter 追加・可視性拡大は不要で、本体は無変更。 + +### 判断 B：YAML 経路 — 本体の構造解釈を再利用（本体器を空インタープリタで取得） + +**検討した選択肢と却下理由** + +YAML も本体の読み込み（`YamlLoader` ＋ Builder 群）が構造解釈と値加工（特殊記法解釈・補完・マージ）を一体で行うため、変換ツールは値加工を外して器だけを取り出す必要がある。当初は本体読み込みを「構造マッピング層／値加工層」へ静的に二分割し、専用の中間表現（`Raw*`）を介す案を検討したが、本体に層と型を増やすコストに見合わず却下した（経緯は steering の D-F／D-H）。 + +**決定** + +Excel 経路（判断 A）と対称に、本体の YAML ビルダ（`YamlTableDataBuilder`／`YamlFileBuilder`／`YamlMessageBuilder`）を **空のインタープリタ・デフォルト値補完なし** で配線するアダプタ（`YamlTestCoreAdapter`、`reader` パッケージ相乗り）を変換ツール側に置く。ビルダは `YamlLoader` が返す順序保持 Map を走査して本体の器（`TableData`／`DataFile`／`MessagePool` 本文）を組み立てる処理をそのまま再利用し、空インタープリタにより `${...}`・`${binaryFile:...}`・`null`・`""` は記法のまま運ばれる。構造解釈は本体 1 箇所に集約され、変換ツールは再実装しない。 + +> **依存の向き**：主軸は NTF 本体。本体の YAML 読み込みは本体基準で設計し本体の器を返す。変換ツールはそれを再利用する側で、依存は変換ツール → 本体の一方向。本体が変換ツールの中間モデルに合わせて設計されることはない。 + +### 特殊記法の扱い：形式に依存するか否かで分ける + +特殊記法には 2 種類あり、扱いが異なる。 + +- **NTF 独自記法**（`${systemTime}`・`${binaryFile:...}` 等）：形式に依存しない NTF 仕様。Excel・YAML とも本体がテストとして読むときの値加工（インタープリタチェーン）で解釈する。変換ツールはいずれの形式でも（空インタープリタ配線により）解釈せず、記法のまま中間モデルへ運ぶ。 +- **形式の構文に属する記法**（クォートによる文字列明示）：形式ごとに担い手が違う。 + - Excel：クォートは NTF 独自の記法で、本体の `QuotationTrimmer` が外す。 + - YAML：クォートは **YAML 標準仕様**であり、YAML ライブラリ（SnakeYAML Engine）が読み込み時に解決する。よって YAML には `QuotationTrimmer` を適用しない（適用すると二重処理になる）。 + +YAML の値は、数値・null・空白を文字列として保つため、書き出し時に**全値をダブルクォートで囲む**（YAML 標準では `123` は数値、`null` は null 値、前後空白はクォートなしだと脱落するため）。読み込み時は YAML ライブラリがこれを文字列として解決する。これは NTF 仕様として確定。 + +### 共通：器の中身を読む手段 + +取り出した器の中身は、`TableData`・`MessagePool` は本体の public getter で読める。`DataFile`／`DataFileFragment` は package-private/protected な内部を、`file` パッケージに相乗りした `TestCoreFileAdapter` が読む。いずれも**本体無変更**（getter 追加・可視性拡大は不要）。 + +| 器 | 中身を読む手段 | +|---|---| +| `TableData` | `getTableName`／`getColumnNames`／`getValue`（public） | +| `DataFile`／`DataFileFragment` | `TestCoreFileAdapter`（`file` 相乗り）が `names`／`types`／`lengths`／`values` を読む | +| `MessagePool` | FW 制御ヘッダは `getFwHeader`（public）。本文は `FixedLengthFile` として取る | +| LIST_MAP | 戻り値が `List>` の素の型 | + +テーブル系は構造解析（`TableData.addRow`）の途中で `dbInfo.getColumnType` を要求する。値は文字列のままで型に依存しないが `dbInfo` が null だと読めないため、カラム型を返すだけの**スタブ `DbInfo`** を構成で差し込む。 + +### 共通：器が正規化する値の原文復元 + +本体の④構造解析は、テスト実行に必要な正規化を器に施す。変換ツールは原文（作成者の記述）が要るため、正規化される箇所だけ原文を補う。**原文の供給元は形式で異なる**：Excel は器を作る素材である**生行**（`PoiXlsReader` の出力）、YAML は器を作る素材である **`YamlLoader` の順序保持 Map**。いずれも器（構造の権威）と同じ素材から原文を取り、index／キーで器のフィールドへ対応させる。全データタイプを通した結果、取り出し経路で原文が変わるのは次の 3 点のみ（値の大半は無加工で器をそのまま使える）。 + +| 正規化 | 器の挙動 | Excel の原文復元（生行） | YAML の原文復元（YamlLoader Map） | +|---|---|---|---| +| カラム名・テーブル名の大文字化 | キーを大文字化（値は無損失） | 復元不要（NTF 仕様上カラム名の大小は無意味） | 同左（復元不要） | +| 長さ省略（`-`）フィールド | 値を改行除去・トリムし、長さを実バイト長に上書き | 長さ行のセルが `-`（`ONDEMAND_CALC_FIELD_SIZE`）かで省略を識別し、原文の値・長さは生行から取る | エントリ `records[].fields[].length` を Map 原文から取る（省略は `null`）。値は器（空インタープリタで未加工）から | +| 型表記 | 設計上の型名をフレームワーク表記（`X`/`N`/`B`/`Z`）に変換 | 原文の型は生行の型行から取る | エントリ `records[].fields[].type` を Map 原文から取る | +| LIST_MAP の列順 | 値 Map を `TreeMap` でキーソート | 元の列順は `HeaderLine` が保持＝器から取れる（生行不要） | 器は `TreeMap` で列順を喪失。エントリ先頭行のキー順（`YamlLoader` が記述順保持）から取る | + +Excel は生行から**マーカー列（`[...]` 形式のセル）を除外**すると、残セルが器のフィールドと同じ順序・同数で並ぶ（index で 1 対 1 対応）。YAML は `YamlLoader` Map のエントリ列が器（グループ絞り込み済み・FW_HEADER スキップ済み）と同順・同数で対応する（zip で 1 対 1）。いずれも器の断片数と原文側の要素数が食い違えば、誤った原文を静かに充填せず即座に失敗させる（fail-fast）。 + +### 重複実装を避ける：ロジックの共通化 + +変換ツールが生行を扱う際、本体と同じ判定を二重に実装すると解釈ズレの温床になる。形式非依存の判定ロジックは本体からユーティリティへ切り出し、本体と変換ツールで共有する（切り出しは private 判定を public ユーティリティへ移すリファクタで、本体の観測挙動を変えない）。 + +| 共通化するロジック | 本体の現所在 | 共通化 | +|---|---|---| +| マーカー列判定（`[...]` 形式の識別）| `HeaderLine` の private 条件 | ユーティリティへ切り出し共有。除外機構 `ListWrapper` は既に独立 util | +| コメント行・空行判定 | `TestDataParsingTemplate` の判定メソッド | 純粋判定をユーティリティへ切り出し共有 | +| 行末空セル除去 | `NablarchTestUtils.trimTailCopy` | 既に独立 util。そのまま共有 | + +行種別（名前行／型行／長さ行／値行）の判定は、本体の状態機械にパース進行と一体で埋め込まれており切り出せない。これは④の器（構造解析の結果）から構造を得て、生行と index 対応させることで、再実装せずに解決する。 + +### 書き出し（OUT）の整形方針 + +書き出しは形式の記法規則で定まるが、Excel だけ整形の判断が要る。読み手が違うため方針を分ける。 + +- **YAML OUT**：AI エージェントが読む前提。機械可読なら足り、記法どおりに書く（全値クォート・インデント程度）。 +- **Excel OUT**：人が見て編集する前提。行種別ごとの装飾やレイアウトで読みやすく整える。整形は**設定で指定可能**とし、未設定でも見やすい既定値を用意する。 + +整形は NTF 仕様上の意味を持たないため中間モデルに乗らず、OUT 時に設定に従って新規付与する。よって Excel → 中間モデル → Excel の往復で元の色・書式は再現されず、設定（またはデフォルト）に従った整形が付く（可逆性の対象外）。 + +| 設定項目 | デフォルト | +|---|---| +| データタイプ識別行・各種ヘッダ行・マーカーカラムの背景色 | [要確認] 見やすい配色を調査して決定 | +| 列幅 | 各列の値の最大文字数に合わせ自動調整 | +| 罫線 | データブロックの外枠に細線 | +| データブロック間の空行 | 1 行挿入 | + +--- + +## 3. 構造 + +中間モデルを介する Reader／Writer 構成。図に役割を持たせ、文は補足に絞る。 + +### 中間モデル + +```mermaid +classDiagram +direction TB +class TestDataContainer +class TestDataSection +class TestDataBlock { + <> + +dataType + +groupId + +identifier +} +class FileDataBlock { + +fileType: FileType +} +class ColumnRowDataBlock { + <> +} +class TableDataBlock +class ListMapBlock +class MessageDataBlock +class RecordLayout +class FieldDef +TestDataContainer "1" --> "*" TestDataSection +TestDataSection "1" --> "*" TestDataBlock +TestDataBlock <|-- FileDataBlock +TestDataBlock <|-- ColumnRowDataBlock +TestDataBlock <|-- MessageDataBlock +ColumnRowDataBlock <|-- TableDataBlock +ColumnRowDataBlock <|-- ListMapBlock +FileDataBlock "1" --> "*" RecordLayout +MessageDataBlock "1" --> "*" RecordLayout +RecordLayout "1" --> "*" FieldDef +``` + +`TestDataContainer` がテストクラス 1 つ分（Excel は 1 ブック／YAML は 1 ディレクトリ）、`TestDataSection` が読み込み単位（Excel は 1 シート／YAML は 1 ファイル）。その下に、データブロック（`FileDataBlock`／テーブル・LIST_MAP をまとめる `ColumnRowDataBlock`／`MessageDataBlock`）と、レコードレイアウト・フィールド定義がぶら下がる。 + +### IN（形式 → 中間モデル） + +各形式を本体の読み込み（2 章）で読み解き、本体の器を受け取って中間モデルへ組む。Excel・YAML とも `reader` 相乗りアダプタ（`TestCoreReaderAdapter`／`YamlTestCoreAdapter`）を空インタープリタで配線して器を取り出す対称な経路をとる。器が正規化する値は、**Excel は生行（`PoiXlsReader` 出力）から、YAML は `YamlLoader` の順序保持 Map から**原文を補う（2 章）。 + +```mermaid +classDiagram +direction LR +class TestDataFormatReader { + <> + +read(basePath, resourceName) TestDataContainer +} +class XlsFormatReader +class YamlFormatReader +class TestCoreReaderAdapter { + <> + +readFiles/readTables/readListMap/readMessage() + +readSendSyncMessages/readHeaders/readBlockBodyLines() +} +class YamlTestCoreAdapter { + <> + +readFiles/readTables/readListMap/readMessage/readSendSyncMessages() + +isResourceExisting/loadRawMap() +} +class TestCoreFileAdapter { + <> + +names/types/lengths/values +} +class ExcelParsers { + <<本体>> DataFileParser ほか + +parse() / +getResult() +} +class YamlBuilders { + <<本体>> YamlLoader + Yaml*Builder（器生成） +} +class StructuredObjects { + <<本体>> DataFile / TableData / MessagePool +} +XlsFormatReader ..|> TestDataFormatReader +YamlFormatReader ..|> TestDataFormatReader +XlsFormatReader --> TestCoreReaderAdapter : 呼ぶ +XlsFormatReader --> TestCoreFileAdapter : file系の内部値を読む +TestCoreReaderAdapter --> ExcelParsers : 空interpretersを配線しparse→getResult +TestCoreFileAdapter --> StructuredObjects : DataFileFragment内部を読む +ExcelParsers ..> StructuredObjects : 構築 +TestCoreReaderAdapter ..> StructuredObjects : 取り出して返す +YamlFormatReader --> YamlTestCoreAdapter : 呼ぶ（器＋loadRawMap 原文） +YamlFormatReader --> TestCoreFileAdapter : file系の内部値を読む +YamlTestCoreAdapter --> YamlBuilders : 空interpretersを配線し器生成 +YamlBuilders ..> StructuredObjects : 構築 +YamlTestCoreAdapter ..> StructuredObjects : 取り出して返す +XlsFormatReader ..> TestDataContainer : 組み立て +YamlFormatReader ..> TestDataContainer : 組み立て +``` + +受け取るのはいずれも**本体の器**で、それを変換ツールが中間モデルへ写す。中間モデルは変換ツール内部の表現で、本体には現れない（依存は変換ツール → 本体の一方向）。 + +経路ごとの要点は 2 章の判断 A・B のとおり。Excel は可視性の壁を越えるため、`nablarch.test.core.reader` に `TestCoreReaderAdapter`（Parser を parse→getResult し構造を取り出す）、`nablarch.test.core.file` に `TestCoreFileAdapter`（`DataFileFragment` の内部値を読む）を相乗りさせ、相乗りの影響をこの 2 枚に局所化する。YAML も対称に、`nablarch.test.core.reader` へ `YamlTestCoreAdapter` を相乗りさせ、本体の Yaml ビルダを空インタープリタで配線して器を取り出す。`YamlFormatReader` は器に加えて `loadRawMap`（`YamlLoader` の順序保持 Map）から原文を補い、`DataFile` 内部値は Excel と同じく `TestCoreFileAdapter` で読む。 + +### OUT（中間モデル → 形式） + +```mermaid +classDiagram +direction LR +class TestDataFormatWriter { + <> + +write(container, path) +} +class YamlFormatWriter +class XlsFormatWriter +class ExcelFormatConfig { + 背景色 / 列幅 / 罫線 / 空行 +} +class YamlTestDataValidator { + +validate(yaml) +} +YamlFormatWriter ..|> TestDataFormatWriter +XlsFormatWriter ..|> TestDataFormatWriter +XlsFormatWriter --> ExcelFormatConfig : 整形設定を参照 +YamlFormatWriter --> YamlTestDataValidator : 出力後スキーマ検証 +``` + +`YamlTestDataValidator`（`ValidationError` と対）は YAML OUT 後にスキーマ検証を行うリンターで、不正な YAML が生成された場合は `ValidationError` リストを返す。 + +`YamlFormatWriter` は記法どおり（全値クォート）、`XlsFormatWriter` は `ExcelFormatConfig`（2 章の整形表。デフォルトを備え上書き可能）を参照して整形付きで書き出す。 + +### 利用の入口 + +利用 PJ も開発チームも、同じ入口 `TestDataConverter`（form／to と入出力先を受け、IN→OUT を実行）を使う。`FormatHandler`（`XlsFormatHandler`／`YamlFormatHandler`）がソース探索・IN・OUT 経路の解決を担い、`TestDataConverter` はこれらを介す。 + +```mermaid +classDiagram +direction LR +class TestDataConverter { +convert(from,to,input,output) } +class FormatHandler { <> +findSources/read/createWriter/resolveOutputBase/outputPaths() } +class XlsFormatHandler +class YamlFormatHandler +NTF本体TestCode --> TestDataConverter : テストコードから呼ぶ +TestDataConverter --> FormatHandler : IN/OUT経路解決 +FormatHandler <|.. XlsFormatHandler +FormatHandler <|.. YamlFormatHandler +TestDataConverter --> TestDataFormatReader : IN +TestDataConverter --> TestDataFormatWriter : OUT +``` + +| 利用者 | やりたいこと | 呼び方 | +|---|---|---| +| NTF 利用 PJ | 既存 Excel を AI が扱える YAML へ移す（または逆） | `TestDataConverter` を `ConversionRequest`（include／exclude・上書き可否等）とともに呼ぶ。`ConverterFileFilter` / `ConverterPathResolver` がファイル選択・パス解決を担う | +| Nablarch 開発チーム | 本体テストを変えず YAML 経路でも通るか確認 | テストコードが `TestDataConverter` を直接呼び、実行時に Excel を一時 YAML へ変換 | + +開発チーム用途では出力先に一時ディレクトリを渡し、変換結果の YAML は git 管理せず実行のたびに生成・破棄する。入口は出力先を引数で受けるだけで、一時／永続を区別しない（後始末はテストコード側の責務）。 + +--- + +## 4. 品質担保 + +品質は「変換しても NTF 仕様上の意味が変わらない」ことに尽きる。粒度の小さい順に 4 段で担保する。 + +1. **各クラスのユニットテスト**：IN／OUT／中間モデルを単体検証。カバレッジ C0／C1 100% を基準とし分岐はモックで網羅。全データブロック種別（FIXED／VARIABLE／TABLE／LIST_MAP／MESSAGE 系）を網羅し、特に IN で値が未変換（特殊記法が記法のまま）であること、器が正規化する 3 点（長さ省略値・型表記・LIST_MAP 列順）が原文どおり復元されることを確認する。 +2. **往復変換の確認**：可逆性の検証。同一形式の往復（Excel→中間→Excel、YAML→中間→YAML）で NTF 仕様上の意味が変わらないこと。意味を持たない情報（色・書式・コメント）は対象外。 +3. **本体テストの YAML 変換**：振る舞い不変の担保。`nablarch-testing` の既存 Excel テストを YAML へ変換し**全件 PASS** すること。アサーションは変えず読み込む形式だけを YAML に差し替える。Excel で全件 PASS の既存テストが YAML 経路でも全件 PASS すれば、変換が意味を保っている担保になる。 +4. **サンプルアプリでの動作確認**：公式サンプルアプリ（Example 各種＋システム開発ガイドのサンプルプロジェクト）のテストデータをすべて YAML へ変換し、全件 PASS すること。 + +--- + +## 5. 開発とバージョン展開 + +### 開発とリポジトリ分割の手順 + +リポジトリ分割を見据え、`nablarch-testing` 内で分割先と同じ境界のパッケージとして分離開発する。 + +1. `nablarch-testing` 内で分割先と同じ境界でパッケージを分けて開発 +2. 品質担保 3（本体テストの YAML 変換が全件 PASS）まで完了 +3. 有識者レビュー +4. 承認後、分割先リポジトリ（nablarch-testing-yaml／nablarch-testing-converter）へ分割 +5. 分割後、品質担保 4（サンプルアプリ確認）を実施 + +### 過去バージョンへの展開 + +機能追加対象は v6 だが、過去展開も見込む。**全バージョンのリリースノートを確認した範囲**での判断を以下に示す（Nablarch は後方互換に影響する変更を API・動的挙動ともリリースノートに記録する方針のため、この確認で判定できる）。 + +- **v6（機能追加対象）**：変換ツールが依存する本体 API・読み込み構造解析に、後方互換を壊す変更は確認されなかった。v6 の `nablarch-testing` は `2.x` 系で、主な変更は Jetty 12 化・Java 21 対応・公開 API 追加にとどまり読み込み構造解析に影響しない。機能追加は阻害なく成立する。 +- **v5・v1.4〜v1.2（過去展開）**：YAML 対応はフォークで作成（対象バージョンに合わせ JDK と NTF バージョンを変える）。変換ツールは、依存する本体 API に後方互換を壊す変更が確認されなかったため、そのまま再利用できる。 + +過去バージョンでは本体の読み込み挙動そのものが次の境界で切り替わる。いずれも本体側の差で、変換ツールは本体の構造解析を再利用するため自動追従する（変換ツール固有の対応は不要）。 + +| 挙動差 | 境界 | 内容 | +|---|---|---| +| 空行の扱い | NTF 1.1 系で修正 | 全カラム空文字レコードを読み飛ばす不具合を、空行を明示記述できるよう修正。境界より前は空エントリの保持挙動が異なる | +| xlsx 形式対応 | NTF 1.2.0 で追加 | xls に加え xlsx 対応（Apache POI 入替）。境界より前は xlsx を読めない | +| 空文字→null 変換 | dataformat（v5 で明確化）| 可変長／固定長読込時、空文字を既定で null に変換（`convertEmptyToNull`）。設定で無効化可 | \ No newline at end of file diff --git a/.rn/ntf-yaml-support/steering.md b/.rn/ntf-yaml-support/steering.md new file mode 100644 index 00000000..93d7e747 --- /dev/null +++ b/.rn/ntf-yaml-support/steering.md @@ -0,0 +1,124 @@ +# Goal + +NTF（Nablarchテストフレームワーク）解説書（`ja/development_tools/testing_framework/guide/development_guide/06_TestFWGuide/` 配下）の全体構成を見直し、テストデータ記述形式として YAML を Excel と並列でサポートする記述を追加する。 + +作業フロー: RSTビルド確認 → 全体構成の認識合わせ → 影響範囲確認・タスク更新 → 文書表現・トンマナ確認・CLAUDE.mdへの作業ルール記載 → 解説書修正 + +# Acceptance criteria + +- `feature/ntf-yaml-support` ブランチで作業し、PR は `develop` ブランチへ向けて作成されている +- 変更前後で `make html`（RST → HTML ビルド）がエラーなく完了する +- 解説書の全体構成について、ユーザーと認識を合わせた内容がステアリングの Decisions に記録されている +- CLAUDE.md に解説書修正の作業ルール（文書表現・トンマナ）が記載されている +- Excel のみ言及していた箇所が YAML にも対応した記述（ExcelまたはYAML形式で記述できると明示）に更新されている +- 新規追加・変更した RST が Sphinx でビルドエラーなく通る +- 既存の RST の toctree 参照が壊れていない + +# Assumptions + +- YAML 対応は `nablarch-testing` 本体（PR #75 / `convert-testdata-excel-to-text` ブランチ）で実装済みであり、解説書はそれに合わせたドキュメント変更である +- 入力資料（`.rn/ntf-yaml-support/input/` 配下10ファイル）が YAML 形式の仕様・記述例の正典となる +- Sphinx ビルド環境は `make html` で実行できる（`requirements.txt` の依存が解決済み） +- 解説書の構成見直しの範囲は `06_TestFWGuide/` 配下が主であり、`05_UnitTestGuide/` 配下への影響は最小限とする（要確認） +- 既存の Excel 記述は削除せず、YAML を「並列サポート」として追記する方向で進める + +# Rules + +- commit and push every change; one completion marker per task +- RST ビルドは各タスク完了前に必ず確認し、エラーがあれば修正してから完了マークをつける +- 文書表現・トンマナは CLAUDE.md に記載したルールに従う +- 日本語で記述する（ファイルパス・コマンド・コード例は除く） +- 既存の Excel 向け記述を削除しない（YAML を追記する形で対応） +- 新規 RST ファイルを追加する場合は toctree にも追記する + +# Tasks + +### #1: RSTビルド確認 + +**Purpose**: 変更作業開始前に現時点のRSTビルドが問題なく通ることを確認し、ベースラインを確立する。 + +**Prerequisites**: none + +**Steps**: + +- [ ] `make html` を実行してビルドが通ることを確認する +- [ ] ビルドエラーや警告があれば原因を調査する（修正は任意 — このタスクの目的はベースライン確認） +- [ ] 結果を `checks/task1.md` に記録する +- [ ] self-check (OK/NG per completion criterion, record in checks/task1.md) +- [ ] user review + +**Completion criteria**: + +- `make html` がエラーなく完了した事実が `checks/task1.md` に記録されている（警告は許容、エラーは不可） + +### #2: 全体構成の認識合わせ + +**Purpose**: NTF解説書の現状の全体構成をまとめ、ユーザーと認識を合わせる。どの文書がどんな役割を担っているかを確認し、YAML対応で修正が必要な範囲の見通しを得る。 + +**Prerequisites**: #1 + +**Steps**: + +- [ ] `06_TestFWGuide/` 配下の全RSTを読み、各ファイルの役割・構成を一覧にまとめる +- [ ] `05_UnitTestGuide/` 配下の影響ありそうなRSTを確認する +- [ ] 入力資料（`input/ntf-testdata-doc.md`・`ntf-doc-terms.md`）をもとに YAML 対応で更新が必要な箇所を洗い出す +- [ ] 全体構成サマリーを `checks/task2.md` に記録しユーザーに提示する +- [ ] user review（構成認識の合意） + +**Completion criteria**: + +- `06_TestFWGuide/` 配下の全ファイルの役割と、YAML対応で修正が必要な箇所の一覧が `checks/task2.md` に記録されている +- ユーザーが全体構成を確認・承認している（Decisions に記録） + +### #3: 影響範囲確認とタスク更新 + +**Purpose**: 全体構成の合意をもとに、修正が必要なファイルと修正内容を具体化し、タスク一覧を更新する。 + +**Prerequisites**: #2 + +**Steps**: + +- [ ] 修正対象ファイルをリストアップし、各ファイルで必要な変更内容を `checks/task3.md` に記録する +- [ ] 解説書修正の各タスク（#5以降）をステアリングに追記する +- [ ] self-check (OK/NG per completion criterion, record in checks/task3.md) +- [ ] user review + +**Completion criteria**: + +- 修正対象ファイルと変更内容の一覧が `checks/task3.md` に記録されている +- ステアリングに解説書修正タスクが追記されている + +### #4: 文書表現・トンマナ確認とCLAUDE.md作業ルール記載 + +**Purpose**: 既存解説書の文書表現・トンマナ（用語の統一・文体・表記ルール）を確認し、解説書修正作業のルールをCLAUDE.mdに記載する。 + +**Prerequisites**: #3 + +**Steps**: + +- [ ] 既存解説書（`06_TestFWGuide/01_Abstract.rst` 等）と入力資料（`ntf-doc-terms.md`）から用語・表記ルールを抽出する +- [ ] 文体（です・ます調 vs だ・である調）・用語統一ルールをまとめる +- [ ] `CLAUDE.md` に作業ルールを記載する +- [ ] self-check (OK/NG per completion criterion, record in checks/task4.md) +- [ ] QA expert review (subagent) +- [ ] user review + +**Completion criteria**: + +- `CLAUDE.md` にNTF解説書修正の作業ルール（文書表現・用語・トンマナ）が記載されている + +### #5以降: 解説書修正（タスク#3完了後に追記） + +（#3完了後、影響範囲確認の結果をもとに具体的な修正タスクをここに追記する） + +# Decisions + +（未記入 — 作業中に記録） + +# State + +- **Status**: not suspended +- **Date**: 2026-06-26 +- **Last completed**: none +- **Next**: #1 RSTビルド確認 +- **Notes**: 入力資料10ファイルを `.rn/ntf-yaml-support/input/` に保存済み From bbd96702951b6fb49ed76e56114b8b25c8644b18 Mon Sep 17 00:00:00 2001 From: kiyotis Date: Fri, 26 Jun 2026 10:08:29 +0900 Subject: [PATCH 02/15] =?UTF-8?q?docs:=20complete=20task=20#1=20=E2=80=94?= =?UTF-8?q?=20RST=E3=83=93=E3=83=AB=E3=83=89=E7=A2=BA=E8=AA=8D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Sonnet 4.6 --- .rn/ntf-yaml-support/checks/task1.md | 45 ++++++++++++++++++++++++++++ .rn/ntf-yaml-support/steering.md | 16 +++++----- 2 files changed, 53 insertions(+), 8 deletions(-) create mode 100644 .rn/ntf-yaml-support/checks/task1.md diff --git a/.rn/ntf-yaml-support/checks/task1.md b/.rn/ntf-yaml-support/checks/task1.md new file mode 100644 index 00000000..9a734af1 --- /dev/null +++ b/.rn/ntf-yaml-support/checks/task1.md @@ -0,0 +1,45 @@ +# task1 Completion Check + +## Completion Criteria + +| Criterion | Self-check | Evidence | QA | QA Evidence | +|---|---|---|---|---| +| `make html` がエラーなく完了した事実が記録されている | OK | Sphinx v1.8.6 (venv: /tmp/sphinx_env) + `make html SPHINXBUILD=/tmp/sphinx_env/bin/sphinx-build` を実行。`build succeeded, 4 warnings.` で完了。エラーなし。警告4件はいずれも既存ファイル（`biz_samples/03/index.rst` の jsp シンタックス × 3、`biz_samples/13/index.rst` の properties シンタックス × 1）のハイライト失敗であり、ビルド自体に影響しない。 | OK | ビルド成果物（495 HTML）・venv・タイムスタンプの整合性を実環境で確認。警告4件の無害性も確認。注意点: requirements.txt 指定の Sphinx 1.3.6 と実使用の 1.8.6 の乖離は後続ビルドで venv 再利用により再現性を確保すること。 | + +## ビルド実行詳細 + +- 実行コマンド: `make html SPHINXBUILD=/tmp/sphinx_env/bin/sphinx-build`（`LC_ALL=C.UTF-8 LANG=C.UTF-8` を付与） +- 使用 Sphinx: v1.8.6（venv に構築） +- ソースファイル数: 334 +- ビルド結果: `build succeeded, 4 warnings.` +- 出力先: `_build/html/` + +### 警告一覧（既存ファイルのみ、新規変更なし） + +| ファイル | 行 | 内容 | +|---|---|---| +| `ja/biz_samples/03/index.rst` | 174 | Could not lex literal_block as "jsp". Highlighting skipped. | +| `ja/biz_samples/03/index.rst` | 255 | Could not lex literal_block as "jsp". Highlighting skipped. | +| `ja/biz_samples/03/index.rst` | 386 | Could not lex literal_block as "jsp". Highlighting skipped. | +| `ja/biz_samples/13/index.rst` | 118 | Could not lex literal_block as "properties". Highlighting skipped. | + +### 環境メモ + +システムの `sphinx-build`（Sphinx 9.1.0, Python 3.12）は `javasphinx` 非互換のため使用不可。 +`requirements.txt` が指定する Sphinx 1.3.6 も Python 3.12 非互換（re モジュール変更、Python 3.8 が必要）。 +Sphinx 1.8.6 を Python 3.12 の venv にインストールすることでビルドを成立させた。 + +## QA Expert Review + +| Aspect | Verdict | Evidence / Improvement | +|---|---|---| +| Meaningful tests/verification | OK | ビルド成果物・venv・タイムスタンプの整合性を実環境確認済み | +| Edge case coverage | OK | 警告4件の無害性確認済み。Sphinx バージョン乖離は引き継ぎ注意事項として記録 | + +## Overall Verdict + +- Self-check: OK +- QA: OK +- Language expert: N/A +- Software-engineering expert: N/A +- Ready for user review: Yes diff --git a/.rn/ntf-yaml-support/steering.md b/.rn/ntf-yaml-support/steering.md index 93d7e747..6b0825c2 100644 --- a/.rn/ntf-yaml-support/steering.md +++ b/.rn/ntf-yaml-support/steering.md @@ -41,11 +41,11 @@ NTF（Nablarchテストフレームワーク）解説書（`ja/development_tools **Steps**: -- [ ] `make html` を実行してビルドが通ることを確認する -- [ ] ビルドエラーや警告があれば原因を調査する（修正は任意 — このタスクの目的はベースライン確認） -- [ ] 結果を `checks/task1.md` に記録する -- [ ] self-check (OK/NG per completion criterion, record in checks/task1.md) -- [ ] user review +- [x] `make html` を実行してビルドが通ることを確認する +- [x] ビルドエラーや警告があれば原因を調査する（修正は任意 — このタスクの目的はベースライン確認） +- [x] 結果を `checks/task1.md` に記録する +- [x] self-check (OK/NG per completion criterion, record in checks/task1.md) +- [x] user review **Completion criteria**: @@ -119,6 +119,6 @@ NTF（Nablarchテストフレームワーク）解説書（`ja/development_tools - **Status**: not suspended - **Date**: 2026-06-26 -- **Last completed**: none -- **Next**: #1 RSTビルド確認 -- **Notes**: 入力資料10ファイルを `.rn/ntf-yaml-support/input/` に保存済み +- **Last completed**: #1 RSTビルド確認 +- **Next**: #2 全体構成の認識合わせ +- **Notes**: ビルド環境は `/tmp/sphinx_env`（Sphinx 1.8.6）。`make html SPHINXBUILD=/tmp/sphinx_env/bin/sphinx-build` で実行。後続タスクも同 venv を再利用すること。 From 6d83d381c84109164ea4f01e13c9af88ee1f7935 Mon Sep 17 00:00:00 2001 From: kiyotis Date: Fri, 26 Jun 2026 10:20:22 +0900 Subject: [PATCH 03/15] =?UTF-8?q?docs:=20task2=20=E5=85=A8=E4=BD=93?= =?UTF-8?q?=E6=A7=8B=E6=88=90=E5=88=86=E6=9E=90=20=E2=80=94=20checks/task2?= =?UTF-8?q?.md=20=E3=82=92=E8=A8=98=E9=8C=B2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Sonnet 4.6 --- .rn/ntf-yaml-support/checks/task2.md | 183 +++++++++++++++++++++++++++ .rn/ntf-yaml-support/steering.md | 8 +- 2 files changed, 187 insertions(+), 4 deletions(-) create mode 100644 .rn/ntf-yaml-support/checks/task2.md diff --git a/.rn/ntf-yaml-support/checks/task2.md b/.rn/ntf-yaml-support/checks/task2.md new file mode 100644 index 00000000..b094c95d --- /dev/null +++ b/.rn/ntf-yaml-support/checks/task2.md @@ -0,0 +1,183 @@ +# task2 Completion Check + +## 06_TestFWGuide/ 全ファイル構成 + +| ファイル | タイトル | 役割 | YAML対応で修正が必要か | +|---|---|---|---| +| index.rst | 自動テストフレームワークの使用方法 | tocのみ。配下ファイルへのリンク | 不要（構造変更なし） | +| 01_Abstract.rst | 自動テストフレームワーク | フレームワーク全体の概要・特徴。「テストデータの外部化」「Excelによるテストデータ記述」「データタイプ一覧」「命名規約（Excelファイル名・シート名）」「シート内の構造」「セルの書式」「特殊記法」「注意事項」を説明 | **要**（主要な修正対象。後述） | +| 02_DbAccessTest.rst | データベースを使用するクラスのテスト | DBアクセステストの方法。準備データ・期待値の記述方法（SETUP_TABLE/EXPECTED_TABLE等）、省略記述方法、デフォルト値、注意点を説明 | **要**（テストデータ記述箇所にExcel固有の表現が多数） | +| 02_RequestUnitTest.rst | リクエスト単体テスト（ウェブアプリケーション） | 内蔵サーバを使ったWebアプリテストの構造・設定・実行方法。データシートに言及 | **要**（「テストデータ（Excelファイル）」等の記述） | +| RequestUnitTest_rest.rst | リクエスト単体テスト（RESTfulウェブサービス） | RESTアプリテストの構造・設定・実行方法。DB操作はDbAccessTestSupportに委譲 | **要**（「テストデータ（Excelファイル）」の記述） | +| RequestUnitTest_batch.rst | リクエスト単体テスト（バッチ処理） | バッチテストの構造・テストデータ（固定長・可変長ファイル）の記述方法・各種設定値 | **要**（「Excelファイル（テストデータ）」の記述、テストデータ記述の文脈） | +| RequestUnitTest_real.rst | リクエスト単体テスト（メッセージ受信処理） | メッセージング受信テストの構造・テストデータの説明 | **要**（「Excelファイル（テストデータ）」の記述） | +| RequestUnitTest_send_sync.rst | リクエスト単体テスト（同期応答メッセージ送信処理） | 同期応答メッセージ送信テストの構造・テストデータの説明 | **要**（「Excelファイル（テストデータ）」の記述） | +| RequestUnitTest_http_send_sync.rst | リクエスト単体テスト（HTTP同期応答メッセージ送信処理） | 同期応答メッセージ送信テストとの差分のみ記述 | 不要（差分記述のみ。本体側で対応） | +| 03_Tips.rst | 目的別API使用方法 | 各種API（データ取得・日付固定・シーケンス採番・ThreadContext等）の使用方法。全て「ExcelファイルからXXXを取得」の文脈で記述 | **要**（セクション見出しやAPI説明にExcel固有表現が多数） | +| 04_MasterDataRestore.rst | マスタデータ復旧機能 | マスタデータ復旧機能の概要・環境構築・設定例。テストデータの記述形式には直接言及しない | 不要（コンポーネント設定・DBスキーマ操作の説明。テストデータ形式への直接言及なし） | +| JUnit5_Extension.rst | JUnit 5用拡張機能 | JUnit 5でNTFを使うExtensionクラス・合成アノテーションの説明。テストデータ形式には言及しない | 不要（テストコード構造の説明のみ） | + +--- + +## YAML対応で修正が必要な箇所一覧 + +### 01_Abstract.rst + +- **特徴 > テストデータの外部化** セクション: + - 「テストデータをExcelファイルに記述できる。」→ ExcelおよびYAMLファイルに記述できる旨の表現に修正 +- **フレームワーク構成表**: + - 「Excelファイル: テストデータを記載する。」→ 「テストデータファイル（ExcelまたはYAML）」への表現変更 +- **テストメソッド記述方法**: 変更不要 +- **「Excelによるテストデータ記述」セクション全体**: + - セクション見出し「Excelによるテストデータ記述」→ 「テストデータの記述」等に変更、またはYAML節を追加 + - 「命名規約 > パス、ファイル名に関する規約」: Excelファイル規約だけでなく、YAMLディレクトリ規約（テストクラスと同名ディレクトリ、ファイル名はシート名と同一）を追加 + - 「Excelシート名に関する規約」: YAMLでの対応（ファイル名＝シート名）を補足 + - 「シート内の構造」: Excelのシート構成の説明に加え、YAMLでの対応構造（トップレベルキー）を追記または別節追加 + - 「データタイプ一覧テーブル」: 現状のデータタイプ名称はYAMLでも共通で使われる概念だが、Excel固有の「データタイプ=値」の記述形式についてはYAMLキーとの対応表を追加 + - 「コメント」セクション: Excelの `//` コメントに加え、YAMLの `#` コメントを記述 + - 「マーカーカラム」セクション: ExcelとYAML両方で有効であることを明示 + - 「セルの書式」セクション: Excel固有（文字列書式、罫線）の説明。YAML固有（値は必ずダブルクォートで囲む等）の注意事項を追記 + - 「日付の記述方法」セクション: 形式自体はExcel/YAML共通。YAML側での値の書き方（クォート必須）を補足 + - 「セルへの特殊な記述方法」セクション: 見出しを「特殊な記述方法」等に変更し、YAMLでの等価記述（例: `"null"` vs `null`）を対応表で示す + - 「注意事項 > テストデータは全てExcelシートに記述する」: 「テストデータは全てテストデータファイルに記述する」等に表現変更。Excelシート/YAMLファイルの両形式を考慮した記述に修正 + - 「複数のデータタイプ使用時はデータタイプごとにまとめてデータを記述する」: YAML対応では制約が変わる（YAMLはセクションキーで構造化されるため混在可能）ことを追記 + +- **「JUnit 5で自動テストフレームワークを動かす」セクション**: 変更不要 + +### 02_DbAccessTest.rst + +- **主なクラス, リソース表**: + - 「テストデータ（Excelファイル）」→ 「テストデータ（ExcelファイルまたはYAMLファイル）」 +- **テストソースコード実装例**（複数箇所）: + - コメント「// Excelに記載した期待値と実際の値が等しいことを確認する」→ 「// テストデータファイルに記載した期待値と実際の値が等しいことを確認する」（またはExcel/YAML両対応の表現） +- **テストデータ記述例（全般）**: + - 「以下のようにデータを記載する。」の説明は構造的にはYAML/Excel共通だが、「1行目：SETUP_TABLE=...」等のExcel前提の説明のみになっているため、YAMLでの等価記述例も追記 + - 参照系テストデータ記述例、更新系テストデータ記述例において「シート名を記載する」という引数説明の注釈はExcel/YAML両対応になっているが、テストデータの書き方例（SETUP_TABLE/LIST_MAP/EXPECTED_TABLE）についてYAMLの書き方例を追加 +- **「データベーステストデータの省略記述方法」セクション**: + - 「Excelファイルの1シート内に複数のテーブルを記述できる」等の文言をYAMl向けに補足 +- **assertTableEqualsメソッドに関する注意点**: + - 「1シート内に複数のテーブルを記述できる」等のExcel固有表現をYAML対応に修正 +- **「setUpDbメソッドに関する注意点」**: + - 「Excelファイルには必ずしも全カラムを記述する必要はない」→ 「テストデータファイルには...」 + - 「Excelファイルの1シート内に複数のテーブルを記述できる」→ 「テストデータファイルの1読み込み単位（ExcelのシートまたはYAMLファイル）内に...」 +- **「Excelファイルに記述できるカラムのデータ型に関する注意点」**: + - 見出し「Excelファイルに記述できる」→ 「テストデータファイルに記述できる」 + - 本文の「Excelファイルには」→ 「テストデータファイルには」 + +### 02_RequestUnitTest.rst + +- **主なクラス, リソース表**: + - 「テストデータ（Excelファイル）」→ 「テストデータ（ExcelファイルまたはYAMLファイル）」（2箇所） +- テストデータそのものの記述方法への直接言及は少なく（詳細はbatch/real/send_sync側に委譲）、修正箇所は軽微 + +### RequestUnitTest_rest.rst + +- **主なクラス, リソース表**: + - 「テストデータ（Excelファイル）」→ 「テストデータ（ExcelファイルまたはYAMLファイル）」 +- それ以外はAPIの使い方説明が中心のため修正は軽微 + +### RequestUnitTest_batch.rst + +- **主なクラス, リソース表**: + - 「Excelファイル（テストデータ）」→ 「テストデータファイル（ExcelまたはYAML）」 +- **テストデータ > 固定長ファイル / 可変長ファイル**: + - 「基本的な記述方法は batch_request_test を参照」で05_UnitTestGuide側に委譲しているが、batch.rstでYAML記述方法を説明した場合は参照先が増える + - バイナリデータの記述方法（`0x` 形式）はYAML/Excel共通のため、現行表現のままでよいが、「テストデータ」という表現のExcel前提部分を修正 + +### RequestUnitTest_real.rst + +- **主なクラス, リソース表**: + - 「Excelファイル（テストデータ）」→ 「テストデータファイル（ExcelまたはYAML）」 +- **TestDataConvertor クラス説明**: + - 「Excelから読み込んだテストデータを編集するためのインタフェース」→ 「テストデータファイルから読み込んだテストデータを編集するためのインタフェース」（2箇所） + - 「Excelに日本語で記述されたデータをURLエンコーディングする等の処理を追加可能である」→ 「テストデータファイルに日本語で記述されたデータを...」 + +### RequestUnitTest_send_sync.rst + +- **主なクラス, リソース表**: + - 「Excelファイル（テストデータ）」→ 「テストデータファイル（ExcelまたはYAML）」 +- **RequestTestingMessagingProvider の説明**: + - 「Excelに記載された要求電文の期待値と、応答電文の読み込みも実行する。」→ 「テストデータファイルに記載された...」 +- **TestDataConvertor の説明**: + - 「Excelから読み込んだテストデータを編集するための...」→ 「テストデータファイルから読み込んだ...」（2箇所） + - 「Excelに日本語で記述されたデータをURLエンコーディングする等の処理」→ 「テストデータに日本語で記述されたデータを...」 + +### 03_Tips.rst + +- **「Excelファイルから、入力パラメータや戻り値に対する期待値などを取得したい」セクション見出し**: + - 見出しからExcelという用語を削除または「テストデータファイル」等に変更 +- **本文説明**: + - 「テスト対象クラスのメソッドを呼び出す際の引数や、メソッドの戻り値をExcelファイルに記載しておくことができる。」→ 「テストデータファイル（ExcelまたはYAML）に記載しておくことができる。」 + - 「以下のメソッドにより、Map形式またはList-Map形式で、Excelファイルよりデータを取得できる。」→ 「テストデータファイルよりデータを取得できる。」 +- **「同じテストメソッドをテストデータを変えて実行したい」セクション**: + - 「Excelデータを追加するだけで、データバリエーションを増やすことができる。」→ 「テストデータを追加するだけで...」 +- **「一つのシートに複数テストケースのデータを記載したい」セクション見出し**: + - 「シート」→ 「1ファイルまたは1シート（Excel）/ 1ファイル（YAML）」のような補足、またはYAMLでの対応方法を追記 + - Excel版のグループIDの書式 `データタイプ[グループID]=値` の説明に加え、YAMLの書式（`group_id:` フィールド）を追記 +- **「任意のディレクトリのExcelファイルを読み込みたい」セクション見出し**: + - 「Excelファイル」→ 「テストデータファイル」に変更 + - 本文：「別のディレクトリに存在するファイルを読み込みたい場合は、TestDataParser実装クラスを直接使用することで取得できる。」→ YAMLの場合もTestDataParserで対応可能かどうかを明記 + - コード例（`Baz.xlsx`）→ YAML対応後はYAMLファイルパスも渡せることを示す例を追加 +- **「ThreadContextにユーザID、リクエストIDなどを設定したい」セクション**: + - 「Excelファイルに設定する値を記述して下記メソッドを呼び出すことで」→ 「テストデータファイルに設定する値を記述して...」 +- **「メッセージング処理でテストデータに対し定型的な変換処理を追加したい」セクション**: + - 「テストデータ用のExcelに記述されたデータはデフォルトでは...」→ 「テストデータファイルに記述されたデータはデフォルトでは...」 + - 「URLエンコーディングされたデータをExcelに記述する必要があるが」→ 「テストデータファイルに記述する必要があるが」 + +--- + +## 05_UnitTestGuide/ への影響 + +05_UnitTestGuide/ はリクエスト単体テストの「具体的な使い方」を説明するハウツーガイドであり、06_TestFWGuide/ の仕様説明と対になっている。以下のファイルが影響を受ける可能性が高い。 + +### 強く影響を受けるファイル + +| ファイル | 影響理由 | +|---|---| +| `02_RequestUnitTest/batch.rst` | バッチリクエスト単体テストのテストデータ記述方法（SETUP_FIXED/SETUP_VARIABLE/EXPECTED_FIXED/EXPECTED_VARIABLE）の実例を含む。Excel前提のテストデータ記述例がYAML対応で追記・変更が必要になる | +| `02_RequestUnitTest/real.rst` | メッセージ受信テストのテストデータ記述方法（MESSAGE/EXPECTED電文等）の実例を含む。Excel前提のテストデータ記述例がYAML対応で追記・変更が必要になる。具体的には: 42行目「テストデータを記載したExcelファイルは…テストソースコードと同じディレクトリに同じ名前で格納する」（命名規則説明）、45行目「how_to_write_excel 参照」リンク、34行目・36行目「１テストクラスにつき１テストメソッド、１テストシートを原則」「メソッドやシートを分割しても良い」（テストメソッド分割方針）、71行目「同じシート内に記載したデータのグループID」、268行目「準備したテストシートに対応するメソッドを作成する」、286行目「テストデータのシート名を指定できる」など計12箇所。YAML対応後は命名規則（ディレクトリ規約・ファイル名）・シート分割概念のYAML版説明を追記する必要がある | +| `02_RequestUnitTest/send_sync.rst` | 同期応答メッセージ送信テストのテストデータ記述方法（EXPECTED_REQUEST_*_MESSAGES/RESPONSE_*_MESSAGES等）の実例を含む。Excel前提 | +| `02_RequestUnitTest/index.rst` | testShots/requestParamsの定義方法（LIST_MAP=testShots等）を説明する。YAML版での記述方法を補足する必要がある | +| `02_RequestUnitTest/http_send_sync.rst` | send_syncと同様 | +| `01_ClassUnitTest/02_componentUnitTest.rst` | コンポーネント単体テストのテストデータ（LIST_MAP等）記述例を含む | +| `01_ClassUnitTest/01_entityUnitTest/01_entityUnitTestWithBeanValidation.rst` | エンティティバリデーションテストのテストデータ記述例を含む | +| `01_ClassUnitTest/01_entityUnitTest/02_entityUnitTestWithNablarchValidation.rst` | 同上 | + +### 軽微な影響が考えられるファイル + +| ファイル | 影響度 | 影響箇所 | +|---|---|---| +| `02_RequestUnitTest/rest.rst` | 軽微（要修正） | 84行目: `how_to_write_excel` 参照リンク、91行目・92行目: 「テストクラス一つにつきExcelファイルが必ず一つ必要」「Excelファイルが存在しない場合でも」、96行目: 「上記以外のテストデータをExcelファイルに記載可能」、97行目: `how_to_get_data_from_excel` 参照リンク、115行目: 「テストデータを記載したExcelファイルにテストメソッドの名前でシートを用意」の計7箇所。参照リンク先（`how_to_write_excel`・`how_to_get_data_from_excel`）がYAML対応で変更された場合はリンク先の更新も必要。それ以外の修正箇所はExcel/YAMLを包含する表現への置き換えで対応可能 | +| `02_RequestUnitTest/mail.rst` | 軽微（要修正） | 28行目: 「期待する上記3テーブルの状態をExcelシートに記述すればよい」→ 「テストデータファイル（ExcelシートまたはYAMLファイル）に記述すればよい」に修正が必要。言及は1箇所のみ | +| `02_RequestUnitTest/fileupload.rst` | 軽微（要修正） | 66行目・111行目: 「テストデータシート」という表現が2箇所。Excelと明示してはいないが「シート」はExcel前提の語であるため、「テストデータファイル」等の表現に修正が必要 | +| `02_RequestUnitTest/http_send_sync.rst` | 軽微（要修正） | 33行目: 「1セルに全部記述すると可読性が落ちる場合」（Excelセルへの言及）、47行目・49行目: 「1Excelシートに1テストケースのみ記述すること」「Excelの各行の文字列長が同一であることを期待している」というNTF制約の説明。YAML対応後は制約の適用範囲をExcel/YAML別に説明する必要がある | +| `02_RequestUnitTest/http_real.rst` | 軽微（要修正） | `real.rst` との差分のみを記述するファイルだが、固有のExcel言及が3箇所ある。39行目: 「Excelファイルのメッセージボディとの比較で行う」（tipブロック内）、151行目: 「1Excelシートに1テストケースのみ記述すること」（JSON/XMLデータ形式使用時のNTF制約）、153行目: 「Excelの各行の文字列長が同一であることを期待している」（NTF制約の理由説明）。`http_send_sync.rst` と同様のパターンであり、YAML対応後は制約の適用範囲をExcel/YAML別に説明する必要がある | +| `03_DealUnitTest/batch.rst` | 強い影響（要修正） | 29行目・37行目・39行目・46行目・52行目・53行目・67行目・80行目・113行目・125行目・136行目・147行目・153行目・164行目・180行目: 「1シートにつき1テストケース」「1つのシートに全テストデータを詰め込む」「1ケースを複数シートに分割して記述してもよい」「1シートに全テストケースを含めてもよい」「1シートにまとめて記述する」「1シート内に複数のバッチ実行を記述」「グループIDを使用することで1シートに複数ケースのテストデータを記述できる」等、テストケース分割方針の説明がExcelシート前提で全面的に記述されている。YAML対応後はファイル単位の対応概念を追加説明する必要がある | +| `03_DealUnitTest/send_sync.rst` | 強い影響（要修正） | 51行目・54行目・55行目・65行目・68行目・70行目・72行目・77行目・84行目・143行目・173行目・176行目・177行目・187行目・189行目・301行目・304行目・312行目・319行目・326行目・333行目: 「応答電文のフォーマットおよびデータをExcelファイルに定義する」「ファイルの名前は「RM21AA0101.xlsx」となる」「Excelファイルの書き方」セクション見出し、「Excelファイルを記載する」「シート名は「message」固定」「Excelファイルの再読み込み」機能の説明、「Excelファイルの配置場所の設定」等、ファイル形式・命名規則・配置設定レベルで多数のExcel前提の記述がある。Excelファイル名（.xlsx）・シート名・配置設定をYAMLに対応させる必要がある | +| `03_DealUnitTest/http_send_sync.rst` | 強い影響（要修正） | 22行目・25行目・27行目・34行目: 「Excelファイルの書き方」セクション見出し（主要見出しレベル）、「定められた記述ルールに従いExcelファイルを記載する」「Excelファイルに定義した応答電文のフォーマットおよびデータは」「以下に、Excelファイルの記載例を示す」。send_sync.rst との差分のみを記述するファイルだが、Excelファイルに関するセクション見出しと説明が直接記述されており修正が必要 | +| `03_DealUnitTest/delayed_receive.rst` | 影響なし（修正不要） | 本文7行のみ。「取引単体テストの実施方法は、同期応答メッセージ受信処理と同じである。実施方法の詳細は `./real` を参照すること。」という参照のみ。Excel/シート/セルへの言及は一切なし | +| `03_DealUnitTest/delayed_send.rst` | 影響なし（修正不要） | 本文7行のみ。「取引単体テストの実施方法は、同期応答メッセージ送信処理と同じである。実施方法の詳細は `./real` を参照すること。」という参照のみ。Excel/シート/セルへの言及は一切なし | +| `01_ClassUnitTest/02_componentUnitTest.rst` | 強い影響（要修正） | 14行目・16行目: ダウンロードリンクで「UserComponentTest.xlsx」というExcelファイル名を直接参照。43行目: 「テストデータ(Excelファイル)そのもの」。47行目・48行目: 「テストデータを記載したExcelファイルは〜同じ名前で格納する（拡張子のみ異なる）」「全てのテストデータは同じExcelのシートに記載する前提」という命名規則・格納方法の説明。242行目・244行目: 「getListMapメソッドを用いてExcelシートからデータを読み込んでいる」「how_to_get_data_from_excel へのリンク参照」。314行目: 「同じExcelシート内に正常系と異常系のデータを混載している」。YAML対応ではディレクトリ規約・ファイル命名・データ読み込み方法の説明を全面的に修正・追記する必要がある | + +--- + +## Completion Criteria + +| Criterion | Self-check | Evidence | QA | QA Evidence | +|---|---|---|---|---| +| 06_TestFWGuide/ 配下の全ファイルの役割とYAML対応修正箇所の一覧が記録されている | OK | 上記「06_TestFWGuide/ 全ファイル構成」テーブル（12ファイル全列挙）および「YAML対応で修正が必要な箇所一覧」セクション（修正が必要な8ファイルについて具体的なセクション・箇所を列挙） | OK | 全26ファイルをfindで列挙して突き合わせ。Excel/シート言及のある未記載ファイルなし。05_UnitTestGuide影響範囲も実ファイル確認済み（2回の修正で補完）。 | + +## QA Expert Review + +| Aspect | Verdict | Evidence / Improvement | +|---|---|---| +| Meaningful tests/verification | OK | 前回2回の指摘事項（計12ファイル）がすべてtask2.mdに反映。影響度・行番号レベルで具体的に記載されている | +| Edge case coverage | OK | 05_UnitTestGuide/ 配下全26ファイルをfindで列挙し突き合わせ。Excel/シート言及のある未記載ファイルはゼロ | + +## Overall Verdict + +- Self-check: OK +- QA: OK +- Language expert: N/A +- Software-engineering expert: N/A +- Ready for user review: Yes diff --git a/.rn/ntf-yaml-support/steering.md b/.rn/ntf-yaml-support/steering.md index 6b0825c2..fd692e40 100644 --- a/.rn/ntf-yaml-support/steering.md +++ b/.rn/ntf-yaml-support/steering.md @@ -59,10 +59,10 @@ NTF（Nablarchテストフレームワーク）解説書（`ja/development_tools **Steps**: -- [ ] `06_TestFWGuide/` 配下の全RSTを読み、各ファイルの役割・構成を一覧にまとめる -- [ ] `05_UnitTestGuide/` 配下の影響ありそうなRSTを確認する -- [ ] 入力資料（`input/ntf-testdata-doc.md`・`ntf-doc-terms.md`）をもとに YAML 対応で更新が必要な箇所を洗い出す -- [ ] 全体構成サマリーを `checks/task2.md` に記録しユーザーに提示する +- [x] `06_TestFWGuide/` 配下の全RSTを読み、各ファイルの役割・構成を一覧にまとめる +- [x] `05_UnitTestGuide/` 配下の影響ありそうなRSTを確認する +- [x] 入力資料（`input/ntf-testdata-doc.md`・`ntf-doc-terms.md`）をもとに YAML 対応で更新が必要な箇所を洗い出す +- [x] 全体構成サマリーを `checks/task2.md` に記録しユーザーに提示する - [ ] user review（構成認識の合意） **Completion criteria**: From d192679e5fd1a218a758cc3973e6d32381b3c902 Mon Sep 17 00:00:00 2001 From: kiyotis Date: Fri, 26 Jun 2026 11:09:30 +0900 Subject: [PATCH 04/15] =?UTF-8?q?docs:=20NTF=E8=A7=A3=E8=AA=AC=E6=9B=B8?= =?UTF-8?q?=E3=82=BC=E3=83=AD=E3=83=99=E3=83=BC=E3=82=B9=E6=96=B0=E6=A7=8B?= =?UTF-8?q?=E6=88=90=E6=A1=88=E3=82=92=E8=BF=BD=E5=8A=A0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Sonnet 4.6 --- .rn/ntf-yaml-support/proposed-structure.md | 265 +++++++++++++++++++++ 1 file changed, 265 insertions(+) create mode 100644 .rn/ntf-yaml-support/proposed-structure.md diff --git a/.rn/ntf-yaml-support/proposed-structure.md b/.rn/ntf-yaml-support/proposed-structure.md new file mode 100644 index 00000000..57a1ac5c --- /dev/null +++ b/.rn/ntf-yaml-support/proposed-structure.md @@ -0,0 +1,265 @@ +# NTF 解説書 新構成案 + +## 設計の背景 + +現状の解説書は以下の問題を抱えている: + +1. **「テストデータの書き方」が10本以上に散在** — `01_Abstract.rst` に全体仕様、各処理方式（batch/real/send_sync 等）にも個別仕様が書かれており、開発者が「どこを読めばわかるか」が不明 +2. **アーキテクト向けと開発者向けの混在** — アーキテクトガイド（`06_TestFWGuide/`）に開発者が日常参照する内容（testShots・特殊記法・Tips）が埋まっている +3. **testShots 仕様が10本以上に重複記述** — 処理方式別ファイルにそれぞれ独立して解説されており、横断的な仕様としてまとめた場所がない +4. **YAML 対応後の入口がない** — 「どちらの形式を使うか」「何が変わるか」を利用者が判断する場所がない + +本設計はこれらをゼロベースで解消し、Excel/YAML 両対応の構成に組み直す。 + +--- + +## 読者ターゲットの定義 + +| 読者 | 関心事 | 使うタイミング | +|---|---|---| +| **アーキテクト** | FW の仕組み・テストクラス基盤の設定・プロジェクトへの導入方針 | プロジェクト立ち上げ時・テスト基盤設計時 | +| **アプリ開発者** | テストデータの書き方・テストクラスの実装手順・よくある使い方の例 | テスト実装時（日常的に参照） | + +--- + +## 新構成ツリー + +``` +テスティングフレームワーク（index.rst） +│ ※「アーキテクトは A 章へ、開発者は B 章へ」を明示 +│ +├── A. 導入・設定ガイド（アーキテクト向け） +│ ├── A-1. 自動テストフレームワークの概要 +│ │ FW の特徴・制約・クラス構成・処理フロー +│ │ ※現: 01_Abstract.rst の前半（特徴・FW構成表） +│ │ +│ ├── A-2. テストクラス基盤の設定 +│ │ ├── A-2-1. DB アクセステスト用クラス（DbAccessTestSupport） +│ │ ├── A-2-2. リクエスト単体テスト用クラス（Web/REST/バッチ） +│ │ └── A-2-3. リクエスト単体テスト用クラス（メッセージング各種） +│ │ ※現: 06_TestFWGuide/02_*.rst の「クラス構成・設定」部分 +│ │ +│ ├── A-3. テストデータ形式の選択（Excel / YAML）★新規★ +│ │ どちらを使うか・プロジェクト内での統一方針・移行手順 +│ │ +│ ├── A-4. JUnit 5 拡張の導入 +│ │ ※現: JUnit5_Extension.rst そのまま +│ │ +│ ├── A-5. マスタデータ復旧機能 +│ │ ※現: 04_MasterDataRestore.rst そのまま +│ │ +│ └── A-6. テストツール +│ ※現: 08_TestTools/ そのまま +│ +└── B. テスト実装ガイド（開発者向け） + ├── B-1. テストデータの書き方（リファレンス）★最大の変更点★ + │ ├── B-1-1. 全体像とファイル構造（Excel / YAML） + │ ├── B-1-2. データブロック種別一覧（14種） + │ ├── B-1-3. テストケース定義（testShots）と処理方式別カラム仕様 + │ ├── B-1-4. テーブルデータ（SETUP_TABLE / EXPECTED_TABLE 等） + │ ├── B-1-5. ファイルデータ（固定長・可変長） + │ ├── B-1-6. メッセージングデータ + │ └── B-1-7. 値の書き方・特殊記法 + │ ※現在10本以上に散在 → ここに集約 + │ ※主素材: input/ntf-testdata-doc.md + example ファイル群 + │ + ├── B-2. クラス単体テスト + │ ※現: 05_UnitTestGuide/01_ClassUnitTest/ ほぼそのまま + │ ※「テストデータの書き方」→ B-1 への参照に置換 + │ + ├── B-3. リクエスト単体テスト + │ ├── ウェブアプリケーション + │ ├── RESTful ウェブサービス + │ ├── バッチ処理 + │ ├── メッセージング（同期応答受信 / 応答不要受信 / HTTP 同期応答受信） + │ ├── メッセージング（同期応答送信 / 応答不要送信 / HTTP 同期応答送信） + │ └── その他（ファイルアップロード / メール / 2重送信防止） + │ ※現: 05_UnitTestGuide/02_RequestUnitTest/ + │ ※各ページの「テストデータの書き方」節 → B-1 参照に置換 + │ + ├── B-4. 業務単体テスト + │ ※現: 05_UnitTestGuide/03_DealUnitTest/ ほぼそのまま + │ ※「テストデータの書き方」→ B-1 への参照に置換 + │ + └── B-5. Tips（目的別 API 使用方法） + ※現: 06_TestFWGuide/03_Tips.rst → 開発者向けに移動 + ※Excel 固有表現をテストデータファイル表現に修正 +``` + +--- + +## 設計の核心：B-1「テストデータの書き方」の独立 + +### なぜ独立させるか + +現状では開発者が「testShots に何を書くか」「SETUP_TABLE の構造は？」を調べるたびに複数ファイルを横断する必要がある。B-1 を独立させることで: + +- **一か所に来れば全部わかる** — データブロック種別・特殊記法・値の型・ディレクティブが揃う +- **Excel / YAML を並列で説明できる** — `ntf-testdata-doc.md` の構成がそのまま活きる +- **各処理方式ページがすっきりする** — 「テストケースの追加は B-1-3 を参照」で済む + +### B-1 の構成イメージ（ntf-testdata-doc.md を主素材） + +| B-1 節 | 内容 | 主素材 | +|---|---|---| +| B-1-1 全体像 | Excel=1ブック/1シート、YAML=1ディレクトリ/1ファイル の対応関係 | ntf-testdata-doc.md §1〜2 | +| B-1-2 データブロック種別 | 14種の一覧・識別方法・Excel vs YAML キー対応表 | ntf-testdata-doc.md §3 | +| B-1-3 testShots | testShots の定義・処理方式別カラム仕様・groupId | ntf-testdata-doc.md §4 + examples-testshots.md | +| B-1-4 テーブルデータ | SETUP_TABLE / EXPECTED_TABLE / LIST_MAP | ntf-testdata-doc.md §5 + examples-table.md | +| B-1-5 ファイルデータ | 固定長・可変長・ディレクティブ | ntf-testdata-doc.md §6・9 + examples-file.md | +| B-1-6 メッセージング | MESSAGE / EXPECTED_REQUEST_* / RESPONSE_* | ntf-testdata-doc.md §7 + examples-messaging.md | +| B-1-7 値の書き方 | null/空文字/日付/${systemTime} 等・Excel vs YAML 対比 | ntf-testdata-doc.md §8・10 + examples-special.md | + +### B-1 記述例のイメージ（Excel / YAML 並列） + +各節の末尾に「記述例」として Excel 表と YAML コードブロックを並べて掲載する。 +現場ですぐ写して使えることを目標とする。 + +``` +テーブルへの準備データ（SETUP_TABLE）の例 +========================================== + +.. tab:: Excel + + .. list-table:: + :header-rows: 1 + + * - SETUP_TABLE=ORDER_HEADER + - ORDER_ID + - ITEM_COUNT + * - + - 10001 + - 10 + +.. tab:: YAML + + .. code-block:: yaml + + setup_tables: + - table: ORDER_HEADER + rows: + - ORDER_ID: "10001" + ITEM_COUNT: "10" +``` + +※タブ切り替えの対応状況次第では「Excel の場合」「YAML の場合」の見出し分けでも可 + +--- + +## 新旧マッピング表（品質担保用） + +既存ファイルの内容が新構成のどこに移るかを示す。この表をもとに「漏れなし」を確認する。 + +| # | 既存ファイル | 内容カテゴリ | 新構成の移動先 | 処理方針 | +|---|---|---|---|---| +| 1 | `06_TestFWGuide/01_Abstract.rst` § 特徴・構成表 | FW の仕組み | **A-1** | 抜粋・移動 | +| 2 | `06_TestFWGuide/01_Abstract.rst` § 命名規約・データタイプ一覧・特殊記法・注意事項 | テストデータ仕様 | **B-1**（Excel+YAML対応に拡充） | 集約・拡充 | +| 3 | `06_TestFWGuide/02_DbAccessTest.rst` § クラス構成・仕組み説明 | テストクラス基盤 | **A-2-1** | 抜粋・移動 | +| 4 | `06_TestFWGuide/02_DbAccessTest.rst` § API 使い方・記述例 | テスト実装方法 | **B-2** に残置 or 参照化 | 検討 | +| 5 | `06_TestFWGuide/02_RequestUnitTest.rst` | リクエスト単体テスト基盤 | **A-2-2** | 移動 | +| 6 | `06_TestFWGuide/RequestUnitTest_batch.rst` | バッチ用クラス設定 | **A-2-2** | 移動 | +| 7 | `06_TestFWGuide/RequestUnitTest_rest.rst` | REST 用クラス設定 | **A-2-2** | 移動 | +| 8 | `06_TestFWGuide/RequestUnitTest_real.rst` | メッセージング受信用クラス設定 | **A-2-3** | 移動 | +| 9 | `06_TestFWGuide/RequestUnitTest_send_sync.rst` | メッセージング送信用クラス設定 | **A-2-3** | 移動 | +| 10 | `06_TestFWGuide/RequestUnitTest_http_send_sync.rst` | HTTP 送信差分説明 | **A-2-3** | 移動 | +| 11 | `06_TestFWGuide/03_Tips.rst` | 目的別 API / Tips | **B-5** | 開発者向けに移動、Excel→テストデータファイル表現に修正 | +| 12 | `06_TestFWGuide/04_MasterDataRestore.rst` | マスタデータ復旧 | **A-5** | そのまま移動 | +| 13 | `06_TestFWGuide/JUnit5_Extension.rst` | JUnit 5 拡張 | **A-4** | そのまま移動 | +| 14 | `05_UnitTestGuide/01_ClassUnitTest/index.rst` | クラス単体テスト概要 | **B-2** | そのまま | +| 15 | `05_UnitTestGuide/01_ClassUnitTest/01_entityUnitTest/01_*.rst` | エンティティ単体テスト（Bean Validation） | **B-2** | テストデータの書き方 → B-1 参照に | +| 16 | `05_UnitTestGuide/01_ClassUnitTest/01_entityUnitTest/02_*.rst` | エンティティ単体テスト（Nablarch Validation） | **B-2** | テストデータの書き方 → B-1 参照に | +| 17 | `05_UnitTestGuide/01_ClassUnitTest/02_componentUnitTest.rst` | コンポーネント単体テスト | **B-2** | テストデータの書き方 → B-1 参照に、命名規約 → B-1-1 参照に | +| 18 | `05_UnitTestGuide/02_RequestUnitTest/index.rst` | リクエスト単体テスト概要 | **B-3** | そのまま | +| 19 | `05_UnitTestGuide/02_RequestUnitTest/batch.rst` | バッチリクエスト単体テスト実装手順 | **B-3** | 「テストデータの書き方」節 → B-1-3〜5 参照に | +| 20 | `05_UnitTestGuide/02_RequestUnitTest/rest.rst` | REST リクエスト単体テスト実装手順 | **B-3** | 「テストデータの書き方」節 → B-1 参照に | +| 21 | `05_UnitTestGuide/02_RequestUnitTest/real.rst` | 同期応答受信 実装手順 | **B-3** | 「テストデータの書き方」節 → B-1-6 参照に | +| 22 | `05_UnitTestGuide/02_RequestUnitTest/http_real.rst` | HTTP 同期応答受信 実装手順 | **B-3** | 「テストデータの書き方」節 → B-1-6 参照に | +| 23 | `05_UnitTestGuide/02_RequestUnitTest/send_sync.rst` | 同期応答送信 実装手順 | **B-3** | 「テストデータの書き方」節 → B-1-6 参照に | +| 24 | `05_UnitTestGuide/02_RequestUnitTest/delayed_send.rst` | 応答不要送信 実装手順 | **B-3** | 参照先へ委譲のため軽微 | +| 25 | `05_UnitTestGuide/02_RequestUnitTest/delayed_receive.rst` | 応答不要受信 実装手順 | **B-3** | 参照先へ委譲のため軽微 | +| 26 | `05_UnitTestGuide/02_RequestUnitTest/http_send_sync.rst` | HTTP 同期応答送信 実装手順 | **B-3** | 「テストデータの書き方」節 → B-1 参照に | +| 27 | `05_UnitTestGuide/02_RequestUnitTest/mail.rst` | メール送信テスト 実装手順 | **B-3** | 軽微修正 | +| 28 | `05_UnitTestGuide/02_RequestUnitTest/fileupload.rst` | ファイルアップロードテスト 実装手順 | **B-3** | 軽微修正 | +| 29 | `05_UnitTestGuide/02_RequestUnitTest/double_transmission.rst` | 2重送信防止テスト 実装手順 | **B-3** | 変更なし | +| 30 | `05_UnitTestGuide/03_DealUnitTest/batch.rst` | バッチ業務単体テスト 実装手順 | **B-4** | 「テストデータの書き方」節 → B-1 参照に | +| 31 | `05_UnitTestGuide/03_DealUnitTest/send_sync.rst` | 同期応答送信 業務単体テスト | **B-4** | 「テストデータの書き方」節 → B-1 参照に | +| 32 | `05_UnitTestGuide/03_DealUnitTest/http_send_sync.rst` | HTTP 同期応答送信 業務単体テスト | **B-4** | 「テストデータの書き方」節 → B-1 参照に | +| 33 | `05_UnitTestGuide/03_DealUnitTest/real.rst` | 同期応答受信 業務単体テスト | **B-4** | そのまま | +| 34 | `05_UnitTestGuide/03_DealUnitTest/rest.rst` | REST 業務単体テスト | **B-4** | そのまま | +| 35 | `05_UnitTestGuide/03_DealUnitTest/delayed_send.rst` | 応答不要送信 業務単体テスト | **B-4** | そのまま（参照のみ） | +| 36 | `05_UnitTestGuide/03_DealUnitTest/delayed_receive.rst` | 応答不要受信 業務単体テスト | **B-4** | そのまま（参照のみ） | +| 37 | `08_TestTools/01_HttpDumpTool/` | HTTP dump ツール | **A-6** | そのまま | +| 38 | `08_TestTools/02_MasterDataSetup/` | マスタデータセットアップツール | **A-6** | そのまま | +| 39 | `08_TestTools/03_HtmlCheckTool/` | HTML チェックツール | **A-6** | そのまま | +| ★ | *(新規)* | テストデータ形式の選択 | **A-3** | 新規作成 | +| ★ | *(新規、ntf-testdata-doc.md 主素材)* | テストデータの書き方リファレンス | **B-1** | ntf-testdata-doc.md + example 群を RST 化 | + +--- + +## input/ 資料と新構成の対応 + +入力資料は B-1 の主素材として使う。各ファイルと対応節を示す。 + +| input/ ファイル | 内容 | 主に使う節 | +|---|---|---| +| `ntf-testdata-doc.md` | テストデータ仕様リファレンス全体（Excel/YAML 両対応） | B-1 全体の主素材 | +| `ntf-testdata-doc-examples-overview.md` | 全体像の記述例（テストケース・セットアップ・検証が共存するファイルの例） | B-1-1 に掲載 | +| `ntf-testdata-doc-examples-testshots.md` | 処理方式別 testShots カラム仕様と Excel/YAML 記述例 | B-1-3 に掲載 | +| `ntf-testdata-doc-examples-table.md` | テーブルデータ（SETUP_TABLE/EXPECTED_TABLE 等）の Excel/YAML 記述例 | B-1-4 に掲載 | +| `ntf-testdata-doc-examples-file.md` | ファイルデータ（固定長・可変長）の Excel/YAML 記述例 | B-1-5 に掲載 | +| `ntf-testdata-doc-examples-messaging.md` | メッセージングデータの Excel/YAML 記述例 | B-1-6 に掲載 | +| `ntf-testdata-doc-examples-special.md` | 特殊値・ディレクティブ・ヘッダ/コメント の Excel/YAML 記述例 | B-1-7 に掲載 | +| `ntf-testdata-loading.md` | FW の内部読み込み機構（4段階変換・クラス設計） | A-1 の補足（内部仕組みの詳細）| +| `ntf-doc-terms.md` | 用語リファレンス（既存解説書からの用語引き表） | 各ページの用語統一に使用 | +| `testdata-converter-design.md` | Excel/YAML 変換ツール設計書 | A-3 の参考資料 | + +--- + +## 品質担保チェックリスト + +実装時にこのリストを使って漏れなく作業する。 + +### Phase 1: 新構成への移行確認 + +- [ ] 新旧マッピング表の全39項目（＋新規2項目）が新構成に存在するか確認 +- [ ] 既存 RST の toctree 参照が全て有効か（`make html` でエラーなし） +- [ ] 既存の内部リンク（`:ref:` ラベル）が移動後も有効か +- [ ] `05_UnitTestGuide/` と `06_TestFWGuide/` 間のクロス参照が壊れていないか + +### Phase 2: B-1 コンテンツ品質 + +- [ ] ntf-testdata-doc.md の全章（§1〜10）が B-1 に対応する節を持つか +- [ ] 全 example ファイル（6本）の記述例が B-1 に掲載されているか +- [ ] Excel 記述例と YAML 記述例が全節に揃っているか（片方だけになっていないか） +- [ ] testShots カラム仕様が処理方式ごとに揃っているか（examples-testshots.md の内容をカバー） + +### Phase 3: 用語・トンマナ + +- [ ] `ntf-doc-terms.md` の用語（データタイプ、グループ ID、testShots 等）が統一されているか +- [ ] 「Excelファイル」→「テストデータファイル」への置換が B-1 を除く全ページで完了しているか +- [ ] Excel 固有の用語（シート・セル・罫線）が単独で使われていないか（常に「Excel の場合」として限定されているか） + +### Phase 4: ビルド確認 + +- [ ] `make html` がエラーなし +- [ ] 生成された HTML で A 章・B 章が index から正しくリンクされているか +- [ ] B-1 の各節間のリンクが有効か + +--- + +## 未決事項・要確認 + +1. **A 章・B 章のディレクトリ構造をどうするか** + - 既存の `05_UnitTestGuide/` と `06_TestFWGuide/` を活かすか、新規ディレクトリを切るか + - 現行 URL を維持する場合（外部リンクへの影響）は既存パスに留置 + toctree 再構成が現実的 + +2. **B-1 を何ファイルに分割するか** + - B-1-1〜7 を7ファイルに分けるか、1ファイルに集約するか + - `ntf-testdata-doc.md` は約380行。RST 化すると例示（example）込みで相当量になるため分割推奨 + +3. **タブ切り替え（Excel/YAML の並列表示）の実装方法** + - Sphinx の `sphinx-tabs` 拡張が使えるか、または見出しで分ける方式か + +4. **`02_DbAccessTest.rst` の扱い** + - 「クラス構成（A-2-1）」と「API の使い方（B-2）」の境界をどう引くか + - 現状ではファイルを分割しないと移動できない From 185e28c6e1a267c8bf58fac53d92eac33c828f91 Mon Sep 17 00:00:00 2001 From: kiyotis Date: Fri, 26 Jun 2026 11:20:09 +0900 Subject: [PATCH 05/15] =?UTF-8?q?docs:=20=E6=96=B0=E6=A7=8B=E6=88=90?= =?UTF-8?q?=E6=A1=88=E3=81=AB=E8=A8=AD=E8=A8=88=E4=B8=8A=E3=81=AE=E5=88=A4?= =?UTF-8?q?=E6=96=AD=E3=82=92=E8=BF=BD=E8=A8=98=EF=BC=88=E3=82=BF=E3=83=96?= =?UTF-8?q?=E5=88=87=E3=82=8A=E6=9B=BF=E3=81=88=E3=83=BB=E3=83=95=E3=82=A1?= =?UTF-8?q?=E3=82=A4=E3=83=AB=E5=88=86=E5=89=B2=E3=83=BB=E3=83=87=E3=82=A3?= =?UTF-8?q?=E3=83=AC=E3=82=AF=E3=83=88=E3=83=AA=E6=A7=8B=E9=80=A0=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Sonnet 4.6 --- .rn/ntf-yaml-support/proposed-structure.md | 98 +++++++++++++++++++--- 1 file changed, 86 insertions(+), 12 deletions(-) diff --git a/.rn/ntf-yaml-support/proposed-structure.md b/.rn/ntf-yaml-support/proposed-structure.md index 57a1ac5c..c080bf59 100644 --- a/.rn/ntf-yaml-support/proposed-structure.md +++ b/.rn/ntf-yaml-support/proposed-structure.md @@ -247,19 +247,93 @@ --- -## 未決事項・要確認 +## 設計上の判断（全て提案） -1. **A 章・B 章のディレクトリ構造をどうするか** - - 既存の `05_UnitTestGuide/` と `06_TestFWGuide/` を活かすか、新規ディレクトリを切るか - - 現行 URL を維持する場合（外部リンクへの影響）は既存パスに留置 + toctree 再構成が現実的 +### 判断1: ディレクトリ構造 — 既存パスを活かす -2. **B-1 を何ファイルに分割するか** - - B-1-1〜7 を7ファイルに分けるか、1ファイルに集約するか - - `ntf-testdata-doc.md` は約380行。RST 化すると例示（example）込みで相当量になるため分割推奨 +**提案**: 既存の `05_UnitTestGuide/` と `06_TestFWGuide/` のディレクトリ構造は維持し、toctree の構成だけ組み替える。 -3. **タブ切り替え（Excel/YAML の並列表示）の実装方法** - - Sphinx の `sphinx-tabs` 拡張が使えるか、または見出しで分ける方式か +**理由**: 公開 URL が変わると外部からのリンクが全て切れる。コンテンツの整理が目的であり、ファイルパスの変更はリスクの割にメリットがない。ディレクトリ名の意味（`05_` `06_`）が薄れるが、利用者が見るのは HTML のタイトルであり、ファイルパスは開発者だけが気にする。 -4. **`02_DbAccessTest.rst` の扱い** - - 「クラス構成（A-2-1）」と「API の使い方（B-2）」の境界をどう引くか - - 現状ではファイルを分割しないと移動できない +**具体的な進め方**: +- B-1（テストデータの書き方）の新規ファイルは `06_TestFWGuide/` 直下に追加 +- A-5（マスタデータ復旧）などは現在地のまま、toctree の親だけ A 章側に付け替える +- 削除・移動は行わず「toctree の並べ替えと新規ファイル追加」だけで完結させる + +--- + +### 判断2: B-1 のファイル分割 — 節単位で7ファイルに分割する + +**提案**: B-1-1〜B-1-7 を独立した RST ファイルとして7本作成し、B-1 の index.rst がそれらを toctree でまとめる構成にする。 + +**理由**: `ntf-testdata-doc.md`（約380行）に example ファイル6本を加えると RST 化で 1,500行以上になる見込み。1ファイルにすると読み込みが重い・節内リンクが複雑になる・レビューしにくい。節単位で分割すれば「SETUP_TABLE の書き方だけ見たい」というユースケースに直接 URL が当たる。 + +**ファイル構成案**: + +``` +06_TestFWGuide/ + testdata/ + index.rst ← B-1 の入口、全節の toctree + overview.rst ← B-1-1 全体像とファイル構造 + data-blocks.rst ← B-1-2 データブロック種別一覧 + testshots.rst ← B-1-3 testShots・処理方式別カラム仕様 + table-data.rst ← B-1-4 テーブルデータ + file-data.rst ← B-1-5 ファイルデータ（固定長・可変長） + messaging.rst ← B-1-6 メッセージングデータ + values.rst ← B-1-7 値の書き方・特殊記法 +``` + +--- + +### 判断3: Excel/YAML の並列表示 — タブ切り替えは使わない、見出し分けを採用する + +**結論: タブ切り替えは現在のこのリポジトリでは使えない。** + +調査結果: +- `sphinx-tabs` 拡張は `requirements.txt` に含まれておらず、インストールされていない +- `conf.py` の `extensions` リストにも未登録 +- 既存ページで `.. tabs::` や `.. tab::` を使っているページは1つもない + +`sphinx-tabs` を新たに導入することは可能だが、Sphinx 1.8.6（現在使用中）との互換性確認・requirements.txt への追加・既存テーマ（sphinx-rtd-theme 0.2.4）との表示確認が必要になり、リスクが工数に見合わない。 + +**採用する代替案: 「Excelの場合」「YAMLの場合」の小見出し分け** + +各記述例を以下の形式で掲載する。縦に並べるため視覚的な切り替えはないが、コピーして使う用途では十分実用的であり、既存の RST 記法だけで実現できる。 + +```rst +SETUP_TABLE の記述例 +-------------------- + +**Excelの場合** + +.. list-table:: + :header-rows: 1 + :widths: 30 20 20 + + * - SETUP_TABLE=ORDER_HEADER + - ORDER_ID + - ITEM_COUNT + * - + - 10001 + - 10 + +**YAMLの場合** + +.. code-block:: yaml + + setup_tables: + - table: ORDER_HEADER + rows: + - ORDER_ID: "10001" + ITEM_COUNT: "10" +``` + +この形式はすでに `.. tip::` や `.. note::` を使っているページと同じスタイルで書けるため、トンマナが壊れない。 + +--- + +### 判断4: `02_DbAccessTest.rst` の扱い — ファイル分割は行わず、参照リンクで対応 + +**提案**: `02_DbAccessTest.rst` はファイル分割せず現在地に置いたままとする。アーキテクト向けセクション（クラス構成・仕組み）と開発者向けセクション（API の使い方）が混在している状態は、当該ファイルの冒頭に「テストデータの書き方は :ref:`testdata_reference` を参照」という誘導を追加することで解消する。 + +**理由**: ファイルを分割すると `make html` を通す・既存の相互参照を全部張り直す・URL が変わるという3つのコストが発生する。一方、利用者の実害（アーキテクト向けページに開発者向け内容がある）は誘導リンク1本で解消できる。完全な整理は将来の大規模リファクタリング時の課題として先送りする。 From c0c715b693a434985dbb197c49392a21610a4b99 Mon Sep 17 00:00:00 2001 From: kiyotis Date: Fri, 26 Jun 2026 11:35:21 +0900 Subject: [PATCH 06/15] =?UTF-8?q?docs:=20=E6=96=B0=E6=A7=8B=E6=88=90?= =?UTF-8?q?=E6=A1=88=E3=81=AE=E3=83=9A=E3=83=BC=E3=82=B8=E3=82=BF=E3=82=A4?= =?UTF-8?q?=E3=83=88=E3=83=AB=E3=82=92FW=E5=81=B4=E3=83=91=E3=82=BF?= =?UTF-8?q?=E3=83=BC=E3=83=B3=E3=81=AB=E7=B5=B1=E4=B8=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Sonnet 4.6 --- .rn/ntf-yaml-support/proposed-structure.md | 62 ++++++++++++++-------- 1 file changed, 39 insertions(+), 23 deletions(-) diff --git a/.rn/ntf-yaml-support/proposed-structure.md b/.rn/ntf-yaml-support/proposed-structure.md index c080bf59..0c98a749 100644 --- a/.rn/ntf-yaml-support/proposed-structure.md +++ b/.rn/ntf-yaml-support/proposed-structure.md @@ -24,25 +24,30 @@ ## 新構成ツリー +タイトルはアプリケーションフレームワーク側（「ウェブアプリケーション編」「Nablarchバッチアプリケーション」等）と同じパターンに揃える。読者の誘導はタイトルではなく index.rst の本文で行う。 + ``` テスティングフレームワーク（index.rst） -│ ※「アーキテクトは A 章へ、開発者は B 章へ」を明示 +│ ※本文で「FW の概要・設定はXXを、テスト実装はXXを参照」と誘導 │ -├── A. 導入・設定ガイド（アーキテクト向け） -│ ├── A-1. 自動テストフレームワークの概要 +├── Nablarchテスティングフレームワークとは ★タイトル確定★ +│ │ ※アーキテクト向け。FW の仕組み・設定・導入 +│ │ ※アプリケーションFW側の architecture + application_design に相当 +│ │ +│ ├── A-1. 自動テストフレームワーク │ │ FW の特徴・制約・クラス構成・処理フロー │ │ ※現: 01_Abstract.rst の前半（特徴・FW構成表） │ │ -│ ├── A-2. テストクラス基盤の設定 -│ │ ├── A-2-1. DB アクセステスト用クラス（DbAccessTestSupport） +│ ├── A-2. テストクラスの設定 +│ │ ├── A-2-1. データベースを使用するクラスのテスト（DbAccessTestSupport） │ │ ├── A-2-2. リクエスト単体テスト用クラス（Web/REST/バッチ） │ │ └── A-2-3. リクエスト単体テスト用クラス（メッセージング各種） │ │ ※現: 06_TestFWGuide/02_*.rst の「クラス構成・設定」部分 │ │ -│ ├── A-3. テストデータ形式の選択（Excel / YAML）★新規★ -│ │ どちらを使うか・プロジェクト内での統一方針・移行手順 +│ ├── A-3. テストデータの形式 ★新規★ +│ │ Excel / YAML の違い・どちらを使うか・プロジェクト統一方針 │ │ -│ ├── A-4. JUnit 5 拡張の導入 +│ ├── A-4. JUnit 5用拡張機能 │ │ ※現: JUnit5_Extension.rst そのまま │ │ │ ├── A-5. マスタデータ復旧機能 @@ -51,23 +56,27 @@ │ └── A-6. テストツール │ ※現: 08_TestTools/ そのまま │ -└── B. テスト実装ガイド（開発者向け） - ├── B-1. テストデータの書き方（リファレンス）★最大の変更点★ - │ ├── B-1-1. 全体像とファイル構造（Excel / YAML） - │ ├── B-1-2. データブロック種別一覧（14種） - │ ├── B-1-3. テストケース定義（testShots）と処理方式別カラム仕様 - │ ├── B-1-4. テーブルデータ（SETUP_TABLE / EXPECTED_TABLE 等） - │ ├── B-1-5. ファイルデータ（固定長・可変長） - │ ├── B-1-6. メッセージングデータ - │ └── B-1-7. 値の書き方・特殊記法 +└── テストの実装方法 ★タイトル確定★ + │ ※開発者向け。テストコードの書き方・テストデータの作り方 + │ ※アプリケーションFW側の feature_details に相当 + │ ※現行「単体テスト実施方法」から「テストの実装方法」に変更 + │ + ├── B-1. テストデータの記述方法 ★最大の変更点★ + │ ├── B-1-1. テストデータの構造（Excel / YAML） + │ ├── B-1-2. データブロックの種別（14種） + │ ├── B-1-3. テストケース定義（testShots） + │ ├── B-1-4. テーブルデータの記述方法 + │ ├── B-1-5. ファイルデータの記述方法 + │ ├── B-1-6. メッセージングデータの記述方法 + │ └── B-1-7. 値の記述方法 │ ※現在10本以上に散在 → ここに集約 │ ※主素材: input/ntf-testdata-doc.md + example ファイル群 │ - ├── B-2. クラス単体テスト + ├── B-2. クラス単体テストの実装方法 │ ※現: 05_UnitTestGuide/01_ClassUnitTest/ ほぼそのまま - │ ※「テストデータの書き方」→ B-1 への参照に置換 + │ ※「テストデータの書き方」節 → B-1 参照に置換 │ - ├── B-3. リクエスト単体テスト + ├── B-3. リクエスト単体テストの実装方法 │ ├── ウェブアプリケーション │ ├── RESTful ウェブサービス │ ├── バッチ処理 @@ -77,15 +86,22 @@ │ ※現: 05_UnitTestGuide/02_RequestUnitTest/ │ ※各ページの「テストデータの書き方」節 → B-1 参照に置換 │ - ├── B-4. 業務単体テスト + ├── B-4. 取引単体テストの実装方法 │ ※現: 05_UnitTestGuide/03_DealUnitTest/ ほぼそのまま - │ ※「テストデータの書き方」→ B-1 への参照に置換 + │ ※「テストデータの書き方」節 → B-1 参照に置換 │ - └── B-5. Tips（目的別 API 使用方法） + └── B-5. 目的別API使用方法 ※現: 06_TestFWGuide/03_Tips.rst → 開発者向けに移動 ※Excel 固有表現をテストデータファイル表現に修正 ``` +### タイトル確定の根拠 + +| タイトル | 根拠 | +|---|---| +| `Nablarchテスティングフレームワークとは` | 「Nablarchバッチアプリケーション」「ウェブアプリケーション編」と同じく **「何のFWか」を先頭に置く** パターン。「〜とは」でFW概要ページであることを明示 | +| `テストの実装方法` | 内容が「テストコードを書く・テストデータを作る」という**実装行為**。「実施」はテストを走らせるQAプロセスのニュアンスで内容とズレがある。現行の「単体テスト実施方法」を正す機会 | + --- ## 設計の核心：B-1「テストデータの書き方」の独立 From f2c593142661259b30e3efe885d1daafa7bd0f49 Mon Sep 17 00:00:00 2001 From: kiyotis Date: Fri, 26 Jun 2026 11:39:52 +0900 Subject: [PATCH 07/15] =?UTF-8?q?docs:=20=E3=80=8C=E8=87=AA=E5=8B=95?= =?UTF-8?q?=E3=83=86=E3=82=B9=E3=83=88=E3=83=95=E3=83=AC=E3=83=BC=E3=83=A0?= =?UTF-8?q?=E3=83=AF=E3=83=BC=E3=82=AF=E3=80=8D=E2=86=92=E3=80=8C=E3=83=86?= =?UTF-8?q?=E3=82=B9=E3=83=86=E3=82=A3=E3=83=B3=E3=82=B0=E3=83=95=E3=83=AC?= =?UTF-8?q?=E3=83=BC=E3=83=A0=E3=83=AF=E3=83=BC=E3=82=AF=E6=A6=82=E8=A6=81?= =?UTF-8?q?=E3=80=8D=E3=80=81input=E8=B3=87=E6=96=99=E3=83=9E=E3=83=83?= =?UTF-8?q?=E3=83=94=E3=83=B3=E3=82=B0=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Sonnet 4.6 --- .rn/ntf-yaml-support/proposed-structure.md | 29 +++++++++++----------- 1 file changed, 14 insertions(+), 15 deletions(-) diff --git a/.rn/ntf-yaml-support/proposed-structure.md b/.rn/ntf-yaml-support/proposed-structure.md index 0c98a749..500f6239 100644 --- a/.rn/ntf-yaml-support/proposed-structure.md +++ b/.rn/ntf-yaml-support/proposed-structure.md @@ -34,7 +34,7 @@ │ │ ※アーキテクト向け。FW の仕組み・設定・導入 │ │ ※アプリケーションFW側の architecture + application_design に相当 │ │ -│ ├── A-1. 自動テストフレームワーク +│ ├── A-1. テスティングフレームワーク概要 │ │ FW の特徴・制約・クラス構成・処理フロー │ │ ※現: 01_Abstract.rst の前半（特徴・FW構成表） │ │ @@ -100,6 +100,7 @@ | タイトル | 根拠 | |---|---| | `Nablarchテスティングフレームワークとは` | 「Nablarchバッチアプリケーション」「ウェブアプリケーション編」と同じく **「何のFWか」を先頭に置く** パターン。「〜とは」でFW概要ページであることを明示 | +| `テスティングフレームワーク概要` | FW側の配下ページは「アーキテクチャ概要」のように **FW名を繰り返さない**。「自動」は「テスティングフレームワーク」から自明なため不要 | | `テストの実装方法` | 内容が「テストコードを書く・テストデータを作る」という**実装行為**。「実施」はテストを走らせるQAプロセスのニュアンスで内容とズレがある。現行の「単体テスト実施方法」を正す機会 | --- @@ -214,20 +215,18 @@ ## input/ 資料と新構成の対応 -入力資料は B-1 の主素材として使う。各ファイルと対応節を示す。 - -| input/ ファイル | 内容 | 主に使う節 | -|---|---|---| -| `ntf-testdata-doc.md` | テストデータ仕様リファレンス全体（Excel/YAML 両対応） | B-1 全体の主素材 | -| `ntf-testdata-doc-examples-overview.md` | 全体像の記述例（テストケース・セットアップ・検証が共存するファイルの例） | B-1-1 に掲載 | -| `ntf-testdata-doc-examples-testshots.md` | 処理方式別 testShots カラム仕様と Excel/YAML 記述例 | B-1-3 に掲載 | -| `ntf-testdata-doc-examples-table.md` | テーブルデータ（SETUP_TABLE/EXPECTED_TABLE 等）の Excel/YAML 記述例 | B-1-4 に掲載 | -| `ntf-testdata-doc-examples-file.md` | ファイルデータ（固定長・可変長）の Excel/YAML 記述例 | B-1-5 に掲載 | -| `ntf-testdata-doc-examples-messaging.md` | メッセージングデータの Excel/YAML 記述例 | B-1-6 に掲載 | -| `ntf-testdata-doc-examples-special.md` | 特殊値・ディレクティブ・ヘッダ/コメント の Excel/YAML 記述例 | B-1-7 に掲載 | -| `ntf-testdata-loading.md` | FW の内部読み込み機構（4段階変換・クラス設計） | A-1 の補足（内部仕組みの詳細）| -| `ntf-doc-terms.md` | 用語リファレンス（既存解説書からの用語引き表） | 各ページの用語統一に使用 | -| `testdata-converter-design.md` | Excel/YAML 変換ツール設計書 | A-3 の参考資料 | +| input/ ファイル | 内容 | 使う/使わない | 用途 | +|---|---|---|---| +| `ntf-testdata-doc.md` | テストデータ仕様リファレンス全体（Excel/YAML 両対応） | **使う** | B-1 全体の主素材 | +| `ntf-testdata-doc-examples-overview.md` | 全体像・groupId の記述例 | **使う** | B-1-1 に掲載 | +| `ntf-testdata-doc-examples-testshots.md` | 処理方式別 testShots カラム仕様と記述例 | **使う** | B-1-3 に掲載 | +| `ntf-testdata-doc-examples-table.md` | テーブルデータの Excel/YAML 記述例 | **使う** | B-1-4 に掲載 | +| `ntf-testdata-doc-examples-file.md` | ファイルデータの Excel/YAML 記述例 | **使う** | B-1-5 に掲載 | +| `ntf-testdata-doc-examples-messaging.md` | メッセージングデータの Excel/YAML 記述例 | **使う** | B-1-6 に掲載 | +| `ntf-testdata-doc-examples-special.md` | 特殊値・ディレクティブ・ヘッダ/コメント の Excel/YAML 記述例 | **使う** | B-1-7 に掲載 | +| `ntf-doc-terms.md` | 用語リファレンス（既存解説書からの用語引き表） | **使う（間接）** | ページには掲載しない。執筆時の用語統一チェックに使用 | +| `ntf-testdata-loading.md` | FW 内部の読み込み機構（4段階変換・クラス設計） | **使わない** | 利用者向けコンテンツの素材にならない内部設計書 | +| `testdata-converter-design.md` | Excel/YAML 変換ツール設計書 | **使わない** | 利用者向けコンテンツの素材にならない内部設計書 | --- From 27d1c6cad6dbc5d30688ec95f2ead8b5a3b69e9c Mon Sep 17 00:00:00 2001 From: kiyotis Date: Fri, 26 Jun 2026 11:45:06 +0900 Subject: [PATCH 08/15] =?UTF-8?q?docs:=20=E3=83=86=E3=82=B9=E3=83=88?= =?UTF-8?q?=E3=83=87=E3=83=BC=E3=82=BF=E9=96=A2=E9=80=A3=E3=82=92=E3=80=8C?= =?UTF-8?q?=E8=A8=98=E8=BF=B0=E6=96=B9=E6=B3=95=E3=80=8D=E3=80=8C=E8=A8=98?= =?UTF-8?q?=E8=BF=B0=E4=BE=8B=E3=80=8D=E3=81=AE2=E3=83=9A=E3=83=BC?= =?UTF-8?q?=E3=82=B8=E6=A7=8B=E6=88=90=E3=81=AB=E5=A4=89=E6=9B=B4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Sonnet 4.6 --- .rn/ntf-yaml-support/proposed-structure.md | 86 ++++++++++++---------- 1 file changed, 46 insertions(+), 40 deletions(-) diff --git a/.rn/ntf-yaml-support/proposed-structure.md b/.rn/ntf-yaml-support/proposed-structure.md index 500f6239..02703bd7 100644 --- a/.rn/ntf-yaml-support/proposed-structure.md +++ b/.rn/ntf-yaml-support/proposed-structure.md @@ -61,22 +61,27 @@ │ ※アプリケーションFW側の feature_details に相当 │ ※現行「単体テスト実施方法」から「テストの実装方法」に変更 │ - ├── B-1. テストデータの記述方法 ★最大の変更点★ - │ ├── B-1-1. テストデータの構造（Excel / YAML） - │ ├── B-1-2. データブロックの種別（14種） - │ ├── B-1-3. テストケース定義（testShots） - │ ├── B-1-4. テーブルデータの記述方法 - │ ├── B-1-5. ファイルデータの記述方法 - │ ├── B-1-6. メッセージングデータの記述方法 - │ └── B-1-7. 値の記述方法 - │ ※現在10本以上に散在 → ここに集約 - │ ※主素材: input/ntf-testdata-doc.md + example ファイル群 + ├── B-1. テストデータの記述方法 ★最大の変更点・1ページ★ + │ テストデータの構造・データブロック種別・testShots・ + │ テーブルデータ・ファイルデータ・メッセージング・値の記述方法 + │ ※現在10本以上に散在 → 1ページに集約。長くてもスクロールで通読できる + │ ※主素材: input/ntf-testdata-doc.md 全章（§1〜10） │ - ├── B-2. クラス単体テストの実装方法 + ├── B-2. テストデータの記述例 ★新規・1ページ★ + │ Excel / YAML 対比例を一覧。仕様を調べるなら B-1、写して使うなら B-2 + │ ※主素材: input/ntf-testdata-doc-examples-*.md 6本をまとめる + │ 　- 全体像・groupId の例 + │ 　- testShots（処理方式別カラム仕様）の例 + │ 　- テーブルデータの例 + │ 　- ファイルデータの例 + │ 　- メッセージングデータの例 + │ 　- 特殊値・ディレクティブ・ヘッダ/コメント の例 + │ + ├── B-3. クラス単体テストの実装方法 │ ※現: 05_UnitTestGuide/01_ClassUnitTest/ ほぼそのまま │ ※「テストデータの書き方」節 → B-1 参照に置換 │ - ├── B-3. リクエスト単体テストの実装方法 + ├── B-4. リクエスト単体テストの実装方法 │ ├── ウェブアプリケーション │ ├── RESTful ウェブサービス │ ├── バッチ処理 @@ -86,11 +91,11 @@ │ ※現: 05_UnitTestGuide/02_RequestUnitTest/ │ ※各ページの「テストデータの書き方」節 → B-1 参照に置換 │ - ├── B-4. 取引単体テストの実装方法 + ├── B-5. 取引単体テストの実装方法 │ ※現: 05_UnitTestGuide/03_DealUnitTest/ ほぼそのまま │ ※「テストデータの書き方」節 → B-1 参照に置換 │ - └── B-5. 目的別API使用方法 + └── B-6. 目的別API使用方法 ※現: 06_TestFWGuide/03_Tips.rst → 開発者向けに移動 ※Excel 固有表現をテストデータファイル表現に修正 ``` @@ -170,7 +175,7 @@ | # | 既存ファイル | 内容カテゴリ | 新構成の移動先 | 処理方針 | |---|---|---|---|---| | 1 | `06_TestFWGuide/01_Abstract.rst` § 特徴・構成表 | FW の仕組み | **A-1** | 抜粋・移動 | -| 2 | `06_TestFWGuide/01_Abstract.rst` § 命名規約・データタイプ一覧・特殊記法・注意事項 | テストデータ仕様 | **B-1**（Excel+YAML対応に拡充） | 集約・拡充 | +| 2 | `06_TestFWGuide/01_Abstract.rst` § 命名規約・データタイプ一覧・特殊記法・注意事項 | テストデータ仕様 | **B-1**（Excel+YAML対応に拡充）、記述例は **B-2** | 集約・拡充 | | 3 | `06_TestFWGuide/02_DbAccessTest.rst` § クラス構成・仕組み説明 | テストクラス基盤 | **A-2-1** | 抜粋・移動 | | 4 | `06_TestFWGuide/02_DbAccessTest.rst` § API 使い方・記述例 | テスト実装方法 | **B-2** に残置 or 参照化 | 検討 | | 5 | `06_TestFWGuide/02_RequestUnitTest.rst` | リクエスト単体テスト基盤 | **A-2-2** | 移動 | @@ -182,34 +187,35 @@ | 11 | `06_TestFWGuide/03_Tips.rst` | 目的別 API / Tips | **B-5** | 開発者向けに移動、Excel→テストデータファイル表現に修正 | | 12 | `06_TestFWGuide/04_MasterDataRestore.rst` | マスタデータ復旧 | **A-5** | そのまま移動 | | 13 | `06_TestFWGuide/JUnit5_Extension.rst` | JUnit 5 拡張 | **A-4** | そのまま移動 | -| 14 | `05_UnitTestGuide/01_ClassUnitTest/index.rst` | クラス単体テスト概要 | **B-2** | そのまま | -| 15 | `05_UnitTestGuide/01_ClassUnitTest/01_entityUnitTest/01_*.rst` | エンティティ単体テスト（Bean Validation） | **B-2** | テストデータの書き方 → B-1 参照に | -| 16 | `05_UnitTestGuide/01_ClassUnitTest/01_entityUnitTest/02_*.rst` | エンティティ単体テスト（Nablarch Validation） | **B-2** | テストデータの書き方 → B-1 参照に | -| 17 | `05_UnitTestGuide/01_ClassUnitTest/02_componentUnitTest.rst` | コンポーネント単体テスト | **B-2** | テストデータの書き方 → B-1 参照に、命名規約 → B-1-1 参照に | -| 18 | `05_UnitTestGuide/02_RequestUnitTest/index.rst` | リクエスト単体テスト概要 | **B-3** | そのまま | -| 19 | `05_UnitTestGuide/02_RequestUnitTest/batch.rst` | バッチリクエスト単体テスト実装手順 | **B-3** | 「テストデータの書き方」節 → B-1-3〜5 参照に | -| 20 | `05_UnitTestGuide/02_RequestUnitTest/rest.rst` | REST リクエスト単体テスト実装手順 | **B-3** | 「テストデータの書き方」節 → B-1 参照に | -| 21 | `05_UnitTestGuide/02_RequestUnitTest/real.rst` | 同期応答受信 実装手順 | **B-3** | 「テストデータの書き方」節 → B-1-6 参照に | -| 22 | `05_UnitTestGuide/02_RequestUnitTest/http_real.rst` | HTTP 同期応答受信 実装手順 | **B-3** | 「テストデータの書き方」節 → B-1-6 参照に | -| 23 | `05_UnitTestGuide/02_RequestUnitTest/send_sync.rst` | 同期応答送信 実装手順 | **B-3** | 「テストデータの書き方」節 → B-1-6 参照に | -| 24 | `05_UnitTestGuide/02_RequestUnitTest/delayed_send.rst` | 応答不要送信 実装手順 | **B-3** | 参照先へ委譲のため軽微 | -| 25 | `05_UnitTestGuide/02_RequestUnitTest/delayed_receive.rst` | 応答不要受信 実装手順 | **B-3** | 参照先へ委譲のため軽微 | -| 26 | `05_UnitTestGuide/02_RequestUnitTest/http_send_sync.rst` | HTTP 同期応答送信 実装手順 | **B-3** | 「テストデータの書き方」節 → B-1 参照に | -| 27 | `05_UnitTestGuide/02_RequestUnitTest/mail.rst` | メール送信テスト 実装手順 | **B-3** | 軽微修正 | -| 28 | `05_UnitTestGuide/02_RequestUnitTest/fileupload.rst` | ファイルアップロードテスト 実装手順 | **B-3** | 軽微修正 | -| 29 | `05_UnitTestGuide/02_RequestUnitTest/double_transmission.rst` | 2重送信防止テスト 実装手順 | **B-3** | 変更なし | -| 30 | `05_UnitTestGuide/03_DealUnitTest/batch.rst` | バッチ業務単体テスト 実装手順 | **B-4** | 「テストデータの書き方」節 → B-1 参照に | -| 31 | `05_UnitTestGuide/03_DealUnitTest/send_sync.rst` | 同期応答送信 業務単体テスト | **B-4** | 「テストデータの書き方」節 → B-1 参照に | -| 32 | `05_UnitTestGuide/03_DealUnitTest/http_send_sync.rst` | HTTP 同期応答送信 業務単体テスト | **B-4** | 「テストデータの書き方」節 → B-1 参照に | -| 33 | `05_UnitTestGuide/03_DealUnitTest/real.rst` | 同期応答受信 業務単体テスト | **B-4** | そのまま | -| 34 | `05_UnitTestGuide/03_DealUnitTest/rest.rst` | REST 業務単体テスト | **B-4** | そのまま | -| 35 | `05_UnitTestGuide/03_DealUnitTest/delayed_send.rst` | 応答不要送信 業務単体テスト | **B-4** | そのまま（参照のみ） | -| 36 | `05_UnitTestGuide/03_DealUnitTest/delayed_receive.rst` | 応答不要受信 業務単体テスト | **B-4** | そのまま（参照のみ） | +| 14 | `05_UnitTestGuide/01_ClassUnitTest/index.rst` | クラス単体テスト概要 | **B-3** | そのまま | +| 15 | `05_UnitTestGuide/01_ClassUnitTest/01_entityUnitTest/01_*.rst` | エンティティ単体テスト（Bean Validation） | **B-3** | テストデータの書き方 → B-1 参照に | +| 16 | `05_UnitTestGuide/01_ClassUnitTest/01_entityUnitTest/02_*.rst` | エンティティ単体テスト（Nablarch Validation） | **B-3** | テストデータの書き方 → B-1 参照に | +| 17 | `05_UnitTestGuide/01_ClassUnitTest/02_componentUnitTest.rst` | コンポーネント単体テスト | **B-3** | テストデータの書き方 → B-1 参照に、命名規約 → B-1 参照に | +| 18 | `05_UnitTestGuide/02_RequestUnitTest/index.rst` | リクエスト単体テスト概要 | **B-4** | そのまま | +| 19 | `05_UnitTestGuide/02_RequestUnitTest/batch.rst` | バッチリクエスト単体テスト実装手順 | **B-4** | 「テストデータの書き方」節 → B-1 参照に | +| 20 | `05_UnitTestGuide/02_RequestUnitTest/rest.rst` | REST リクエスト単体テスト実装手順 | **B-4** | 「テストデータの書き方」節 → B-1 参照に | +| 21 | `05_UnitTestGuide/02_RequestUnitTest/real.rst` | 同期応答受信 実装手順 | **B-4** | 「テストデータの書き方」節 → B-1 参照に | +| 22 | `05_UnitTestGuide/02_RequestUnitTest/http_real.rst` | HTTP 同期応答受信 実装手順 | **B-4** | 「テストデータの書き方」節 → B-1 参照に | +| 23 | `05_UnitTestGuide/02_RequestUnitTest/send_sync.rst` | 同期応答送信 実装手順 | **B-4** | 「テストデータの書き方」節 → B-1 参照に | +| 24 | `05_UnitTestGuide/02_RequestUnitTest/delayed_send.rst` | 応答不要送信 実装手順 | **B-4** | 参照先へ委譲のため軽微 | +| 25 | `05_UnitTestGuide/02_RequestUnitTest/delayed_receive.rst` | 応答不要受信 実装手順 | **B-4** | 参照先へ委譲のため軽微 | +| 26 | `05_UnitTestGuide/02_RequestUnitTest/http_send_sync.rst` | HTTP 同期応答送信 実装手順 | **B-4** | 「テストデータの書き方」節 → B-1 参照に | +| 27 | `05_UnitTestGuide/02_RequestUnitTest/mail.rst` | メール送信テスト 実装手順 | **B-4** | 軽微修正 | +| 28 | `05_UnitTestGuide/02_RequestUnitTest/fileupload.rst` | ファイルアップロードテスト 実装手順 | **B-4** | 軽微修正 | +| 29 | `05_UnitTestGuide/02_RequestUnitTest/double_transmission.rst` | 2重送信防止テスト 実装手順 | **B-4** | 変更なし | +| 30 | `05_UnitTestGuide/03_DealUnitTest/batch.rst` | バッチ業務単体テスト 実装手順 | **B-5** | 「テストデータの書き方」節 → B-1 参照に | +| 31 | `05_UnitTestGuide/03_DealUnitTest/send_sync.rst` | 同期応答送信 業務単体テスト | **B-5** | 「テストデータの書き方」節 → B-1 参照に | +| 32 | `05_UnitTestGuide/03_DealUnitTest/http_send_sync.rst` | HTTP 同期応答送信 業務単体テスト | **B-5** | 「テストデータの書き方」節 → B-1 参照に | +| 33 | `05_UnitTestGuide/03_DealUnitTest/real.rst` | 同期応答受信 業務単体テスト | **B-5** | そのまま | +| 34 | `05_UnitTestGuide/03_DealUnitTest/rest.rst` | REST 業務単体テスト | **B-5** | そのまま | +| 35 | `05_UnitTestGuide/03_DealUnitTest/delayed_send.rst` | 応答不要送信 業務単体テスト | **B-5** | そのまま（参照のみ） | +| 36 | `05_UnitTestGuide/03_DealUnitTest/delayed_receive.rst` | 応答不要受信 業務単体テスト | **B-5** | そのまま（参照のみ） | | 37 | `08_TestTools/01_HttpDumpTool/` | HTTP dump ツール | **A-6** | そのまま | | 38 | `08_TestTools/02_MasterDataSetup/` | マスタデータセットアップツール | **A-6** | そのまま | | 39 | `08_TestTools/03_HtmlCheckTool/` | HTML チェックツール | **A-6** | そのまま | -| ★ | *(新規)* | テストデータ形式の選択 | **A-3** | 新規作成 | -| ★ | *(新規、ntf-testdata-doc.md 主素材)* | テストデータの書き方リファレンス | **B-1** | ntf-testdata-doc.md + example 群を RST 化 | +| ★ | *(新規)* | テストデータの形式（Excel / YAML） | **A-3** | 新規作成 | +| ★ | *(新規、ntf-testdata-doc.md 主素材)* | テストデータの記述方法（仕様リファレンス） | **B-1** | ntf-testdata-doc.md を RST 化、1ページ | +| ★ | *(新規、examples 6本 主素材)* | テストデータの記述例（Excel/YAML 対比） | **B-2** | examples 6本をまとめて RST 化、1ページ | --- From cc4effbf382e5ced15d383e75304a20c552f9819 Mon Sep 17 00:00:00 2001 From: kiyotis Date: Fri, 26 Jun 2026 11:46:35 +0900 Subject: [PATCH 09/15] =?UTF-8?q?chore:=20suspend=20session=20=E2=80=94=20?= =?UTF-8?q?ntf-yaml-support?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Sonnet 4.6 --- .rn/ntf-yaml-support/steering.md | 25 +++++++++++++++++++++---- 1 file changed, 21 insertions(+), 4 deletions(-) diff --git a/.rn/ntf-yaml-support/steering.md b/.rn/ntf-yaml-support/steering.md index fd692e40..b23f5b0b 100644 --- a/.rn/ntf-yaml-support/steering.md +++ b/.rn/ntf-yaml-support/steering.md @@ -117,8 +117,25 @@ NTF（Nablarchテストフレームワーク）解説書（`ja/development_tools # State -- **Status**: not suspended +- **Status**: paused - **Date**: 2026-06-26 -- **Last completed**: #1 RSTビルド確認 -- **Next**: #2 全体構成の認識合わせ -- **Notes**: ビルド環境は `/tmp/sphinx_env`（Sphinx 1.8.6）。`make html SPHINXBUILD=/tmp/sphinx_env/bin/sphinx-build` で実行。後続タスクも同 venv を再利用すること。 +- **Last completed**: #2 全体構成の認識合わせ（QA PASS） +- **Next**: #3 影響範囲確認とタスク更新 +- **Notes**: | + ユーザーと新構成について議論し、proposed-structure.md（`.rn/ntf-yaml-support/proposed-structure.md`）として + ゼロベース設計案を作成・合意済み。ステアリングのタスク #3〜#5 は proposed-structure.md の内容をもとに + 組み直す必要がある。 + + 【合意済みの設計内容】 + - トップ2ページ: 「Nablarchテスティングフレームワークとは」「テストの実装方法」 + - テストデータは2ページ構成: B-1「テストデータの記述方法」（仕様1ページ）、B-2「テストデータの記述例」（例1ページ） + - Excel/YAML 並列表示はタブ切り替えなし（sphinx-tabs 未導入）、「Excelの場合」「YAMLの場合」小見出し分け + - ディレクトリ構造は既存パスを維持し toctree だけ組み替え + - input/ のうち ntf-testdata-loading.md と testdata-converter-design.md は使わない + + 【次のアクション】 + ステアリングの #3（影響範囲確認とタスク更新）を実行する前に、タスク #3〜#5 の内容を + proposed-structure.md の合意内容に合わせて書き直すこと。 + 具体的には「全体構成見直し」「YAML対応」という2軸を分解したタスクを追加する。 + + ビルド環境: `/tmp/sphinx_env`（Sphinx 1.8.6）、`make html SPHINXBUILD=/tmp/sphinx_env/bin/sphinx-build` From d08c2194c02312a1622f2e15b55111d09a1fcbad Mon Sep 17 00:00:00 2001 From: kiyotis Date: Fri, 26 Jun 2026 11:55:37 +0900 Subject: [PATCH 10/15] =?UTF-8?q?docs:=20complete=20task=20#2=20=E2=80=94?= =?UTF-8?q?=20=E5=85=A8=E4=BD=93=E6=A7=8B=E6=88=90=E3=81=AE=E8=AA=8D?= =?UTF-8?q?=E8=AD=98=E5=90=88=E3=82=8F=E3=81=9B=E3=80=81=E3=82=BF=E3=82=B9?= =?UTF-8?q?=E3=82=AF=20#3=E3=80=9C#6=20=E3=82=92=E6=96=B0=E6=A7=8B?= =?UTF-8?q?=E6=88=90=E3=81=AB=E5=90=88=E3=82=8F=E3=81=9B=E3=81=A6=E6=9B=B4?= =?UTF-8?q?=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Sonnet 4.6 --- .rn/ntf-yaml-support/steering.md | 109 ++++++++++++++++++++----------- 1 file changed, 71 insertions(+), 38 deletions(-) diff --git a/.rn/ntf-yaml-support/steering.md b/.rn/ntf-yaml-support/steering.md index b23f5b0b..61040491 100644 --- a/.rn/ntf-yaml-support/steering.md +++ b/.rn/ntf-yaml-support/steering.md @@ -63,79 +63,112 @@ NTF（Nablarchテストフレームワーク）解説書（`ja/development_tools - [x] `05_UnitTestGuide/` 配下の影響ありそうなRSTを確認する - [x] 入力資料（`input/ntf-testdata-doc.md`・`ntf-doc-terms.md`）をもとに YAML 対応で更新が必要な箇所を洗い出す - [x] 全体構成サマリーを `checks/task2.md` に記録しユーザーに提示する -- [ ] user review（構成認識の合意） +- [x] user review（構成認識の合意） **Completion criteria**: - `06_TestFWGuide/` 配下の全ファイルの役割と、YAML対応で修正が必要な箇所の一覧が `checks/task2.md` に記録されている - ユーザーが全体構成を確認・承認している（Decisions に記録） -### #3: 影響範囲確認とタスク更新 +### #3: 文書表現・トンマナ確認とCLAUDE.md作業ルール記載 -**Purpose**: 全体構成の合意をもとに、修正が必要なファイルと修正内容を具体化し、タスク一覧を更新する。 +**Purpose**: 既存解説書の文書表現・トンマナ（用語の統一・文体・表記ルール）を確認し、解説書修正作業のルールをCLAUDE.mdに記載する。 **Prerequisites**: #2 **Steps**: -- [ ] 修正対象ファイルをリストアップし、各ファイルで必要な変更内容を `checks/task3.md` に記録する -- [ ] 解説書修正の各タスク（#5以降）をステアリングに追記する +- [ ] 既存解説書（`06_TestFWGuide/01_Abstract.rst` 等）と入力資料（`ntf-doc-terms.md`）から用語・表記ルールを抽出する +- [ ] 文体（です・ます調 vs だ・である調）・用語統一ルールをまとめる +- [ ] `CLAUDE.md` に作業ルールを記載する - [ ] self-check (OK/NG per completion criterion, record in checks/task3.md) +- [ ] QA expert review (subagent) - [ ] user review **Completion criteria**: -- 修正対象ファイルと変更内容の一覧が `checks/task3.md` に記録されている -- ステアリングに解説書修正タスクが追記されている +- `CLAUDE.md` にNTF解説書修正の作業ルール（文書表現・用語・トンマナ）が記載されている -### #4: 文書表現・トンマナ確認とCLAUDE.md作業ルール記載 +### #4: toctree 構成変更（A章・B章の骨格作成） -**Purpose**: 既存解説書の文書表現・トンマナ（用語の統一・文体・表記ルール）を確認し、解説書修正作業のルールをCLAUDE.mdに記載する。 +**Purpose**: proposed-structure.md の新構成ツリーに合わせて、既存の toctree を組み替え、A章・B章の骨格（index.rst）を作成する。ファイル移動は行わず toctree の付け替えと新規 index.rst の追加のみで完結させる。 **Prerequisites**: #3 **Steps**: -- [ ] 既存解説書（`06_TestFWGuide/01_Abstract.rst` 等）と入力資料（`ntf-doc-terms.md`）から用語・表記ルールを抽出する -- [ ] 文体（です・ます調 vs だ・である調）・用語統一ルールをまとめる -- [ ] `CLAUDE.md` に作業ルールを記載する +- [ ] 新構成ツリーに合わせた index.rst の変更・新規ファイルを確認・作成する + - `06_TestFWGuide/index.rst`（または親ページ）の toctree を A章・B章構成に組み替える + - `06_TestFWGuide/testdata/index.rst` を新規作成（B-1 の入口） +- [ ] `make html` でビルドエラーがないことを確認する - [ ] self-check (OK/NG per completion criterion, record in checks/task4.md) - [ ] QA expert review (subagent) - [ ] user review **Completion criteria**: -- `CLAUDE.md` にNTF解説書修正の作業ルール（文書表現・用語・トンマナ）が記載されている +- A章（`Nablarchテスティングフレームワークとは`）・B章（`テストの実装方法`）が toctree に現れている +- `make html` がエラーなく完了する +- 既存ファイルへの toctree 参照が壊れていない + +### #5: B-1「テストデータの記述方法」新規作成 -### #5以降: 解説書修正（タスク#3完了後に追記） +**Purpose**: `ntf-testdata-doc.md` を主素材に、テストデータ仕様リファレンス（B-1-1〜B-1-7）を RST ファイルとして新規作成する。Excel/YAML 並列記述は「Excelの場合」「YAMLの場合」見出し分けで行う。 -（#3完了後、影響範囲確認の結果をもとに具体的な修正タスクをここに追記する） +**Prerequisites**: #4 + +**Steps**: + +- [ ] `06_TestFWGuide/testdata/` 配下に以下の7ファイルを作成する: + `overview.rst` / `data-blocks.rst` / `testshots.rst` / `table-data.rst` / `file-data.rst` / `messaging.rst` / `values.rst` +- [ ] 各ファイルに `ntf-testdata-doc.md` の対応章（§1〜10）と examples ファイルの内容を RST 化して記述する +- [ ] `testdata/index.rst` の toctree にすべて追加する +- [ ] `make html` でビルドエラーがないことを確認する +- [ ] self-check (OK/NG per completion criterion, record in checks/task5.md) +- [ ] QA expert review (subagent) +- [ ] user review + +**Completion criteria**: + +- `testdata/` 配下に B-1-1〜B-1-7 の RST ファイルが存在し、toctree に追加されている +- `ntf-testdata-doc.md` の全章（§1〜10）が B-1 のいずれかの節に対応している +- Excel/YAML の記述例が各節に両方掲載されている +- `make html` がエラーなく完了する + +### #6: 既存ページのテストデータ参照をB-1へ差し替え + +**Purpose**: `05_UnitTestGuide/` 配下の各ページで「テストデータの書き方」を解説している箇所を B-1 への参照リンクに置き換え、重複記述を解消する。 + +**Prerequisites**: #5 + +**Steps**: + +- [ ] proposed-structure.md の新旧マッピング表を参照し、対象ページ（B-3〜B-5 相当）を特定する +- [ ] 各ページの「テストデータの書き方」節を `:ref:` 参照リンクに置き換える +- [ ] `02_DbAccessTest.rst` の冒頭にテストデータ参照誘導を追加する +- [ ] `make html` でビルドエラー・壊れた参照がないことを確認する +- [ ] self-check (OK/NG per completion criterion, record in checks/task6.md) +- [ ] QA expert review (subagent) +- [ ] user review + +**Completion criteria**: + +- 対象ページの「テストデータの書き方」節が B-1 への参照に変わっている +- `make html` がエラーなく完了する +- 既存の `:ref:` ラベルが壊れていない # Decisions -（未記入 — 作業中に記録） +### D-1: 新構成案への合意（2026-06-26） + +ユーザーと議論の上、proposed-structure.md（`.rn/ntf-yaml-support/proposed-structure.md`）に記載の新構成案で合意した。主な合意内容: + +- トップ2ページ: 「Nablarchテスティングフレームワークとは」（A章）「テストの実装方法」（B章） +- テストデータは B-1「テストデータの記述方法」（仕様）+ B-2「テストデータの記述例」の2ページ構成（※B-2はタスク追加時に検討） +- Excel/YAML 並列表示は「Excelの場合」「YAMLの場合」見出し分けを採用（sphinx-tabs は使わない） +- ディレクトリ構造は既存パスを維持し toctree のみ組み替える +- input/ のうち `ntf-testdata-loading.md` と `testdata-converter-design.md` は使わない # State -- **Status**: paused -- **Date**: 2026-06-26 -- **Last completed**: #2 全体構成の認識合わせ（QA PASS） -- **Next**: #3 影響範囲確認とタスク更新 -- **Notes**: | - ユーザーと新構成について議論し、proposed-structure.md（`.rn/ntf-yaml-support/proposed-structure.md`）として - ゼロベース設計案を作成・合意済み。ステアリングのタスク #3〜#5 は proposed-structure.md の内容をもとに - 組み直す必要がある。 - - 【合意済みの設計内容】 - - トップ2ページ: 「Nablarchテスティングフレームワークとは」「テストの実装方法」 - - テストデータは2ページ構成: B-1「テストデータの記述方法」（仕様1ページ）、B-2「テストデータの記述例」（例1ページ） - - Excel/YAML 並列表示はタブ切り替えなし（sphinx-tabs 未導入）、「Excelの場合」「YAMLの場合」小見出し分け - - ディレクトリ構造は既存パスを維持し toctree だけ組み替え - - input/ のうち ntf-testdata-loading.md と testdata-converter-design.md は使わない - - 【次のアクション】 - ステアリングの #3（影響範囲確認とタスク更新）を実行する前に、タスク #3〜#5 の内容を - proposed-structure.md の合意内容に合わせて書き直すこと。 - 具体的には「全体構成見直し」「YAML対応」という2軸を分解したタスクを追加する。 - - ビルド環境: `/tmp/sphinx_env`（Sphinx 1.8.6）、`make html SPHINXBUILD=/tmp/sphinx_env/bin/sphinx-build` +（未記入 — 作業中に記録） From dd2baea5572f95673a5e484c69ef0c0c59fe295f Mon Sep 17 00:00:00 2001 From: kiyotis Date: Fri, 26 Jun 2026 11:57:49 +0900 Subject: [PATCH 11/15] =?UTF-8?q?docs:=20NTF=E8=A7=A3=E8=AA=AC=E6=9B=B8?= =?UTF-8?q?=E4=BF=AE=E6=AD=A3=E3=81=AE=E4=BD=9C=E6=A5=AD=E3=83=AB=E3=83=BC?= =?UTF-8?q?=E3=83=AB=E3=82=92CLAUDE.md=E3=81=AB=E8=A8=98=E8=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Sonnet 4.6 --- CLAUDE.md | 210 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 210 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..adc74ea7 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,210 @@ +# CLAUDE.md — nablarch-document 作業ルール + +## NTF解説書修正の作業ルール + +本セクションは `feature/ntf-yaml-support` ブランチにおける NTF（Nablarch テスティングフレームワーク）解説書修正の作業ルールを定める。対象ファイルは `ja/development_tools/testing_framework/guide/development_guide/06_TestFWGuide/` 配下の RST ファイル。 + +--- + +### 1. 文体 + +- **です・ます調**を使用する（「〜できる」「〜する」「〜される」等、既存解説書の文体に準拠）。 +- 体言止めは見出し・表のセル内では使用可。本文（説明文）では使用しない。 +- 箇条書きの各項は文末を「〜する。」「〜できる。」等の体言止め以外の形にそろえる（ただし短い列挙項目は体言止めも可）。 +- 「だ・である調」は使用しない。 + +--- + +### 2. 用語統一ルール + +以下の用語は `.rn/ntf-yaml-support/input/ntf-doc-terms.md` を正典とし、表記を統一する。 + +#### フレームワーク名称 + +| 正式表記 | 使用しない表記 | +|---|---| +| 自動テストフレームワーク（見出し・冒頭での呼称） | NTF（本文での略称は可） | +| テスティングフレームワーク（`testing_framework` モジュールの文脈） | テストフレームワーク | + +#### テストデータ関連 + +| 用語 | 正式表記 | 備考 | +|---|---|---| +| データタイプ | `データタイプ` | コード中では `SETUP_TABLE` 等の全大文字英字 | +| グループ ID | `グループID`（半角スペースなし） | 書式例: `SETUP_TABLE[case_001]=テーブル名` | +| testShots | `testShots`（キャメルケース） | クラス名は `TestShot` | +| requestParams | `requestParams`（キャメルケース） | | +| setUpDb | `setUpDb`（キャメルケース） | シート名も同じ表記 | +| LIST_MAP | `LIST_MAP`（全大文字） | | + +#### Excel / YAML 関連 + +| 用語 | 正式表記 | 備考 | +|---|---|---| +| Excel ファイル | `Excelファイル` | 「エクセルファイル」は使用しない | +| Excel シート | `Excelシート` | | +| シート名 | `シート名` | | +| セル | `セル` | 複数形は「各セル」 | +| 罫線 | `罫線` | | +| マーカーカラム | `マーカーカラム` | | +| YAML ファイル | `YAMLファイル` | | + +#### DB 関連 + +| 用語 | 正式表記 | 備考 | +|---|---|---| +| 準備データ | `準備データ` | 「テストデータ」との混用に注意 | +| カラム | `カラム` | 「列」「フィールド」は文脈に合わせて使い分け可 | +| レコード | `レコード` | | + +--- + +### 3. RST 記法ルール + +#### 見出しレベル + +既存ファイルで使われているパターンに準拠する: + +```rst +======== +ページ題 +======== + +-------- +大見出し +-------- + +中見出し +======== + +小見出し +-------- + +細見出し +~~~~~~~~ +``` + +- ページ題（`=====` 上下）は各 RST ファイルに 1 つだけ置く。 +- 大見出し（`-----` 上下）はセクション区切りに使う。 +- 中見出し以下は必要に応じて使う。 + +#### コードブロック + +```rst +.. code-block:: java + + // インデントは3スペース + public class Sample {} +``` + +- 言語指定: Java は `java`、YAML は `yaml`、シェルは `bash`。 +- インデントはスペース3つ。 + +#### リストテーブル（listtable / grid table） + +既存ファイルでは以下の 2 種が混在している。いずれも使用可: + +- グリッドテーブル（`+---+---+` 形式） +- `=====` 区切りのシンプルテーブル + +新規追加時は可読性を優先してグリッドテーブルを推奨する。 + +#### ラベルとクロスリファレンス + +- ラベルは小文字英字・アンダースコアのスネークケース: `.. _label_name:` +- 参照は `:ref:\`label_name\`` 形式。 + +#### 注意・ヒントブロック + +```rst +.. tip:: + ヒント内容 + +.. important:: + 重要事項 + +.. note:: + 補足事項 +``` + +--- + +### 4. Excel / YAML 並列記述の方針 + +YAML 対応追記は「既存の Excel 向け記述は削除せず、YAML を並列で追記する」方針とする。 + +#### 見出し分けのルール + +1. セクション内で Excel と YAML の記述が異なる場合、同一見出しの直下に以下のサブ見出しを置く: + +```rst +Excelの場合 +----------- + +（Excel 向けの説明・例） + +YAMLの場合 +---------- + +（YAML 向けの説明・例） +``` + +2. Excel / YAML で共通の説明は見出し分けせず、冒頭にまとめて記述する。 + +3. 説明文の冒頭で両形式に対応していることを明示する場合: + + > テストデータは Excel または YAML ファイルで記述できる。 + +4. sphinx-tabs（タブ切り替え）は使用しない（D-1 の合意に従う）。 + +--- + +### 5. YAML テストデータの用語 + +YAML 形式のテストデータで使用する用語は、Excel 用語との対応を以下のとおり定める: + +| Excel 用語 | YAML 対応用語 | 備考 | +|---|---|---| +| シート | ドキュメント（YAML ドキュメント区切り `---`） | | +| セル | 値（スカラー） | | +| データタイプ行（1 行目） | `dataType` キー | YAML の場合はブロックマッピングのキー | +| グループ ID | `id` キー | | + +YAML 固有のキー名・書式は入力資料（`.rn/ntf-yaml-support/input/` 配下）を参照する。 + +--- + +### 6. コミット・ブランチ運用 + +- ブランチ: `feature/ntf-yaml-support` +- コミット単位: タスク（`#N`）ごとに 1 コミット以上 +- コミットメッセージは日本語で `docs:` プレフィックスを付ける（例: `docs: テストデータ記述方法にYAML対応を追記`） +- `complete task #` の文字列はコミットメッセージに含めない +- チェックファイル（`checks/task*.md`）はコミットしない +- RST 変更後は必ず `make html` でビルドエラーがないことを確認してからコミットする + +--- + +### 7. ファイル・ディレクトリ構造 + +``` +ja/development_tools/testing_framework/guide/development_guide/ +├── 06_TestFWGuide/ # NTF 解説書のメイン置き場 +│ ├── index.rst # toctree +│ ├── 01_Abstract.rst # A章: テスティングFWとは（テストデータ構造概要） +│ ├── 02_DbAccessTest.rst # B章: DBアクセステスト +│ ├── 03_Tips.rst # Tips / 目的別 API +│ ├── testdata/ # B-1: テストデータ記述方法（新設） +│ │ ├── index.rst +│ │ ├── overview.rst +│ │ ├── data-blocks.rst +│ │ ├── testshots.rst +│ │ ├── table-data.rst +│ │ ├── file-data.rst +│ │ ├── messaging.rst +│ │ └── values.rst +│ └── _images/ +└── 05_UnitTestGuide/ # 各テスト種別ガイド（参照リンクのみ変更） +``` + +新規 RST ファイルを追加する場合は必ず親ディレクトリの `index.rst` の toctree にも追加する。 From 137064e3727cc00f2b977e1b3ff8205259f7147e Mon Sep 17 00:00:00 2001 From: kiyotis Date: Fri, 26 Jun 2026 12:02:09 +0900 Subject: [PATCH 12/15] =?UTF-8?q?docs:=20CLAUDE.md=20QA=E6=8C=87=E6=91=98?= =?UTF-8?q?=E4=BF=AE=E6=AD=A3=EF=BC=88=E8=A6=8B=E5=87=BA=E3=81=97=E4=BE=8B?= =?UTF-8?q?=E3=83=BB=E6=96=87=E4=BD=93=E3=83=AB=E3=83=BC=E3=83=AB=E3=83=BB?= =?UTF-8?q?=E7=94=A8=E8=AA=9E=E3=83=AB=E3=83=BC=E3=83=AB=E6=95=B4=E7=90=86?= =?UTF-8?q?=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - [NG-2] Section 4のRST見出し例にアンダーライン長の注意事項と見出しレベルの補足を追加 - [NG-3] 体言止めルールを「見出し・表・箇条書き短い列挙項目では可、説明段落の地の文では不可」に整理（矛盾を解消） - [NG-5] フレームワーク名称ルールを実ファイル（01_Abstract.rst）確認の上シンプル化 - [NG-6] コードブロックインデントを実ファイルの実態に合わせて3スペース→4スペースに修正 - [NG-7] Section 5にSection 2テストデータ関連用語表への参照を明示 - [NG-8] Section 6のビルド確認手順に具体的なコマンドを追記 - [NG-9] Section 4のルール2と3（共通説明の冒頭まとめ・両形式対応の明示）を統合 Co-Authored-By: Claude Sonnet 4.6 --- CLAUDE.md | 38 ++++++++++++++++++++++++-------------- 1 file changed, 24 insertions(+), 14 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index adc74ea7..37823921 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -9,8 +9,8 @@ ### 1. 文体 - **です・ます調**を使用する（「〜できる」「〜する」「〜される」等、既存解説書の文体に準拠）。 -- 体言止めは見出し・表のセル内では使用可。本文（説明文）では使用しない。 -- 箇条書きの各項は文末を「〜する。」「〜できる。」等の体言止め以外の形にそろえる（ただし短い列挙項目は体言止めも可）。 +- 体言止めは見出し・表のセル内・箇条書きの短い列挙項目では使用可。説明段落の地の文では使用しない。 +- 箇条書きの各項は文末を「〜する。」「〜できる。」等の述語で終わる形にそろえる（短い列挙項目は体言止めも可）。 - 「だ・である調」は使用しない。 --- @@ -23,8 +23,12 @@ | 正式表記 | 使用しない表記 | |---|---| -| 自動テストフレームワーク（見出し・冒頭での呼称） | NTF（本文での略称は可） | -| テスティングフレームワーク（`testing_framework` モジュールの文脈） | テストフレームワーク | +| 自動テストフレームワーク（各ページの既存見出し・冒頭表記に従う） | テストフレームワーク | +| NTF（本文での略称として使用可） | — | + +- 初出時はページの既存表記（例: `01_Abstract.rst` では「自動テストフレームワーク」）に従う。 +- 2回目以降の本文では略称「NTF」を使用してよい。 +- `testing_framework` モジュール名（URL・パス等）とドキュメントの呼称は別物であり、モジュール名はそのまま表記する。 #### テストデータ関連 @@ -93,12 +97,12 @@ ```rst .. code-block:: java - // インデントは3スペース - public class Sample {} + // インデントは4スペース + public class Sample {} ``` - 言語指定: Java は `java`、YAML は `yaml`、シェルは `bash`。 -- インデントはスペース3つ。 +- インデントはスペース4つ（既存ファイル `01_Abstract.rst` の実態に準拠）。 #### リストテーブル（listtable / grid table） @@ -135,7 +139,7 @@ YAML 対応追記は「既存の Excel 向け記述は削除せず、YAML を並 #### 見出し分けのルール -1. セクション内で Excel と YAML の記述が異なる場合、同一見出しの直下に以下のサブ見出しを置く: +1. セクション内で Excel と YAML の記述が異なる場合、同一見出しの直下に以下のサブ見出しを置く（Section 3 の「小見出し」レベル `--------` に相当）: ```rst Excelの場合 @@ -145,17 +149,18 @@ Excelの場合 YAMLの場合 ---------- - -（YAML 向けの説明・例） ``` -2. Excel / YAML で共通の説明は見出し分けせず、冒頭にまとめて記述する。 + - RST の見出しアンダーラインはテキストの表示幅以上の長さが必要。 + - 「Excelの場合」は6文字（全角4+半角2相当）なので `-` を 11 本以上にそろえる。 + - 「YAMLの場合」も同様。文字種（`-`）が同じであれば同じ見出しレベルとして扱われる。 + - 上記例のダッシュ数はあくまで最低限の目安。実際は揃っていれば問題ない。 -3. 説明文の冒頭で両形式に対応していることを明示する場合: +2. Excel / YAML で共通の説明（両形式に対応していることの明示を含む）は見出し分けせず、冒頭にまとめて記述する: > テストデータは Excel または YAML ファイルで記述できる。 -4. sphinx-tabs（タブ切り替え）は使用しない（D-1 の合意に従う）。 +3. sphinx-tabs（タブ切り替え）は使用しない（D-1 の合意に従う）。 --- @@ -170,6 +175,8 @@ YAML 形式のテストデータで使用する用語は、Excel 用語との対 | データタイプ行（1 行目） | `dataType` キー | YAML の場合はブロックマッピングのキー | | グループ ID | `id` キー | | +YAML キーとして使われる主要な識別子（`testShots`・`requestParams`・`setUpDb`・`LIST_MAP` 等）は Section 2「テストデータ関連用語表」と同じ表記を使用する。 + YAML 固有のキー名・書式は入力資料（`.rn/ntf-yaml-support/input/` 配下）を参照する。 --- @@ -181,7 +188,10 @@ YAML 固有のキー名・書式は入力資料（`.rn/ntf-yaml-support/input/` - コミットメッセージは日本語で `docs:` プレフィックスを付ける（例: `docs: テストデータ記述方法にYAML対応を追記`） - `complete task #` の文字列はコミットメッセージに含めない - チェックファイル（`checks/task*.md`）はコミットしない -- RST 変更後は必ず `make html` でビルドエラーがないことを確認してからコミットする +- RST 変更後は必ず以下のコマンドでビルドエラーがないことを確認してからコミットする（`ja/` 配下のドキュメントルートで実行）: + ```bash + make html SPHINXBUILD=/tmp/sphinx_env/bin/sphinx-build + ``` --- From f0a8fad2b232e2d1a7e766d02a8e0b2d235b2d40 Mon Sep 17 00:00:00 2001 From: kiyotis Date: Fri, 26 Jun 2026 12:08:16 +0900 Subject: [PATCH 13/15] =?UTF-8?q?docs:=20CLAUDE.md=20=E6=96=87=E4=BD=93?= =?UTF-8?q?=E3=83=AB=E3=83=BC=E3=83=AB=E3=82=92=E3=80=8C=E3=81=A0=E3=83=BB?= =?UTF-8?q?=E3=81=A7=E3=81=82=E3=82=8B=E8=AA=BF=E3=80=8D=E3=81=AB=E4=BF=AE?= =?UTF-8?q?=E6=AD=A3=EF=BC=88=E6=97=A2=E5=AD=98RST=E7=A2=BA=E8=AA=8D?= =?UTF-8?q?=E7=B5=90=E6=9E=9C=E3=82=92=E5=8F=8D=E6=98=A0=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CLAUDE.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 37823921..d7264691 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -8,10 +8,10 @@ ### 1. 文体 -- **です・ます調**を使用する（「〜できる」「〜する」「〜される」等、既存解説書の文体に準拠）。 +- **だ・である調**を使用する（`01_Abstract.rst` 等の既存解説書の文体に準拠）。 +- 例: 「〜できる。」「〜である。」「〜とする。」「〜であり、」 +- 「です・ます調」（「〜できます。」「〜ください。」）は使用しない。 - 体言止めは見出し・表のセル内・箇条書きの短い列挙項目では使用可。説明段落の地の文では使用しない。 -- 箇条書きの各項は文末を「〜する。」「〜できる。」等の述語で終わる形にそろえる（短い列挙項目は体言止めも可）。 -- 「だ・である調」は使用しない。 --- From 4e5958c95169f459b860d761bbaf32f6e8fd19b0 Mon Sep 17 00:00:00 2001 From: kiyotis Date: Fri, 26 Jun 2026 12:13:26 +0900 Subject: [PATCH 14/15] =?UTF-8?q?docs:=20CLAUDE.md=E3=82=92=E6=B1=8E?= =?UTF-8?q?=E7=94=A8=E3=83=AB=E3=83=BC=E3=83=AB=E9=9B=86=E3=81=AB=E5=88=B7?= =?UTF-8?q?=E6=96=B0=E3=80=81=E3=82=BF=E3=82=B9=E3=82=AF=E5=9B=BA=E6=9C=89?= =?UTF-8?q?=E3=83=AB=E3=83=BC=E3=83=AB=E3=82=92=E3=82=B9=E3=83=86=E3=82=A2?= =?UTF-8?q?=E3=83=AA=E3=83=B3=E3=82=B0=E3=81=AB=E7=A7=BB=E5=8B=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Sonnet 4.6 --- .rn/ntf-yaml-support/steering.md | 50 ++++++- CLAUDE.md | 227 +++++++------------------------ 2 files changed, 100 insertions(+), 177 deletions(-) diff --git a/.rn/ntf-yaml-support/steering.md b/.rn/ntf-yaml-support/steering.md index 61040491..ddfe895b 100644 --- a/.rn/ntf-yaml-support/steering.md +++ b/.rn/ntf-yaml-support/steering.md @@ -26,11 +26,59 @@ NTF（Nablarchテストフレームワーク）解説書（`ja/development_tools - commit and push every change; one completion marker per task - RST ビルドは各タスク完了前に必ず確認し、エラーがあれば修正してから完了マークをつける -- 文書表現・トンマナは CLAUDE.md に記載したルールに従う +- 文書表現・トンマナは CLAUDE.md に記載した汎用ルールに従う - 日本語で記述する（ファイルパス・コマンド・コード例は除く） - 既存の Excel 向け記述を削除しない（YAML を追記する形で対応） - 新規 RST ファイルを追加する場合は toctree にも追記する +## このブランチ固有の記述ルール + +### Excel/YAML 並列記述の方針 + +- 「Excelの場合」「YAMLの場合」の見出し分けで並列掲載する（sphinx-tabs は使用しない — D-1 合意） +- 共通説明は見出し分けせず冒頭にまとめる。冒頭に「テストデータは Excel または YAML ファイルで記述できる。」を入れる +- 見出し分けの例（`小見出し` レベルの `-` アンダーライン）: + + ```rst + Excelの場合 + ----------- + + （Excel 向けの説明・例） + + YAMLの場合 + ---------- + + （YAML 向けの説明・例） + ``` + +### 用語対応表（Excel ↔ YAML） + +YAML 追記時、以下の対応で表記する（input/ の仕様資料を正典とする）: + +| Excel 用語 | YAML 対応用語 | +|---|---| +| シート | ファイル（YAMLファイル） | +| データタイプ行（1行目） | `dataType` キー | +| グループID | `id` キー | + +- `testShots`・`LIST_MAP` 等の識別子名は既存ページでの表記をそのまま使う +- YAML 固有のキー名・構造は `.rn/ntf-yaml-support/input/ntf-testdata-doc.md` を参照する + +### ファイル構造（このブランチで追加するファイル） + +``` +06_TestFWGuide/ + testdata/ + index.rst ← B-1 の入口 + overview.rst ← B-1-1 全体像 + data-blocks.rst ← B-1-2 データブロック種別 + testshots.rst ← B-1-3 testShots + table-data.rst ← B-1-4 テーブルデータ + file-data.rst ← B-1-5 ファイルデータ + messaging.rst ← B-1-6 メッセージング + values.rst ← B-1-7 値の書き方 +``` + # Tasks ### #1: RSTビルド確認 diff --git a/CLAUDE.md b/CLAUDE.md index d7264691..4fbd9ad4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,220 +1,95 @@ # CLAUDE.md — nablarch-document 作業ルール -## NTF解説書修正の作業ルール +## RST 解説書の執筆ルール -本セクションは `feature/ntf-yaml-support` ブランチにおける NTF（Nablarch テスティングフレームワーク）解説書修正の作業ルールを定める。対象ファイルは `ja/development_tools/testing_framework/guide/development_guide/06_TestFWGuide/` 配下の RST ファイル。 +### 文体 ---- +既存ページ（`01_Abstract.rst`・`03_Tips.rst` 等）に準拠し、**だ・である調**を使用する。 -### 1. 文体 +- 説明文: 「〜できる。」「〜である。」「〜とする。」「〜とみなされる。」 +- 手順文: 「〜すること。」「〜を参照。」 +- 「〜できます。」「〜ください。」等のです・ます調は使用しない。 +- 体言止めは見出し・表のセル・箇条書きの短い列挙では使用可。説明段落の地の文では使用しない。 -- **だ・である調**を使用する（`01_Abstract.rst` 等の既存解説書の文体に準拠）。 -- 例: 「〜できる。」「〜である。」「〜とする。」「〜であり、」 -- 「です・ます調」（「〜できます。」「〜ください。」）は使用しない。 -- 体言止めは見出し・表のセル内・箇条書きの短い列挙項目では使用可。説明段落の地の文では使用しない。 +### 用語 ---- +**既存ページに登場する表記を必ず確認し、そこに合わせる。推測で用語を作らない。** -### 2. 用語統一ルール +- 用語が既存ページに存在しない場合は、最も近い既存表現を探して踏襲するか、ユーザーに確認する。 +- 英字識別子（クラス名・メソッド名・データタイプ名等）は既存ページでの表記（大文字・小文字・キャメルケース）をそのまま使う。 -以下の用語は `.rn/ntf-yaml-support/input/ntf-doc-terms.md` を正典とし、表記を統一する。 +### 導入文・説明文のパターン -#### フレームワーク名称 +既存ページで使われているパターンに合わせる: -| 正式表記 | 使用しない表記 | -|---|---| -| 自動テストフレームワーク（各ページの既存見出し・冒頭表記に従う） | テストフレームワーク | -| NTF（本文での略称として使用可） | — | +- セクション冒頭: 「〜について説明する。」 +- 例を示す前: 「以下に〜を示す。」「例を以下に示す。」「以下の例では〜。」 +- 規約の列挙前: 「〜に関する規約は以下の通り。」「〜を以下に記載する。」 -- 初出時はページの既存表記（例: `01_Abstract.rst` では「自動テストフレームワーク」）に従う。 -- 2回目以降の本文では略称「NTF」を使用してよい。 -- `testing_framework` モジュール名（URL・パス等）とドキュメントの呼称は別物であり、モジュール名はそのまま表記する。 +### 見出しレベル -#### テストデータ関連 - -| 用語 | 正式表記 | 備考 | -|---|---|---| -| データタイプ | `データタイプ` | コード中では `SETUP_TABLE` 等の全大文字英字 | -| グループ ID | `グループID`（半角スペースなし） | 書式例: `SETUP_TABLE[case_001]=テーブル名` | -| testShots | `testShots`（キャメルケース） | クラス名は `TestShot` | -| requestParams | `requestParams`（キャメルケース） | | -| setUpDb | `setUpDb`（キャメルケース） | シート名も同じ表記 | -| LIST_MAP | `LIST_MAP`（全大文字） | | - -#### Excel / YAML 関連 - -| 用語 | 正式表記 | 備考 | -|---|---|---| -| Excel ファイル | `Excelファイル` | 「エクセルファイル」は使用しない | -| Excel シート | `Excelシート` | | -| シート名 | `シート名` | | -| セル | `セル` | 複数形は「各セル」 | -| 罫線 | `罫線` | | -| マーカーカラム | `マーカーカラム` | | -| YAML ファイル | `YAMLファイル` | | - -#### DB 関連 - -| 用語 | 正式表記 | 備考 | -|---|---|---| -| 準備データ | `準備データ` | 「テストデータ」との混用に注意 | -| カラム | `カラム` | 「列」「フィールド」は文脈に合わせて使い分け可 | -| レコード | `レコード` | | - ---- - -### 3. RST 記法ルール - -#### 見出しレベル - -既存ファイルで使われているパターンに準拠する: +`01_Abstract.rst` で実際に使われているパターン: ```rst -======== -ページ題 -======== +======================== +ページ題（= 上下） +======================== -------- -大見出し +大見出し（- 上下） -------- -中見出し -======== +中見出し（= 下のみ） +==================== -小見出し --------- +小見出し（- 下のみ） +-------------------- -細見出し -~~~~~~~~ +細見出し（~ 下のみ） +~~~~~~~~~~~~~~~~~~~~ ``` -- ページ題（`=====` 上下）は各 RST ファイルに 1 つだけ置く。 -- 大見出し（`-----` 上下）はセクション区切りに使う。 -- 中見出し以下は必要に応じて使う。 - -#### コードブロック - -```rst -.. code-block:: java - - // インデントは4スペース - public class Sample {} -``` - -- 言語指定: Java は `java`、YAML は `yaml`、シェルは `bash`。 -- インデントはスペース4つ（既存ファイル `01_Abstract.rst` の実態に準拠）。 - -#### リストテーブル（listtable / grid table） - -既存ファイルでは以下の 2 種が混在している。いずれも使用可: +- アンダーラインはテキストの表示幅以上の長さにする（日本語全角は2幅）。 +- 各ファイルで最初に現れた文字種がそのレベルに固定される（RST の相対レベル仕様）。 +- 新規ファイルは既存の近いファイルの構造を参照して合わせる。 -- グリッドテーブル（`+---+---+` 形式） -- `=====` 区切りのシンプルテーブル +### RST 記法 -新規追加時は可読性を優先してグリッドテーブルを推奨する。 - -#### ラベルとクロスリファレンス - -- ラベルは小文字英字・アンダースコアのスネークケース: `.. _label_name:` -- 参照は `:ref:\`label_name\`` 形式。 - -#### 注意・ヒントブロック +**コードブロック**: インデントは4スペース（既存ファイル実測値）。 ```rst -.. tip:: - ヒント内容 - -.. important:: - 重要事項 +.. code-block:: java -.. note:: - 補足事項 + public class SampleTest { + } ``` ---- +言語指定: `java` / `xml` / `yaml` / `text` / `bash` -### 4. Excel / YAML 並列記述の方針 +**テーブル**: グリッドテーブル（`+---+`）とシンプルテーブル（`===`）が既存ファイルで混在している。 +新規追加時はグリッドテーブルを推奨するが、近接する既存テーブルのスタイルに合わせる。 -YAML 対応追記は「既存の Excel 向け記述は削除せず、YAML を並列で追記する」方針とする。 - -#### 見出し分けのルール - -1. セクション内で Excel と YAML の記述が異なる場合、同一見出しの直下に以下のサブ見出しを置く（Section 3 の「小見出し」レベル `--------` に相当）: +**ラベルとクロスリファレンス**: ```rst -Excelの場合 ------------ - -（Excel 向けの説明・例） +.. _label_name: -YAMLの場合 ----------- +見出し +====== ``` - - RST の見出しアンダーラインはテキストの表示幅以上の長さが必要。 - - 「Excelの場合」は6文字（全角4+半角2相当）なので `-` を 11 本以上にそろえる。 - - 「YAMLの場合」も同様。文字種（`-`）が同じであれば同じ見出しレベルとして扱われる。 - - 上記例のダッシュ数はあくまで最低限の目安。実際は揃っていれば問題ない。 - -2. Excel / YAML で共通の説明（両形式に対応していることの明示を含む）は見出し分けせず、冒頭にまとめて記述する: - - > テストデータは Excel または YAML ファイルで記述できる。 +参照: `:ref:\`label_name\`` -3. sphinx-tabs（タブ切り替え）は使用しない（D-1 の合意に従う）。 +**アドモニション**（`.. tip::` / `.. note::` / `.. important::`）: 本文は2スペースインデント。 ---- +**脚注**: `.. [#]` 形式（既存ページ参照）。 -### 5. YAML テストデータの用語 +### ビルド確認 -YAML 形式のテストデータで使用する用語は、Excel 用語との対応を以下のとおり定める: +RST を変更したら必ず以下でビルドエラーがないことを確認する（`ja/` 配下のドキュメントルートで実行）: -| Excel 用語 | YAML 対応用語 | 備考 | -|---|---|---| -| シート | ドキュメント（YAML ドキュメント区切り `---`） | | -| セル | 値（スカラー） | | -| データタイプ行（1 行目） | `dataType` キー | YAML の場合はブロックマッピングのキー | -| グループ ID | `id` キー | | - -YAML キーとして使われる主要な識別子（`testShots`・`requestParams`・`setUpDb`・`LIST_MAP` 等）は Section 2「テストデータ関連用語表」と同じ表記を使用する。 - -YAML 固有のキー名・書式は入力資料（`.rn/ntf-yaml-support/input/` 配下）を参照する。 - ---- - -### 6. コミット・ブランチ運用 - -- ブランチ: `feature/ntf-yaml-support` -- コミット単位: タスク（`#N`）ごとに 1 コミット以上 -- コミットメッセージは日本語で `docs:` プレフィックスを付ける（例: `docs: テストデータ記述方法にYAML対応を追記`） -- `complete task #` の文字列はコミットメッセージに含めない -- チェックファイル（`checks/task*.md`）はコミットしない -- RST 変更後は必ず以下のコマンドでビルドエラーがないことを確認してからコミットする（`ja/` 配下のドキュメントルートで実行）: - ```bash - make html SPHINXBUILD=/tmp/sphinx_env/bin/sphinx-build - ``` - ---- - -### 7. ファイル・ディレクトリ構造 - -``` -ja/development_tools/testing_framework/guide/development_guide/ -├── 06_TestFWGuide/ # NTF 解説書のメイン置き場 -│ ├── index.rst # toctree -│ ├── 01_Abstract.rst # A章: テスティングFWとは（テストデータ構造概要） -│ ├── 02_DbAccessTest.rst # B章: DBアクセステスト -│ ├── 03_Tips.rst # Tips / 目的別 API -│ ├── testdata/ # B-1: テストデータ記述方法（新設） -│ │ ├── index.rst -│ │ ├── overview.rst -│ │ ├── data-blocks.rst -│ │ ├── testshots.rst -│ │ ├── table-data.rst -│ │ ├── file-data.rst -│ │ ├── messaging.rst -│ │ └── values.rst -│ └── _images/ -└── 05_UnitTestGuide/ # 各テスト種別ガイド（参照リンクのみ変更） +```bash +make html SPHINXBUILD=/tmp/sphinx_env/bin/sphinx-build ``` -新規 RST ファイルを追加する場合は必ず親ディレクトリの `index.rst` の toctree にも追加する。 +新規 RST ファイルを追加した場合は、親ディレクトリの `index.rst` の toctree にも追加すること。 From 6aeb89f8894c0647d701f0e9319e859342c0e7a3 Mon Sep 17 00:00:00 2001 From: kiyotis Date: Fri, 26 Jun 2026 16:19:05 +0900 Subject: [PATCH 15/15] =?UTF-8?q?chore:=20suspend=20session=20=E2=80=94=20?= =?UTF-8?q?ntf-yaml-support?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .rn/ntf-yaml-support/steering.md | 24 +++++++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) diff --git a/.rn/ntf-yaml-support/steering.md b/.rn/ntf-yaml-support/steering.md index ddfe895b..1337c03b 100644 --- a/.rn/ntf-yaml-support/steering.md +++ b/.rn/ntf-yaml-support/steering.md @@ -219,4 +219,26 @@ YAML 追記時、以下の対応で表記する（input/ の仕様資料を正 # State -（未記入 — 作業中に記録） +- **Status**: paused +- **Date**: 2026-06-26 +- **Last completed**: #3 文書表現・トンマナ確認とCLAUDE.md作業ルール記載（QA PASS、ユーザーレビュー待ち） +- **Next**: #3 のユーザー承認 → チェックオフ → #4 toctree 構成変更 +- **Notes**: | + Task #3 は実装・QA ともに完了し、ユーザーレビュー段階で中断した。 + CLAUDE.md をユーザー指摘により刷新済み（汎用ルール集に絞り、タスク固有ルールはステアリングの Rules に移動）。 + + 【CLAUDE.md の現在の内容】 + - 文体: だ・である調（既存ページ実測） + - 用語: 「既存ページに合わせる、推測しない」を原則 + - RST 記法: 見出しレベル・コードブロック（4スペース）・テーブル・ラベル等 + - ビルドコマンド: make html SPHINXBUILD=/tmp/sphinx_env/bin/sphinx-build + + 【Task #3 完了基準】 + - CLAUDE.md にNTF解説書修正の作業ルール（文書表現・用語・トンマナ）が記載されている → OK + + 【次のアクション】 + 1. ユーザーに Task #3 の承認を求める + 2. 承認後 steering.md の #3 をチェックオフしてコミット + 3. Task #4（toctree 構成変更 — A章・B章の骨格作成）に着手 + + ビルド環境: `/tmp/sphinx_env`（Sphinx 1.8.6）、`make html SPHINXBUILD=/tmp/sphinx_env/bin/sphinx-build`