Перейти к содержимому
Поиск
Разработка

MSW: API для интерфейсов — мастерская и 9 сетевых сценариев

Готовим интерфейс к разным ответам API: каталог, форма, пустые данные, задержка, отмена, ошибки и повтор. Девять настоящих сценариев MSW, Node.js-тесты и исходники.

Александр Некрасов
MSW: API для интерфейсов — мастерская и 9 сетевых сценариев — обложка

MSW: проверяем интерфейс до готовности настоящего API

Макет каталога выглядит хорошо, пока у него четыре аккуратные карточки и мгновенный ответ. В рабочем приложении результат может оказаться пустым, сеть — медленной, форма — отклонённой сервером, а доступ — просроченным. Чтобы заранее увидеть эти ситуации, нужен управляемый источник ответов. Mock Service Worker, или MSW, позволяет описать поведение API и проверять интерфейс с обычными сетевыми запросами.

Приложение продолжает вызывать fetch, читать JSON, проверять HTTP-статус и отображать результат. В учебной среде ответ ему предоставляет MSW. Поэтому можно разрабатывать кабинет до готовности backend, воспроизводить редкую ошибку на демонстрации или использовать одинаковые сценарии в автоматических тестах. При переходе к настоящему API меняется окружение запросов, а не вся логика компонентов.

Ниже находится мастерская из девяти ситуаций на примере сервиса услуг: каталог, поиск, страницы, создание записи, медленная сеть, отмена, HTTP-ошибка, сетевой сбой, временный ответ и учебный доступ. Это работающая библиотека, а не заранее нарисованные результаты. В ZIP лежат исходники интерфейса, общие handlers для браузера и Node.js, тесты, готовая сборка и инструкции Windows/Linux.

Где это полезно: кабинет, CRM, админка и согласование дизайна

Представьте команду, которая одновременно создаёт API и личный кабинет. Серверная часть ещё не умеет сохранять услугу, но форма уже нужна для обсуждения. Разработчик описывает ожидаемые ответы 201 и 422, дизайнер проверяет ошибки рядом с полями, менеджер видит понятное подтверждение. Когда реальный endpoint готов, тот же сценарий повторяют с ним и сравнивают контракт.

Другой случай — интерфейс существует, но проблема возникает редко. Например, внешняя система отвечает 503 только во время обслуживания. Вместо попыток поймать этот момент вы включаете известный сценарий и проверяете повтор, сохранение введённых данных и сообщение пользователю. Команда может воспроизвести ситуацию на любом компьютере, не меняя рабочий сервер.

MSW полезен и для демонстраций: стабильные учебные данные помогают обсуждать продукт, не показывая клиентские записи. При этом демонстрацию следует явно подписывать. Ответ mock-сервиса не доказывает, что платёж прошёл, запись попала в базу или письмо доставлено. Он показывает, как интерфейс реагирует на соответствующий договорённый ответ.

MSW, тестовый сервер и заглушка функции: что выбираем

Самый простой способ показать данные — вернуть массив прямо из компонента. Это удобно для первого эскиза, но перестаёт проверять разбор JSON, статус ответа, заголовки и отмену запроса. Подмена функции клиента в каждом тесте тоже может привести к разным правилам: один тест ожидает поле total, другой — count. Общий слой handlers помогает держать один понятный сетевой контракт.

Настоящий тестовый сервер проверяет другую часть системы: маршрутизацию, авторизацию, бизнес-правила, базу и интеграции. Он нужен для подтверждения работоспособности backend. MSW не исполняет ваш PHP-контроллер и не обращается к PostgreSQL вместо него. Для настоящих сервисов в тестах пригодится Testcontainers, а для ручных и автоматизированных API-коллекций — Bruno.

Эти инструменты удобно использовать вместе. MSW быстро перебирает состояния интерфейса, интеграционные проверки подтверждают работу настоящего API, а небольшое число сквозных сценариев проверяет связь частей. Выбор зависит от вопроса: «как показать ошибку поля» и «правильно ли сервер проверил право пользователя» требуют разных доказательств.

Мини-мастерская: девять сетевых ситуаций в одном кабинете

Сначала нажмите «Включить Mock API». После запуска появятся состояние и scope — каталог, внутри которого действует Service Worker. Выберите ситуацию, прочитайте подсказку и выполните запрос. Ниже одновременно видны интерфейс, метод и адрес запроса, JSON-ответ либо ошибка. Последние действия сохраняются в журнале текущей страницы, поэтому удобно сравнивать первую и повторную попытки.

