testing-integration

目的

このスキルは、Supertest（Node.js）、httpx（Python）、テスト環境の管理に使うTestcontainers、コントラクトテストに使うPactなどのツールに重点を置き、APIやサービスの統合テストを支援します。サービス間のやり取り、データベースとの統合、APIコントラクトをエンドツーエンドで検証できます。

使用する場面

実環境でAPIエンドポイントを検証するとき、サービス統合（データベースや外部サービスとの統合など）をテストするとき、コンテナ化されたテストを実行するとき、またはマイクロサービス間のコントラクトを適用するときに、このスキルを使用してください。CI/CDパイプラインでの回帰テストや、依存関係のモックでは不十分な場合にも適用できます。

主な機能

• Supertestを使用してNode.jsアプリのHTTP APIテストを実行します。モックやアサーションにも対応しています。
• Pythonでhttpxを使用して非同期HTTPリクエストを実行し、データベースと連携します。
• Testcontainersを使用してテストコンテナを管理し、分離された環境（Dockerベースのデータベースなど）を起動します。
• Pactを使用してコントラクトテストを実施し、APIのプロバイダーとコンシューマー間の合意を定義して検証します。
• APIと外部サービスやデータベースを接続するなど、サービス統合テストをサポートします。

使用パターン

このスキルを使用するには、まず必要な依存関係をインストールします（例：npmまたはpipを使用）。プロジェクトにテストファイルを設定し、$API_BASE_URLなどの変数を使って環境を構成してから、テストランナーでテストを実行します。APIテストでは、リクエストを送信してレスポンスを検証するようにコードを構成します。コントラクトテストでは、別々のファイルでPactを定義し、プロバイダーに対して検証します。副作用を避けるため、常にコンテナを使ってテストを分離してください。使用パターンの例：ツールをインポートし、テスト関数を定義して、リクエストを送信し、2～3行でアサーションを処理します。

主なコマンド/API

• Supertest（Node.js）：Expressアプリのテストにsupertestを使用します。コマンド：npm install supertest。コード例：

  const request = require('supertest');
  const app = require('./app');
  request(app).get('/api/users').expect(200);
  

  CLIフラグ：npx jest --runInBandで実行すると、テストを順次実行できます。
• httpx（Python）：非同期HTTPテストに使用します。コマンド：pip install httpx。コード例：

  import httpx
  response = httpx.get('http://example.com/api/data', headers={'Authorization': f'Bearer {os.environ.get("API_KEY")}'}).json()
  assert response['status'] == 'success'
  

  APIエンドポイント：クエリパラメーター（例：?limit=10）を含むhttps://api.service.com/endpointのようなURLを渡します。
• Testcontainers：統合テスト用のコンテナを起動します。コマンド：pom.xmlまたはrequirementsに追加します。コード例：

  GenericContainer container = new GenericContainer("postgres:13").withExposedPorts(5432);
  container.start();
  String jdbcUrl = container.getJdbcUrl();
  

  設定形式：YAMLでDockerイメージの仕様を指定します。例：image: postgres:13と、$DB_PASSWORDなどの環境変数を使用します。
• Pact（コントラクトテスト）：コントラクトを定義して検証します。コマンド：npm install @pact-foundation/pactまたはpip install pact-python。コード例：

  const { Pact } = require('@pact-foundation/pact');
  const pact = new Pact({ consumer: 'MyConsumer', provider: 'MyProvider' });
  pact.addInteraction({ state: 'default', uponReceiving: 'a request' });
  

  API：検証には/pacts/provider/MyProvider/consumer/MyConsumer/verificationのようなエンドポイントを使用し、$PACT_BROKER_TOKENで認証します。

統合に関する注意

ビルドツールに追加してこのスキルを統合します。Node.jsではJestまたはMochaの設定に含め、Pythonではpytestのフィクスチャを使用します。データベース接続には$DATABASE_URL、認証が必要なリクエストには$SERVICE_API_KEYなどの環境変数を設定します。コンテナとの統合では、Dockerがインストールされていることを確認し、Testcontainersを使用してサービスを接続します（例：withExposedPorts(8080)でポートを公開）。Pactと組み合わせる場合は、Pact BrokerにPactを公開します（例：pact-broker publish --broker-url=$PACT_BROKER_URLを使用）。設定形式：PactファイルにはJSONを使用します。例：{ "interactions": [...] }。また、run: docker-compose up -dなどのステップを追加し、GitHub ActionsなどのCIツールとの互換性を確保してください。

エラー処理

リクエストをtry-catchブロックで囲んでエラーを処理します。Supertestでは、レスポンスのステータスと本文を確認します。例：.expect(200)が失敗した場合、console.error(response.error)でエラーをログに記録します。httpxでは、ネットワークの問題に対処するためhttpx.HTTPErrorをキャッチします。例：

try:
    response = httpx.get(url)
    response.raise_for_status()
except httpx.HTTPError as e:
    print(f"Error: {e} - Check $API_BASE_URL")

Testcontainersでは、テストの前にcontainer.isRunning()でコンテナの起動を確認します。Pactでは、pact.verify()を使用し、不一致がある場合はPactファイルを確認して対処します。よくあるパターン：リトライには環境変数（例：$RETRY_COUNT=3）を使用し、スタックトレースとともに詳細なエラーをログに記録します。

具体的な使用例

1. Supertest を使った API 統合テスト：データベースを使用する Node.js アプリでユーザーエンドポイントをテストするには、まず $DB_URL=postgres://user:pass@localhost:5432/db を設定します。テストファイルを作成します。Supertest をインポートし、GET リクエストを送信して、レスポンスを検証します。npx jest tests/integration.test.js で実行します。これにより、API がデータベースに接続し、データを返すことを確認できます。

2. Pact を使ったコントラクトテスト：コンシューマーとプロバイダーの構成では、インタラクションを含む pact をファイル（例：pacts/my-pact.json）に定義します。$PACT_BROKER_TOKEN を渡して、プロバイダーのエンドポイント（例：http://provider.com）に対して pact.verify() を使用します。npx pact-verifier --provider-base-url=$PROVIDER_URL で実行します。これにより、コンシューマーの期待がプロバイダーの実装と一致することを確認できます。

グラフの関係

• 関連するクラスター：「testing」（例：unit-testing スキルとタグを共有）。
• スキル「api-development」とは、API ワークフロー向けの integration-test タグを通じてつながっています。
• Pact ベースの検証向けの contract-test タグを通じて、「contract-management」につながっています。
• データベーステスト用のテストコンテナーにより、「database-integration」に関連付けられています。