Mockarty: Руководство по быстрому старту

Начните работу с Mockarty за 20 минут. Это руководство проведет вас через установку, создание первого мока, его тестирование и знакомство с ключевыми возможностями.

Содержание

1. Что такое Mockarty
2. Установка
3. Первый запуск
4. Понимание пространств имен
5. Создание первого мока
6. Тестирование мока
7. Faker для динамических ответов
8. Добавление условий
9. Импорт из OpenAPI
10. API-тестирование
11. Запись трафика
12. Нагрузочное тестирование
13. Фаззинг
14. Генерация автономного сервера
15. AI-ассистент
16. Дальнейшие шаги

Что такое Mockarty

Mockarty — это полноценная платформа для бэкенд-тестирования: от мокирования API до нагрузочного тестирования, фаззинга, хаос-инжиниринга, контрактной валидации и управления тест-кейсами — всё в одном инструменте. Команды используют его, чтобы заменить разрозненные тулчейны (Postman + WireMock + k6 + TestRail + Jira + …) единой платформой, охватывающей весь жизненный цикл тестирования.

Поддерживаемые протоколы:

Прямые протоколы — обслуживаются нодой Mockarty по адресу /stubs/{namespace}/...:

• HTTP / REST — полноценное мокирование REST API с параметрами маршрутов, заголовками, query-параметрами и условиями на тело запроса
• GraphQL — определение запросов и мутаций с гибким мокированием ответов
• SOAP — мокирование сервисов на основе WSDL
• SSE — Server-Sent Events для потоков данных в реальном времени
• MCP — инструменты, ресурсы и промпты Model Context Protocol

Протоколы с генерируемым сервером — моки создаются в UI, но трафик обслуживается автономным сервером, собранным с помощью mockarty-server-generator (см. Руководство по генератору серверов):

• gRPC — унарные и потоковые моковые ответы из .proto файлов
• WebSocket — мокирование двунаправленной коммуникации
• Kafka — мокирование сообщений на основе топиков с имитацией consumer/producer
• RabbitMQ — мокирование очередей и обменников с маршрутизацией сообщений
• TCP / UDP — мокирование raw-сокетной коммуникации

Ключевые возможности:

• Веб-интерфейс с визуальным Конструктором моков — код не требуется
• ИИ-ассистент — опишите, что вам нужно, на естественном языке, и агент создаст моки за вас
• Движок Faker — генерация реалистичных динамических данных (имена, email, UUID, адреса, даты и многое другое)
• Интерполяция JsonPath — извлечение значений из запросов и использование их в ответах
• Система хранилищ (Store) — поддержание состояния между запросами с помощью Global, Chain и Mock Store
• Сопоставление условий — маршрутизация запросов к различным ответам на основе тела, заголовков, query-параметров
• Режим прокси — пересылка запросов к реальным сервисам с добавлением задержки, модификацией заголовков или логированием
• Импорт OpenAPI / Swagger — генерация моков из существующих спецификаций API
• API Tester — встроенный инструмент тестирования, аналогичный Postman, для тестирования моков и реальных API
• Фаззинг — встроенный фаззер для обнаружения уязвимостей в ваших API
• Генераторы кода — создание автономных серверов gRPC, MCP, Kafka, RabbitMQ и других протоколов
• Хаос-инжиниринг — внедрение сбоев (остановка подов, задержки, нагрузка на ресурсы) в Kubernetes-кластеры для проверки устойчивости
• Контрактное тестирование — валидация моков по спецификациям OpenAPI, обнаружение дрифта API и consumer-driven контрактные тесты (совместимо с Pact)
• Управление тест-кейсами (TCM) — полноценный TMS: папки с кейсами, версионированные шаги, общие шаги, рабочие процессы ревью, ссылки на внешние трекеры (Jira, GitHub, Linear)
• Тест-планы — оркестрация любых комбинаций функциональных, нагрузочных, фаззинговых, хаос- и контрактных тестов в DAG-воркфлоу с расписаниями, гейтами и CI/CD-триггерами
• Многоузловая архитектура — масштабирование с помощью resolver-узлов и runner-агентов

Основные термины

Если вы новичок в Mockarty, вот несколько терминов, которые встречаются в этом руководстве:

• Пространство имен (Namespace) — изолированная рабочая область (как папка проекта). У каждого пространства имен свои моки, хранилища и коллекции тестов. Разные команды или сервисы могут использовать отдельные пространства, не мешая друг другу.
• Система хранилищ (Store system) — механизм сохранения состояния между запросами. В Mockarty три типа хранилищ: Global Store (общее состояние в пределах пространства имен), Chain Store (состояние для цепочки связанных моков) и Mock Store (временное состояние, существующее только во время обработки одного мока).
• Резолвинг моков (Mock resolution) — процесс выбора подходящего мока для входящего запроса. Mockarty анализирует маршруты, методы, условия и приоритеты, чтобы найти наилучшее совпадение.
• VU (Virtual Users) — виртуальные пользователи в нагрузочном тестировании. VU — это имитированный пользователь, отправляющий запросы параллельно. Например, vus: 10 означает, что 10 пользователей одновременно обращаются к вашему API.

Облако, self-hosted или локальная разработка

Mockarty работает в трёх конфигурациях. Выберите подходящую, прежде чем начинать:

Если нужно просто попробовать Mockarty (запустить пару моков, познакомиться с CLI), быстрее всего — облако: mockarty-cli auth login уже подключается туда и ведёт через OAuth. Переходите к разделу Открытие веб-интерфейса.

Если нужен self-hosted инстанс (corporate compliance, air-gapped), пройдите шаги «Установка» ниже и один раз настройте mockarty-cli:

mockarty-cli config set server_url https://mockarty.your-corp.example

Для локальной разработки поднимите admin-server у себя и укажите его через env-переменную:

export MOCKARTY_SERVER=http://localhost:5780
mockarty-cli auth login

Полное описание четырёхуровневой цепочки приоритетов flag > env > file > cloud default — в Подключение к серверу.

Установка

Уже развёрнуто? Если Mockarty уже работает в вашей организации (развёрнут администратором на корпоративном сервере или в Kubernetes), устанавливать ничего не нужно. Переходите сразу к разделу Открытие веб-интерфейса. Вам понадобится URL-адрес Mockarty и учётные данные от администратора.