Начните с каталога и поиска по слову «кабинет». Затем попробуйте пустой результат, невалидную форму и отмену медленного запроса. В сценарии временного ответа добавьте разовую акцию и выполните запрос дважды. В сценарии доступа сравните ответ без учебного заголовка и с ним. После изменения параметров старый результат очищается, чтобы его нельзя было скачать как новый.

Все данные вымышленные и находятся в памяти страницы. Учебный API не сохраняет услуги на сайте. После экспериментов нажмите «Выключить и убрать регистрацию». На телефоне можно открыть мастерскую отдельно: кнопки и поля располагаются вертикально, а длинный JSON прокручивается внутри блока. Исходники доступны в нижней части мастерской и полным архивом.

Версия MSW 3 и воспроизводимые зависимости

Проект закреплён на MSW 3.0.7, Bootstrap 5.3.9 и esbuild 0.28.2. В примерах используется Node.js 24 LTS не ниже 24.15.0. Сама библиотека допускает Node от 22.12.0, однако воспроизводимость этого проекта проверяется на выбранной ветке 24. Точный граф зависимостей находится в package-lock.json, поэтому используйте npm ci вместо произвольного обновления всех пакетов.

Для MSW 3 нужно внимательно смотреть на текущий API. В старых статьях встречаются rest.get и параметр onUnhandledRequest. Здесь используются http, HttpResponse и актуальный onUnhandledFrame. У worker.stop асинхронный результат: перед удалением собственной регистрации мы ожидаем завершения остановки. Перенос одного старого фрагмента без проверки версии может оставить поведение, отличное от ожидаемого.

В исходниках сохранён официальный mockServiceWorker.js из установленного пакета. При обновлении MSW обновляйте его вместе с клиентским bundle. Успешная установка npm сама по себе не проверяет браузерный worker: после обновления повторите включение, запрос, остановку и проверку области действия. Основные изменения ищите в официальных материалах по миграции и релизах проекта.

Фрагмент package.json

{
  "name": "aen-msw-workshop", "version": "1.0.0", "private": true, "type": "module",
  "engines": {"node": ">=24.15.0"},
  "scripts": {"build": "node tools/build.mjs", "start": "node tools/serve.mjs", "test": "node --test tests/*.test.mjs", "capture": "node tools/capture.mjs"},
  "dependencies": {"msw": "3.0.7", "bootstrap": "5.3.9"},
  "devDependencies": {"esbuild": "0.28.2"}
}

Windows: установка и первый запуск из PowerShell

Распакуйте архив в отдельный каталог и откройте PowerShell. Проверьте версию Node.js, установите зависимости, выполните тесты и сборку. Команда npm start поднимает небольшой статический сервер на 127.0.0.1:8596. Он раздаёт HTML, CSS, JavaScript и файл Service Worker. Настоящего маршрута сохранения услуг у него нет: ответы API появятся только после включения MSW в браузере.

Открывайте адрес localhost или 127.0.0.1 из терминала. Двойной щелчок по index.html создаёт адрес file://, для которого этот сценарий не предназначен. Если порт занят, задайте переменную PORT перед запуском и используйте новый адрес. Не останавливайте чужой процесс только ради стандартного номера порта; выберите свободный.

После запуска откройте каталог, найдите услугу и создайте одну тестовую запись. Затем выключите Mock API кнопкой и завершите собственный сервер через Ctrl+C. Такой порядок позволяет отличить остановку запросов от остановки сервера файлов: это два отдельных механизма, и один не должен восприниматься как подтверждение другого.

Фрагмент README.md

Set-Location .\msw-project
node --version
npm ci --ignore-scripts
npm test
npm run build
npm start
$env:PORT = "8606"
npm start

Linux: тот же проект, handlers и тесты

На Linux выполняются те же npm-команды и используются те же исходники. Это полезно для CI: команда может разрабатывать интерфейс в Windows, а автоматические проверки запускать в Linux. Важнее совпадение версии зависимостей и контракта, чем похожий вывод терминала. Проверяйте реальные значения ответа, ошибки и ограничения, а не только сообщение «тесты пройдены».

Команда capture запускает настоящий setupServer и обычный fetch, затем записывает четырнадцать ответов и ошибок в runtime/capture.json. Этот каталог относится к результатам проверки, поэтому не нужен для работы мастерской и исключён из исходного архива. В браузерной демонстрации ответы вычисляются заново: запись Node используется как отдельное доказательство поведения общих handlers.

Без графического окружения Linux способен выполнить Node-тесты. Для проверки Service Worker всё равно нужен браузер на доверенном origin. Серверные тесты не проверяют касания, фокус, размер кнопок или разрешённый scope. Поэтому автоматическая проверка и просмотр адаптивного интерфейса дополняют друг друга.

Фрагмент README.md

