APIをテストしてCIで実行する

チェックを使うと、リクエストがテストになります。送信のたびに、何が成功し何が失敗したかがわかります。このチュートリアルでは、Alpenglowのリクエストにチェックを追加し、ランナーでフォルダを実行し、さらに同じワークスペースをGitHub Actionsでpushのたびにecholot runで実行します。

• 所要時間：20分。
• 必要なもの：Alpenglowワークスペースと、最後のパートでpushできるGitHubリポジトリ。
• 学べること：チェック、ランナーとそのレポート、echolot run、CIでのシークレット。

1. リクエストにあるチェックを確認するCopy Anchor Link

1. Catalog › List productsを開いて、テストタブを選びます。
2. チェックは4つあります。ステータスが200と等しい、JSONの値$.items.lengthが0より大きい、ヘッダーContent-Typeがjsonを含む、レスポンス時間（ms）が1000より小さい、です。
3. 送信します。タブには4件成功と表示され、レスポンスのテストタブには4/4と表示されて、チェックの下に各チェックが並びます。

2. 自分のチェックを追加するCopy Anchor Link

1. テストタブでテストを追加を開いて、JSONの値を選びます。
2. パスを$.items[0].price.currency、比較を次と等しい、期待値をCHFにします。
3. もう一度テストを追加を開いて、サイズ（バイト）、次より小さい、65536を選びます。
4. 送信します。6つのチェックが成功します。

チェックをもっと手早く追加する方法が2つあります。

• レスポンスのJSONツリーで値を右クリックして、チェックを追加を選びます。チェックには、その値のパスと値が入ります。
• レスポンスから生成…は、最新のレスポンスからチェックを提案します。ボディのJSON Schemaも含まれます。

次に、失敗を見てみましょう。レスポンス時間のチェックを次より小さい1に変更して送信します。タブに6件中1件が失敗と表示され、レスポンスのテストタブには、失敗したチェックの下に返ってきた内容が表示されます。1000に戻します。

コードが必要なチェックは、スクリプトタブでpm.test()を使ったテストスクリプトを書きます。スクリプトとテストを参照してください。

3. ランナーでフォルダを実行するCopy Anchor Link

1. Catalogフォルダを右クリックして、フォルダを実行を選びます。ランナーページが開き、中のすべてのリクエストを順番に実行します。
2. 統計には、リクエスト、成功、失敗、失敗したチェック、時間が表示され、結果カードには各リクエストのステータス、時間、失敗したチェックが並びます。
3. 自分で実行を設定するには、表示 › ランナー（⌥⌘R）を選びます。実行カードで次を設定します。
   • 対象：ワークスペース全体、フォルダのどれか1つ、または1件のリクエスト。Authを選んで実行し、次にOrdersを実行してください。Ordersのリクエストは、Sign inが保存したトークンを送信します。
   • 環境、反復（3を試してください）、リクエスト間の遅延（ミリ秒）、失敗したリクエストの再試行回数、最初の失敗で停止。
   • データ：CSVまたはJSONを選択…で、行ごとに1回、その行の列を変数として実行します。
4. 実行を選びます（⌘R）。
5. レポートを保存を開いて、JUnit XML…、JSON…、HTML…、HAR（すべてのやり取り）…のいずれかを選びます。

ワークスペース全体を実行すると、RealtimeとInventoryも実行されます。ローカルのサーバが動いていないと、Socket.IO、MQTT、gRPCのリクエストは失敗します。 詳しくはランナーを参照してください。

4. ターミナルから実行するCopy Anchor Link

1. コマンドラインツールをインストールします。Echolot › コマンドラインツールをインストール…を選ぶか、設定 › 一般でオンにします。echolotがPATHに追加されます。

   Mac App Store版

   App Store版には、コマンドラインツールが含まれていません。リリースからecholot-<version>-macos.zipをダウンロードして展開し、echolotをPATHにあるフォルダに置いてください。CLIを参照してください。

   エディションを比較

2. すべてのファイルが読み込め、すべての変数が解決できることを確認します。

   テキストをコピー

   echolot validate Alpenglow.echolot

   29 requests, 3 environments: no problemsと出力されます。