Вариант A: CLI-установщик (рекомендуется)

Команда mockarty-cli install — самый быстрый способ развернуть Mockarty. Она автоматически определяет вашу платформу, находит последнюю версию и скачивает правильный бинарник — без ручной сборки URL.

Сначала скачайте и установите сам CLI:

# Скачать последнюю версию mockarty-cli
curl -fsSL https://mockarty.ru/download/latest/mockarty-cli-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m) -o mockarty-cli
chmod +x mockarty-cli
sudo mv mockarty-cli /usr/local/bin/

Режим SQLite — разработка, один бинарник, без внешних зависимостей, мгновенный запуск:

mockarty-cli install mockarty --mode sqlite

Режим Docker Compose — генерирует docker-compose.yml + .env с PostgreSQL + Redis:

mockarty-cli install mockarty --mode docker-compose
docker compose up -d

Режим Kubernetes — выполняет helm install с PostgreSQL/Redis из Bitnami:

mockarty-cli install mockarty --mode kubernetes --namespace mockarty --admin-password <your-password>

Режим CRD Operator — устанавливает MockartyCluster CRD и создаёт ресурс кластера:

mockarty-cli install --mode operator --namespace mockarty

Все режимы кратко:

mockarty-cli install mockarty --mode sqlite           # dev / быстрый старт
mockarty-cli install mockarty --mode docker-compose    # генерация compose-файлов
mockarty-cli install mockarty --mode kubernetes        # helm install в кластер
mockarty-cli install --mode operator                   # CRD + оператор
mockarty-cli install --all                             # скачать все бинарники

Примечание: --mode sqlite предназначен только для разработки и быстрого старта. Для production используйте --mode kubernetes или --mode docker-compose с PostgreSQL.

Вариант Б: Скачать бинарный файл вручную

Предпочтительнее использовать CLI-установщик (Вариант A). Если нужен прямой доступ к бинарникам, скачайте их для вашей платформы с GitHub Releases:

• macOS (Apple Silicon): mockarty-darwin-arm64
• macOS (Intel): mockarty-darwin-amd64
• Linux (x86_64): mockarty-linux-amd64
• Linux (ARM64): mockarty-linux-arm64
• Windows (x86_64): mockarty-windows-amd64.exe

Сделайте файл исполняемым и запустите (macOS/Linux):

chmod +x mockarty-darwin-arm64
DB_USE=sqlite ./mockarty-darwin-arm64

Примечание: DB_USE=sqlite только для разработки. Для production используйте PostgreSQL (см. Вариант Г или Д).

Вариант В: Docker (официальный образ)

docker run -d --name mockarty -p 5770:5770 \
  -e HTTP_BIND_ADDR=0.0.0.0 \
  -e DB_USE=sqlite \
  -e COOKIE_SECURE=false \
  mockarty/mockarty:latest

Вариант Г: Docker Compose с PostgreSQL

Для окружений, приближенных к продакшену, с PostgreSQL. Сгенерируйте compose-файлы через CLI (mockarty-cli install mockarty --mode docker-compose) или создайте docker-compose.yml вручную:

# docker-compose.yml
services:
  mockarty:
    image: mockarty/mockarty:latest
    ports:
      - "5770:5770"
    environment:
      HTTP_BIND_ADDR: "0.0.0.0"
      DB_DSN: "postgres://mockarty:mockarty@postgres:5432/mockarty?sslmode=disable"
      CACHE_TYPE: redis
      REPO_REDIS_HOST: redis
      REPO_REDIS_PORT: "6379"
      FIRST_ADMIN_LOGIN: admin
      FIRST_ADMIN_PASSWORD: "${FIRST_ADMIN_PASSWORD:-change_me}"
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: mockarty
      POSTGRES_PASSWORD: mockarty
      POSTGRES_DB: mockarty
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U mockarty"]
      interval: 5s
      retries: 10

  redis:
    image: redis:7-alpine
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      retries: 10

volumes:
  pgdata:

docker compose up -d

Вариант Д: Kubernetes (Helm)

Рекомендуется: Используйте CLI-установщик (mockarty-cli install mockarty --mode kubernetes) — он выполняет настройку репозиториев, сборку зависимостей и Helm install одной командой.

Ручная установка через Helm (если нужен полный контроль):

Предварительные требования: Kubernetes 1.24+, Helm 3.10+

# 1. Добавить репозиторий Bitnami (подчарты PostgreSQL и Redis)
helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update

# 2. Перейти в директорию Helm-чарта (включён в репозиторий Mockarty)
cd deploy/helm/mockarty

# 3. Собрать зависимости подчартов
helm dependency update

# 4. Установка — минимальный профиль (один admin-узел + PostgreSQL + Redis)
helm install mockarty . \
  -f values.minimal.yaml \
  --set admin.secrets.FIRST_ADMIN_PASSWORD="<your-password>" \
  --set postgresql.auth.password="<db-password>" \
  --namespace mockarty --create-namespace

Кластерный профиль (HA: 2 admin, resolvers, runners, orchestrator):

helm install mockarty . \
  -f values.cluster.yaml \
  --set admin.secrets.FIRST_ADMIN_PASSWORD="<your-password>" \
  --set postgresql.auth.password="<db-password>" \
  --namespace mockarty --create-namespace

# 5. Доступ к интерфейсу
kubectl port-forward svc/mockarty -n mockarty 5770:5770
open http://localhost:5770/ui/

Развёрнутые компоненты (кластерный профиль): Admin Node (веб-интерфейс + API), Mock Resolver (горизонтальное масштабирование), Runner Agent (выполнение тестов), Orchestrator (генерация кода), PostgreSQL, Redis. Задача token bootstrap автоматически создаёт интеграционные токены.

Вариант Е: CRD Operator (GitOps)

Для GitOps-процессов доступен custom resource definition MockartyCluster. Оператор отслеживает CR MockartyCluster и разворачивает полный стек.

Рекомендуется: mockarty-cli install --mode operator

Ручная установка:

kubectl apply -f deploy/operator/bundle.yaml
kubectl apply -f mockartycluster.yaml