cd msw-project
node --version
npm ci --ignore-scripts
npm test
npm run build
npm run capture
npm start

Как запрос проходит через браузер и MSW

Кнопка запуска вызывает обычный клиент requestJSON. Он передаёт fetch адрес, метод, заголовки, тело и AbortSignal. Активный Service Worker получает запрос страницы под своим управлением, а MSW сопоставляет его с handlers. Найденный обработчик возвращает ответ с нужным статусом и данными. Клиент обрабатывает его тем же способом, что и ответ рабочего сервиса.

Важна точность адреса. Наша фабрика makeApi получает абсолютную базу и создаёт endpoints только внутри собственного api-каталога. Поиск и номер страницы передаются query-параметрами. Обработчик проверяет путь и метод, а параметры читает через URL. Это позволяет показывать запросы, которые похожи на реальный контракт, без захвата всех адресов origin.

Не смешивайте состояние интерфейса с деталями mock. Компоненту не нужно знать, что данные пришли из MSW. В нашем проекте об этом знает панель учебного режима, а клиент и отрисовка работают с обычным результатом. Такой подход облегчает замену окружения и не заставляет переписывать форму при подключении backend.

Фрагмент src/client.mjs

export class ApiError extends Error{constructor(message,status,details){super(message);this.name='ApiError';this.status=status;this.details=details;}}
export async function requestJSON(url,options={}){const response=await fetch(url,options);let body;try{body=await response.json();}catch{throw new ApiError('Сервер вернул неожиданный формат.',response.status,null);}if(!response.ok)throw new ApiError(body.message||`HTTP ${response.status}`,response.status,body);return{status:response.status,body};}

Scope Service Worker: ограничиваем мастерскую своим каталогом

Service Worker управляет страницами в своей области действия. Для сайта с множеством материалов нельзя включать учебный перехват на всём домене ради одного примера. Поэтому адрес worker и scope вычисляются относительно app.js: при публикации в каталоге плагина обе границы остаются внутри public этой мастерской. В корне WordPress ничего не регистрируется.

Дополнительно handlers используют точный origin и собственный путь api. Нераспознанные запросы пропускаются через onUnhandledFrame: bypass. Это необходимо для обычных файлов и соседнего содержимого. В автоматических Node-тестах выбран error, чтобы случайный непокрытый запрос не ушёл в сеть незаметно. Назначение этих режимов различается, поэтому механически копировать строгую тестовую настройку на весь сайт не нужно.

В мастерской нет заголовка Service-Worker-Allowed, расширяющего доступ до корня. Не добавляйте его ради исправления неправильно выбранного пути. Сначала сопоставьте адрес HTML, app.js, worker и scope. Документация о расположении worker объясняет связь этих адресов; в нашем стенде используется узкая область.

const scope = new URL('./', import.meta.url).href;
const workerURL = new URL('mockServiceWorker.js', scope).href;
const api = makeApi(new URL('api/', scope).href);
const worker = setupWorker(...api.handlers);
const registration = await worker.start({
  serviceWorker: { url: workerURL, options: { scope, updateViaCache: 'none' } },
  quiet: true,
  onUnhandledFrame: 'bypass',
});

Пример 1. Каталог услуг и нормальный успешный ответ

Первый сценарий показывает четыре карточки из двенадцати. В ответе находятся items, total, page, pageSize и pages. Разделение списка и общего количества важно: интерфейс не должен считать число страниц по длине текущей порции. На последней странице может быть меньше элементов, но это не меняет общего результата поиска.

Цена хранится в копейках и форматируется только при выводе. Название и категория вставляются через textContent, поэтому учебное поле не превращается в HTML. Это удобно проверять ещё до backend: длинное название, символы кавычек или пустой массив сразу показывают слабые места вёрстки. Сама библиотека MSW не выбирает формат цены и способ вставки текста — эти решения остаются в коде приложения.

В собственном кабинете начните с минимального контракта одной карточки: идентификатор, имя, статус, цена или дата. Не добавляйте десятки необязательных полей без потребности интерфейса. Затем согласуйте, какие поля могут отсутствовать, и подготовьте примеры такого отсутствия. Стабильная форма ответа делает состояния понятными и для пользователя, и для тестов.

http.get(endpoint('services'), ({ request }) => {
  return list(request);
});
// Обычный клиент не зависит от среды MSW:
const { body } = await requestJSON(api.endpoint('services'));
console.log(body.items, body.total);

Пример 2. Пустой ответ — отдельное полезное состояние

Пустой список не означает сетевую ошибку. Пользователь мог открыть новый кабинет, выбрать слишком узкий фильтр или ещё не создать первую запись. В примере endpoint возвращает HTTP 200 и items: []. Интерфейс завершает загрузку и предлагает изменить поиск, вместо того чтобы оставлять человека перед пустой областью.