3. デモAPIだけで動く3つのフォルダを実行します。

   テキストをコピー

   echolot run Alpenglow.echolot --folder auth --folder catalog --folder orders

   テキストをコピー

   ✓ POST   auth/sign-in  200 142 ms
       ✓ Status equals 200
       ✓ JSON value $.access_token exists
   ✓ GET    auth/who-am-i  200 87 ms
       ✓ Status equals 200
   …
   All 13 requests passed  18/18 checks passed · 1.35 s

   --folderには、フォルダまたはリクエストのファイル名（auth、catalog/list-products）を指定します。リクエストにレスポンスがない場合やチェックが失敗した場合、終了コードは1になるので、スクリプトやCIはそこで止まれます。

4. コンソール出力に加えて、JUnitレポートも書き出します。

   テキストをコピー

   echolot run Alpenglow.echolot --folder auth --folder catalog --folder orders \
     --reporter junit --out results.xml --reporter console

   各リクエストがtestsuiteに、各チェックがtestcaseになります。すべてのオプションはecholot runにあります。

5. GitHub Actionsで実行するCopy Anchor Link

1. Alpenglow.echolotをリポジトリにコミットします。

2. .github/workflows/api.ymlを追加します。

   テキストをコピー

   name: API checks
   on: [push, pull_request]
   
   jobs:
     api:
       runs-on: macos-15
       steps:
         - uses: actions/checkout@v4
   
         - name: Install the Echolot CLI
           env:
             GH_TOKEN: ${{ github.token }}
           run: |
             gh release download --repo staticdreams/echolot-public --pattern 'echolot-*-macos.zip' --dir "$RUNNER_TEMP"
             unzip -q "$RUNNER_TEMP"/echolot-*-macos.zip -d "$RUNNER_TEMP/echolot"
             echo "$RUNNER_TEMP/echolot" >> "$GITHUB_PATH"
   
         - name: Validate
           run: echolot validate Alpenglow.echolot
   
         - name: Run
           run: >
             echolot run Alpenglow.echolot
             --folder auth --folder catalog --folder orders
             --reporter console --reporter junit --out results.xml
   
         - name: Keep the report
           if: always()
           uses: actions/upload-artifact@v4
           with:
             name: echolot-results
             path: results.xml

3. pushします。Runステップには、Macと同じ行が出力され、チェックが失敗するとジョブも失敗します。JUnitファイルはecholot-resultsとして実行に添付されます。JUnitのテストレポート用アクションなら、どれでも表として表示できます。

コマンドラインツールはAppleシリコンのmacOSで動作するため、ジョブにはmacOSのランナーを使います。

6. CIにシークレットを渡すCopy Anchor Link

Macのキーチェーンは、ワークスペースと一緒には移動しません。CIでは、コマンドラインツールは、シークレット変数nameを環境変数ECHOLOT_SECRET_NAMEから、または--secretsで指定したNAME=value形式の行のファイルから読み取ります。

Alpenglowのデモのパスワードは公開されているため、通常の変数です。実際のパスワードでは次のようにします。

1. ワークスペースで、たとえばpasswordというシークレット変数にして、コミットします。

2. GitHubで、リポジトリのシークレットAPI_PASSWORDを追加します（Settings › Secrets and variables › Actions）。

3. ステップに渡します。

   テキストをコピー

         - name: Run
           env:
             ECHOLOT_SECRET_PASSWORD: ${{ secrets.API_PASSWORD }}
           run: echolot run Alpenglow.echolot --env staging --reporter console --reporter junit --out results.xml

--envには、.tomlを除いた環境のファイル名、または環境の名前を指定します。CIについて詳しくはCIを参照してください。

次のステップCopy Anchor Link

• 仕様ファーストで設計してモックにする：OpenAPI仕様に対してレスポンスをチェックします。アプリでもCIでも。
• ランナー：データファイル、反復の並べて表示、再試行。
• echolot run：--bail、--delay、HTMLレポートを含むすべてのオプション。