EcholotPostmanから移行する
Postmanのコレクションと環境を読み込み、対応関係を知り、実行し、Postmanに書き出して戻します。
EcholotはPostmanのコレクションと環境を、スクリプトも含めてそのまま読み込めます。このチュートリアルでは、コレクションを読み込み、各部分がどこに行ったかを確認し、実行し、ワークスペースをPostmanに書き出して戻します。
- 所要時間：15分。
- 必要なもの：Postmanのコレクション（v2.0またはv2.1）と、JSONで書き出した環境。手元にコレクションがなければ、ステップ1でAlpenglowから作れます。
- 学べること：読み込み、対応関係、読み込んだスクリプトの信頼、コレクションを読み込む場合と読み込まない場合の実行、書き出し。
1. コレクションを用意する
Postmanから：コレクションの⋯メニューを開き、Exportを選んで、Collection v2.1のままにします。環境も、それぞれのメニューから同じように書き出します。
代わりにAlpenglowで練習する場合：
- Alpenglowワークスペースを開いて、ファイル › ワークスペースを書き出す…を選びます（⇧⌘E）。
- Postman Collection v2.1を選びます。その行には、29件のリクエストのうち21件が対応すると表示されます。PostmanのコレクションにはWebSocket、Socket.IO、MQTT、gRPC、MCPのリクエストがないため、それらは含まれません。
- 環境を含める（3）はオンのままにして、書き出す…を選びます。環境を含めると、書き出しはファイルのフォルダになります。名前を付けて書き出すを選びます。
フォルダには、Alpenglow.postman_collection.jsonと、環境ごとに1つの.postman_environment.jsonが入ります。レポートには、除外された内容と書き出し時に変更された内容が一覧されます。
Echolotのチェックはpm.test()スクリプトになり、レスポンスのキャプチャは書き出されず、シークレット変数は値なしで名前だけが書き出されます。
2. 読み込む
-
新しいワークスペースを作ります。ファイル › 新規ワークスペース…（⌥⌘N）で、名前を
From Postmanにします。 -
ファイル › 読み込む…（⇧⌘I）を選びます。コレクションと環境のファイルを一緒に選択して、読み込むを選びます。
ファイルをウインドウにドラッグしたり、コレクションのJSONをコピーしてサイドバーにペーストしたり（⌘V）することもできます。
-
レポート読み込み結果には、各ファイルが形式（Postmanコレクションv2.1、Postman環境）と取り込まれた内容とともに一覧されます。注記には、そのままでは取り込めなかった内容が示されます。
Alpenglowの書き出しでは、注記に、19件のテストスクリプトが読み込まれ、信頼すると実行されること、そして2件のシークレットの値が、ワークスペースのファイルではなくキーチェーンに保存されたことが示されます。コレクションに入力されていた、デモのパスワードとOAuthのクライアントシークレットです。
リクエストは、これらを{{password}}と{{orders_with_oauth_2_clientSecret}}として参照するようになります。サイドバーに表示を選びます。
3. 対応関係を知る
| Postman | Echolot |
|---|---|
| コレクション | コレクションの名前が付いたフォルダ。変数、認証、スクリプトは、そのフォルダのフォルダ設定…にあります |
| フォルダ | フォルダ。説明はドキュメントに、変数、認証、スクリプトはフォルダ自身のものとして入ります |
| リクエスト | 1つのファイルとして保存されたリクエスト。rawボディは種類を保ち、urlencodedはURLエンコードに、form-dataはマルチパートになり、GraphQLのボディはGraphQLリクエストになります |
| 環境 | 環境のページ（⌥⌘E）の環境。secret型の値はキーチェーンに入ります |
| コレクション変数 | コレクションのフォルダの変数。その中のすべてのリクエストに適用され、環境の変数より優先されます |
| Pre-request Script、Tests | スクリプトタブのプリリクエストスクリプトとテストスクリプト。リクエスト、フォルダ、ワークスペースのいずれかに入ります |
pm.* | 同じAPI：pm.test、pm.expect、pm.response、pm.request、pm.environment、pm.variables、pm.collectionVariables、pm.globals、pm.iterationData、pm.sendRequest、pm.cookies、pm.setNextRequest、pm.visualizer、および古いpostman.*とtests[…] |
require() | lodash、ajv、tv4、crypto-js、uuid、atob、btoa |
| 認証 | 同じ種類：Basic、Digest、Bearerトークン、APIキー、OAuth 1.0、OAuth 2.0（詳細設定を含む：アドレス内のトークン、更新URL、追加パラメータ）、AWS署名、JWT Bearer、Hawk、Akamai EdgeGrid、NTLM。ASAP（Atlassian）は、同じように設定したJWT Bearerになります。OAuth 2.0のクライアント資格情報とパスワード資格情報はそのままで、インプリシットはPKCE付きの認可コードになり、読み込みレポートにその旨が表示されます |
{{$guid}}、{{$timestamp}}、{{$randomInt}}、{{$randomFirstName}}などの$random…の値 | 同じ名前の動的な値（ダミーデータを含む）と、さらに多くの値 |
| Collection Runner、Newman | ランナーとecholot run |
| モックサーバ | Mac上のモック：例とダミーデータを使ったルート、またはOpenAPI仕様 |
| モニター | スケジュールで実行するフロー、またはCIでのecholot run |
form-dataのファイルボディとファイルフィールドは、ファイルが別のコンピュータにあるため読み込まれません。レポートにそれぞれが示されるので、ボディタブでファイルを選び直してください。
4. スクリプトを信頼する
スクリプトは、スクリプトにできることなら何でもできるため、読み込んだスクリプトは、あなたが許可するまで実行されません。
- Catalog › List productsのように、テストスクリプトがあるリクエストを開き、そのスクリプトタブを開きます。バナーにこれらのスクリプトはEcholotの外部から来たものですと表示されます。
- スクリプトを読んで、スクリプトを信頼を選びます。先に送信した場合はEcholotが尋ね、信頼して送信を選ぶと、信頼してすぐに送信します。
- 送信します。スクリプトの
pm.test()の結果が、レスポンスのテストタブのスクリプトの下に表示されます。
スクリプトは、Nodeではなく、Echolot独自のJavaScriptサンドボックスで実行されます。スクリプトとテストとスクリプトAPIを参照してください。
5. 実行する
- ページヘッダーで、読み込んだ環境（Stagingなど）を選びます。AlpenglowのデモAPIでは環境なしを選びます。
- コレクションのフォルダを右クリックして、フォルダを実行を選びます。ランナーが、すべてのリクエストをスクリプトとチェックとともに実行します。
コマンドラインツールは、Newmanと同じように、コレクションを読み込まずに実行できます。そこでは、スクリプトは確認なしで実行されます。
echolot run Alpenglow.postman_collection.json --folder catalog --reporter console --reporter junit --out results.xml--env-fileにはPostmanの環境ファイルを、--folderにはフォルダの名前を小文字とハイフンで（catalog、agent-tools）指定します。--data users.csvは、行ごとに1回実行します。シークレットの値は、ECHOLOT_SECRET_<NAME>環境変数から取得されます。
6. 動作の違い
- すべてがファイルです。 ワークスペースは、リクエストごとに1つのTOMLファイルが入ったフォルダで、Gitにすぐ使えます。アカウントも同期サービスもありません。チームでの共有はGitで行います。Gitとチームを参照してください。
- 保存は自動です。 ⌘Sはありません。サイドバーの下部にすべて保存済みと表示されます。
- シークレットがファイルに入ることはありません。 シークレット変数の値は、このMacのキーチェーンにあります。ファイルに入るのはその名前だけです。
- コードなしのチェック。 テストタブでは、ステータス、ヘッダー、JSONの値、時間、JSON Schema、OpenAPI仕様を、スクリプトなしでチェックできます。スクリプトとテストを参照してください。
- コードなしのキャプチャ。 テストスクリプトに
pm.environment.set("token", …)と書く代わりに、レスポンスの値にポインタを重ねて変数に保存…を選びます。リクエストをつなぐを参照してください。 - HTTPだけではありません。 同じワークスペースに、WebSocket、Socket.IO、MQTT、gRPC、MCPのリクエスト、仕様、モック、フローを入れられます。
7. Postmanに書き出して戻す
- ファイル › ワークスペースを書き出す…を選ぶか、フォルダを右クリックしてフォルダを書き出す…を選びます。
- Postman Collection v2.1を選びます。シートには、いくつのリクエストが対応するかが表示されます。WebSocketなどのセッション系のリクエストは含まれません。Insomnia v5はWebSocket、Socket.IO、gRPCも書き出せ、Brunoコレクションは
.bruファイルのフォルダを書き出します。 - 環境を含めるかどうかを選んで、書き出す…を選びます。
認証やヘッダーのフィールドに入力した認証情報は平文で書き出され、レポートにその件数が表示されます。先にシークレット変数に移してください。シークレット変数は、値なしで名前だけが書き出されます。書き出しを参照してください。
次のステップ
- 最初のワークスペース：ワークスペースの構成。
- 読み込み：Insomnia、OpenAPI、HAR、cURL、Paw、Brunoにも対応しています。
- APIをテストしてCIで実行する：パイプラインのNewmanを置き換えます。