PHPで外部APIを呼び出すコードのユニットテスト手法を徹底解説

PHPで外部APIを利用する際、適切なユニットテストを行うことは、コードの信頼性を高めるために重要です。API呼び出しは外部のサービスに依存するため、ネットワーク接続やAPIサーバーの状態に影響を受けやすく、安定したテストが難しい側面があります。特に実際のAPIエンドポイントにアクセスするテストでは、意図しないエラーが発生するリスクがあり、再現性のあるテストを行うためにモック化の技術が必須となります。

本記事では、PHPで外部APIを呼び出すコードを対象にしたユニットテストの手法を解説します。モックオブジェクトの作成やGuzzleの活用法、エラーハンドリングのテストまで、効果的なテストを行うための基本から応用までを網羅します。

外部APIのユニットテストの課題

外部APIを用いたアプリケーションのユニットテストにはいくつかの課題が伴います。最も大きな課題は、外部サービスへの依存性です。外部APIに直接リクエストを送ると、ネットワーク接続の問題やAPIサーバーの障害などが原因で、テスト結果が安定しない場合があります。加えて、テストのたびに外部APIを呼び出すことは、料金の発生やAPI制限に触れるリスクがあるため、効率的ではありません。

さらに、実環境とは異なる状況をシミュレートしづらいという問題もあります。たとえば、特定のエラーレスポンスやタイムアウトなどを意図的に発生させることは困難です。このため、ユニットテストでのAPI呼び出しには、モックオブジェクトの利用やリクエストのシミュレーションが有効となります。

ユニットテストでのモック化とは

モック化は、ユニットテストにおいて実際のオブジェクトを仮のオブジェクトで置き換える手法です。これにより、外部APIの挙動をシミュレートし、再現性のあるテストを可能にします。モックオブジェクトは、実際のAPI呼び出しを行わずに、指定したレスポンスやエラーレスポンスを返すことができるため、APIへのアクセスが不要となり、テストの迅速化や信頼性向上に役立ちます。

モック化を用いると、APIの返すべきデータやエラー状況を自由に設定でき、ネットワークや外部サービスの影響を受けずにテストを実行できます。また、特定のエッジケースやエラーケースを簡単に再現できるため、実運用に近いテストが可能です。これにより、APIの依存性が解消され、テストコード自体の可読性も向上します。

PHPでモックオブジェクトを作成する方法

PHPでモックオブジェクトを作成するには、PHPUnitのモック機能を利用するのが一般的です。PHPUnitは、PHP向けのユニットテストフレームワークであり、簡単にモックオブジェクトを作成・管理できるため、API呼び出しのテストには非常に便利です。

PHPUnitを使ったモックの基本的な手順は以下の通りです：

1. モックオブジェクトの作成

モックを作成するには、createMock()メソッドを使用します。このメソッドは、指定したクラスのモックを生成し、テストで任意の振る舞いを設定できます。例えば、APIクライアントクラスApiClientのモックを作成する場合、以下のように記述します：

$mockClient = $this->createMock(ApiClient::class);

2. モックメソッドの設定

次に、モックオブジェクトが返すべきレスポンスや挙動を設定します。method()メソッドで呼び出したいメソッドを指定し、willReturn()やwillThrowException()を使って戻り値や例外を定義します。

$mockClient->method('fetchData')
           ->willReturn(['status' => 'success', 'data' => [/* サンプルデータ */]]);

この例では、fetchDataメソッドが呼び出された際、成功ステータスとサンプルデータが返るように設定しています。

3. エラーや例外のシミュレーション

特定のエラーや例外の状況をテストする場合、willThrowException()を用いて、API呼び出し時に意図的に例外を発生させることができます。

$mockClient->method('fetchData')
           ->willThrowException(new Exception('API Error'));

これにより、fetchDataメソッドが呼ばれると例外が発生し、エラーハンドリングのテストが可能になります。

PHPでモックオブジェクトを活用することで、安定したユニットテストの実装が可能となり、APIの依存度を低減できます。

PHPUnitでのモック化と外部APIのテスト手法

