【第1回】API Scanでエンドポイントを探索してみよう
Tricentis ToscaでAPIテストを実行してみたシリーズ#1
本記事は「ToscaでAPIテストを実行してみた」シリーズの第1回になります。
有効なTricentis Toscaのライセンスを保持している事を前提に記載しております。
今回の目的
今回は、Tosca API Scanを使って実際にAPIの構造を読み込み、テストモジュールを生成する手順を紹介します。
ToscaのAPIテストは、UIテストとは異なり「API構造を理解してモジュール化」するところから始まります。
ここでは、無料で利用できるサンプルAPI（例: Swagger Petstore）を使いながら進めます。
ToscaのAPIテストは「API構造を理解してモジュール化」する所から始まります。
ここではサンプルとして利用する以下のREST API用の簡易デモソフトを利用してAPIのテストを実行確認してみようと思います。
API Scanとは？
Toscaの「API Scan」は、HTTP通信（REST/SOAP）を分析・再現し、
テストに使えるAPIモジュール（リクエスト＋レスポンス構造）を自動生成するツールです。
主な機能
- REST / SOAP / OData / GraphQL のリクエスト構造をインポート
- Swagger / OpenAPIファイルの読み込み
- 実際にAPIを呼び出してレスポンスを確認
- Tosca Commanderへモジュールとして送信
UIテストで言う「スキャン＝画面探索」と同じ概念をAPIに適用したものです。
ステップ1：API Scanを起動
- Tosca Commanderを開く
- リボンメニューから API Testing → API Scan を選択
すると独立したウィンドウでAPI Scanツールが起動します。
初回起動時は、以下のようなシンプルな画面が表示されます。
API Scanは単体ツールとしても動作するため、トラブル時は単独で起動確認するのがおすすめです。
ステップ2：Swagger / OpenAPIファイルを読み込む
Tosca API ScanはSwagger/OpenAPI仕様を直接読み込むことができます。
- [File] → [Import API Definition] をクリック
定義ファイルを指定します。
2. 「Import from URL」または「Import from file」を選択 以下のようなURLを指定します（Swagger Petstore例）
（例）https://petstore.swagger.io/v2/swagger.json
今回はLocalにホストしている定義ファイルの場を指定します。
http://localhost:9090/petclinic/v3/api-docs
3. Importを押すと、API Scanの左ペインに多数のエンドポイント（例：/owner, /pet, /pettypes）が表示されます。
これで、Swaggerの定義から自動的に各APIのRequest/Response構造が読み込まれた状態になります。
ステップ3：REST vs SOAPの違い（Toscaでの扱い）
| 項目 | REST API | SOAP API |
|---|---|---|
| 通信形式 | JSON / HTTP | XML / SOAP Envelope |
| 認識方法 | URLとHTTPメソッド（GET/POST/PUT/DELETE） | WSDLファイルによる定義 |
| Toscaでの読み込み | Swagger / OpenAPIファイル | WSDLファイルのImport |
| 検証方法 | JSON Pathで値を抽出・検証 | XPathで要素を抽出・検証 |
実務では、REST APIが主流です。
ただしSAPや一部のERPではSOAPが残っているため、両方の構造理解が役立ちます。
本稿ではREST APIを前提に進めます。
ステップ4：APIリクエスト構造を理解する
Swaggerから読み込んだエンドポイントをクリックすると、リクエストの構造が表示されます。
たとえば GET /api/pets/{petsId} を選ぶと以下のような構造になります。
| 要素 | 内容 | 例 |
|---|---|---|
| Method | HTTPメソッド | GET |
| Endpoint | エンドポイント | [http://localhost:9090] |
| Resource | リソースパス | /petclinic/api/pets/{petID} |
| Query Parameter | petId | Type: Path |
| Header | 任意のヘッダ値 | （例）Accept: application/json |
| Payload (Body) | （POST/PUT時のみ）送信データ | JSONオブジェクト |
ステップ5：実際にGETリクエストを送ってみる
API Scan上部の「▶ Send Request」ボタンをクリックします。
下部の「Response」タブに、APIサーバーからのレスポンスが返ってきます。
例：GET /petclinic/api/pets/2
{
"name": "Basil",
"birthDate": "2012-08-06",
"type": {
"name": "hamster",
"id": 6
},
"id": 2,
"ownerId": 2,
"visits": []
}
成功すればステータスコード 200 OK が表示され、JSONレスポンスの内容も確認できます。
ステップ6：Tosca Commanderへ転送する
確認したAPIをToscaでテストに使いたい場合は、次の手順です。
- 右上の「API Test Case > Export to Component Folders」をクリック
- 送信後、Tosca CommanderのModulesフォルダ内に
ApiScan_Import → Modules → GET getPet_1Request」などのモジュールが生成されます。
このモジュールは後ほどTestCase設計時に使用します。
⚠️ よくある失敗例と対処法
| 症状 | 原因 | 対処法 |
|---|---|---|
| 「Unable to connect」エラー | URLが間違っている、VPN/Proxyブロック | APIが外部通信を許可しているか確認 |
| 「401 Unauthorized」 | トークンやBasic認証が必要 | Headerに認証情報を追加（Authorization: Bearer ...） |
| 「Invalid JSON format」 | BodyのJSON構文エラー | JSON Linterで整形して再送信 |
| 「文字化け」 | Encoding設定不一致 | Headerで Content-Type: application/json; charset=utf-8 を明示 |
まとめ
今回は、Tosca API Scanを使ってSwagger定義をインポートし、API構造を理解してモジュール化するまでを体験しました。
ここまでできれば、次回は実際にTestCaseを作成し、APIリクエストを自動化して実行できます。
参考リンク
記事のポイントまとめ
- ToscaのAPI ScanはUIスキャンの「API版」
- Swagger / OpenAPIを読み込むだけでモジュール化できる
- リクエスト送信でAPIの構造を体験できる
- Commanderに転送すれば、すぐにTestCase化可能