DB Tester

日本語

English

日本語

English

テーマ

DB Tester仕様 - データフォーマット ​

サポートされる形式 ​

フレームワークは2つの区切りテキスト形式をサポートします:

形式拡張子区切り文字デフォルト
CSV.csvカンマ（,）はい
TSV.tsvタブ（\t）いいえ

形式の選択 ​

ConventionSettingsで形式を設定します:

java
var conventions = ConventionSettings.builder()
    .dataFormat(DataFormat.TSV)
    .build();

ディレクトリからデータセットを読み込む際、設定された拡張子に一致するファイルのみが処理されます。

ファイル構造 ​

基本構造 ​

各ファイルは1つのデータベーステーブルを表します:

  • ファイル名（拡張子なし）= テーブル名
  • 最初の行 = カラムヘッダー
  • 後続の行 = データレコード

CSVの例 ​

ファイル: USERS.csv

csv
id,name,email,created_at
1,Alice,alice@example.com,2024-01-01 00:00:00
2,Bob,bob@example.com,2024-01-02 00:00:00

表現:

カラム値
id1, 2
nameAlice, Bob
emailalice@example.com, bob@example.com
created_at2024-01-01 00:00:00, 2024-01-02 00:00:00

TSVの例 ​

ファイル: ORDERS.tsv

tsv
order_id	user_id	amount	status
1001	1	99.99	PENDING
1002	2	149.50	COMPLETED

シナリオフィルタリング ​

シナリオマーカーカラム ​

シナリオマーカーカラムにより、複数のテストメソッドでデータセットファイルを共有できます:

カラム名設定可能デフォルト
[Scenario]はい[Scenario]

シナリオカラムの動作 ​

データセットファイルにシナリオマーカーカラムが含まれている場合、本フレームワークは以下の処理を行います:

  1. マーカーが現在のシナリオに一致する行をフィルタリング
  2. 結果のデータセットからシナリオマーカーカラムを削除
  3. 残りのカラムとデータをデータベース操作に渡す

シナリオを使用した例 ​

ファイル: USERS.csv

csv
[Scenario],id,name,email
testCreate,1,Alice,alice@example.com
testCreate,2,Bob,bob@example.com
testUpdate,3,Charlie,charlie@example.com
testDelete,4,Diana,diana@example.com

テストメソッドtestCreateの場合、本フレームワークは以下にフィルタリングします:

idnameemail
1Alicealice@example.com
2Bobbob@example.com

シナリオ解決 ​

シナリオ名は以下の順序で解決されます:

  1. @DataSetSourceアノテーションの明示的なscenarioNames
  2. テストメソッド名（ScenarioNameResolver SPI経由）

複数シナリオ ​

単一のテストで複数のシナリオを使用できます:

java
@DataSet(sources = @DataSetSource(scenarioNames = {"scenario1", "scenario2"}))
void testMultipleScenarios() { }

指定されたシナリオのいずれかに一致する行が含まれます。

特殊値 ​

NULL値 ​

空のフィールドを使用してSQL NULLを表現します:

csv
id,name,description
1,Alice,
2,Bob,A description

行1: descriptionはNULL 行2: descriptionは"A description"

空文字列とNULL ​

ファイル内容解釈
空のフィールドNULL
空のクォートフィールド（""）空文字列

例:

csv
id,nullable_col,empty_string_col
1,,""
  • nullable_col = NULL
  • empty_string_col = ""（空文字列）

クォートされた値 ​

区切り文字や特殊文字を含む値はクォートする必要があります:

値エンコーディング
カンマを含む"value,with,commas"
クォートを含む"value ""with"" quotes"
改行を含む"line1\nline2"
空白で始まる" leading space"

ディレクトリ規約 ​

標準ディレクトリ構造 ​

src/test/resources/
└── {package}/
    └── {TestClassName}/
        ├── TABLE1.csv          # 準備データ
        ├── TABLE2.csv
        ├── load-order.txt      # テーブル順序（オプション）
        └── expected/           # 期待データ
            ├── TABLE1.csv
            └── TABLE2.csv

パッケージパス解決 ​

パッケージパスはテストクラスのパッケージをミラーリングします:

テストクラスパッケージパス
com.example.UserRepositoryTestcom/example/UserRepositoryTest/
org.app.service.OrderServiceTestorg/app/service/OrderServiceTest/

ネストされたテストクラス ​

JUnitのネストされたテストクラスの場合:

テストクラスディレクトリ
UserTest$NestedTest{package}/UserTest$NestedTest/

テーブル名の導出 ​

テーブル名はファイル名から導出されます:

ファイル名テーブル名
USERS.csvUSERS
order_items.csvorder_items
CamelCase.csvCamelCase

大文字小文字の区別はデータベース設定に依存します。

読み込み順序 ​

概要 ​

load-order.txtファイルは、データベース操作中にテーブルが処理される順序を制御します。これは、親テーブルを子テーブルより先に投入する必要がある外部キー関係を持つテーブルにとって重要です。