Для своего продукта продумайте разные причины пустоты. «Нет записей вообще» может предлагать создать первую; «ничего не найдено» — очистить фильтр; «данные пока готовятся» — объяснить ожидание. Один текст «нет данных» часто не даёт следующего действия. Наличие отдельного mock-сценария помогает обсудить формулировку с командой и увидеть её на телефоне.

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

http.get(endpoint('empty'), () => HttpResponse.json({
  items: [], total: 0, page: 1, pageSize: 4, pages: 1,
}));

Пример 3. Поиск и пагинация без потери параметров

Выберите поиск и страницы. Без фильтра доступны три страницы по четыре услуги; на третьей находятся идентификаторы 9–12. Запрос с «кабинет» возвращает одну запись. Строка поиска проходит через URLSearchParams, поэтому кириллица и специальные символы кодируются стандартным способом. Обработчик приводит запрос к нижнему регистру и сравнивает с названиями.

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

В проекте отрицательный, дробный и нечисловой номер страницы отклоняется ответом 400. В рабочем API ограничения размера страницы и сортировки тоже должны быть частью контракта. Не доверяйте query только потому, что в интерфейсе есть выпадающий список: адрес можно изменить вручную. Mock показывает договорённость, а сервер обязан проверять её самостоятельно.

const url = new URL(api.endpoint('services'));
url.searchParams.set('q', 'кабинет');
url.searchParams.set('page', '1');
const result = await requestJSON(url);

Пример 4. Создание записи, HTTP 201 и ошибки 422

В сценарии формы отправляется POST с названием и ценой в копейках. Корректный запрос получает 201 и объект новой услуги. Обработчик добавляет её в массив текущего опыта, поэтому повторное создание получает следующий идентификатор. Смена сценария возвращает исходный набор. Это небольшая модель состояния API, а не постоянная база на сервере.

Оставьте имя пустым или задайте отрицательную цену. Ответ 422 содержит errors.name и errors.price, а интерфейс размещает сообщения около соответствующих полей. Общая надпись объясняет, что нужно исправить форму. Такой формат удобнее одного строкового сообщения, если сервер может обнаружить несколько независимых ошибок сразу.

Поле цены требует целое безопасное число в заданном диапазоне. Неправильный JSON и массив вместо объекта дают 400. Разделение ошибок позволяет тестировать и клиентский разбор, и поведение формы. Для настоящего проекта правила допустимых значений следует согласовать с сервером; при необходимости используйте общую схему, например подход из материала про Zod.

const result = await requestJSON(api.endpoint('services'), {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'Поддержка кабинета', price: 35000 }),
});
// При 422 клиент получает details.errors и связывает их с полями.

Пример 5. Медленный запрос, загрузка и отмена

Мгновенный mock скрывает состояние загрузки. В этом опыте handler действительно ждёт две секунды через delay(2000). Пока запрос выполняется, основная кнопка отключена, статус сообщает о работе, а отмена остаётся доступной. Пользователь видит, что действие принято, и не запускает несколько одинаковых операций подряд.

Нажмите отмену до получения ответа. AbortController прекращает ожидание со стороны клиента. Дополнительно интерфейс использует номер ревизии запроса: даже если обработчик закончит работу позже, результат старой ревизии не попадёт на экран. Это полезно и для поиска, когда человек быстро меняет фильтры и ответы приходят в другом порядке.

Отмена fetch не означает отмену уже начатой серверной операции. Если рабочий backend отправляет письмо или формирует отчёт, ему нужен отдельный протокол отмены и статус задания. В мастерской отмена демонстрирует клиентское поведение без таких побочных действий. API delay позволяет отдельно управлять временем ответа, а не замедлять весь интерфейс искусственной паузой.

http.get(endpoint('slow'), async ({ request }) => {
  await delay(2000);
  return list(request);
});
const controller = new AbortController();
const pending = requestJSON(api.endpoint('slow'), { signal: controller.signal });
// По нажатию пользователя:
controller.abort();

Пример 6. HTTP 503 и понятная повторная попытка

Первая попытка в этом сценарии получает 503 с объяснением временной недоступности. Повторный запрос возвращает каталог. Счётчик попыток живёт в модели опыта и сбрасывается при повторном выборе сценария. Поэтому ошибку можно воспроизвести точно, а не надеяться на случайный ответ тестового сервера.

Обработчик добавляет Retry-After: 1. В мастерской повтор выполняется вручную, чтобы человек видел обе стадии. В настоящем клиенте автоматический повтор должен учитывать тип операции, лимит попыток, задержку и возможность повторного выполнения. Повтор безопасного чтения и повтор платежа — разные задачи; успешный mock не делает любое действие идемпотентным.