PHPUnitはPHPでのユニットテストを効率的に行うためのフレームワークであり、外部APIのテストには非常に適しています。PHPUnitでは、モックオブジェクトを使用してAPIの動作をシミュレートし、リクエストの送信やレスポンスの確認が可能です。ここでは、PHPUnitでのモック化と、外部APIのユニットテスト方法について詳しく解説します。

1. PHPUnitによるモックの基本設定

まず、PHPUnitで外部APIクライアントのモックオブジェクトを生成します。createMock()メソッドを使用することで、実際のAPIを呼び出さずにテストを実施でき、モックオブジェクトのメソッドの戻り値を制御することが可能です。

$mockApiClient = $this->createMock(ApiClient::class);

2. APIの成功レスポンスのテスト

成功レスポンスをテストする際には、モックの特定のメソッドが期待するデータを返すよう設定します。例えば、APIから期待するデータが返ってくるかを確認するためには、以下のように記述します。

$mockApiClient->method('getData')
              ->willReturn(['status' => 'success', 'data' => [/* 実際のデータ構造 */]]);

次に、このモックを使って実際の処理が期待通りに動作するかを確認します。

$this->assertEquals('success', $mockApiClient->getData()['status']);

3. エラーレスポンスのテスト

APIがエラーレスポンスを返す場合のテストも同様に行えます。例えば、リクエストエラーやサーバーエラーをシミュレーションする場合、willThrowException()で例外を設定します。

$mockApiClient->method('getData')
              ->willThrowException(new Exception('API Error'));

この例では、getDataメソッドが呼び出されると、例外が発生するため、エラーハンドリングが正しく機能するかをテストできます。

4. モック化によるテストの再現性

モック化によって、テスト時に外部APIの状態に依存せず、一貫した結果を得ることができます。たとえば、インターネット接続が不安定な状況や、APIの仕様変更があっても、モックオブジェクトを使えば安定したテストが可能です。

このように、PHPUnitでモックオブジェクトを活用することで、外部APIに依存しない、再現性の高いテスト環境を構築でき、APIのレスポンスの種類に応じた柔軟なテストが可能になります。

Guzzleを用いたAPIリクエストのモックテスト

Guzzleは、PHPで広く使用されるHTTPクライアントライブラリで、APIリクエストの管理とモックテストに非常に役立ちます。特に、Guzzleのモック機能を使用することで、実際のAPIを呼び出さずにリクエストやレスポンスのシミュレーションが可能です。ここでは、Guzzleを用いたモックテストの具体的な手法について解説します。

1. Guzzleでのモックハンドラーの設定

Guzzleには、APIレスポンスを模倣するためのモックハンドラーが用意されています。これにより、外部のAPIサーバーにリクエストを送信せずに、指定したレスポンスを返すよう設定できます。

まず、モックハンドラーとクライアントをセットアップします。

use GuzzleHttp\Client;
use GuzzleHttp\Handler\MockHandler;
use GuzzleHttp\HandlerStack;
use GuzzleHttp\Psr7\Response;

// モックハンドラーを作成し、レスポンスを定義
$mock = new MockHandler([
    new Response(200, [], json_encode(['status' => 'success', 'data' => [/* サンプルデータ */]])),
]);

// ハンドラースタックを作成し、クライアントに設定
$handlerStack = HandlerStack::create($mock);
$client = new Client(['handler' => $handlerStack]);

この設定により、Guzzleクライアントは実際のAPIを呼び出さずに、定義したレスポンスを返します。

2. モックレスポンスの利用方法

上記で設定したGuzzleクライアントを利用してAPIを呼び出すと、事前に定義されたレスポンスが返されます。例えば、GETリクエストを送信し、返されたデータが期待通りかを確認します。

$response = $client->request('GET', '/test-endpoint');
$responseData = json_decode($response->getBody(), true);

// レスポンス内容のテスト
$this->assertEquals('success', $responseData['status']);

この例では、/test-endpointへのリクエストが常にモックレスポンスを返すため、テストが安定します。

3. エラーレスポンスのテスト

モックハンドラーに複数のレスポンスを定義し、エラーのシミュレーションも可能です。例えば、404エラーや500エラーをモックする場合は以下のように設定します。

$mock = new MockHandler([
    new Response(404, [], 'Not Found'),
    new Response(500, [], 'Internal Server Error'),
]);