Подробнее см. Руководство по развёртыванию и Архитектура масштабирования.

Примечания для Docker:

• HTTP_BIND_ADDR — По умолчанию Mockarty привязывается к localhost (127.0.0.1), что недоступно снаружи контейнера. При запуске в Docker всегда устанавливайте HTTP_BIND_ADDR=0.0.0.0, чтобы сервер слушал на всех интерфейсах.
• COOKIE_SECURE — Если вы обращаетесь к Mockarty по обычному HTTP (без TLS), установите COOKIE_SECURE=false. В противном случае cookies аутентификации не будут отправляться браузером и вход не будет работать.
• DB_USE=sqlite только для разработки и быстрого старта. Для production используйте PostgreSQL (Вариант Г или Д).

Первый запуск

Важно — Mockarty является серверным приложением. API Tester, рекордер, вебхуки и нагрузочные запуски отправляют трафик из самого процесса Mockarty, а не из вашего браузера. По умолчанию эти серверные компоненты блокируют запросы к приватным, loopback- и link-local адресам (127.0.0.1, localhost, 10.x.x.x, 192.168.x.x, ::1 и т.д.) для защиты от SSRF. Если вам нужно, чтобы Mockarty ходил к сервису на той же машине (локальный бэкенд, dev-API, соседний контейнер на ноутбуке), установите переменную окружения ALLOW_PROXY_TO_PRIVATE_IPS=true перед запуском бинарника. Для удалённого или корпоративного развёртывания значение по умолчанию правильное — оставьте выключенным.

# Локальная разработка: разрешить запросы к localhost / приватным сетям
ALLOW_PROXY_TO_PRIVATE_IPS=true DB_USE=sqlite ./mockarty-darwin-arm64

Самый простой способ начать — использовать встроенную базу данных SQLite. Внешние зависимости не требуются.

Запуск с SQLite

DB_USE=sqlite ./mockarty-darwin-arm64

Mockarty выполнит следующее:

1. Создаст базу данных SQLite по пути ~/.mockarty/data.db
2. Автоматически применит все миграции
3. Создаст администратора по умолчанию (логин: admin, пароль: admin)
4. Создаст пространство имен по умолчанию — sandbox
5. Запустит HTTP-сервер на порту 5770

В консоли вы увидите вывод, подобный этому:

INFO  Starting Mockarty ...
INFO  Using SQLite database: ~/.mockarty/data.db
INFO  Migrations applied successfully
INFO  HTTP server listening on :5770

Открытие веб-интерфейса

Откройте браузер и перейдите по адресу:

http://localhost:5770/ui/

Вы увидите страницу входа в Mockarty. Войдите с учетными данными по умолчанию: admin / admin.

После входа вы увидите главную панель управления с навигацией в боковом меню.

Примечание по безопасности: Измените пароль администратора по умолчанию после первого входа. Перейдите в Настройки в боковом меню, чтобы обновить учетные данные.

Пробная лицензия: При первом запуске Mockarty запускается с пробной лицензией на 7 дней, предоставляющей полный доступ ко всем функциям с неограниченным количеством мест (seats). Единственное ограничение — вы ограничены пространством имён sandbox; создание пользовательских пространств имён требует коммерческой лицензии. Чтобы снять ограничение на пространства имён и убрать срок действия, примените лицензионный ключ в разделе Администрирование → Лицензия.

Подключение к существующему развёртыванию

Если Mockarty развёрнут вашим администратором, устанавливать ничего не нужно. Узнайте у администратора:

1. URL-адрес Mockarty — например, https://mockarty.company.com
2. Учётные данные — логин и пароль, или данные для входа через SSO/LDAP/OAuth

Откройте полученный URL в браузере, войдите в систему и переходите к разделу Понимание пространств имен, чтобы начать создавать моки. Все примеры в этом руководстве используют localhost:5770 — замените на URL вашего экземпляра Mockarty (см. URL-адреса в примерах ниже).

URL-адреса в примерах документации

Во всех примерах документации используется localhost:5770 — адрес Mockarty по умолчанию. Это работает при локальной разработке. Если ваш экземпляр Mockarty работает на удалённом сервере, замените localhost:5770 на реальный адрес.

Пример: если ваш Mockarty развёрнут по адресу https://mockarty.staging.company.com, то вместо:

curl http://localhost:5770/api/v1/mocks

используйте:

curl https://mockarty.staging.company.com/api/v1/mocks

Важно для серверных функций (Рекордер, Фаззер, Нагрузочное тестирование): Эти функции работают на сервере Mockarty, а не в браузере. Когда Рекордер создаёт прокси на порту (например, 8085), этот порт открывается на машине, где работает Mockarty. Если Mockarty на удалённом сервере 192.168.1.50, ваше приложение должно слать трафик на http://192.168.1.50:8085, а не на http://localhost:8085. Подробнее — в документации Рекордера.

Совет: В SDK (Go, Python, Java) базовый URL задаётся один раз при создании клиента. Все последующие вызовы используют этот URL автоматически. См. Руководство по SDK.

Понимание пространств имен

Mockarty организует все ресурсы в пространства имен (namespaces). Пространство имен — это изолированная рабочая область: у каждого пространства имен свои моки, хранилища и коллекции тестов. Это ключевая концепция, которую необходимо понять перед созданием моков.

Что такое пространство имен?

Думайте о пространстве имен как о папке проекта. Если у вас несколько команд или микросервисов, каждый может иметь собственное пространство имен с независимыми моками, которые не пересекаются друг с другом.

При первом запуске Mockarty автоматически создаёт пространство имён sandbox — общую песочницу, доступную всем пользователям. Создавать новые пространства имён могут только Администраторы и Support (системные роли). Владелец (Owner) пространства (роль пространства) может добавлять пользователей в своё пространство.

Шаблон URL

Все запросы к мокам маршрутизируются через пространства имен. Шаблон URL:

{АДРЕС_MOCKARTY}/stubs/{namespace}/{ваш-маршрут}

Например, если вы создали мок с маршрутом /api/users в пространстве имён sandbox:

Примечание: В примерах ниже используется localhost:5770. Замените на реальный адрес вашего Mockarty при работе на удалённом сервере (см. URL-адреса в примерах выше).