Посмотрите, сохраняется ли полезный контекст при ошибке. Пользователь должен понимать, какое действие не завершилось и что можно сделать дальше. Не заменяйте всю страницу одной технической трассировкой. На этой странице отдельно показываются дружелюбный статус, код HTTP и структурированные детали для изучения. Такой разбор помогает отделить текст продукта от диагностической информации.

http.get(endpoint('unstable'), ({ request }) => {
  attempt++;
  return attempt === 1
    ? HttpResponse.json({ message: 'Сервис временно недоступен.' }, {
        status: 503, headers: { 'Retry-After': '1' },
      })
    : list(request);
});

Пример 7. Сетевая ошибка без HTTP-ответа

Сетевой сбой отличается от статуса 503: приложение не получило ответ с кодом, заголовками и JSON. HttpResponse.error создаёт такой сценарий, а fetch отклоняет Promise. В интерфейсе появляется сообщение, что HTTP-ответ отсутствует. Нельзя пытаться читать status у несуществующего Response или объявлять любую сетевую ошибку «сервер вернул 500».

Этот опыт полезен для устройств с нестабильным соединением, внешних интеграций и проверки сообщения после потери сети. При этом он не доказывает правильность CORS, DNS, сертификатов или прокси реальной системы. Для этих причин нужны отдельные проверки окружения. Mock воспроизводит наблюдаемое клиентом состояние ошибки, а не всю физическую причину отказа.

В собственной форме сохраняйте введённые данные после такого сбоя. Если пользователь вынужден заново заполнять десять полей, корректный catch не делает интерфейс удобным. Также не предлагайте бесконечный повтор без обратной связи. Покажите состояние, оставьте возможность вернуться к действию и объясните, что результат отправки не подтверждён.

http.get(endpoint('offline'), () => HttpResponse.error());
try {
  await requestJSON(api.endpoint('offline'));
} catch (error) {
  // У сетевой ошибки нет HTTP status нашего ApiError.
  console.log(error.name);
}

Пример 8. Временный handler, разовая акция и resetHandlers

Нажмите «Добавить разовую акцию» и выполните запрос. Ответ покажет скидку 15%. Следующий запрос вернёт стандартный тариф без скидки. Для этого worker.use добавляет handler с once: true перед основным обработчиком. Такой приём помогает проверить редкий ответ, не переписывая постоянные сценарии приложения.

Кнопка сброса удаляет временные handlers и возвращает учебные данные. Это две разные операции: resetHandlers восстанавливает набор обработчиков, а api.reset очищает массив и счётчики нашей модели. Библиотека не знает, какие переменные разработчик использует внутри resolver. Если забыть о данных, следующий тест может зависеть от действий предыдущего.

Практический пример — показать одну ошибку сохранения, а затем успех, либо один раз вернуть новый тариф для проверки баннера. В тестах фиксируйте порядок и смысл ответа. Не делайте очередность сложной настолько, что читателю приходится разгадывать скрытый сценарий. use и resetHandlers дают механизм, а понятную структуру опытов задаёт проект.

worker.use(http.get(api.endpoint('offer'), () =>
  HttpResponse.json({ title: 'Разовая акция', discount: 15 }),
  { once: true },
));
// Удалить временные обработчики:
worker.resetHandlers();
// Отдельно сбросить данные нашего учебного API:
api.reset();

Пример 9. Ответы 401 и 200 для состояния доступа

Последний сценарий показывает личный раздел. Без демонстрационного заголовка запрос получает 401, а при включённой отметке — имя учебного пользователя, роль и число проектов. Это позволяет проверить сообщение о необходимости входа и то, как интерфейс меняется после получения данных. Реальные пароли, cookies и токены в опыте не используются.

Заголовок X-Demo-Session специально простой и явно учебный. Он не является способом авторизации рабочего приложения. Любой посетитель может воспроизвести его, поэтому по нему нельзя выдавать реальные данные или права. В production доступ должен проверять сервер на основании настоящей сессии и правил приложения.

Полезно отдельно подготовить варианты 401, 403 и пустого доступного списка. Они означают разные ситуации для пользователя: нужно войти, нет права на действие или просто ещё нет записей. В этой мастерской подробно показана первая граница; расширяйте контракт осознанно и не называйте все отказы одним текстом «ошибка сервера».

http.get(endpoint('profile'), ({ request }) => {
  const allowed = request.headers.get('x-demo-session') === 'demo-allowed';
  return allowed
    ? HttpResponse.json({ name: 'Демо-пользователь', role: 'Наблюдатель', projects: 3 })
    : HttpResponse.json({ message: 'Включите учебную демо-сессию.' }, { status: 401 });
});

