Echolotモック
手書きのルート（ダミーデータも使えます）またはOpenAPI仕様から作るローカルのモックサーバ。応答の内容を選び、リクエストを検証し、ネットワークで共有できます。
モックは、Macのポートで動作し、APIのように応答するサーバです。APIがまだない間や、実際のAPIが停止している間も、フロントエンド、アプリ、テストから利用できます。 モックは、次の2つの情報源から単独で、または組み合わせて応答します。
- 手書きのルート：メソッドとパス、そして応答するJSON、XML、テキスト。ボディにはリクエストごとに変わるダミーデータ（
{{$randomFullName}}、{{$randomEmail}}）や、リクエストの一部（{{request.params.id}}）を含められます。仕様は不要です。ルートとダミーデータを参照してください。 - OpenAPI仕様：すべてのオペレーションが、仕様に記述されたレスポンス、その例、またはスキーマから作った本文で応答します。仕様に違反するリクエストには理由を示す
400が返るので、クライアントが誤ったものを送信したときにもモックが教えてくれます。
コードや状態が必要な応答には、モックにJavaScriptのルートも使えます。
このページは、サイドバーのモジュール切り替えでモックを選ぶか、⌘4で開きます。
モックを作成する
サイドバーのモックヘッダーの+をクリックするか、空のページのボタンを使います。
- 新規モックは、ルートで構成するモックを作成します。最初に、5人分のダミーのユーザーを返す
GET /usersルートが1つ含まれているので、開始してボディでできることを確認できます。これを変更するか、自分のルートを追加します。ルートとダミーデータを参照してください。 - 仕様のモック（+メニュー、または空のページの仕様のモック）は、ワークスペース内の仕様のモックを作成します。たとえばAlpenglow demo shopのモックのようになります。
新しいモックには、4010から数えて最初の空きポートが割り当てられます。
モックの設定とルートはワークスペースのmocksフォルダ内のファイルになるため、チームはGitでモックを共有できます。
ルートのモックから仕様を提供することも、仕様のモックにルートを追加することもできます。設定カードの仕様を提供で仕様を追加し、変更 › 仕様の提供を停止で外します。
開始と停止
開始（⌘R）をクリックします。上部のバーにモックのアドレスがhttp://127.0.0.1:4010のように表示されます。
モックが提供する仕様のサーバURLにパスが含まれる場合（https://demo.echolot.dev/v1）、アドレスはそのパスで終わり（http://127.0.0.1:4010/v1）、モックはそのパスの下で応答します。リクエストでそのパスを省略しても構いません。
アドレスの横のコピーボタンで、アドレスをコピーできます。
ターミナルから試してみましょう。
curl http://127.0.0.1:4010/users停止で停止します。どのモックが動作中かはサイドバーに表示されます。緑のドットと、仕様のタイトルの横のポートまたはルートの数です（Alpenglow demo shop · :4010、3 routes · stopped）。
モックを右クリックすると、開始または停止と削除…を選べます。削除する前に確認が表示されます。設定ファイルはゴミ箱に入り、仕様は残ります。
モックは、そのワークスペースのウインドウが開いている間、動作します。動作中のモックは、ルート、仕様、設定の変更を、停止せずに取り込みます。 ほかのプログラムが使っているポートは使えません。その場合はEcholotが知らせるので、別のポートを選択してください。
モックにリクエストを送信する
- ルートカードのリクエストを作成は、モックのルートを呼び出すリクエストのフォルダを作成し、
{{baseUrl}}にモックのアドレスを設定します。ルートからのリクエストを参照してください。 - 環境で使用（モックの動作中）は、
{{baseUrl}}がモックのアドレスであるMock: <name>という名前の環境を作成し、それを有効にします。 仕様からリクエストを生成で作成されるような、{{baseUrl}}で始まるリクエストは、別の環境を選択するまで、モックに送信されます。環境を参照してください。
設定
| 設定 | 内容 |
|---|---|
| 名前 | サイドバーに表示されるモックの名前。 |
| 仕様 | 提供する仕様、またはなし：ルートだけが応答します。開くは仕様ページで仕様を開き、仕様を提供と変更は仕様を選択するか、提供を停止します。 |
| ポート | 待ち受けるポート（1〜65535）。 |
| ネットワーク上の他のデバイスに応答 | すべてのネットワークインターフェースで待ち受けます。スマートフォンやコンテナからのテストに使います。オフの場合は、このMacからのみ接続できます。 |
| 遅延 | 応答の前に待つミリ秒数（最大60,000）。遅いAPIを試すために使います。 |
| 失敗 | 500を意図的に返すリクエストの割合（％）。クライアントの対処を試すために使います。 |
| チェック | 仕様がある場合：仕様に違反するリクエストを拒否（理由付きで400）。デフォルトでオンです。 |
リクエストが受け取るレスポンス
リクエストは、そのメソッドとパスに応答を持つ、次のうち最初のものに渡されます。
- モックのJavaScriptのルート。何も設定しないルートは、リクエストを次に渡します。
- 手書きのルート。ルートには複数のレスポンスを持たせられます。リクエストが名前またはステータスで指定することも、リクエストに対するルールで別のものを選ぶことも、それ以外はルートのデフォルトが応答することもできます。
- 次に説明する、仕様のオペレーション。
ルートでもオペレーションでも、固定のパスセグメントはパラメータより優先されるため、/pets/mineは/pets/{id}より先に選ばれます。
仕様のオペレーションでは、モックは次の順序でレスポンスを選びます。
- リクエストが指定したもの：
Prefer: code=404, example=emptyヘッダー、またはPostmanのx-mock-response-codeとx-mock-response-nameヘッダー。 - 仕様のレスポンスカードでそのオペレーションに選択したレスポンス。
- オペレーションの最初の成功レスポンス。
仕様のレスポンスカードには、すべてのオペレーションがメニューとともに一覧表示されます。最初の成功レスポンス、または記述されているステータスのいずれかで、複数の例があるステータスでは、その例を選べます。選択はモックとともに保存されます。
ボディは、レスポンスの名前付きの例（指定されたもの、または最初のもの）、単一のexample、またはスキーマから作った本文です。
スキーマから作る場合は、各フィールドの型、フォーマット、名前に合ったダミーデータ（フォーマットがemailのフィールドならメールアドレス）が、スキーマの制約の範囲内で、リクエストごとに作り直されます。
パスパラメータと同じ名前のフィールドには、その値が入ります。
仕様に複数のメディアタイプが記述されている場合は、リクエストのAcceptヘッダーで1つが選ばれます。記述されているヘッダーとコンテンツタイプも送信されます。
204、304、HEADへの応答にはボディがありません。
モックが返すそのほかの応答は次のとおりです。
| ステータス | 条件 |
|---|---|
400 | モックが仕様を提供していてチェックがオンで、リクエストが仕様に違反している場合：パス、クエリ、ヘッダー、Cookieのパラメータの欠落や型の誤り、コンテンツタイプの誤り、JSON Schemaに合わないボディ。ボディにすべての理由が一覧表示されます。 |
404 | そのパスを持つルートもオペレーションもない。 |
405 | パスはあるが、このメソッドではない。Allowヘッダーに、ルートと仕様を合わせた、受け付けるメソッドが一覧表示されます。 |
413 | リクエストボディが32 MBを超えている。 |
500 | 意図的な失敗（失敗を参照）。 |
501 | 指定されたステータスのレスポンスが、オペレーションに記述されていない。 |
ブラウザは別のポートのページからモックを呼び出せます。モックはプリフライトリクエストに応答し、CORSヘッダーを送信します。
ログ
ページの下部には、選択したモックが応答したリクエストが新しい順に一覧表示されます。時刻、ステータス、メソッドとパス、使われたレスポンス（ルートのレスポンス名、仕様の例の名前、またはボディがスキーマから作られた場合はgenerated）、かかった時間です。
問題は、リクエストの下の行に表示されます。仕様に違反した箇所や、ルートのボディで作れなかったダミーの値などです。
リクエストにポインタを置くと、レスポンスボディ、リクエストのボディ、コンテンツタイプが表示されます。レスポンスをコピーでボディをコピーできます。消去でログを空にします。
Appleのオンデバイスモデルが利用できる場合は、消去の横のボタンでログを要約できます。
例を仕様に保存する
仕様のオペレーションでは、モックが何を返すかの唯一の情報源が仕様なので、実際に得たレスポンスは例として仕様に保存します。
履歴で、仕様に従うリクエストのやり取りを右クリックし、モックの例として保存…を選択します。two tentsのような名前を付けて、保存をクリックします。
レスポンスは、そのリクエストが従う仕様の、該当オペレーションのレスポンスの名前付きの例になります。仕様のレスポンスカードで選択するか、Prefer: example=two tentsで指定します。
仕様にないパスや、仕様のないモックには、ルートを作成して、ボディを貼り付けます。
ネットワークで共有する
ネットワーク上の他のデバイスに応答をオンにすると、スマートフォン、タブレット、コンテナからモックに接続できます。ほかのデバイスは、ローカルネットワーク上のMacのアドレスとモックのポートを使います。
初回は、Echolotがローカルネットワーク上のデバイスを見つけて接続することを許可するかどうか、macOSが確認する場合があります。許可しないと、ほかのデバイスからモックに接続できません。 あとから、システム設定 › プライバシーとセキュリティ › ローカルネットワークで変更できます。
オンにすると、ネットワーク上の誰でもモックを呼び出せます。必要がないときは、共有をオフにしてください。
コマンドラインから
echolot mock alpenglow.yamlは仕様ファイルを提供し、echolot mock -w <workspace> <mock>は、ワークスペースのモックを、仕様の有無にかかわらず設定とルートとともに提供します。CIやコンテナで使えます。echolot mockを参照してください。
echolot fakeは、同じテンプレートからダミーデータを作成します。フィクスチャやシードデータに使えます。
エージェントは、EcholotのMCPサーバを通じてモックを開始してログを読み取れます。また、モックツールセットがオンの場合は、モックの作成、ルートの追加と変更、ダミーデータの生成、ルートからのリクエストの作成もできます。エージェントを参照してください。