ファイルの場所 ​

読み込み順序ファイルはデータセットディレクトリに配置されます:

src/test/resources/
└── {package}/
    └── {TestClassName}/
        ├── load-order.txt    # 読み込み順序指定
        ├── PARENT_TABLE.csv
        └── CHILD_TABLE.csv

ファイル形式 ​

load-order.txtファイルは単純な行ベースの形式を使用します:

要素説明
テーブル名1行につき1つのテーブル名（ファイル拡張子なし）
コメント#で始まる行は無視
空行無視
空白先頭と末尾の空白はトリミング

例 ​

ファイル: load-order.txt

# 親テーブルを先に
USERS
CATEGORIES

# 子テーブルは親の後に
ORDERS
ORDER_ITEMS

デフォルト動作 ​

データセットディレクトリにload-order.txtが存在しない場合:

  1. テーブルはファイル名でアルファベット順にソートされます
  2. フレームワークはファイルを自動生成しません

注意: 他のデータベーステストフレームワークとは異なり、db-testerはload-order.txtファイルを自動作成しません。これはDbUnit互換性のため、およびテストリソースの変更を避けるための意図的な設計です。

読み込み順序ファイルを明示的に必須にするには、以下を使用します:

java
@DataSet(tableOrdering = TableOrderingStrategy.LOAD_ORDER_FILE)

load-order.txtが見つからない場合、DataSetLoadExceptionがスローされます。

操作ごとの処理順序 ​

テーブル順序はデータベース操作と以下のように相互作用します:

操作処理順序
INSERTファイル順序で処理（上から下）
DELETE, DELETE_ALLファイル順序の逆順で処理（下から上）
TRUNCATE_TABLEファイル順序の逆順で処理
CLEAN_INSERT逆順でDELETE、次に順方向でINSERT
TRUNCATE_INSERT逆順でTRUNCATE、次に順方向でINSERT

TableOrderingStrategyとの関係 ​

TableOrderingStrategy enumはテーブル順序の決定方法を制御します。詳細はデータベース操作を参照してください。

戦略動作
AUTO（デフォルト）load-order.txtが存在すれば使用、次にFKメタデータ、次にアルファベット順
LOAD_ORDER_FILEload-order.txtを必須（見つからない場合はエラー）
FOREIGN_KEYFKベースの順序付けにJDBCメタデータを使用
ALPHABETICALテーブル名でアルファベット順にソート

ベストプラクティス ​

  1. 順序ファイルをコミット: 再現可能なテストのためにload-order.txtをバージョン管理に含める
  2. 親テーブルを先に: 外部キー制約を満たすために親テーブルを子テーブルより先にリスト
  3. コメントを使用: 明らかでない順序決定の理由を文書化
  4. FK戦略を検討: 適切なFK制約を持つデータベースでは、TableOrderingStrategy.FOREIGN_KEYが手動ファイルメンテナンスなしで自動順序付けを提供

エラーハンドリング ​

エラー例外
順序ファイルを読み取れないDataSetLoadException
ファイルが必須だが見つからない（LOAD_ORDER_FILE戦略）DataSetLoadException

解析ルール ​

CSV解析 ​

RFC 4180に拡張機能を追加して準拠:

ルール説明
区切り文字カンマ（,）
クォート文字ダブルクォート（"）
エスケープシーケンス埋め込みクォートには""
改行処理CRLFとLFをサポート
先頭/末尾の空白クォートされていない限り保持

TSV解析 ​

ルール説明
区切り文字タブ（\t）
クォート文字ダブルクォート（"）
エスケープシーケンス埋め込みクォートには""
改行処理CRLFとLFをサポート

ヘッダー行の要件 ​

  • 最初の行はカラム名を含む必要があります
  • カラム名はテーブル内で一意である必要があります
  • 空のカラム名は許可されません
  • シナリオマーカーカラムはオプションです

データ型処理 ​

すべての値は文字列として解析され、データベース操作中に変換されます:

データベース型文字列変換
INTEGER, BIGINT整数として解析
DECIMAL, NUMERICBigDecimalとして解析
VARCHAR, TEXTそのまま使用
DATEISO形式で解析（YYYY-MM-DD）
TIMESTAMPISO形式で解析（YYYY-MM-DD HH:MM:SS）
BOOLEAN"true"/"false"として解析（大文字小文字を区別しない）
BLOBBase64デコード
CLOBそのまま使用

エンコーディング ​

  • ファイルエンコーディング: UTF-8
  • BOM（Byte Order Mark）: サポートされていますがオプション

エラーハンドリング ​

エラー動作
ファイルが見つからないDataSetLoadException
無効な形式行番号付きのDataSetLoadException
カラム数の不一致DataSetLoadException
解析エラー詳細付きのDataSetLoadException

関連仕様 ​

Released under the MIT License.

Copyright © 2025 Seiji Kohara