sovcomocks

sovcomocks

Framework-agnostic мокирование HTTP-запросов через Service Worker. Фикстуры — JSON-файлы в git-репозитории проекта (шарятся между разработчиками как обычный код), рантайм — этот пакет. Работает с Vue, React, Angular и чистым HTML-проектом с package.json.

Конвенция: папка mocks/ в корне проекта (дефолт middleware и CLI) — коммитится в git, любой разработчик докидывает фикстуру, остальные видят её в панели после обновления страницы.

Полная спецификация: docs/sovcomocks-package-spec.md в rocket-lk.

Быстрый старт

npm i -D sovcomocks
npx sovcomocks copy-sw --out public   # кладёт sovcomocks-sw.js в статику

1. Инициализация до маунта приложения:

import { init } from 'sovcomocks';

await init(); // резолвится, когда SW контролирует страницу
app.mount('#app');

2. Dev-middleware, раздающий папку mocks/ (Vite):

// vite.config.ts
import { createMocksMiddleware } from 'sovcomocks/middleware';

export default defineConfig({
  plugins: [
    {
      name: 'sovcomocks',
      configureServer(server) {
        // без опций раздаёт ./mocks из корня проекта;
        // другая папка: createMocksMiddleware({ mocksDir: 'src/mocks' })
        server.middlewares.use(createMocksMiddleware());
      },
    },
  ],
});

Webpack-dev-server: setupMiddlewares: (m, { app }) => { app.use(createMocksMiddleware({ mocksDir: 'src/mocks' })); return m; }. Express/connect: app.use(createMocksMiddleware({ mocksDir: 'src/mocks' })). Без dev-сервера: npx sovcomocks serve --dir ./mocks --port 4567 + init({ mocksBaseUrl: 'http://localhost:4567/__mocks__' }).

3. UI-панель (опционально):

import 'sovcomocks/ui';

<sovcomocks-panel></sovcomocks-panel>

Конвенция фикстур

mocks/<путь запроса>/<МЕТОД>.<статус>[.<комментарий>].json
mocks/v1/cards/[id]/extended/GET.200.json
mocks/v1/auth/reg/otp/POST.400.block.json

[id]-сегмент матчит любое значение сегмента — один мок покрывает все id.

API

init(options?): Promise<void>

Опция	Дефолт	Описание
swUrl	/sovcomocks-sw.js	URL SW-скрипта
mocksBaseUrl	/__mocks__	префикс dev-middleware
enabled	true	дефолт глобального тумблера (сохранённое в UI значение приоритетнее)
rules	[]	начальные правила; добавляются только новые (по method+path)
timeoutMs	10000	таймаут ожидания контроля SW

Правило

interface Rule {
  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
  path: string;      // '/v1/cards/[id]/extended'
  status?: number;   // без него — первый 2xx
  variant?: string;  // комментарий из имени файла
  enabled: boolean;
}

Также экспортируются getState(), updateRules(rules), setEnabled(bool) — программное управление; всё персистится в IndexedDB и мгновенно синхронизируется с SW.

Entry points

Import	Что это
sovcomocks	init() + программное API
sovcomocks/middleware	connect-style middleware (Node)
sovcomocks/ui	<sovcomocks-panel> Custom Element
sovcomocks/sw	SW как ESM-модуль (для своей сборки воркера)
sovcomocks/core	чистые функции: матчер, парсер имён
sovcomocks/sw.js	готовый classic-скрипт воркера

Ограничения

• Мокаются только запросы из браузера (fetch/XHR). SSR/server-to-server — мимо SW.
• Cross-origin запросы (API на другом порту/домене) перехватываются: правило без origin матчит путь на любом origin; точечно — { origin: 'http://localhost:55000', ... }.
• Нужен HTTPS или localhost (ограничение Service Worker API).
• Один SW scope на origin; несколько SPA на одном origin — возможен конфликт.
• Прод-сборка: просто не зови init() (или зови под if (import.meta.env.DEV)).

Разработка

npm i
npm run build      # tsup → dist/
npm test           # vitest: core + middleware
npm run example    # demo: http://localhost:4567