スクリプトとテスト

テストは、レスポンスが期待どおりかどうかを教えてくれます。Echolotでは、テストの書き方が2つあります。リクエストのテストタブで設定するコード不要のチェックと、 リクエストの送信前と応答後に実行されるJavaScriptのスクリプトです。どちらも送信のたびに、ランナーやコマンドラインでも実行されます。

テストタブのチェックCopy Anchor Link

1. リクエストを開きます。たとえば、AlpenglowワークスペースのCatalog › List productsです。
2. テストタブを選びます。
3. テストを追加を選び、チェックする対象を選びます。
4. 横のメニューから比較方法を選び、期待する値を入力します。
5. リクエストを送信します。各チェックには緑のチェックマークか赤の×が表示され、失敗したものには下にその理由が表示されます。

チェックはリクエストとともに保存され、以降のすべてのレスポンスに対して実行されます。行の先頭のボックスは、チェックを削除せずにオフにします。マイナスボタンで削除します。 テストタブのバッジにはチェックの数が表示され、タブの下部には4件成功や4件中1件が失敗のように、合格した数が表示されます。

期待値はテンプレートなので、{{variables}}が使えます。Catalog › Get productは、$.skuが{{productId}}と等しいことをチェックします。

チェックできるものCopy Anchor Link

新しいチェックは、妥当な値で始まります：ステータスは200と等しい、レスポンス時間（ms）は1000より小さい、GraphQLエラーは0と等しい、MCPエラーはfalseと等しい、 gRPCステータスはOKと等しい、JSON Schemaは{"type": "object"}です。

値の比較方法Copy Anchor Link

• 次と等しいは、数値を数値として比較するので、200は200.0と等しく、値の前後のスペースは無視されます。
• 次のいずれかには、200, 201, 204のようにカンマ区切りのリストを指定します。
• 次の正規表現に一致は、正規表現が値のどこかに一致すれば合格します。
• 次の型であるには、object、array、string、number、integer、boolean、nullのいずれかを指定します。
• 数値の比較は、両辺が数値である必要があります。そうでない場合は、その旨のメッセージとともに失敗します。

JSONの値Copy Anchor Link

パスは、キーとインデックスからなり$で始まるJSONPathです：$.items[0].sku、$.data.search.totalCount。 負のインデックスは末尾から数えます：$.items[-1]。.lengthを付けると、配列の項目数やオブジェクトのキーの数を数えます：$.items.lengthが0より大きい。 Echolotは値に至る途中のボディの部分だけを読み取るので、JSONのチェックはどんなサイズのボディでも動作します。

ボディの次を含むと次を含まないも、どんなサイズのボディでも動作します。ほかのボディの比較と、JSON SchemaおよびGraphQLエラーは、ボディ全体を読み取り、50 MBで止まります。

ほかの種類のリクエストのチェックCopy Anchor Link

• GraphQL：サーバはステータス200でエラーを返すので、GraphQLエラーが0と等しいチェックを追加して検出します。特定のメッセージが返ることを確認するには、次を含むを使います。
• MCP呼び出し：MCPエラーがfalseと等しいチェックは、呼び出しが成功したときに合格します。エラーとしてマークされた結果とJSON-RPCエラーでは失敗し、メッセージにサーバの返した内容が表示されます。 ツールの出力スキーマは、ツールの結果をツールが宣言するスキーマに対してチェックします。ツールが何も宣言していないと失敗します。MCPリクエストを参照してください。
• gRPC：gRPCステータスには、OKやNOT_FOUNDなどの名前、または0〜16のコードを指定します。5、not_found、NOT_FOUNDは同じステータスです。 失敗したチェックには、ステータスメッセージが表示されます。gRPCを参照してください。
• OpenAPI仕様：リクエストのフォルダ（またはその上のフォルダ）が仕様にリンクされていて、リクエストがその仕様のオペレーションのいずれかに従っている必要があります。 チェックは、返ってきたステータスに対して仕様が記述しているスキーマに対して、ボディを検証します。仕様がJSONボディなしで記述しているステータスは合格し、記述のないステータスは失敗します。 仕様を参照してください。

レスポンスからチェックを追加するCopy Anchor Link

すべてのチェックを手で入力する必要はありません：

