Mirage.js для mock API в React

Важно: Mirage.js запускается в памяти в рамках клиента и подходит для разработки и тестирования UI. Для интеграционного тестирования или симуляции сложного сетевого поведения рассмотрите дополнительно Mock Service Worker или локальный тестовый бекенд.

Код React в редакторе кода

Коротко о Mirage.js

Mirage.js — это библиотека на JavaScript, которая создаёт на стороне клиента mock API с маршрутизацией, моделями и in-memory базой данных. Определяя сервер в коде фронтенда, вы перехватываете запросы fetch/XHR и возвращаете заранее заданные ответы. Однострочное определение: Mirage.js имитирует поведение API, используя модели и маршруты, чтобы интерфейс мог работать автономно.

Ключевые понятия:

Сервер — инстанс, который перехватывает HTTP-запросы.
Модель — структура данных для имитации сущности (например, Todo).
seeds — начальные данные в in-memory базе.
routes — обработчики GET/POST/DELETE и других HTTP методов.

Зачем использовать mock API

Быстрая разработка интерфейса без ожидания бекенда.
Стабильные тесты UI с предсказуемыми ответами.
Эксперименты с разными схемами данных и ошибочными ответами.
Возможность локализовать баги, связанных с контрактацией API.

Установка и начальная настройка

Создайте проект React (create-react-app или Vite). Установите Mirage.js как dev-зависимость:

npm install --save-dev miragejs

Создайте файл сервера в src/server.js и экспортируйте фабрику для инстанса сервера. Ниже — пример минимальной конфигурации с моделью Todo и namespace api.

import { createServer, Model } from 'miragejs';

const DEFAULT_CONFIG = {
  environment: "development",
  namespace: "api",
};

export function makeServer({ environment, namespace } =
  DEFAULT_CONFIG) {
  let server = createServer({
    environment,
    namespace,
    models: {
      Todo: Model,
    },
  });

  return server;
}

Советы по локализации namespace: если у реального API путь начинается с /api/v1, укажите namespace: ‘api/v1’, чтобы на раннем этапе фронтенд использовал те же URL.

Импорт сервера в точку входа приложения

Импортируйте и запускайте makeServer в development-сборке, чтобы не поднимать mock в проде:

import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App.jsx'
import { makeServer } from './server'

if (process.env.NODE_ENV === 'development' &&
    typeof makeServer === 'function'
) {
  makeServer();
}

ReactDOM.createRoot(document.getElementById('root')).render(
  
    
  ,
)

Добавление seed данных

Mirage.js содержит in-memory базу, которую можно предзаполнить через seeds. Это удобно для демо и тестов UI. Добавьте функцию seeds рядом с моделями в server.js:

seeds(server) {
  server.create('Todo', {
    title: 'item no 1',
    body: 'Do something nice for someone I care about',
  });
  server.create('Todo', {
    title: 'item no 2',
    body: 'Memorize the fifty states and their capitals.',
  });
  server.create('Todo', {
    title: 'item no 3',
    body: 'Watch a classic movie.',
  });
},

Заметка: для генерации объёмных или разнообразных тестовых данных удобно подключать генераторы типа Faker, но их использование увеличивает объём зависимостей.

Определение маршрутов mock API

Добавьте обработчики маршрутов внутри конфигурации сервера. В примере ниже namespace установлен на api/todos — это упрощает формирование URL в fetch запросах на фронтенде.

routes() {
  this.namespace = 'api/todos';

  this.get('/', (schema, request) => {
    return schema.all('Todo');
  });

  this.post('/', (schema, request) => {
    let attrs = JSON.parse(request.requestBody);
    return schema.create('Todo', attrs);
  });

  this.delete('/:id', (schema, request) => {
    let id = request.params.id;
    return schema.find('Todo', id).destroy();
  });
}