Если позже вы создадите пространство имен payments и добавите мок с маршрутом /api/invoices, вы будете вызывать его по адресу:

http://localhost:5770/stubs/payments/api/invoices

Управление пространствами имен

Создавать и управлять пространствами имен можно в разделе Администрирование в боковом меню. Каждое пространство имен может иметь:

• Собственный набор моков
• Назначенных пользователей с определенными ролями
• Независимые Global и Chain Store
• Отдельные коллекции тестов и окружения

В данном руководстве мы будем использовать пространство имён sandbox, которое создается автоматически.

Создание первого мока

Давайте создадим простой HTTP-мок, который возвращает список пользователей.

Шаг 1: Откройте Конструктор

Нажмите Конструктор в боковом меню. Это визуальный инструмент для создания моков.

Шаг 2: Настройте маршрут

Заполните основные параметры мока:

Шаг 3: Определите ответ

В разделе Ответ установите:

• Код статуса: 200
• Content-Type: application/json
• Тело ответа:

{
  "users": [
    {
      "id": "$.fake.UUID",
      "name": "$.fake.Name",
      "email": "$.fake.Email",
      "age": "$.fake.Number"
    },
    {
      "id": "$.fake.UUID",
      "name": "$.fake.Name",
      "email": "$.fake.Email",
      "age": "$.fake.Number"
    }
  ],
  "total": 2
}

Шаг 4: Сохраните мок

Нажмите кнопку Создать мок. Появится уведомление об успешном создании, и мок отобразится в списке моков.

Тестирование мока

Теперь давайте вызовем мок и посмотрим ответ. Помните, что все вызовы моков идут через шаблон URL с пространством имен.

С помощью curl

curl -s http://localhost:5770/stubs/sandbox/api/users | jq

Пример ответа:

{
  "users": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "John Smith",
      "email": "john.smith@example.com",
      "age": 34
    },
    {
      "id": "f9e8d7c6-b5a4-3210-fedc-ba0987654321",
      "name": "Emily Johnson",
      "email": "emily.johnson@example.net",
      "age": 28
    }
  ],
  "total": 2
}

Каждый вызов генерирует новые случайные данные благодаря функциям Faker. Повторный вызов вернет другие имена, email и UUID.

С помощью встроенного API Tester

Вы также можете тестировать прямо из интерфейса Mockarty:

1. Перейдите в API Tester в боковом меню
2. Создайте новый запрос
3. Установите метод GET и URL http://localhost:5770/stubs/sandbox/api/users
4. Нажмите Отправить

Faker для динамических ответов

Функции Faker генерируют реалистичные случайные данные при каждом запросе. Используйте их в теле ответа с префиксом $.fake..

Основные функции Faker

Выборка наиболее полезных функций Faker. См. Faker Reference для полного списка из 70+ функций.

Интерполяция данных запроса

Вы также можете ссылаться на значения из входящего запроса:

Пример: Возврат данных пользователя

Создайте мок для POST /api/users, который возвращает отправленные данные вместе со сгенерированными полями:

{
  "id": "$.fake.UUID",
  "name": "$.req.name",
  "email": "$.req.email",
  "createdAt": "$.fake.RFC3339",
  "status": "active"
}

При отправке POST-запроса с телом {"name": "Alice", "email": "alice@example.com"} ответ будет содержать отправленные имя и email вместе со сгенерированным UUID и временной меткой.

Проверьте:

curl -s -X POST http://localhost:5770/stubs/sandbox/api/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "email": "alice@example.com"}' | jq

Добавление условий

Условия позволяют возвращать различные ответы в зависимости от содержимого входящего запроса. Именно так вы имитируете реалистичное поведение API.

Пример: Разные ответы по ID пользователя

Создайте отдельные моки для разных ID пользователей или используйте условия на query-параметры на одном маршруте.

Вариант A: Отдельные моки для разных маршрутов

Создайте один мок для GET /api/users/1, возвращающий пользователя-администратора, и другой мок для GET /api/users/999, возвращающий ошибку «не найдено».

Мок 1 — Маршрут: /api/users/1, Ответ (статус 200):

{
  "id": 1,
  "name": "Admin User",
  "role": "admin"
}

Мок 2 — Маршрут: /api/users/999, Ответ (статус 404):

{
  "error": "User not found"
}

Вариант B: Использовать условия на query-параметры

Создайте один мок для GET /api/users и добавьте условия на query-параметр (например, ?id=1).

Условие:

• Тип: queryParam
• Ключ: id
• Проверка: equals
• Значение: 1

Ответ (статус 200):

{
  "id": 1,
  "name": "Admin User",
  "role": "admin"
}

Затем создайте второй мок для GET /api/users без условий и с более низким приоритетом — он будет ответом по умолчанию.

Ответ (статус 404):

{
  "error": "User not found"
}

Проверьте условный мок:

# Возвращает пользователя-администратора (условие совпадает)
curl -s "http://localhost:5770/stubs/sandbox/api/users?id=1" | jq

# Возвращает 404 (условие не совпадает, используется ответ по умолчанию)
curl -s "http://localhost:5770/stubs/sandbox/api/users?id=999" | jq

Типы условий

Действия проверки (Assert)

Расширенные поля условий (только API)

Условия также поддерживают дополнительные поля (decode, sortArray, valueFromFile) при создании моков через REST API. Эти поля недоступны в визуальном конструкторе Web UI. Подробнее см. Справочник API.

Настройка условий в интерфейсе

1. В Конструкторе прокрутите до раздела Условия
2. Нажмите Добавить условие
3. Выберите тип условия (body, header, queryParam)
4. Введите ключ и ожидаемое значение
5. Выберите действие проверки

Несколько условий на одном моке используют логику И (AND) — все условия должны совпасть для выбора данного ответа.

Импорт из OpenAPI

Если у вас уже есть спецификация OpenAPI (Swagger), Mockarty может автоматически сгенерировать моки для всех ваших эндпоинтов.

Шаг 1: Откройте Генератор

Нажмите Генератор в боковом меню.

Шаг 2: Загрузите спецификацию

Вы можете:

• Вставить URL вашей спецификации OpenAPI (JSON или YAML)
• Загрузить файл с компьютера
• Вставить содержимое непосредственно в редактор

Поддерживаемые форматы:

• OpenAPI 3.0 / 3.1 (JSON и YAML)
• Swagger 2.0 (JSON и YAML)

Шаг 3: Настройте параметры генерации

Выберите параметры генерации:

Шаг 4: Генерация

Нажмите Сгенерировать моки. Mockarty создаст мок для каждого эндпоинта в вашей спецификации.

Шаг 5: Проверка и тестирование

Перейдите на страницу Моки, чтобы увидеть все сгенерированные моки. Каждый мок будет содержать:

• Корректный маршрут и HTTP-метод
• Тело ответа на основе определений схемы
• Соответствующие коды статусов
• Динамические значения на основе Faker (если включено)

Вы можете отредактировать любой сгенерированный мок в Конструкторе для дополнительной настройки. Не забывайте тестировать их через шаблон URL с пространством имен:

curl -s http://localhost:5770/stubs/sandbox/your-generated-route | jq

API-тестирование

Mockarty включает встроенный инструмент API-тестирования — считайте его Postman прямо внутри вашего мок-сервера. Вы можете тестировать моки, реальные API или и то, и другое.

Что такое API Tester?

API Tester позволяет:

• Отправлять HTTP-запросы на любой URL и видеть ответ
• Организовывать запросы в коллекции (как папки для ваших тестов)
• Писать тестовые скрипты на JavaScript для автоматической проверки ответов
• Использовать окружения для переключения между серверами (dev, staging, prod)
• Запускать целые коллекции разом для поиска регрессий
• Планировать запуски тестов по расписанию

Шаг 1: Создайте коллекцию

Коллекция — это просто группа связанных запросов. Думайте о ней как о наборе тестов.

1. Перейдите в API Tester в боковом меню
2. Нажмите Новая коллекция
3. Задайте имя, например Тесты API пользователей
4. Нажмите Создать

Шаг 2: Добавьте первый запрос

1. Внутри коллекции нажмите Добавить запрос
2. Заполните:
   • Имя: Получить пользователей (это просто метка для вас)
   • Метод: GET (выберите из выпадающего списка)
   • URL: http://localhost:5770/stubs/sandbox/api/users
3. Нажмите Отправить, чтобы сразу попробовать

Ответ появится ниже: код статуса, время ответа, заголовки и JSON-тело.

Шаг 3: Добавьте POST-запрос

Давайте также добавим запрос, который отправляет данные:

1. Снова нажмите Добавить запрос
2. Заполните:
   • Имя: Создать пользователя
   • Метод: POST
   • URL: http://localhost:5770/stubs/sandbox/api/users
3. Перейдите на вкладку Заголовки и добавьте:
   • Ключ: Content-Type, Значение: application/json
4. Перейдите на вкладку Тело, выберите raw и вставьте:

{
  "name": "Alice",
  "email": "alice@example.com"
}

5. Нажмите Отправить

Шаг 4: Добавьте тестовые скрипты

Тестовые скрипты позволяют автоматически проверять корректность ответа. Перейдите на вкладку Тесты запроса Получить пользователей и вставьте:

// Проверяем, что получили 200 OK
mk.test("Статус 200", function() {
    mk.response.to.have.status(200);
});

// Проверяем, что в ответе есть массив пользователей
mk.test("Содержит массив пользователей", function() {
    var data = mk.response.json();
    mk.expect(data.users).to.be.an('array');
    mk.expect(data.users.length).to.be.greaterThan(0);
});

// Проверяем, что у каждого пользователя есть обязательные поля
mk.test("Пользователь имеет обязательные поля", function() {
    var user = mk.response.json().users[0];
    mk.expect(user).to.have.property('id');
    mk.expect(user).to.have.property('name');
    mk.expect(user).to.have.property('email');
});

Нажмите Отправить снова. Теперь под ответом вы увидите результаты тестов — зелёные галочки для пройденных, красные крестики для непройденных.

Шаг 5: Используйте окружения

Окружения позволяют менять URL без редактирования каждого запроса. Например:

1. Нажмите на выпадающий список Окружения (верхний правый угол API Tester)
2. Нажмите Управление окружениями → Добавить окружение
3. Назовите его Локальное и добавьте переменную:
   • Переменная: base_url, Значение: http://localhost:5770/stubs/sandbox
4. В URL запроса используйте: {{base_url}}/api/users

Теперь при переключении окружений все запросы обновятся автоматически. Это удобно, когда нужно тестировать один и тот же API на разных серверах.

Шаг 6: Запустите всю коллекцию

Чтобы выполнить все запросы в коллекции разом:

1. Нажмите Запустить коллекцию (кнопка воспроизведения на коллекции)
2. Выберите, какие запросы включить
3. Нажмите Запустить

Результаты покажут сводку: сколько тестов прошло, сколько провалилось и общее время выполнения.

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

Pre-Request скрипты

Вы также можете писать скрипты, которые выполняются перед каждым запросом. Это полезно для генерации токенов аутентификации или подготовки тестовых данных:

// Генерируем случайный ID пользователя для этого запроса
var userId = Math.floor(Math.random() * 1000);
mk.environment.set("user_id", userId);

Затем используйте {{user_id}} в URL или теле запроса.

Запись трафика

Рекордер трафика перехватывает реальный HTTP-трафик и автоматически превращает его в моки. Вместо ручного создания моков вы можете направить рекордер на реальный API, запустить приложение и позволить Mockarty создать моки из реальных запросов и ответов.

Что такое Рекордер?

Представьте рекордер как «шпиона», который стоит между вашим приложением и реальным API. Он пропускает весь трафик без изменений, но записывает всё. После записи вы можете экспортировать захваченный трафик как:

• Моки — готовые к использованию в Mockarty
• Тестовые коллекции — для API-тестирования
• Скрипты нагрузочного тестирования — для нагрузочных тестов

Шаг 1: Запустите сессию записи

1. Перейдите в Рекордер в боковом меню
2. Нажмите Новая сессия
3. Выберите режим Reverse Proxy (самый простой вариант)
4. Введите Целевой URL — это реальный API, который вы хотите записать. Например: https://jsonplaceholder.typicode.com
5. При желании укажите Порт прослушивания (напр., 8085) или оставьте пустым для автоназначения
6. Нажмите Старт