Один набор handlers для браузера и Node.js

Файл api.mjs не зависит от DOM. Он создаёт handlers и собственное состояние, принимая базовый URL. Браузер передаёт адрес своего вложенного каталога, а тесты — специальный домен aen-msw.invalid. Благодаря этому правила поиска, формы и ошибок выполняются в обеих средах, а не копируются в два расходящихся файла.

В Node применяется setupServer. Несмотря на название, он не поднимает HTTP-порт и не делает API доступным другому процессу. Перехват действует в текущем процессе Node. Если отдельный PHP-скрипт выполнит запрос по тому же адресу, эти handlers для него автоматически не появятся. Для общего тестового HTTP API нужен настоящий сервер, а не только setupServer.

Жизненный цикл теста начинается с listen, между опытами сбрасывает обработчики и данные, а в конце вызывает close. Такое завершение важно, чтобы перехват не влиял на следующие проверки. Существующий материал про Vitest показывает организацию тестов; здесь используется встроенный node:test, чтобы сосредоточиться на сетевом контракте.

Фрагмент README.md

import {setupServer} from 'msw/node';
import {makeApi} from './src/api.mjs';
const api = makeApi('https://aen-msw.invalid/workshop/api/');
const server = setupServer(...api.handlers);
server.listen({onUnhandledFrame:'error'});
try {
  const response = await fetch(api.endpoint('services'));
  console.log(await response.json());
} finally {
  server.close();
}

Что проверяют тесты и чего они не подтверждают

В проекте восемнадцать содержательных проверок: количество карточек, поиск по кириллице, третья страница, пустой ответ, неправильный номер страницы, создание услуги, ошибки полей, повреждённый JSON, неверный тип тела, дробная цена, повтор после 503, сетевая ошибка, фактическая задержка, отмена, временный handler, сброс, учебный доступ и допустимость базы URL.

Тест формы не ограничивается статусом 201: он затем читает список и проверяет созданное значение. Тест задержки измеряет прошедшее время, а тест отмены ожидает AbortError. При этом ошибка, которую мы намеренно описали в mock, не проверяет аналогичный путь настоящего сервера. Она проверяет потребителя и согласованную модель ответа.

Для полного проекта добавьте контрактные проверки с backend и отдельные браузерные проверки интерфейса. Если ваш API поменял имя поля, mock не узнает об этом сам. Хорошая практика — хранить согласованные схемы и реальные обезличенные примеры ответов, а после изменений сравнивать их с handlers. Контроль расхождения важнее увеличения числа почти одинаковых тестов.

before(() => server.listen({ onUnhandledFrame: 'error' }));
beforeEach(() => {
  server.resetHandlers();
  api.reset();
});
after(() => server.close());

test('страница 3 содержит записи 9–12', async () => {
  const result = await requestJSON(api.endpoint('services') + '?page=3');
  assert.deepEqual(result.body.items.map(x => x.id), [9, 10, 11, 12]);
});

Кеш запросов, Storybook и компоненты интерфейса

MSW удобно подключать к окружению компонентных демонстраций. Например, одна история карточки показывает обычный ответ, другая — пустой список, третья — долгую загрузку. При этом компонент продолжает обращаться к тому же клиенту. В материале про Storybook разобрана идея мастерской состояний; MSW может стать источником управляемых сетевых ответов для таких историй.

Если приложение использует кеш запросов, состояние сети и состояние кеша нужно разделять. Новый handler может не вызваться, когда клиент уже имеет свежий результат. Для опыта очистите нужный кеш или явно запросите обновление. Иначе возникает ложный вывод, что MSW не работает, хотя запрос просто не был отправлен. Сценарии такого клиента рассмотрены в TanStack Query во Vue.

Не превращайте каждую историю в произвольную копию backend. Поддерживайте небольшой набор понятных состояний с общими данными. У каждого должны быть цель, входные условия и ожидаемое действие человека. Это делает демонстрацию полезной для дизайна и приёмки, а не только удобной для разработчика.

Включение, остановка и несколько вкладок

В этой мастерской MSW не запускается автоматически. Пользователь явно включает режим, видит его состояние и может остановить. Для одной области применяется Web Lock: если тот же стенд уже включён в другой вкладке, новая вкладка объяснит причину и не будет бороться за общую регистрацию. Это локальное ограничение нашего учебного интерфейса, а не универсальное требование MSW.