これにより、Guzzleクライアントで順番に404エラーと500エラーをテストできます。これにより、エラーハンドリングの動作確認が可能になります。

Guzzleを用いたモックテストは、実際のAPI呼び出しを行わずにさまざまなレスポンスをシミュレートできるため、APIの依存性を排除し、効率的なテストを行うための強力な手段となります。

外部APIのレスポンスを検証する方法

モックを使用して外部APIのレスポンスをシミュレートすることで、APIの正確な動作を検証できます。APIのレスポンスにはさまざまな形式があり、正確なレスポンスデータを検証することが重要です。ここでは、APIレスポンスの内容とその検証方法について解説します。

1. 正常レスポンスの検証

正常なAPIレスポンスの検証では、レスポンスデータの内容や構造が期待通りかを確認します。たとえば、ステータスコードやデータ形式、レスポンス内の特定のフィールドが正しいかをテストします。

// レスポンスを取得
$response = $client->request('GET', '/api/endpoint');
$responseData = json_decode($response->getBody(), true);

// ステータスコードの確認
$this->assertEquals(200, $response->getStatusCode());

// レスポンス内容の確認
$this->assertArrayHasKey('data', $responseData);
$this->assertEquals('success', $responseData['status']);

このようにして、APIのレスポンスが成功ステータスであることや、データのフィールドが期待通りであることを確認できます。

2. エラーレスポンスの検証

APIからエラーが返された場合、そのエラーハンドリングが正しく行われるかをテストすることも重要です。たとえば、404エラーや500エラーなど、異なるエラーレスポンスに応じてアプリケーションが適切な処理を行うかを確認します。

$mock = new MockHandler([
    new Response(404, [], json_encode(['error' => 'Not Found'])),
]);
$client = new Client(['handler' => HandlerStack::create($mock)]);

// エラーレスポンスのテスト
try {
    $client->request('GET', '/invalid-endpoint');
} catch (ClientException $e) {
    $response = $e->getResponse();
    $responseData = json_decode($response->getBody(), true);

    $this->assertEquals(404, $response->getStatusCode());
    $this->assertEquals('Not Found', $responseData['error']);
}

この例では、404エラーが発生した際に、エラー内容が正しくレスポンスに含まれているかを確認しています。

3. データの妥当性検証

APIレスポンスのデータが正しいフォーマットであることや、特定の条件を満たしているかを検証することも大切です。たとえば、日時や数値が特定の範囲に収まっているか、文字列が期待するパターンに一致するかなどを確認します。

$this->assertIsArray($responseData['data']);
$this->assertGreaterThan(0, count($responseData['data']));
$this->assertMatchesRegularExpression('/^\d{4}-\d{2}-\d{2}$/', $responseData['data']['date']);

このように、レスポンスの妥当性を検証することで、データが正しく返ってきているかを保証できます。

APIレスポンスの検証は、APIが期待通りに動作することを確認するための基本的なステップです。モックを使用したテストにより、さまざまなケースに対して迅速かつ信頼性の高いテストが行えるようになります。

非同期APIリクエストのユニットテスト

非同期APIリクエストは、実行の順番が保証されないため、ユニットテストでのテストが難しくなります。非同期リクエストのテストでは、リクエストの完了を待ち、レスポンスが期待通りであることを確認する必要があります。ここでは、PHPで非同期リクエストをテストするための手法と注意点について解説します。

1. 非同期リクエストとは

非同期リクエストは、リクエストが完了する前にコードが次に進むリクエスト形式です。これにより、他の処理をブロックせずに並行して実行でき、レスポンスが戻ってきたタイミングで結果を処理するコールバック関数が使用されます。GuzzleのsendAsyncメソッドを使うことで、PHPでも非同期リクエストが可能です。

2. 非同期リクエストのモック化

PHPUnitで非同期APIリクエストをテストする際には、モックを使用してリクエストの完了タイミングを制御できます。GuzzleではMockHandlerを使って非同期レスポンスをシミュレーションします。

use GuzzleHttp\Promise\PromiseInterface;
use GuzzleHttp\Psr7\Response;
use GuzzleHttp\Handler\MockHandler;
use GuzzleHttp\HandlerStack;
use GuzzleHttp\Client;

// モックハンドラーに非同期レスポンスを設定
$mock = new MockHandler([
    new Response(200, [], json_encode(['status' => 'success', 'data' => 'Async data'])),
]);

$handlerStack = HandlerStack::create($mock);
$client = new Client(['handler' => $handlerStack]);

// 非同期リクエストの送信
$promise = $client->getAsync('/async-endpoint');

このように、非同期で返されるレスポンスを事前に設定し、リクエストの完了をシミュレーションします。

3. 非同期レスポンスの検証

非同期リクエストの結果をテストするには、レスポンスが返ってくるまで待機する必要があります。wait()メソッドを使うと、プロミスが解決されるまでコードが待機します。

$response = $promise->wait();
$responseData = json_decode($response->getBody(), true);

// レスポンスの確認
$this->assertEquals(200, $response->getStatusCode());
$this->assertEquals('success', $responseData['status']);
$this->assertEquals('Async data', $responseData['data']);

ここでは、非同期リクエストの完了後にレスポンス内容を確認しています。

4. エラー処理の検証

非同期リクエストにおいてもエラーケースをテストできます。たとえば、リクエストエラーやタイムアウトが発生する場合の処理を確認するには、willThrowException()でエラーを設定します。

$mock = new MockHandler([
    new Response(500, [], 'Server Error'),
]);

// 非同期リクエストでエラーをシミュレート
$promise = $client->getAsync('/async-error');
try {
    $response = $promise->wait();
} catch (\Exception $e) {
    $this->assertStringContainsString('Server Error', $e->getMessage());
}

非同期リクエストでのエラー処理が期待通りかを確認することで、アプリケーションの安定性を高めることができます。

非同期APIリクエストのテストには、プロミスの完了待機やエラー処理のテストが重要です。これにより、非同期処理が実環境で安定して動作することを確認できます。

エラーハンドリングのテスト方法

API呼び出し時に発生するエラーは、適切なハンドリングが不可欠です。エラー発生時にアプリケーションが正しく動作を停止せず、例外処理やフォールバック処理が機能するかをユニットテストで確認することが大切です。ここでは、さまざまなエラーケースに対するテスト方法について解説します。

1. ネットワークエラーのシミュレーション

ネットワークの不具合でAPIリクエストが失敗するケースをテストするには、タイムアウトエラーや接続エラーをシミュレーションします。GuzzleのwillThrowException()を使用して、例外が発生するシナリオをモックします。

use GuzzleHttp\Exception\ConnectException;
use GuzzleHttp\Psr7\Request;

$mock = new MockHandler([
    new ConnectException('Connection failed', new Request('GET', '/endpoint'))
]);

$client = new Client(['handler' => HandlerStack::create($mock)]);

try {
    $client->request('GET', '/endpoint');
} catch (ConnectException $e) {
    $this->assertStringContainsString('Connection failed', $e->getMessage());
}

この例では、接続エラーが発生した際に適切に例外が発生し、エラーメッセージが期待通りであることを確認しています。

2. HTTPステータスエラーのテスト

APIからのHTTPステータスエラー、例えば404（Not Found）や500（Internal Server Error）などのエラーレスポンスも考慮する必要があります。これらのエラーが返されたときに、アプリケーションが正しく例外処理を行うかをテストします。

$mock = new MockHandler([
    new Response(404, [], json_encode(['error' => 'Not Found'])),
]);

$client = new Client(['handler' => HandlerStack::create($mock)]);

try {
    $client->request('GET', '/invalid-endpoint');
} catch (ClientException $e) {
    $response = $e->getResponse();
    $responseData = json_decode($response->getBody(), true);

    $this->assertEquals(404, $response->getStatusCode());
    $this->assertEquals('Not Found', $responseData['error']);
}

このテストにより、404エラー時に適切なエラーハンドリングが行われ、エラーメッセージが期待通りであることを確認できます。

3. タイムアウトエラーのテスト

タイムアウトエラーが発生する場合のテストも重要です。外部APIに接続しているとき、特に通信速度が低下している状況で、適切にタイムアウトが設定され、エラーハンドリングが機能するかを確認します。

use GuzzleHttp\Exception\RequestException;

$mock = new MockHandler([
    new RequestException('Request timed out', new Request('GET', '/timeout'))
]);

$client = new Client(['handler' => HandlerStack::create($mock)]);

try {
    $client->request('GET', '/timeout');
} catch (RequestException $e) {
    $this->assertStringContainsString('timed out', $e->getMessage());
}

このテストは、タイムアウトが発生した場合に正しいエラーメッセージが表示され、適切なエラーハンドリングが行われることを確認します。

4. 例外処理の確認

予期しないエラーやサーバーエラーなど、一般的な例外処理のテストも必要です。例外が発生した際に、アプリケーションが異常終了せず、適切なフォールバック処理を行うかを確認します。

エラーハンドリングのテストは、APIの信頼性や安定性を保つために非常に重要です。モックを使用することで、あらゆるエラーシナリオを網羅的にテストし、アプリケーションの強固なエラーハンドリング機能を構築できます。

APIの認証・認可のテスト手法

認証や認可が必要なAPIでは、ユーザーの権限に応じてリクエストを制限することが重要です。認証が不十分な場合、不正アクセスが発生する恐れがあるため、認証・認可に関するテストを行い、正確なアクセス制御が実施されているか確認する必要があります。ここでは、API認証と認可をテストするための手法を解説します。

1. 認証トークンのテスト

APIでは、一般的にJWT（JSON Web Token）やAPIキーを使用してリクエストの認証が行われます。認証トークンが正しく設定されているか、またはトークンが不正な場合に適切なエラーが返されるかをテストします。

use GuzzleHttp\Exception\ClientException;

$mock = new MockHandler([
    new Response(401, [], json_encode(['error' => 'Unauthorized'])),
]);

$client = new Client(['handler' => HandlerStack::create($mock)]);

try {
    // トークンなしでリクエスト
    $client->request('GET', '/protected-resource');
} catch (ClientException $e) {
    $response = $e->getResponse();
    $responseData = json_decode($response->getBody(), true);

    $this->assertEquals(401, $response->getStatusCode());
    $this->assertEquals('Unauthorized', $responseData['error']);
}

このテストにより、トークンがない場合に401エラーが返され、正しく認証されていないリクエストが拒否されることを確認できます。

2. 有効なトークンによるリクエストのテスト

認証が成功する場合、正しいトークンを用いたリクエストが正常に処理され、期待通りのデータが返されるかをテストします。通常、リクエストに認証ヘッダーを追加して、保護されたエンドポイントへのアクセスを試みます。

$mock = new MockHandler([
    new Response(200, [], json_encode(['status' => 'success', 'data' => 'Authorized data'])),
]);

$client = new Client([
    'handler' => HandlerStack::create($mock),
    'headers' => ['Authorization' => 'Bearer valid-token']
]);

$response = $client->request('GET', '/protected-resource');
$responseData = json_decode($response->getBody(), true);

$this->assertEquals(200, $response->getStatusCode());
$this->assertEquals('success', $responseData['status']);
$this->assertEquals('Authorized data', $responseData['data']);

このテストにより、認証が成功した際に、保護されたリソースへアクセスできることを確認します。

3. 認可エラーのテスト

特定のユーザーが許可されていないリソースへのアクセスを試みた場合、適切な認可エラーレスポンスが返されるかを確認します。このテストは、権限レベルが適切に管理されていることを確認するために重要です。

$mock = new MockHandler([
    new Response(403, [], json_encode(['error' => 'Forbidden'])),
]);

$client = new Client([
    'handler' => HandlerStack::create($mock),
    'headers' => ['Authorization' => 'Bearer valid-token']
]);

try {
    $client->request('GET', '/restricted-resource');
} catch (ClientException $e) {
    $response = $e->getResponse();
    $responseData = json_decode($response->getBody(), true);

    $this->assertEquals(403, $response->getStatusCode());
    $this->assertEquals('Forbidden', $responseData['error']);
}

この例では、アクセス権がないユーザーがリソースにアクセスしようとした場合、403エラーが返され、正しいアクセス制御が行われていることを確認しています。

4. トークンの有効期限の確認

APIトークンの有効期限が切れた場合、適切なエラーメッセージが返され、再認証が要求されることをテストします。これにより、セッションの安全性を確認できます。

