API テスト

API テストは、テスト内で API 呼び出し（HTTP リクエスト）を行います。これにより、他ステップで使うデータの取得や、バックエンドとフロントエンドの値の整合を確認する検証が可能です。API リクエストはヘッダー（認証情報を含む）とボディを持つ完全な HTTP リクエストです。
API ステップには Add API action と Validate API の 2 種類があります。

• Add API action — API 応答からデータを取得したい場合に使用（返ってくることの確認にも利用可）
• Validate API — API 応答の検証に使用（主にバックエンドのデータ検証）

Validate API ステップの追加

API 検証ステップで応答を検証します。ヘッダー／ボディ／ステータスコードで検証可能です。検証全般はこちらを参照。
“Add API validation” を追加するには:

1. Add API validation ステップを追加したい位置の （矢印）アイコン、または最後のステップの後ろにある + アイコンにカーソルを合わせます。
2. “M”（Testim predefined steps）ボタンをクリックします。
   Predefined steps メニューが開きます。
3. Validations をクリックします。
   Validations メニューが展開されます。
4. メニューをスクロールし、Validate API を選択します。

Add Step ウィンドウが表示されます。

5. Name the new step フィールドに、このステップの名前を入力します。
6. このステップを他のテストでも再利用できる共有ステップとして保存したい場合は、Shared step チェックボックス（デフォルトでオン）をそのままにし、Select shared step フォルダーリストから保存先フォルダーを選択します。共有ステップにしない場合はチェックを外します。
   共有ステップの詳細は グループ を参照してください。
7. Create Step をクリックします。
   Run Shared API Validation ウィンドウが開きます。

8. URL フィールドで使用する HTTP リクエストメソッドを選択し、ルートエンドポイントとパスを入力します。必要に応じて URL にパラメーターを追加します。詳細は後述の Using Parameters を参照してください。
9. Header セクションで、API に送信するヘッダーのキーと値を入力します。ヘッダーを個別のキー／値フィールドで入力したい場合は Key-Value（デフォルト）を選択し、ブラウザの DevTools Network パネルからコピーした文字列などをそのまま貼り付けたい場合は Raw を選択します。
   複数のヘッダーを定義している場合、左側のチェックボックスをオンにしたヘッダーを使ったリクエストが順に実行されます。ヘッダーを削除したい場合は右端の X をクリックします。

10. 認証ヘッダーを設定するには Authorization タブをクリックし、次のいずれかの方式を選択します。

• None – 認証情報を送信しない場合、または Basic / Bearer 以外の認証方式を使いたい場合に選択します。この場合、認証ヘッダーは Header タブで手動入力する必要があります。
• Basic – エンドポイントが Basic 認証を使用する場合に選択します。ユーザー名とパスワードを入力します。
• Bearer – エンドポイントが Bearer トークン認証を使用する場合に選択します。トークンを入力します。

11. Body セクションのドロップダウンで送信したいデータ形式を選択し、下の入力欄にリクエストボディを入力します。例えばキーと値のペアなど任意のテキストを送りたい場合は Text オプションを使用します。利用できる形式は Text / JSON / JavaScript / XML / HTML です。Body にもパラメーターを埋め込めます。詳細は後述の Using Parameters を参照してください。

Assertion セクションでは、コードを書かずにレスポンスのヘッダー／ボディ／ステータスコードに対する検証を追加できます。Assertion は後述の「Run additional code on request results」で記述するコードよりも先に実行され、TRUE なら成功、FALSE なら失敗となります。Assertion が失敗した場合、そのステップとテスト全体が失敗となり、「Run additional code on request results」のコードは実行されません。設定手順:

• 1 つ目のドロップダウンで検証対象（Status code / ヘッダー / Body (JSON) / Body (Text) など）を選択します。
• 2 つ目のドロップダウンで比較演算子を選択します。
• 3 つ目の入力欄に比較する値を入力します。値には波括弧なしでパラメーターを指定することもできます。
• 追加の Assertion を設定したい場合は同じ手順で行を追加し、左のチェックボックスで有効／無効を切り替えます。

12. Assertion では表現しきれない複雑な検証や追加処理（失敗時にカスタムエラーメッセージを投げるなど）を行いたい場合は、Run additional code on request results をオンにします。ここではレスポンス結果を受け取って任意の JavaScript コードを実行できます。パラメーターも利用可能で、詳しくは後述の Using Parameters を参照してください。

