# Моки (/ru/docs/mocks)

Мок — это сервер на порту вашего Mac, который отвечает как API. Фронтенд, приложения и тесты могут пользоваться им,
пока API ещё нет или пока настоящий не работает. Мок отвечает из двух источников, по отдельности или вместе:

- **Маршруты, созданные вручную**: метод, путь и то, что мок отвечает, — JSON, XML или текст. В телах могут быть
  тестовые данные (`{{$randomFullName}}`, `{{$randomEmail}}`), которые меняются при каждом запросе, и части запроса
  (`{{request.params.id}}`). Спецификация не нужна. См. [маршруты и тестовые данные](/docs/mocks/routes).
- **Спецификация OpenAPI**: каждая операция отвечает ответами, описанными в спецификации, её примерами или телом,
  собранным из её схем. Запросы, нарушающие спецификацию, получают `400` с объяснением причины, так что мок ещё и
  сообщает, когда клиент отправляет что-то не то.

Для ответов, которым нужны код или состояние, в моке могут быть и [маршруты на JavaScript](/docs/mocks/scripted-routes).

Откройте страницу через **Моки** в переключателе разделов боковой панели или нажмите <kbd>⌘</kbd><kbd>4</kbd>.

<Shot id="mocks-running" alt="Запущенный мок демо-магазина Alpenglow: сверху его адрес с кнопками «Использовать в окружении» и «Остановить», карточка «Настройки» со спецификацией, карточка «Маршруты» с двумя маршрутами, созданными вручную, и внизу журнал обработанных запросов — от маршрутов и от спецификации" />

## Создание мока [#creating-a-mock]

Нажмите **+** в заголовке **Моки** боковой панели или воспользуйтесь кнопками на пустой странице:

- **Новый мок** создаёт мок из маршрутов. В нём сразу есть один маршрут, `GET /users`, который отвечает пятью
  тестовыми пользователями, так что можно запустить мок и посмотреть, на что способно тело. Измените его или добавьте
  свои; см. [маршруты и тестовые данные](/docs/mocks/routes).
- **Мок спецификации** (в меню **+** или на пустой странице) создаёт мок спецификации из рабочего пространства,
  например **Мок спецификации «Alpenglow demo shop»**.

Новый мок занимает первый свободный порт, начиная с `4010`. Его настройки и маршруты — файл в папке `mocks` рабочего
пространства, поэтому команда делится моками через Git.

Мок из маршрутов тоже может обслуживать спецификацию, а у мока спецификации могут быть свои маршруты: **Обслуживать
спецификацию** в карточке **Настройки** добавляет её, **Изменить** › **Перестать обслуживать спецификацию** убирает.

## Запуск и остановка [#starting-and-stopping]

Нажмите **Старт** (<kbd>⌘</kbd><kbd>R</kbd>). В панели сверху виден адрес мока, например `http://127.0.0.1:4010`.
Если мок обслуживает спецификацию, в URL сервера которой есть путь (`https://demo.echolot.dev/v1`), адрес
заканчивается им (`http://127.0.0.1:4010/v1`), и мок отвечает по этому пути; запросы могут и не указывать его.
Кнопка копирования рядом с адресом копирует его.

Проверьте из Терминала:

```sh
curl http://127.0.0.1:4010/users
```

**Остановить** останавливает мок. Боковая панель показывает, какие моки запущены: зелёная точка и порт рядом с
названием спецификации или число маршрутов (`Alpenglow demo shop · :4010`, `3 routes · stopped`). Щёлкните мок
правой кнопкой, чтобы выбрать **Старт** или **Остановить** и **Удалить…**. Удаление сначала спрашивает; файл настроек
попадает в Корзину, а спецификация остаётся.

Моки работают, пока открыто окно их рабочего пространства. Работающий мок подхватывает изменения маршрутов,
спецификации и настроек, не останавливаясь. Порт, который занят другой программой, взять нельзя: Echolot сообщит об
этом; выберите другой порт.

### Отправка запросов в мок [#sending-requests-to-the-mock]

- **Создать запросы** в карточке **Маршруты** создаёт папку запросов, которые обращаются к маршрутам мока, с `{{baseUrl}}`,
  равным адресу мока. См. [запросы из маршрутов](/docs/mocks/routes#requests-from-routes).
- **Использовать в окружении** (пока мок запущен) создаёт окружение `Mock: <name>`, в котором `{{baseUrl}}` — адрес
  мока, и делает его активным. Запросы, начинающиеся с `{{baseUrl}}`, например созданные
  [«Создать запросы»](/docs/specs#requests-that-follow-the-spec) из спецификации, после этого идут в мок, пока вы не
  выберете другое окружение. См. [Окружения](/docs/workspaces/environments).

## Настройки [#settings]

| Настройка | Что делает |
| --- | --- |
| **Имя** | Имя мока в боковой панели. |
| **Спецификация** | Спецификация, которую он обслуживает, или **Нет: отвечают только его маршруты**. **Открыть** открывает спецификацию на странице «Спецификации»; **Обслуживать спецификацию** и **Изменить** выбирают спецификацию или перестают её обслуживать. |
| **Порт** | Порт, который он слушает, от 1 до 65535. |
| **Отвечать другим устройствам в сети** | Слушает на всех сетевых интерфейсах, чтобы можно было тестировать с телефона или из контейнера. Выключено: мок доступен только с этого Mac. |
| **Задержка** | Сколько миллисекунд ждать перед каждым ответом, до 60 000, чтобы попробовать медленное API. |
| **Ошибки** | Доля запросов в процентах, на которые подставляется `500`, чтобы проверить, как справляется клиент. |
| **Проверки** | Для спецификации: **Отклонять запросы, нарушающие спецификацию (400 с причинами)**. По умолчанию включено. |

## Какой ответ получает запрос [#which-response-a-request-gets]

Запрос идёт к первому из перечисленного, у кого есть ответ для его метода и пути:

1. [Маршруты на JavaScript](/docs/mocks/scripted-routes) мока. Маршрут, который ничего не задаёт, передаёт запрос
   дальше.
2. Его [маршруты, созданные вручную](/docs/mocks/routes). У маршрута может быть несколько ответов; запрос может
   попросить нужный по имени или статусу, другие выбирают правила для запроса, а в остальных случаях отвечает ответ
   маршрута по умолчанию.
3. Операции спецификации, как описано ниже.

Буквальные сегменты пути важнее параметров, поэтому `/pets/mine` выбирается раньше `/pets/{id}` и в маршрутах, и в
операциях.

Для операции спецификации мок выбирает ответ в таком порядке:

1. То, что просит запрос: заголовок `Prefer: code=404, example=empty` или заголовки Postman `x-mock-response-code` и
   `x-mock-response-name`.
2. Ответ, выбранный для операции в карточке **Ответы спецификации**.
3. Первый успешный ответ операции.

Карточка **Ответы спецификации** перечисляет каждую операцию с меню: **Первый успешный** или один из описанных
статусов, а если у статуса несколько примеров, то и пример. Выбор сохраняется вместе с моком.

Тело — это именованный пример ответа (запрошенный или первый), его единственный `example` либо тело, собранное из
схемы: тестовые данные, подходящие по типу, формату и имени каждого поля (адрес электронной почты для поля формата
`email`), в пределах ограничений схемы, создаваемые заново при каждом запросе. Поле с именем, как у параметра пути,
повторяет его значение. Если в спецификации описано несколько типов медиа, один из них выбирает заголовок `Accept`
запроса. Описанные заголовки и тип содержимого тоже отправляются. У ответов `204`, `304` и на `HEAD` тела нет.

Другие ответы мока:

| Статус | Когда |
| --- | --- |
| `400` | Мок обслуживает спецификацию, проверки включены, и запрос её нарушает: нет параметра пути, запроса, заголовка или cookie либо у него неверный тип, неверный тип содержимого или тело не соответствует своей JSON Schema. В теле перечислены все причины. |
| `404` | Такого пути нет ни у одного маршрута и ни у одной операции. |
| `405` | Путь есть, но не с этим методом. Заголовок `Allow` перечисляет методы, которые он принимает, из маршрутов и спецификации вместе. |
| `413` | Тело запроса больше 32 МБ. |
| `500` | Подставленная ошибка (см. **Ошибки**). |
| `501` | Для операции не описан ответ с запрошенным статусом. |

Браузеры могут обращаться к моку со страницы на другом порту: он отвечает на предварительные запросы и отправляет
заголовки CORS.

## Журнал [#the-log]

Внизу страницы перечислены запросы, на которые ответил выбранный мок, новые первыми: время, статус, метод и путь,
использованный ответ (имя ответа маршрута, имя примера спецификации или `generated`, если тело собрано из схемы) и
сколько это заняло. Проблемы указаны в строках под запросом: где он нарушил спецификацию или какое тестовое значение
не удалось создать в теле маршрута. Наведите указатель на запрос, чтобы увидеть тело ответа, тело запроса и тип
содержимого; **Скопировать ответ** копирует тело. **Очистить** очищает журнал.

Там, где доступна встроенная модель Apple, кнопка рядом с **Очистить** составляет сводку журнала.

## Сохранение примеров в спецификацию [#saving-examples-into-the-spec]

Для операций спецификации единственный источник того, что отвечает мок, — сама спецификация, поэтому настоящий
полученный ответ сохраняется в неё как пример: в [Истории](/docs/workspaces/history) щёлкните правой кнопкой обмен
запроса, который следует спецификации, и выберите **Сохранить как пример мока…**. Задайте имя, например `two tents`, и
нажмите **Сохранить**.

Ответ становится именованным примером ответа его операции в спецификации, которой следует запрос. Выберите его в
карточке **Ответы спецификации** или запросите заголовком `Prefer: example=two tents`.

Для пути, которого нет в спецификации, и для мока без спецификации создайте [маршрут](/docs/mocks/routes) и вставьте
тело.

## Доступ в сети [#sharing-on-the-network]

Включите **Отвечать другим устройствам в сети**, чтобы обращаться к моку с телефона, планшета или из контейнера.
Другие устройства используют адрес вашего Mac в локальной сети и порт мока.

В первый раз macOS может спросить, можно ли Echolot находить устройства в локальной сети и подключаться к ним.
Разрешите, иначе другие устройства не смогут обратиться к моку. Ответ можно изменить позже в **Системные настройки ›
Конфиденциальность и безопасность › Локальная сеть**.

После этого к моку может обратиться любой, кто есть в сети. Когда доступ не нужен, выключите его.

## Из командной строки [#from-the-command-line]

`echolot mock alpenglow.yaml` обслуживает файл спецификации, а `echolot mock -w <workspace> <mock>` обслуживает мок
рабочего пространства с его настройками и маршрутами, со спецификацией или без, для CI или контейнера. См.
[echolot mock](/docs/cli/mock). [`echolot fake`](/docs/cli/fake) создаёт тестовые данные по тем же шаблонам, для
фикстур и начальных данных.

Агенты могут запускать моки и читать их журналы через MCP-сервер Echolot, а при включённом наборе инструментов
**Моки** — создавать моки, добавлять и изменять маршруты, генерировать тестовые данные и создавать запросы из
маршрутов. См. [Агенты](/docs/ai/agents).