Замечание: вы можете эмулировать задержки и ошибки, возвращая статус 500 или используя функцию timing. Это полезно для проверки обработчиков ошибок в UI.

Клиентская часть на React

В этом руководстве используется Chakra UI, но вы можете применять любую библиотеку компонентов. Установите зависимости:

npm install @chakra-ui/react @emotion/react @emotion/styled framer-motion

Создайте компонент списка задач src/components/TodoList.jsx. Ниже — переведённый и упрощённый пример компонента с основными хуками и обработчиками.

import React, { useState, useEffect } from 'react';
import {
  Button,
  Box,
  Container,
  Text,
  Input,
  FormControl,
  Flex,
} from '@chakra-ui/react';

export default function TodoList() {
  const [todos, setTodos] = useState([]);
  const [newTodo, setNewTodo] = useState({ title: '', body: '' });
  const [loading, setLoading] = useState(true);
  const [renderKey, setRenderKey] = useState(0);

  useEffect(() => {
    fetch('/api/todos')
      .then((response) => response.json())
      .then((data) => {
        setTodos(data.todos);
        setLoading(false);
      });
  }, [renderKey]);

  const handleInputChange = (e) => {
    const { name, value } = e.target;
    setNewTodo((prevTodo) => ({ ...prevTodo, [name]: value }));
  };

  const handleAddTodo = () => {
    setLoading(true);
    fetch('/api/todos', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(newTodo),
    }).then((response) => response.json()).then((createdTodo) => {
      setTodos((prevTodos) => [createdTodo, ...prevTodos]);
      setNewTodo({ title: '', body: '' });
      setRenderKey((prevKey) => prevKey + 1);
      setLoading(false);
    }).catch((error) => {
      console.error('Error adding todo:', error);
      setLoading(false);
    });
  };

  const handleDelete = (id) => {
    let deleteInProgress = true;
    fetch(`/api/todos/${id}`, {
      method: 'DELETE',
    }).then((response) => {
        if (response.status === 204) {
          return null;
        } else {
          return response.json();
        }
      }) .then((data) => {
        if (data && data.error) {
          console.error('Error deleting todo:', data.error);
        } else {
          setTodos((prevTodos) => prevTodos.filter((todo) => todo.id !== id));
          setRenderKey((prevKey) => prevKey + 1);
        }
        deleteInProgress = false;
      }).catch((error) => {
        console.error('Error deleting todo:', error);
        deleteInProgress = false;
      }) .finally(() => {
        setLoading(deleteInProgress);
      });
  };

  return (
    
      Todo List
      
        
      
      
      {loading ? ( Loading... ) : (
        todos.map((todo) => (
          
            
              {todo.body}
              
            
          
        ))
      )}
    
  );
}

Включите компонент в App.jsx:

import TodoList from './components/TodoList';

// код приложения ...

Ноутбук на столе с открытым кодом

Когда mocking не подходит или даёт ложное представление

Если ваш продакшн API использует сложные авторизационные схемы или поток данных с вебсокетами, клиентский mock может не покрыть все нюансы.
Эмуляция производительности сети и задержек не гарантирует поведения реального окружения под высокой нагрузкой.
При несогласованности контрактов mock может скрыть ошибки интеграции. Регулярно запускайте интеграционные тесты с реальным бэкендом.

Альтернативы и сравнение

Mock Service Worker (MSW) — перехватывает запросы на уровне network layer, работает и в тестах, и в браузере; предпочтителен для более «реалистичного» перехвата.
json-server — запускает настоящий локальный JSON REST API на Node.js, подходит для простых CRUD-демо.
Mirage.js — удобен для быстрого старта в SPA и имеет удобные модели и фабрики.

Короткая эвристика: если нужен лёгкий in-memory mock на клиенте и интеграция с моделями — используйте Mirage.js; если нужен сетевой перехват, покрывающий всё окружение — рассмотрите MSW.

Модель зрелости использования mock API