13. Show step properties をクリックして、ステップのプロパティパネルを開きます。

14. Properties パネルの Send via web page チェックボックスでは API 呼び出しの実行コンテキストを制御できます。

• チェックを外す – ブラウザコンテキストの外側から API を送信します。ブラウザの制限（CORS など）を避けたい場合に有効です。
• チェックを付ける – ブラウザ情報（Cookie など）も含めて送信したい場合に使用します（Cookie は自動的に送信されます）。

15. Allow API request retry では、リクエストが失敗した場合に再送を行うかどうかを制御します。
16. チェックを付ける – リクエスト自体が失敗したとき（エラーステータスコードのとき）のみ再送を行います。
17. チェックを外す – ステータスコードがエラーであっても再送は行わず、検証と追加コードの実行に進みます。例えば「エラーコードであること」を Assertion で期待している場合などに有用です。
18. Params フィールドでは、後述の Using Parameters で利用するパラメーターを定義します。

AUT コンテキスト外でリクエストを試す

テストを実行せずに、AUT（対象アプリ）コンテキスト外で素早くリクエストだけを試したい場合は、URL フィールドの Send ボタンを使います。このとき Run additional code on request results で設定したコードや Assertion は実行されません。
送信されるのは Properties パネルで定義されたローカルパラメーターのうち、静的な値のみです。動的な値は空文字として送信されます。
利用可能なステップパラメーターは URL フィールド下に一覧表示され、Edit をクリックすると Properties パネルで編集できます。

Adding an API Action Step

API アクションステップ（Add API action）は、レスポンスを利用した追加処理を行いたいケースで使用します。返却データを計算に利用したり、後続ステップで利用するためにエクスポートパラメーターとして保存したりできます。header / body / status code いずれの情報も利用可能です。
“Add API action” ステップを追加するには:

1. 追加したい位置の （矢印）または最後のステップ後ろの + にカーソルを合わせます。
2. “M”（Testim predefined steps）をクリックします。
   Predefined steps メニューが開きます。
3. Actions をクリックします。
   Actions メニューが展開されます。
4. 一覧から Add API action を選択します。

Add Step ウィンドウが表示されます。

5. 上記「Validate API ステップの追加」の 手順 5〜13 に従って、URL ・ヘッダー・ボディ・ Assertion などを設定します（ただし目的は「検証」ではなく「応答データの利用」になります）。
6. レスポンスデータを使った追加処理（パラメーター抽出、DB 接続のクローズなど）を行いたい場合は、Run additional code on request results をオンにします。ここではレスポンスの status code / response headers / response body などを利用して任意の JavaScript コードを実行できます。レスポンスボディが XML/JSON の場合は Object、それ以外は文字列として渡されます。

7. 残りのプロパティ（送信コンテキストやリトライ設定、Params など）は、「Validate API ステップの追加」の 手順 14〜16 を参照して設定します。

Including a File and/or Text field with an API Call Using Form Data

Validate API / Add API action ステップでは、フォームデータを使ってファイルやテキストフィールドを API に含めることができます。
API 呼び出しにファイルを含めるには:

1. 対象テストで Validate API または API Action ステップを追加します（前述手順参照）。
2. ステップの Body セクションで Form Data エントリタイプを選択します。

3. エントリタイプとして File を選択します。

Testim はヘッダーの Content-Type を自動的に multipart/form-data に更新します。

4. ファイル名を受け取る Key 名を入力します。

5. Upload File ボタンをクリックし、ローカルマシンからファイルを選択してアップロードします。

アップロードされたファイルはテストサーバーに保存され、テスト実行時にそのファイルが API 呼び出しの一部として送信されます。

API 呼び出しにテキストフィールドを含めるには:

1. 対象テストで Validate API または API Action ステップを追加します。
2. ステップの Body セクションで Form Data エントリタイプを選択します。
3. エントリタイプとして Text を選択します。
4. テキストフィールドの Key 名を入力します。
5. テキストフィールドの Value を入力します。

設定した key

Cancel a File Upload in Progress

アップロード中のファイルを途中でキャンセルすることもできます。
アップロード中のファイルをキャンセルするには:

1. アップロード中のエントリの右側にある “X” をクリックします。

Testim がファイルのアップロードをキャンセルし、別のファイルを再度アップロードできる状態になります。

Replace a File Attachment

既存エントリに添付済みのファイルを別のファイルに差し替えることもできます。
ファイル添付を別のファイルに置き換えるには:

1. 既存のファイルが添付されているエントリの “X” をクリックします。

2. Upload File ボタンをクリックし、新しいファイルを選択してアップロードします。

Exclude or Delete an Entry from the Body Section

Body セクションに定義したエントリは、一時的に無効化したり完全に削除したりできます。 API 呼び出しからエントリだけ除外するには:

1. テストから除外したいエントリの左側にあるチェックボックスをオフにします。

テスト実行時、そのエントリはリクエストから除外されますが、定義自体は残るため、あとから再度有効化できます。
Body セクションからエントリを完全に削除するには:

1. 削除したい Body エントリ右側の “X” をクリックします。

エントリは完全に削除されます。

パラメーターの使用 {#using-parameters}

API ステップでは、他のコードステップと同様にパラメーターを利用できます。送信する HTTP リクエストの URL／ヘッダー／ボディにパラメーターを埋め込んだり、レスポンスから値を取り出してパラメーターに保存したり、Assertion の値として使用したりできます。パラメーターは入力パラメーター（依存性注入）として受け取るか、exportsGlobal や exportsTest 経由で出力パラメーターとしてエクスポートできます。また、テストスコープ内の他の変数も参照可能です。
パラメーターの詳細は Parameters を参照してください。

送信する HTTP リクエストでのパラメーター利用 {#using-parameters-in-the-sent-http-request}

パラメーターは、送信する HTTP リクエストのヘッダー／ボディ／URL に埋め込めます。これらのセクションは純粋な JS で書くと煩雑になるため、Testim ではパラメーターを「二重／三重の波括弧」で簡単に埋め込めるようになっています。

Body へのパラメーター追加

パラメーターの値をエンコードせずそのまま埋め込みたい場合は、三重波括弧を使います（例: {{{param}}}）。

URL へのパラメーター追加

テストの Base URL と同じホストにある API に対して呼び出しを行いたい場合は、URL 全体を記述する代わりに {{{BASE_URL}}} パラメーターを使えます。URL フィールドで {{{BASE_URL}}} の後ろにパスを続けて入力してください。ここでもパラメーターをエンコードしたくない場合は三重波括弧を使用します（例: {{{param}}}）。

Header へのパラメーター追加

ヘッダーにパラメーターを入れる場合も同様で、値をエンコードしたくない場合は {{{param}}} のように三重波括弧を使用します。

HTTP レスポンスでのパラメーター利用

Properties パネルで追加したパラメーターは、API ステップ内のコードの関数シグネチャに自動的に追加されます。これにより、レスポンスを処理するコード内でパラメーターを直接利用できます。

Assertion でのパラメーター利用

Assertion セクションでも、比較値としてパラメーターをそのまま使用できます。この場合、値には波括弧を付ける必要はありません。

実行後の結果の確認

ステップ実行後は、Response タブで API レスポンスを確認できます。ここでは、レスポンスボディだけでなく、ステータスコードやリクエスト時間、バイナリファイルのサイズなどの追加情報も表示されます。また、送信されたリクエスト内容を確認したり、レスポンス情報をダウンロードしたりすることもできます。

Response タブでは次の機能が利用できます。

• View Sent Request – クリックすると送信されたリクエストの完全な内容を表示するウィンドウが開きます。パラメーターは実際の値に展開された状態で表示されます。この画面からレスポンス情報を JSON として ダウンロード したり、内容をクリップボードに コピー したりできます。

• Download the response info – View Sent Request の右側にあるダウンロードボタンをクリックすると、レスポンス全体を含んだ JSON ファイルをローカルにダウンロードできます。
• Assertion response – Assertion を設定している場合、それぞれの Assertion の横に次のいずれかの結果が表示されます。
• Passed – 条件が TRUE になり、Assertion が成功したことを示します。
• Failed – 条件が FALSE となり、Assertion が失敗したことを示します。この場合ステップは失敗し、テスト全体も失敗となります。

Usage examples - 具体的な使用例は こちら を参照してください。

Troubleshooting - よくあるエラーと対処方法は こちら を参照してください。