Остановка сначала отменяет текущий запрос, затем ожидает worker.stop. После этого код сверяет scope и точный scriptURL перед unregister, а затем отдельно проверяет отсутствие регистрации через getRegistration(scope). Если MSW уже удалил её, повторный unregister может вернуть false: важен проверенный итог, а не только это возвращаемое значение. В журнале отображаются ownRegistrationAbsent и exactScopeAbsent. Нельзя удалять все регистрации через getRegistrations только потому, что закончен один опыт: на том же origin может работать другое приложение. Проверка принадлежности защищает соседние мастерские и уже существующие функции сайта.

Событие pagehide выполняет дополнительную очистку, но уход со страницы не является удобным подтверждением результата. Для проверяемого завершения используйте кнопку остановки и её сообщение. Подробное различие между остановкой перехвата и удалением регистрации описано в документации stop. После отключения кнопка запроса в нашей мастерской недоступна.

await worker.stop();
if (registration?.scope === scope) {
  const script = registration.active?.scriptURL
    || registration.waiting?.scriptURL
    || registration.installing?.scriptURL;
  if (script === workerURL) await registration.unregister();
}
const remaining = await navigator.serviceWorker.getRegistration(scope);
const exactScopeAbsent = !remaining || remaining.scope !== scope;
// getRegistration может вернуть регистрацию родительского scope.
// Её не удаляем: проверяем только собственный точный каталог.

Linux/VPS: разместить отдельный стенд по HTTPS

Для публичной мастерской достаточно статической раздачи public. Node.js нужен при сборке и для тестов, но постоянный Node-процесс на VPS не требуется. Разместите файлы в отдельном каталоге с чтением для web-сервера. Исходники, runtime-отчёты, секреты и рабочие клиентские JSON не должны автоматически попадать в web-root вместе с демонстрацией.

На удалённом сервере используйте HTTPS и настоящий домен. Исключение браузеров для localhost не означает, что HTTP по IP VPS будет подходить для Service Worker. Перед переключением проверьте DNS, сертификат, MIME JavaScript и фактическое расположение файла worker. Если он получает HTML страницы ошибки, регистрация не заработает независимо от правильности handlers.

Примеры для Nginx и Caddy входят в архив. Подставьте свой домен и путь, проверьте конфигурацию и только затем перезагружайте свой сервис. Эти команды показывают способ внедрения; они не означают, что стенд уже развёрнут на вашем рабочем VPS. Практические настройки также разобраны в статье Nginx и статье Caddy.

Фрагмент README.md

sudo install -d -m 0755 /srv/aen-msw/public
sudo cp -a public/. /srv/aen-msw/public/
sudo chown -R root:root /srv/aen-msw/public
sudo find /srv/aen-msw/public -type d -exec chmod 0755 {} +
sudo find /srv/aen-msw/public -type f -exec chmod 0644 {} +

Фрагмент deploy/nginx.conf

# Fragment INSIDE an existing HTTPS server. /srv/aen-msw/public is static output.
# The browser visits https://demo.example.test/msw/index.html.
location /msw/ {
    alias /srv/aen-msw/public/;
    index index.html;
    add_header Cache-Control "no-cache";
    # Include your distribution mime.types at http/server level.
    # .js must be text/javascript or application/javascript.
    # Do NOT add Service-Worker-Allowed: /.
}
# Do not forward /msw/api/ to a production backend. With mocking disabled,
# an unhandled demo request should be a real 404, never production data.

Проверка размещения: URL, MIME и отсутствие fallback

После загрузки public проверьте адреса app.js и mockServiceWorker.js отдельными HTTP-запросами. Ожидаются код 200 и JavaScript MIME. Для отсутствующих ресурсов сервер должен вернуть 404, а не подставлять index.html под любой URL. Универсальный SPA-fallback часто маскирует неверный путь worker, из-за чего диагностика начинается не с того места.

Затем откройте саму мастерскую, включите Mock API и прочитайте показанный scope. Он должен соответствовать каталогу стенда. Выполните успешный и ошибочный запрос, выключите режим и убедитесь, что регистрация удалена. Обычная доступность HTML ещё не подтверждает работу Service Worker или корректную остановку.

Для обновления сначала подготовьте согласованный набор bundle и worker из одного lock-файла. Не заменяйте только один файл случайной новой версией. На нашем стенде используется no-cache для проверки актуальности ресурсов; стратегию кеширования собственного продукта выбирайте отдельно и проверяйте обновление на уже открытой вкладке, а не только в чистом профиле.

Фрагмент README.md

sudo nginx -t
sudo systemctl reload nginx
curl -I https://demo.example.test/msw/mockServiceWorker.js
curl -I https://demo.example.test/msw/app.js

Docker и CI: проверяем Linux без внешнего API