Рекордер запущен. Он слушает на указанном порту и пересылает все запросы на целевой URL.

Шаг 2: Отправьте трафик через рекордер

Теперь направьте ваше приложение (или curl) на рекордер вместо реального API:

# Вместо вызова реального API:
# curl https://jsonplaceholder.typicode.com/users

# Вызываем через рекордер:
curl http://localhost:8085/users

Рекордер пересылает ваш запрос на jsonplaceholder.typicode.com, получает ответ и записывает и запрос, и ответ. Записи появляются в интерфейсе Рекордера в реальном времени.

Шаг 3: Просмотрите записанный трафик

Каждая запись показывает:

• Запрос: метод, URL, заголовки, тело
• Ответ: код статуса, заголовки, тело, тайминг
• Разбивка по времени: DNS, TLS-рукопожатие, время до первого байта

Нажмите на любую запись для просмотра полных деталей.

Шаг 4: Экспортируйте как моки

После записи достаточного количества трафика:

1. Нажмите Стоп для завершения сессии
2. Нажмите Экспорт в моки
3. Выберите, какие записи экспортировать
4. Выберите целевое пространство имён (напр., sandbox)
5. Нажмите Экспорт

Mockarty создаст моки из записанного трафика. Каждая пара запрос/ответ станет моком с правильным маршрутом, методом, заголовками и телом ответа.

Шаг 5: Добавьте сетевые эффекты (по желанию)

Рекордер может имитировать сетевые проблемы во время записи. Перед запуском сессии можно включить Токсины (Toxics):

Это полезно для тестирования того, как ваше приложение справляется с медленными или ненадёжными API.

Режимы записи

Нагрузочное тестирование

Mockarty включает встроенный движок нагрузочного тестирования, совместимый с k6-синтаксисом (базовая сборка, без расширений). Установка внешнего k6 не требуется. Вы пишете JavaScript-скрипты с использованием синтаксиса k6 ESM (import http from 'k6/http'), и Mockarty выполняет их, имитируя множество пользователей, одновременно обращающихся к вашему API. Основные глобальные функции k6 (check, sleep, group, fail) доступны нативно.

Что такое нагрузочное тестирование?

Нагрузочное тестирование отвечает на вопросы:

• Сколько запросов в секунду может обработать мой API?
• Что произойдёт, если 100 пользователей одновременно обратятся к API?
• Деградирует ли время ответа под нагрузкой?

Шаг 1: Откройте API Tester

Перейдите в API Tester в боковом меню. Нагрузочные тесты живут внутри коллекций API Tester — в той же рабочей области, где вы собираете обычные API-запросы.

Шаг 2: Создайте коллекцию Performance

1. В левой панели API Tester переключитесь на группу протокола Performance (нагрузочные тесты в стиле k6).
2. Нажмите + рядом с “Performance” и выберите Создать коллекцию.
3. Введите имя коллекции (например, my-first-load-test) и подтвердите.

Шаг 3: Создайте новый нагрузочный скрипт

Внутри новой Performance-коллекции нажмите кнопку + или откройте контекстное меню коллекции и выберите Новый запрос. Для Performance-коллекций это открывает промпт для имени скрипта (по умолчанию New Load Test). Введите имя и подтвердите.

Откроется редактор со стартовым шаблоном. Замените его на этот минимальный пример:

import http from 'k6/http';
import { check, sleep } from 'k6';

// Конфигурация: 10 виртуальных пользователей на 30 секунд
export const options = {
  vus: 10,
  duration: '30s',
};

// Эта функция выполняется один раз за итерацию для каждого виртуального пользователя
export default function () {
  // Отправляем GET-запрос
  const res = http.get('http://localhost:5770/stubs/sandbox/api/users');

  // Проверяем, что ответ корректен
  check(res, {
    'статус 200': (r) => r.status === 200,
    'время ответа < 500мс': (r) => r.timings.duration < 500,
  });

  // Ждём 1 секунду между итерациями (имитация реального пользователя)
  sleep(1);
}

Что это делает: Создаёт 10 «виртуальных пользователей», каждый из которых непрерывно отправляет GET-запросы на ваш моковый эндпоинт в течение 30 секунд с паузой 1 секунда между запросами.

Шаг 4: Запустите тест

Нажмите Запустить. Вы увидите метрики в реальном времени:

• Запросов в секунду — как быстро отвечает ваш API
• Время ответа — перцентили p50, p95, p99
• Процент ошибок — доля неуспешных запросов
• Виртуальные пользователи — сколько имитированных пользователей активно

Шаг 5: Попробуйте тест с постепенным увеличением нагрузки

Более реалистичный тест постепенно увеличивает нагрузку. Замените options в скрипте:

export const options = {
  stages: [
    { duration: '10s', target: 5 },   // Наращиваем до 5 пользователей за 10 секунд
    { duration: '20s', target: 20 },   // Наращиваем до 20 пользователей за 20 секунд
    { duration: '10s', target: 0 },    // Снижаем до 0 пользователей за 10 секунд
  ],
};

Тест начинается с 5 пользователей, постепенно увеличивается до 20, затем снижается обратно. Это даёт более чёткое представление о том, как API справляется с возрастающей нагрузкой.

Шаг 6: Протестируйте POST-эндпоинт

Нагрузочное тестирование — не только для GET-запросов. Вот как протестировать POST-эндпоинт:

import http from 'k6/http';
import { check, sleep } from 'k6';

export const options = {
  vus: 5,
  duration: '20s',
};

export default function () {
  const payload = JSON.stringify({
    name: 'Тестовый пользователь ' + Math.random(),
    email: 'test' + Math.random() + '@example.com',
  });

  const params = {
    headers: { 'Content-Type': 'application/json' },
  };

  const res = http.post(
    'http://localhost:5770/stubs/sandbox/api/users',
    payload,
    params
  );

  check(res, {
    'статус 200 или 201': (r) => r.status === 200 || r.status === 201,
    'время ответа < 1000мс': (r) => r.timings.duration < 1000,
  });

  sleep(0.5);
}

