setup-sdk-testing

SDK テストのセットアップ

コントラクトテスト、カスタム Arazzo ワークフロー、またはライブ API に対する統合テストを使用して、Speakeasy で生成した SDK のテストをセットアップして実行します。

コンテンツガイド

トピック	ガイド
Arazzo リファレンス	content/arazzo-reference.md

Arazzo リファレンスでは、ワークフロー、ステップ、成功条件、環境変数、操作の連鎖に関する構文をすべて確認できます。

使用するタイミング

• 生成した SDK の自動テストをセットアップするとき
• gen.yaml でコントラクトテストの生成を有効にするとき
• Arazzo で複数ステップの API ワークフローのカスタムテストを作成するとき
• ライブ API に対する統合テストを設定するとき
• ResponseValidationError またはテスト失敗の原因を調査するとき
• ユーザーが「SDK のテスト」「コントラクトテスト」「Arazzo テスト」「speakeasy test」「モックサーバー」「テスト生成」と言ったとき

入力

入力	必須	説明
gen.yaml	はい	生成設定。コントラクトテストはここで有効にします
OpenAPI 仕様	はい	SDK の生成元となる API 仕様
ターゲット言語	はい	typescript、python、go、または java（コントラクトテストに対応）
.speakeasy/tests.arazzo.yaml	いいえ	カスタム Arazzo テスト定義
ライブ API の認証情報	いいえ	統合テストの場合にのみ必要です

出力

出力	場所
生成されたコントラクトテスト	SDK 出力内の tests/ ディレクトリ
モックサーバーの設定	コントラクトテストと同時に自動生成
Arazzo テスト結果	speakeasy test のターミナル出力
CI ワークフロー	.github/workflows/（統合テストが設定されている場合）

前提条件

• Speakeasy CLI がインストールされ、認証済みであること（speakeasy auth login）
• SDK 生成のセットアップが機能していること（gen.yaml と OpenAPI 仕様）
• 統合テストの場合：環境変数として設定された API 認証情報

判断基準

必要な内容に基づいて、適切なテスト方法を選択します。

必要な内容	方法	工数
SDK の型とメソッドが API コントラクトと一致することを確認する	コントラクトテスト	低（自動生成）
複数ステップの API ワークフロー（作成後に検証など）をテストする	カスタム Arazzo テスト	中
実データを使ってライブ API に対する動作を検証する	統合テスト	高
SDK を再生成するたびにリグレッションを検出する	コントラクトテスト + CI	低
認証フローをエンドツーエンドでテストする	統合テスト	高
データ依存関係のある連鎖操作を検証する	カスタム Arazzo テスト	中

まずはコントラクトテストから始めましょう。 自動生成され、最も一般的な問題を検出できます。ワークフローのカバレッジにはカスタム Arazzo テストを追加し、ライブ API の検証が必要な場合にのみ統合テストを追加します。

コマンド

コントラクトテストを有効にする

gen.yaml に追加します。

generation:
  tests:
    generateTests: true

次に、SDK を再生成します。

speakeasy run --output console

テストを実行する

# Run all Arazzo-defined tests (contract + custom)
speakeasy test

# Run tests for a specific target
speakeasy test --target my-typescript-sdk

# Run with verbose output for debugging
speakeasy test --verbose

CI で実行する

テスト生成が有効になっている場合、Speakeasy GitHub Actions ワークフローでコントラクトテストが自動的に実行されます。コントラクトテストに追加の CI 設定は必要ありません。

例

1. コントラクトテスト（クイックスタート）

gen.yaml でテスト生成を有効にします。

generation:
  tests:
    generateTests: true

SDK を再生成します。

speakeasy run --output console

生成されたテストを実行します。

speakeasy test

CLI は OpenAPI 仕様からテストを生成し、仕様に準拠したレスポンスを返すモックサーバーを作成して、SDK がリクエストとレスポンスを正しく処理することを検証します。

2. カスタム Arazzo テスト

.speakeasy/tests.arazzo.yaml を作成または編集します。

arazzo: 1.0.0
info:
  title: Custom SDK Tests
  version: 1.0.0

sourceDescriptions:
  - name: my-api
    type: openapi
    url: ./openapi.yaml

workflows:
  - workflowId: create-and-verify-resource
    steps:
      - stepId: create-resource
        operationId: createResource
        requestBody:
          payload:
            name: "test-resource"
            type: "example"
        successCriteria:
          - condition: $statusCode == 201
        outputs:
          resourceId: $response.body#/id

      - stepId: get-resource
        operationId: getResource
        parameters:
          - name: id
            in: path
            value: $steps.create-resource.outputs.resourceId
        successCriteria:
          - condition: $statusCode == 200
          - condition: $response.body#/name == "test-resource"

  - workflowId: list-and-filter
    steps:
      - stepId: list-resources
        operationId: listResources
        parameters:
          - name: limit
            in: query
            value: 10
        successCriteria:
          - condition: $statusCode == 200

カスタムテストを実行します。

speakeasy test

Arazzo テストで環境変数を使用する

機密値には環境変数を参照します。

steps:
  - stepId: authenticated-request
    operationId: getProtectedResource
    parameters:
      - name: Authorization
        in: header
        value: Bearer $env.API_TOKEN
    successCriteria:
      - condition: $statusCode == 200