• テストタブのレスポンスから生成…は、最新のレスポンスからチェックを提案します。ステータス、コンテンツタイプ、JSON Schemaとしてのボディの形など、正常なレスポンスなら常に成り立つチェックは、最初からチェックが入っています。 呼び出しごとに変わる値と時間は、提案されますがチェックは入っていません。推定されたスキーマを選ぶと、提案されたスキーマを読めます。 チェックの入ったものを残すには、テストを1件追加（またはテストをN件追加）を選びます。先にリクエストを送信してください。ボタンにはレスポンスが必要です。
• レスポンスのボディのJSONツリー表示で値を右クリックしてチェックを追加を選ぶと、そのパスがその値と等しいというJSONの値のチェックが追加されます。
• レスポンスのヘッダーでヘッダーを右クリックしてチェックを追加を選ぶと、そのヘッダーがその値と等しいというヘッダーのチェックが追加されます。

結果Copy Anchor Link

レスポンスペインのテストタブには、各チェックの結果と見つかった値（got 200）が一覧され、続いてスクリプトの各テストが表示されます。 サイドバーのテストページ（表示 › テスト、⌥⌘T）には、チェックを持つすべてのリクエストが、最新のレスポンスでの状況とともに一覧されます。クリックするとリクエストが開きます。

スクリプトCopy Anchor Link

スクリプトは、Postmanのpm.* APIを使うJavaScriptなので、ほとんどのPostmanスクリプトはそのまま動作します。リクエストには2つのスクリプトを持てます：

• プリリクエストスクリプトは、リクエストの送信前に実行されます。リクエストを変更したり、変数を設定したり、リクエストをスキップしたりできます。
• テストスクリプトは、レスポンスが届いた後に実行されます。pm.testでレスポンスをチェックし、後のリクエストのために値を保存できます。

1. リクエストを開き、スクリプトタブを選びます。
2. 上部のプリリクエストまたはテストを選びます。テスト •のように名前の後にドットがあると、コードのあるスクリプトです。
3. スクリプトを書きます。エディタはJavaScriptに色を付け、入力中にpm.のパスを補完します。スニペットは、よくあるケース向けの定型スクリプトを追加します。
4. リクエストを送信します。

たとえば、Catalog › List productsのテストスクリプト：

pm.test("Status code is 200", () => {
  pm.response.to.have.status(200);
});

pm.test("Returns tents", () => {
  const body = pm.response.json();
  pm.expect(body.items.length).to.be.above(0);
});

そして、実行対象のすべてのリクエストにヘッダーを追加するプリリクエストスクリプト：

pm.request.headers.add({ key: "X-Request-Id", value: pm.variables.replaceIn("{{$guid}}") });

各pm.testは、テストタブのチェックの後に、レスポンスのテストタブのスクリプトの下に表示されます。例外を投げたスクリプトは、メッセージ付きでスクリプトエラーと表示されます。 スクリプトがconsole.log、console.info、console.warn、console.errorで書き出した内容は、preまたはtestの印付きで、レスポンスのコンソールタブに表示されます。タブはスクリプトが実行された後に現れます。

スニペットCopy Anchor Link

フォルダとワークスペースのスクリプトCopy Anchor Link

フォルダとワークスペースにも、その中のすべてのリクエストに対するスクリプトを設定できます。サイドバーのフォルダのコンテキストメニュー（フォルダ設定…）かワークスペース設定…から、スクリプトタブで開きます。

各リクエストでは、Echolotは最初にワークスペースのスクリプト、次に外側から順に各フォルダのスクリプト、最後にリクエスト自身のスクリプトを実行します。 プリリクエストスクリプトとテストスクリプトのどちらも、同じ順序です。スクリプトが実行されるのは、保存済みのリクエストだけです。

MCP呼び出しにはスクリプトタブがなく、スクリプトも実行されません。ほかのすべての種類のリクエストにはあります。

pm APIの概要Copy Anchor Link

完全な一覧は、スクリプトAPIリファレンスにあります。

requireは、lodash、ajv、tv4、crypto-js、uuid、atob、btoaを提供します。_（lodash）、tv4、btoa、atob、setTimeoutは、これを使わなくても使えます。 Postmanの古いグローバル（postman.setEnvironmentVariable、tests[...]、environment、globals、data、iteration）も、引き続き動作します。 それ以外のモジュールは、「The module … is not available in Echolot scripts.」というメッセージで失敗します。

スクリプトが設定する変数Copy Anchor Link