$mock = new MockHandler([
    new Response(401, [], json_encode(['error' => 'Token expired'])),
]);

$client = new Client([
    'handler' => HandlerStack::create($mock),
    'headers' => ['Authorization' => 'Bearer expired-token']
]);

try {
    $client->request('GET', '/protected-resource');
} catch (ClientException $e) {
    $response = $e->getResponse();
    $responseData = json_decode($response->getBody(), true);

    $this->assertEquals(401, $response->getStatusCode());
    $this->assertEquals('Token expired', $responseData['error']);
}

このテストでは、有効期限が切れたトークンが使用された場合に、正しく再認証を求められるかを確認しています。

APIの認証と認可のテストは、アプリケーションのセキュリティを保つために非常に重要です。モックによってさまざまなケースを再現することで、アクセス制御が適切に行われているかを確認し、不正アクセスを防ぐための強固な認証・認可の実装を支援します。

実際のAPI環境での動作確認方法

ユニットテストでモックを使用してAPIの挙動をシミュレーションした後、実際のAPI環境で動作確認を行うことは重要です。これにより、テスト環境では確認できなかった実際のネットワークやサーバーの応答を確認し、APIが期待通りに動作するかを検証できます。ここでは、実際のAPI環境でのテスト方法とその注意点について解説します。

1. ステージング環境でのテスト

本番環境に影響を与えないよう、まずステージング環境を利用して動作確認を行います。ステージング環境では、本番環境と同様の構成でAPIが動作するため、リリース前に本番環境に近い条件でテストできます。

2. 実際のデータを使ったレスポンスの確認

実際のAPIエンドポイントにリクエストを送信し、レスポンスが期待通りであるかを確認します。認証が必要なエンドポイントや特定のパラメータが含まれるリクエストを送信し、レスポンスが正確に返ってくるかを検証します。

$client = new Client(['base_uri' => 'https://api.example.com']);
$response = $client->request('GET', '/real-endpoint', [
    'headers' => ['Authorization' => 'Bearer real-token']
]);
$responseData = json_decode($response->getBody(), true);

$this->assertEquals(200, $response->getStatusCode());
$this->assertArrayHasKey('data', $responseData);

このテストでは、実際のAPIレスポンスを確認し、期待通りのデータが返っているかをチェックします。

3. リクエストのパフォーマンスと応答時間の測定

実際の環境では、APIの応答速度やパフォーマンスも重要な要素です。リクエストごとのレスポンスタイムを計測し、遅延が許容範囲内に収まっているかを確認します。APIのレスポンスが遅い場合、ユーザーエクスペリエンスに影響が出るため、最適化が必要になる場合があります。

$start = microtime(true);
$response = $client->request('GET', '/real-endpoint');
$end = microtime(true);
$duration = $end - $start;

$this->assertLessThan(2, $duration); // 応答時間が2秒以内であることを確認

このように、APIの応答時間が適切かを確認し、性能が基準を満たしているかを検証します。

4. エラーハンドリングの検証

本番環境では予期しないエラーが発生することもあるため、エラーハンドリングが正常に機能するかも確認します。ネットワーク障害やAPIサーバーの一時的なダウンを想定し、アプリケーションが適切にリトライやフォールバックを行うかテストします。

5. ログ出力の確認

本番環境では、エラーや警告を適切に記録することも重要です。APIエラー時にログが出力され、必要に応じて管理者が確認できるようにしておきます。これにより、問題が発生した際に迅速な対応が可能になります。

実際のAPI環境での動作確認により、モックテストでは見つからなかった問題やパフォーマンスの課題を特定でき、より実運用に近い信頼性の高いAPIを構築できます。

まとめ

本記事では、PHPで外部APIを呼び出すコードに対するユニットテストの方法について詳しく解説しました。モックオブジェクトやGuzzleのモックハンドラーを使ったテスト手法から、非同期リクエストやエラーハンドリング、認証・認可のテスト方法、さらに実際のAPI環境での動作確認まで、幅広い視点で効果的なテスト方法を紹介しました。

適切なユニットテストを行うことで、外部APIに依存するコードの安定性と信頼性を高め、将来的なトラブルを未然に防ぐことができます。モックを活用した効率的なテスト設計で、実運用に耐えうるAPI連携を実現しましょう。