特定のテストを無効にする

オーバーレイを使用すると、生成されたテストを削除せずに無効にできます。

overlay: 1.0.0
info:
  title: Disable flaky test
actions:
  - target: $["workflows"][?(@.workflowId=="flaky-test")]
    update:
      x-speakeasy-test:
        disabled: true

3. 統合テスト

ライブ API をテストするには、SDK ファクトリパターンを使用します。

TypeScript の例：

import { SDK } from "./src";

function createTestClient(): SDK {
  return new SDK({
    apiKey: process.env.TEST_API_KEY,
    serverURL: process.env.TEST_API_URL ?? "https://api.example.com",
  });
}

describe("Integration Tests", () => {
  const client = createTestClient();

  it("should list resources", async () => {
    const result = await client.resources.list({ limit: 5 });
    expect(result.statusCode).toBe(200);
    expect(result.data).toBeDefined();
  });

  it("should create and delete resource", async () => {
    // Create
    const created = await client.resources.create({ name: "integration-test" });
    expect(created.statusCode).toBe(201);

    // Cleanup
    const deleted = await client.resources.delete({ id: created.data.id });
    expect(deleted.statusCode).toBe(204);
  });
});

Python の例：

import os
import pytest
from my_sdk import SDK

@pytest.fixture
def client():
    return SDK(
        api_key=os.environ["TEST_API_KEY"],
        server_url=os.environ.get("TEST_API_URL", "https://api.example.com"),
    )

def test_list_resources(client):
    result = client.resources.list(limit=5)
    assert result.status_code == 200
    assert result.data is not None

@pytest.mark.cleanup
def test_create_and_delete(client):
    created = client.resources.create(name="integration-test")
    assert created.status_code == 201
    try:
        fetched = client.resources.get(id=created.data.id)
        assert fetched.data.name == "integration-test"
    finally:
        client.resources.delete(id=created.data.id)

統合テスト用の GitHub Actions CI：

name: Integration Tests
on:
  schedule:
    - cron: "0 6 * * 1-5"
  workflow_dispatch:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: speakeasy-api/sdk-generation-action@v15
        with:
          speakeasy_version: latest
      - run: speakeasy test
        env:
          SPEAKEASY_API_KEY: ${{ secrets.SPEAKEASY_API_KEY }}
      - name: Run integration tests
        run: npm test -- --grep "integration"
        env:
          TEST_API_KEY: ${{ secrets.TEST_API_KEY }}
          TEST_API_URL: ${{ secrets.TEST_API_URL }}

避けるべきこと

• 次のことはしないでください：コントラクトテストを省略し、すぐに統合テストに進むこと。コントラクトテストは無料で実行でき、ほとんどの問題を検出できます
• 次のことはしないでください：Arazzo テストファイルに API キーやシークレットをハードコードすること。$env.VARIABLE_NAME 構文を使用してください
• 次のことはしないでください：自動生成されたテストファイルを直接変更すること。再生成時に上書きされます。代わりにカスタム Arazzo テストを使用してください
• 次のことはしないでください：失敗したコントラクトテストを調査せずに無効化すること。通常、ResponseValidationError は仕様と API の同期が取れていないことを意味します
• 次のことはしないでください：本番環境で破壊的な操作を伴う統合テストを実行すること。必ずテスト環境またはステージング環境を使用してください
• 次のことはしないでください：すべての言語がコントラクトテストをサポートしていると思い込むこと。現在サポートされている言語は TypeScript、Python、Go、Java です

トラブルシューティング

コントラクトテストでの ResponseValidationError

SDK のレスポンスが OpenAPI 仕様と一致していません。よくある原因は次のとおりです。

1. 仕様が古い：最新の API 仕様から再生成してください
2. 必須フィールドが不足している：仕様内の required 配列が実際の API レスポンスと一致しているか確認してください
3. 型が一致しない：スキーマ定義の type フィールドと format フィールドを確認してください

# Regenerate with latest spec and re-run tests
speakeasy run --output console && speakeasy test --verbose

ローカルではテストが成功するのに CI では失敗する

1. すべての環境変数が CI のシークレットに設定されていることを確認してください
2. CI ランナーがモックサーバーのポートにネットワークアクセスできることを確認してください
3. Speakeasy CLI のバージョンがローカルと CI で一致していることを確認してください

speakeasy test コマンドが見つからない

Speakeasy CLI を更新してください。

speakeasy update

モックサーバーの起動に失敗する

1. デフォルトのモックサーバーポートで競合がないか確認してください
2. OpenAPI 仕様が有効であることを確認してください：speakeasy lint openapi -s spec.yaml
3. generateTests: true が gen.yaml に設定されており、SDK が再生成されていることを確認してください

カスタム Arazzo テストが実行されない

1. ファイルが .speakeasy/tests.arazzo.yaml にあることを確認してください
2. operationId の値が OpenAPI 仕様内の値と完全に一致していることを確認してください
3. YAML 構文を検証してください。インデントエラーが最もよくある原因です

統合テストが断続的に失敗する

1. ネットワークに依存するテストに再試行ロジックを追加してください
2. 衝突を避けるため、タイムスタンプを付けた一意のリソース名を使用してください
3. テストが失敗した場合でもクリーンアップが実行されるようにしてください（finally または afterEach を使用）