pm.environment.set、pm.collectionVariables.set、pm.globals.setが書き込むのは現在値です。ウインドウが開いている間だけ存在し、リクエストの解決時にそのスコープの保存された値を上書きし、 ワークスペースのファイルには書き込まれません。そのため、スクリプトが保存したトークンは、Gitに入ることなく後のリクエストに届きます。 レスポンスの値をワークスペースに保持するには、代わりにキャプチャを使います。

pm.variables.setは現在の実行だけの値を設定します。実行は、この方法でスクリプトが設定した値なしで始まります。

ほかのリクエストを送信するCopy Anchor Link

pm.sendRequestは、スクリプトからリクエストを送信します。たとえば、先にトークンを取得するようなものです。URL、またはurl、method、header、bodyを持つオブジェクトを受け取り、 コールバックか、返されるPromiseのどちらかで結果を受け取ります：

pm.sendRequest({
  url: pm.variables.replaceIn("{{baseURL}}/auth/token"),
  method: "POST",
  header: { "Content-Type": "application/json" },
  body: { mode: "raw", raw: JSON.stringify({ email: "heidi@alpenglow.ch", password: "alpenglow" }) },
}, (error, response) => {
  if (!error) pm.environment.set("token", response.json().access_token);
});

リクエストは、Echolotからのほかの送信と同じように、同じプロキシと証明書を使って送信されますが、ワークスペースやフォルダの認証は使われません。スクリプトは、応答を最大30秒待ちます。

リクエストのスキップと次のリクエストの選択Copy Anchor Link

プリリクエストスクリプトのpm.execution.skipRequest()は、リクエストの送信を止めます。レスポンスペインとランナーには、スキップされたことが表示されます。 実行中のpm.execution.setNextRequest("Get order")は、次にそのリクエストへ移動し、setNextRequest(null)は実行を終了します。ランナーを参照してください。

Echolotの外部から来たスクリプトCopy Anchor Link

スクリプトはコードなので、EcholotはこのMacで信頼されたものだけを実行します。Echolotで書いたスクリプトは、保存した時点で信頼されます。 インポート、Git、別のエディタでの編集など、ほかの方法で届いたスクリプトは待機します：

• スクリプトタブに、スクリプトを信頼ボタン付きでこれらのスクリプトはEcholotの外部から来たものですと表示されます。
• リクエストを送信すると、スクリプトを確認…で止まります。これを選ぶとこれらのスクリプトを実行しますか？が開き、まだ実行されていない各スクリプトと、その出どころ（リクエスト、フォルダ、ワークスペース）が表示されます。 読んでから、信頼して送信またはキャンセルを選びます。

信頼はこのMac上でワークスペースごとに、正確なコードに対して保持されます。Echolotの外でスクリプトが変更されると、あらためて確認されます。 信頼はワークスペースとともに移動することはないので、共有されたワークスペースが自分のスクリプトを信頼することはできません。

コマンドラインツールは、指定したワークスペースのすべてのスクリプトを実行します。echolot mcp serveは、起動時にワークスペースにあったスクリプトだけを実行します。

サンドボックスとその制限Copy Anchor Link

スクリプトは、Echolot内のJavaScriptサンドボックスで実行されます。ファイルシステムも、独自のネットワークも、Macへのアクセスもありません。外へ出る手段は、pm.sendRequest、console、変数だけです。 送信のたびに、新しいサンドボックスが始まります。

実行時間が長すぎるスクリプトは「the script took longer than 5 s」で失敗し、メモリを使いすぎるスクリプトは「the script used more memory than allowed」で失敗します。 スクリプトは引き続き、シークレットを含むワークスペースの変数を読み取り、pm.sendRequestで送信できます。外部から来たスクリプトが信頼を待つのは、そのためです。

トラブルシューティングCopy Anchor Link

• レスポンスから生成…がグレーになっている：先にリクエストを送信してください。HTTPとGraphQLのリクエストで使えます。
• 「このリクエストのフォルダにはOpenAPI仕様がリンクされていません」：フォルダを仕様にリンクするか、OpenAPI仕様のチェックを削除してください。
• 「「…」はこのバージョンで解釈できるJSONPathではありません」：$.items[0].skuのように、キーとインデックスだけを使ってください。
• スクリプトが実行されない：リクエストが保存されていること、MCP呼び出しでないこと、スクリプトが信頼を待っていないことを確認してください。