Уровень 0 — нет mock, разработка параллельно с бэкендом.
Уровень 1 — простые заглушки и fixtures для отдельных компонентов.
Уровень 2 — единый клиентский mock сервер (Mirage.js) для всей локальной разработки.
Уровень 3 — интеграция mock в pipeline тестов, симуляция ошибок и latency.
Уровень 4 — контрактное тестирование и регулярная валидация схем с бэкендом.

Методология быстрой настройки mock API для команды

Определите контракт API (эндпоинты, поля, статусы).
Настройте базовую конфигурацию Mirage.js и предзаполните seeds.
Подключите mock только в development среде.
Параллельно разрабатывайте интеграционные тесты против реального API-стейджа.
При появлении реального API замените namespace или отключите Mirage.js.

Миграция с mock на реальный API

Поддерживайте одинаковую структуру URL и форматы JSON в mock и в реальном API.
Используйте переменные окружения для базового URL: REACT_APP_API_BASE_URL. Mirage.js может имитировать тот же базовый путь, поэтому при переключении нужно менять только конфиг.
Выполняйте smoke-тесты после переключения: запросы GET/POST/DELETE должны возвращать ожидаемые схемы и статусы.

Критерии приёмки

Компоненты корректно показывают seed данные из mock API.
Добавление новой записи через POST обновляет список в UI.
Удаление записи через DELETE удаляет элемент из UI и из in-memory базы.
Обработка ошибок (500, 404) проверена и пользователь видит дружелюбные сообщения.
Mirage.js запускается только в development и не попадает в production-сборку.

Роль‑ориентированные чеклисты

Frontend разработчик:

Настроить makeServer в точке входа приложения.
Использовать те же URL, что ожидает реальный API.
Эмулировать ошибки и задержки для тестирования UX.

Backend разработчик:

Предоставить контракт (OpenAPI/JSON Schema) или пример ответов.
Договориться с фронтендом о полях обязательных для рендера.

QA инженер:

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

Тестовые сценарии и приёмочные тесты

Тест кейс 1 — Получение списка задач:

Ожидаем: GET /api/todos возвращает массив todos с полями id, title, body.

Тест кейс 2 — Добавление задачи:

Действие: отправить POST /api/todos с телом { title, body }.
Ожидаем: в ответе объект созданной задачи с уникальным id и HTTP 201 или 200.

Тест кейс 3 — Удаление задачи:

Действие: DELETE /api/todos/:id.
Ожидаем: задача удалена из списка, сервер возвращает 204 или объект без ошибки.

Тест кейс 4 — Ошибки сети:

Эмулировать 500 и убедиться, что UI показывает сообщение об ошибке и не ломается.

Безопасность и приватность

Mirage.js работает в памяти на клиенте, поэтому реальные персональные данные туда не загружайте.
Для тестирования конфиденциальных сценариев используйте изолированные тестовые объекты или моки без PII.
Обратите внимание: mock не проверяет авторизацию сервера. Если в проде используется JWT/OAuth, тестируйте flow отдельно.

Шаблон плана внедрения mock API в проекте

Добавить src/server.js с makeServer и export.
Подключить makeServer в index.jsx только в development.
Создать базовые модели и seeds по контракту.
Реализовать маршруты для необходимых операций.
Документировать в README как включать/отключать mock.

Когда отключать Mirage.js

В CI и production сборках.
При запуске интеграционных тестов против реального бекенда.
Когда протестирован и принят контракт с бэкендом.

Короткая памятка по отладке

Проверьте, что makeServer вызывается (лог в консоли).
Убедитесь, что namespace совпадает с путями в fetch.
Используйте server.logging = true для вывода запросов Mirage.js в консоль.

Ресурсы для продолжения работы

Официальная документация Mirage.js — изучите фабрики, сериализаторы и timing.
Рассмотрите MSW для кросс‑окружного перехвата запросов.

Вывод

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

Краткие выводы: