test-component

Keboola コンポーネントテスター

テスト方針

優先度順に、次の3つのレベルがあります。

1. Datadir テスト — KBC_DATADIR の構造を使用する機能テスト。すべてのコンポーネントで主に使用する方法です
2. ユニットテスト — 変換、検証、設定の解析を対象とする分離されたロジックテストです
3. VCR 機能テスト — 外部 HTTP API を呼び出すコンポーネント向けです（エクストラクター／ライターでは手動モックより推奨されます）

VCR とモックの選択

コンポーネントが外部 HTTP 呼び出しを行う場合は、VCR（keboola.datadirtest）を使用します。

• 実際の API とのやり取りを一度記録し、認証情報なしで CI で決定論的に再生します
• 手作業で作成したモックより現実に近く、API コントラクトの変更を検出できます
• エクストラクターでは必須です。外部 API を呼び出すライターでも推奨されます

次の場合は、モック（unittest.mock）を使用します。

• 純粋なロジック、変換、検証のコードをテストする場合
• 個々の関数のユニットテストを作成する場合
• コンポーネントが HTTP 呼び出しを行わない場合（アプリケーション、純粋な変換）

VCR のセットアップ手順

1. pyproject.toml の開発依存関係に keboola.datadirtest>=2.0.0 を追加し、uv sync -U を実行します
2. component-developer:component-defaults のアセットから tests/test_functional.py をコピーします
3. コンポーネント（src/component.py、src/configuration.py、component_config/configSchema.json）を読み、tests/setup/configs.json を作成します。vcr-configs-format.md を参照してください
4. 認証が必要な API の場合：ユーザーに実際の認証情報を尋ね、secrets.json に保存します（.gitignore に含まれていることを確認してください）
5. 記録用のスキャフォールドを実行します：uv run python -m keboola.datadirtest scaffold [--secrets secrets.json] [--chain-state]
6. カセットにサニタイズされていない動的な値がないか確認します。vcr-sanitizers.md を参照してください
7. .gitignore、Dockerfile（COPY tests/ tests）、push.yml（python -m pytest を使用）を更新します
8. ローカルと Docker で python -m pytest を実行して確認します

すべてのスキャフォールドコマンドについては、vcr-quickstart.md を参照してください。よくある失敗については、vcr-troubleshooting.md を参照してください。

リファレンス

ファイル	読むタイミング
references/datadir-tests.md	Datadir テストのセットアップ — ディレクトリ構造、config.json、出力アサーション、状態、エラーケース
references/unit-and-mock-tests.md	ユニットテスト、モックのパターン、freezegun、コンポーネントの種類別の説明
references/vcr-configs-format.md	configs.json の作成 — ラップ形式、OAuth、ライター、カバレッジのガイドライン
references/vcr-sanitizers.md	VCR_SANITIZERS の追加 — DefaultSanitizer、ResponseUrlSanitizer、QueryParamSanitizer
references/vcr-quickstart.md	すべてのスキャフォールド／記録コマンドとリポジトリのレイアウト
references/vcr-troubleshooting.md	よくある VCR の失敗と修正方法
references/vcr-debug-from-platform.md	Keboola プラットフォームのデバッグジョブ出力（stage_output.zip）を使ったリグレッションテスト