Шаг 7: Добавьте пороговые значения (критерии прохождения)

Добавьте пороговые значения для автоматической пометки теста как неуспешного при слишком медленной работе:

export const options = {
  vus: 10,
  duration: '30s',
  thresholds: {
    'http_req_duration': ['p(95)<500'],  // 95% запросов должны быть быстрее 500мс
    'http_req_failed': ['rate<0.01'],     // Менее 1% запросов могут завершиться ошибкой
  },
};

Если любой порог превышен, тест помечается как FAILED — полезно для CI/CD-пайплайнов, где нужно автоматически ловить деградацию производительности.

Когда использовать нагрузочное тестирование

Фаззинг

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

Доступ к фаззеру

Нажмите Фаззинг в боковом меню, чтобы открыть интерфейс фаззинга.

Быстрый фаззинг

Самый быстрый способ начать — запустить быстрый фаззинг-тест:

1. Введите Целевой URL — это может быть любой HTTP-эндпоинт (ваши моки, staging API или локальные сервисы)
2. Выберите Категории полезных нагрузок для тестирования:
   • SQL Injection — распространенные паттерны SQL-инъекций
   • XSS — полезные нагрузки межсайтового скриптинга
   • Path Traversal — попытки обхода директорий
   • Command Injection — паттерны инъекций команд ОС
   • Header Injection — манипуляции с HTTP-заголовками
   • Overflow — тесты на переполнение буфера и большие входные данные
3. Настройте метод запроса и необходимые заголовки (напр., токены аутентификации)
4. Нажмите Начать фаззинг

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

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

• Уровень серьезности — Critical, High, Medium, Low или Info
• Полезная нагрузка — точные входные данные, вызвавшие находку
• Детали ответа — код статуса, тело ответа и время выполнения
• Категория — к какой категории полезных нагрузок относится находка

Пример: Фаззинг эндпоинта авторизации

Чтобы быстро протестировать эндпоинт авторизации на SQL-инъекции:

1. Установите Целевой URL: http://localhost:5770/stubs/sandbox/api/login
2. Установите Метод: POST
3. Установите шаблон тела: {"username": "{{payload}}", "password": "test"}
4. Выберите категорию SQL Injection
5. Нажмите Начать фаззинг

Фаззер заменит {{payload}} различными строками SQL-инъекций и сообщит о любых подозрительных ответах (неожиданные коды статуса, утечка внутренних деталей в сообщениях об ошибках и т.д.).

Когда использовать фаззинг

• Перед деплоем — протестируйте ваши реальные API на распространенные уязвимости
• Валидация моков — убедитесь, что моки корректно обрабатывают граничные случаи
• Интеграция с CI/CD — запускайте фаззинг-тесты как часть пайплайна качества
• Аудит безопасности — систематическое тестирование валидации входных данных

Генерация автономного сервера

Некоторые протоколы (gRPC, Kafka, RabbitMQ, WebSocket, TCP, UDP) требуют сгенерированного автономного сервера для обслуживания трафика. Вы создаёте моки в веб-интерфейсе Mockarty, затем генерируете сервер, который принимает протокольные запросы и обращается к ноде Mockarty за резолвингом моков.

Генератор серверов также работает с прямыми протоколами (OpenAPI, GraphQL, SOAP, SSE, MCP) — полезно для создания автономных мок-серверов для CI/CD.

Примечание: Режим -create-mocks генератора серверов требует, чтобы функция mock была включена в вашей лицензии.

Установка Server Generator

Скачайте mockarty-server-generator со страницы релизов на GitHub:

• macOS (Apple Silicon): mockarty-server-generator-darwin-arm64
• macOS (Intel): mockarty-server-generator-darwin-amd64
• Linux (x86_64): mockarty-server-generator-linux-amd64

chmod +x mockarty-server-generator-darwin-arm64

Пример: Генерация из спецификации OpenAPI

./mockarty-server-generator openapi \
  -input ./petstore.yaml \
  -output server.go \
  -package main \
  -create-mocks \
  -api-token mk_your_token \
  -namespace sandbox

Это создаст полноценный Go-проект с:

• Всеми маршрутами из спецификации OpenAPI
• Моковыми ответами на основе определений схем
• Встроенным административным интерфейсом по адресу /ui
• Эндпоинтом проверки здоровья по адресу /health/live
• Вендорированными зависимостями (для сборки не нужен интернет)

Пример: Генерация gRPC-сервера

gRPC-моки создаются в веб-интерфейсе Mockarty (Конструктор → протокол gRPC), но для обслуживания gRPC-трафика необходим сгенерированный сервер:

# Генерация сервера + создание моков из proto-файлов
./mockarty-server-generator grpc \
  -input ./proto/ \
  -output server.go \
  -package main \
  -create-mocks \
  -api-token mk_your_token \
  -namespace sandbox \
  -server-name my-grpc-service

Передавайте .proto файлы как есть — option go_package необязательна, любой её формат принимается, а опции для других языков (java_package, php_namespace и т.п.) вычищаются автоматически. Устанавливать protoc не нужно.

Пример: Генерация Kafka-сервера

./mockarty-server-generator kafka \
  -input kafka-config.json \
  -output kafka_server.go \
  -package main \
  -create-mocks \
  -api-token mk_your_token \
  -server-name my-kafka-server

Где kafka-config.json описывает топики, адрес брокера и группу потребителей. См. Руководство по генератору серверов для полного формата конфигурации.

Сборка и запуск сгенерированного сервера

Все сгенерированные серверы включают вендорированные зависимости и могут быть собраны полностью офлайн:

cd generated-server
go build -mod=vendor -o server .

# Запуск с необходимыми переменными окружения
HTTP_PORT=8080 \
HTTP_ADMIN_BASE_URL=http://localhost:5770 \
NAMESPACE=sandbox \
./server

Сгенерированный сервер подключается к ноде Mockarty (HTTP_ADMIN_BASE_URL) для резолвинга моков при каждом запросе. Нода Mockarty должна быть запущена и доступна.

Поддерживаемые типы серверов

Использование: mockarty-server-generator <тип> [флаги]

AI-ассистент