Dockerfile использует закреплённый образ Node.js и устанавливает зависимости по lock-файлу. Тестовый контейнер запускается без сети: все ожидаемые запросы обрабатываются настоящим MSW внутри процесса. Такой режим помогает заметить случайную зависимость теста от доступности внешнего сервиса и делает повтор проверки более предсказуемым.

Сборка образа требует доступа к пакетному реестру. Запрет сети применяется к выполнению готовых тестов, а не к установке зависимостей. Не смешивайте эти стадии в описании: фраза «работает без сети» здесь относится к проверяемым сценариям после установки, а не к получению самого проекта с нуля.

Корневая файловая система контейнера доступна только для чтения, временный каталог выделен отдельно, процесс выполняется от пользователя node. Для capture нужен отдельный каталог вывода с разрешённой записью. При внедрении в CI сохраняйте stdout и результаты как артефакты, но не публикуйте в них реальные заголовки авторизации или клиентские данные.

Фрагмент README.md

docker build -t aen-msw:1.0.0 .
docker run --rm --network none --read-only --tmpfs /tmp aen-msw:1.0.0

Фрагмент Dockerfile

FROM node:24.22.3-bookworm-slim@sha256:dc26ae92c9fb15cf6b1d63e20f0944b2efe0f115b20e00be48fb23fceb061c54
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --ignore-scripts --no-audit --no-fund
COPY . .
RUN npm run build && chown -R node:node /app
USER node
CMD ["npm", "test"]

Типичные ошибки при интеграции и как их найти

Если запрос не перехватывается, начните с простых фактов: режим включён, start завершился, страница находится в scope, адрес и HTTP-метод совпадают с handler. Затем проверьте query отдельно от пути. При относительных URL на вложенном сайте легко случайно обратиться к корню, хотя handler ожидает каталог мастерской.

Если интерфейс показывает прежний результат, проверьте собственный кеш, незавершённый запрос и сброс состояния при выборе нового сценария. Если разовая ошибка больше не возникает, мог сработать once-handler или остаться счётчик попыток. Сброс обработчиков и сброс данных — разные действия. В нашем журнале видны последовательность запросов и ответы, поэтому эти причины можно различить.

При неработающей регистрации проверьте HTTPS, MIME и отсутствие HTML вместо worker. Не расширяйте scope до всего сайта как универсальное средство исправления. Если браузер уже содержит другой worker в нужном точном scope, проект выводит сообщение и сохраняет его. Выберите отдельный каталог либо явно разберите архитектуру общего приложения.

Как не разойтись с настоящим backend

Mock полезен только пока его контракт похож на реальный. Согласуйте имена полей, типы, статусы ошибок, единицы измерения и пагинацию. Для формы особенно важны имена ошибок полей: если backend возвращает amount, а интерфейс ждёт price, успешный тест mock не обнаружит проблему без сравнения контракта. Изменения должны попадать и в сервис, и в сценарии UI.

Храните небольшие обезличенные примеры ответов и проверяйте их схемой. Для критических потоков дополните MSW интеграционным тестом настоящего endpoint. Не переносите в handlers всю бизнес-логику приложения: иначе получится вторая система, которую тоже нужно поддерживать и которая может ошибаться иначе. Mock должен воспроизводить значимые для потребителя варианты, а не скрывать отсутствие согласованного API.

Полезный критерий готовности — человек может пройти успешный путь, понять отказ, исправить поле и повторить действие без потери контекста. Сетевой контракт и интерфейс здесь связаны. Поэтому проверяйте и содержимое ответа, и то, что пользователь видит после него. Такой подход делает мастерскую рабочим инструментом разработки, а не только коллекцией красивых экранов.

Исходники, границы проверки и первый шаг в своём проекте

В архиве находятся готовая public, src, tests, tools, конфигурации Nginx/Caddy, Dockerfile, README, лицензия и package-lock.json. Встроенный просмотр показывает точные исходные файлы. Можно скачать весь проект, запустить его локально и заменить учебные услуги своим небольшим контрактом. Лицензии MSW и Bootstrap сохранены рядом с публичной сборкой.

Начните с одного экрана, которому сейчас трудно показать редкое состояние. Опишите успешный ответ, пустой результат и одну полезную ошибку. Подключите общий клиент, проверьте мобильный интерфейс и только затем расширяйте набор ситуаций. Автоматические тесты должны подтверждать важное поведение, а не зеркально повторять каждую строчку handler.

Основные первоисточники: документация MSW, интеграция в браузер, интеграция в Node.js, HttpResponse и репозиторий проекта. Примеры этой страницы используют MSW 3; при другой версии сначала сверяйте API. Linux-тесты и браузерная мастерская не заменяют проверку настоящего backend вашего приложения.