Mockarty включает встроенного AI-ассистента, который может создавать моки, заполнять формы, управлять интерфейсом и отвечать на вопросы на естественном языке. AI-ассистент, внутренняя агентская сеть и MCP-сервер являются частью базового продукта — доступны каждому пользователю без необходимости специальной лицензии на функцию.

Единственная лицензируемая AI-функция — A2A (протокол Agent-to-Agent), позволяющая использовать вашу установку Mockarty как узел во внешних агентских сетях. Она управляется флагом a2a и не влияет на работу встроенного AI-ассистента.

Предварительные требования

AI-ассистенту необходимо:

1. Настройка LLM-провайдера — администратор должен настроить хотя бы один LLM-профиль (серверный режим), либо вы можете использовать собственный API-ключ (клиентский режим — см. ниже).

Когда LLM-провайдер настроен, в правом нижнем углу каждой страницы веб-интерфейса появляется плавающая кнопка чата. Нажмите на неё, чтобы открыть чат. Также можно перейти в Чат с агентом в боковом меню для полноэкранного режима.

Серверный режим (настроенный администратором)

Рекомендуемый подход для команд. Администратор настраивает LLM-профили в Администрирование → Настройки LLM:

• Профили создаются и управляются централизованно — пользователи выбирают из доступных профилей в настройках чата
• Поддерживаемые провайдеры: OpenAI, Anthropic (Claude), OpenRouter, Google (Gemini), Mistral, Groq, Ollama (локальный), и Custom (любой OpenAI-совместимый эндпоинт)
• API-ключи хранятся безопасно на сервере
• Администратор также может настроить MCP-серверы для расширенных возможностей инструментов

Клиентский режим (свой API-ключ)

Если вы предпочитаете использовать собственный API-ключ, или если серверные профили не настроены:

1. Откройте плавающий чат и нажмите на иконку Настройки (шестерёнка)
2. Выберите провайдера (например, OpenAI, Anthropic, OpenRouter)
3. Введите свой API-ключ и выберите модель
4. Нажмите Сохранить

В клиентском режиме ваш API-ключ хранится в localStorage браузера, а запросы отправляются напрямую к LLM-провайдеру — сервер Mockarty никогда не видит ваш ключ. Сервер задействуется только для выполнения вызовов инструментов (создание моков, чтение данных и т.д.).

Что может AI-ассистент?

• Создание моков: «Создай GET /api/users endpoint, который возвращает список пользователей с фейковыми именами и email»
• Заполнение форм: «Установи код ответа 404 и добавь JSON-ответ с ошибкой»
• Управление интерфейсом: Ассистент может взаимодействовать с элементами страницы, заполнять поля и нажимать кнопки от вашего имени
• Объяснение функций: «Как использовать условия для сопоставления запросов по заголовку?»
• Отладка: «Почему мой мок не сопоставляется с запросами?»

Режим автоматического одобрения

По умолчанию каждый вызов инструмента AI требует ручного одобрения (Принять/Отклонить). Включите Auto Approve в выпадающем списке панели чата для автоматического выполнения вызовов инструментов без подтверждения.

Подробные инструкции по настройке LLM см. в Руководстве администратора и Руководстве по AI-функциям.

Устранение проблем

Распространённые ошибки при первом запуске:

Если ни один пункт не подходит, проверьте логи сервера — структурированный вывод Zap содержит идентификатор запроса и цепочку ошибок для каждого неуспешного обращения.

Дальнейшие шаги

Теперь у вас есть работающий экземпляр Mockarty с первым моком. Вот куда двигаться дальше:

Узнайте больше

Типичные следующие шаги

1. Настройте PostgreSQL для продакшена — SQLite отлично подходит для разработки, но PostgreSQL рекомендуется для командной работы и продакшен-окружений.

2. Создайте дополнительные пространства имен для организации моков по проектам или командам. Перейдите в Панель администратора для создания пространств имен и назначения пользователей.

3. Импортируйте существующие API с помощью Генератора OpenAPI или импорта HAR-файлов. Записывайте реальный API-трафик и создавайте моки автоматически.

4. Используйте AI-ассистента — откройте плавающий чат или перейдите в Чат с агентом в боковом меню и опишите, какие моки вам нужны, на естественном языке. Ассистент — часть базового продукта и доступен всем пользователям. Подробнее см. AI-функции.

5. Настройте интеграцию с CI/CD — используйте REST API для программного создания и управления моками в ваших тестовых пайплайнах.

6. Изучите режим прокси — пересылайте запросы к реальным сервисам, добавляя задержки, модифицируя ответы или логируя трафик.

7. Масштабируйтесь с resolver-узлами — разверните несколько resolver-узлов для высокодоступного обслуживания моков. Подробности в Руководстве по интеграциям.

8. Запустите фаззинг-тесты — используйте встроенный фаззер для тестирования ваших реальных API на уязвимости перед деплоем.

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

10. Хаос-инжиниринг — внедряйте сбои (остановка подов, сетевые задержки, нагрузка на ресурсы) в Kubernetes-кластеры для проверки устойчивости ваших сервисов к отказам. Подробнее см. Хаос-инжиниринг.

11. Управление тест-кейсами — если ваша команда ведёт тест-кейсы вручную (таблицы, Confluence, TestRail), перейдите на встроенный TMS Mockarty. Организуйте кейсы в папках, добавляйте пошаговые инструкции, связывайте с задачами Jira/GitHub, отправляйте на ревью и запускайте автоматические прогоны. Подробнее см. Управление тест-кейсами.

12. Тест-планы — оркестрируйте весь регрессионный набор как DAG-воркфлоу: сначала функциональные тесты, потом нагрузочные, потом хаос — с гейтами, которые блокируют следующий шаг при неудаче предыдущего. Запускайте из CI/CD через API или cron. Подробнее см. Тест-планы.

Получение помощи

• Документация: Все руководства доступны в боковом меню в разделе Документация
• Проверка здоровья: Перейдите по адресу http://localhost:5770/health/live для проверки работоспособности сервера
• Swagger UI: Перейдите по адресу http://localhost:5770/swagger/index.html для интерактивной документации API
• Логи: Проверяйте вывод консоли для получения структурированных логов с деталями запросов

Удачного мокирования!