mockingbird

mockingbird - сервис эмуляции REST-сервисов и сервисов с интерфейсами-очередями

Руководство по инсталляции

Руководство по настройке

Работа с очередями

Общие принципы работы

mockingbird поддерживает следующие сценарии:

прогон конкретного кейса с конкретным набором событий и HTTP/GRPC ответов
постоянная имитация happy-path для обеспечения автономности контура(ов)

Типы конфигураций:

countdown - автономные конфигурации для тестирования конкретного сценария. Имеют наивысший приоритет при разрешении неоднозначностей. Каждый мок срабатывает n раз (количество задаётся при создании). Автоматически удаляются в полночь.
ephemeral - конфигурации, автоматически удаляемые в полночь. Если одновременно вызывают метод/приходит сообщение, для которого подходит countdown и ephemeral моки - сработает countdown.
persistent - конфигурация, предназначеная для постоянной работы. Имеет наименьший приоритет

Пример небольшого кейса (короткая заявка) - в конце спецификации

Сервисы

Для упорядочения моков в UI и минимизации количества конфликтных ситуаций в mockingbird реализованы т.н. сервисы. Каждый мок (как HTTP так и сценарий) всегда принадлежит к какому-то из сервисом. Сервисы создаются заранее и хранятся в базе. Сервис имеет suffix (являющийся по совместительству уникальным id сервиса) и человекочитаемый name.

Шаблонизатор JSON

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

Шаблон:

{
  "description": "${description}",
  "topic": "${extras.topic}",
  "comment": "${extras.comments.[0].text}",
  "meta": {
    "field1": "${extras.fields.[0]}"
  }
}

Значения для подстановки:

{
  "description": "Some description",
  "extras": {
    "fields": ["f1", "f2"],
    "topic": "Main topic",
    "comments": [
      {"text": "First nah!"}, {"text": "Okay"}
    ]
  }
}

Результат:

{
  "description": "Some description",
  "topic": "Main topic",
  "comment": "First nah!",
  "meta": {
    "field1": "f1"
  }
}

В данный момент поддерживается следующий синтаксис:

${a.[0].b} - подстановка значения (JSON)
${/a/b/c} - подстановка значения (XPath)

ВНИМАНИЕ! НЕ ИСПОЛЬЗУЙТЕ НЕЙМСПЕЙСЫ В XPATH ВЫРАЖЕНИЯХ

Шаблонизатор XML

Шаблон:

<root>
    <tag1>${/r/t1}</tag1>
    <tag2 a2="${/r/t2/@a2}">${/r/t2}</tag2>
</root>

Значения для подстановки:

<r>
    <t1>test</t1>
    <t2 a2="attr2">42</t2>
</r>

Результат:

<root>
    <tag1>test</tag1>
    <tag2 a2="attr2">42</tag2>
</root>

Состояния (state)

Для поддержки сложных сценариев сервис поддерживает сохранение произвольных состояний. Состояние - документ с произвольной схемой, технически состояние - документ в mongodb. Запись новых состояний может происходить:

при записи в state (секция persist) с пустым (или отсутствующим) предикатом (секция state)

Манипуляции со state

State аккумулятивно дописывается. Разрешено переписывание полей.

Поля, по которым будем производиться поиск (используемые в предикатах) должны начинаться с "_".

для таких полей будет автоматически создаваться sparse индекс

Префиксы:

seed - значения из блока seed (рандомизируемые на старте заявки)
state - текущий state
req - тело запроса (режимы json, jlens, xpath)
message - тело собщения (в сценариях)
query - query параметры (в заглушках)
pathParts - значения, извлекаемые из URL (в заглушках) см. Экстрация данных из URL
extracted - извлечённые значения
headers - HTTP заголовки

{
  "a": "Просто строка", //В поле "a" записывается константа (может быть любое JSON значение)
  "b": "${req.fieldB}", //В поле "b" записывается значение из поля fieldB запроса
  "c": "${state.c}", //В поле "c" записывается значение из поля "c" текущего состояния
  "d": "${req.fieldA}: ${state.a}" //В поле d запишется строка, содержащая req.fieldA и state.a
}

Поиск state

Предикаты для поиска state перечисляются в блоке state. Пустой объект ({}) в поле state недопустим. Для поиска state можно использовать данные запроса (без префикса), query параметры (префикс __query), значения, извлекаемые из URL (префикс __segments) и HTTP заголовки (префикс __headers)

Пример:

{
  "_a": "${fieldB}", //поле из тела запроса
  "_b": "${__query.arg1}", //query параметр
  "_c": "${__segments.id}", //сегмент URL, см. `Экстрация данных из URL`
  "_d": "${__headers.Accept}" //HTTP заголовок
}

Seeding

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

В seed'ах поддерживается синтаксис псевдофункций:

%{randomString(n)} - подстановка случайной строки длиной n
%{randomString("ABCDEF1234567890", m, n)} - подстановка случайной строки, состоящей из символов ABCDEF1234567890 длиной в интервале [m, n)
%{randomNumericString(n)} - подстановка случайной строки, состоящей только из цифр, длиной n
%{randomInt(n)} - подстановка случайного Int в диапазоне [0, n)
%{randomInt(m,n)} - подстановка случайного Int в диапазоне [m, n)
%{randomLong(n)} - подстановка случайного Long в диапазоне [0, n)
%{randomLong(m,n)} - подстановка случайного Long в диапазоне [m, n)
%{UUID} - подстановка случайного UUID
%{now(yyyy-MM-dd'T'HH:mm:ss)} - текущее время в заданном формате
%{today(yyyy-MM-dd)} - текущая дата в заданном формате

Можно определять строки со сложным форматом: %{randomInt(10)}: %{randomLong(10)} | %{randomString(12)}, поддерживаются все псевдофункции из списка выше

Резолвинг заглушек/сценариев

Найденые заглушки - кандидаты, оставшиеся после валидации URL, заголовков и тела запроса Найденые сценарии - кандидаты, оставшиеся после валидации тела сообщения

Найденые заглушки (сценарии)	Требуется состояние	Найдено состояний	Результат
№1	нет	-	Сработает №1
№1	да	0	Ошибка
№1	да	1	Сработает №1
№1 №2	нет нет	-	Ошибка
№1 №2	нет да	- 0	Сработает №1
№1 №2	нет да	- 1	Сработает №2
№1 №2	нет да	- 2 (и более)	Ошибка
№1 №2	да да	0 0	Ошибка
№1 №2	да да	0 1	Сработает №2
№1 №2	да да	0 2 (и более)	Ошибка
№1 №2	да да	1 1 (и более)	Ошибка
№1 №2 №3	да да да	0 1 0	Сработает №2
№1 №2 №3	да да да	0 1 1	Ошибка
№1 №2 №3	да да да	0 2 0	Ошибка

Эмуляция REST сервисов

Алгоритм работы:

Поиск мока по URL/HTTP-verb/заголовков
Валидация body
Поиск state по предикату
Подстановка значений в шаблон ответа
Модификация state
Отдача response

Конфигурация HTTP заглушек

HTTP заголовки валидируются на полное соответствие значений, лишние заголовки не являются ошибкой

Валидация тела запросы в HTTP заглушках может работать в следующих режимах:

no_body - запрос должен быть без тела
any_body - тело запроса должно быть не пустым, при этом никак не парсится и не проверяется
raw - тело запроса никак не парсится и проверяется на полное соответствие с содержимым request.body
json - тело запроса должно быть валидным JSON'ом и проверяется на соответствие с содержимым request.body
xml - тело запроса должно быть валидным XML и проверяется на соответствие с содержимым request.body
jlens - тело запроса должно быть валидным JSON'ом и валидируется по условиям, описаным в request.body
xpath - тело запроса должно быть валидным XML и валидируется по условиям, описаным в request.body
web_form - тело запроса должно быть в формате x-www-form-urlencoded и валидируется по условиям, описаным в request.body
multipart - тело запроса должно быть в формате multipart/form-data. Правила валидации частей конфигурируются индивидуально (см. раздел ниже)

ВНИМАНИЕ! multipart запросы необходимо выполнять на отдельный метод - /api/mockingbird/execmp

Для ответов поддерживаются следующие режимы:

raw
json
xml
binary
proxy
json-proxy
xml-proxy

Режимы request и response полностью независимы друг от друга (можно сконфигурировать ответ xml'ем на json запрос при желании, кроме режимов json-proxy и xml-proxy)

В поле delay можно передать корректный FiniteDuration не дольше 30 секунд

Экстрация данных из URL

Бывает, что URL содержит какой-нибудь идентификатор не как параметр, а как непосредственно часть пути. В таких случаях становится невозможным описать persistent заглушку из-за невозможности полного совпадения пути. На помощь приходит поле pathPattern, в которое можно передать регулярку, на соответствие которой будет проверяться путь. Отмечу, что хоть сопоставление и производится в монге эффективным способом, злоупотребять этой возможностью не стоит и при возможности сопоставления по полному совпадению не следует использовать pathPattern

Пример:

{
  "name": "Sample stub",
  "scope": "persistent",
  "pathPattern": "/pattern/(?<id>\d+)",
  "method": "GET",
  "request": {
    "headers": {},
    "mode": "no_body",
    "body": {}
  },
  "response": {
    "code": 200,
    "mode": "json",
    "headers": {"Content-Type":  "application/json"},
    "body": {"id": "${pathParts.id}"}
  }
}

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

Экстракторы

В некоторых случаях нужно подставить в ответ данные, которые невозможно извлечь простыми средствами. Для этих целей были добавлены экстракторы

Экстрактор xcdata

Достаёт значения из XML, лежащего в CDATA

конфигурация:

{
  "type": "xcdata",
  "prefix": "/root/inner/tag", //Путь до тэга с CDATA
  "path": "/path/to" //Путь до нужного тэга
}

Экстрактор jcdata

Достаёт значения из JSON, лежащего в CDATA

конфигурация:

{
  "type": "jcdata",
  "prefix": "/root/inner/tag", //Путь до тэга с CDATA
  "path": "path.to" //Путь до нужного значения
}

CDATA inlining

Иногда приходится иметь дело с запросами, в которых внутри CDATA лежит XML. В таких случаях можно заинлайнить содержимое DATA с помощью параметра inlineCData (поддерживается в xpath и xml)

Примеры

Полное совпадение, режим json

{
    "name": "Sample stub",
    "method": "POST",
    "path": "/pos-loans/api/cl/get_partner_lead_info",
    "state": {
      // Предикаты
    },
    "request": {
        "headers": {"Content-Type": "application/json"},
        "mode": "json",
        "body": {
            "trace_id": "42",
            "account_number": "228"
        }
    },
    "persist": {
      // Модификации состояния
    },
    "response": {
        "code": 200,
        "mode": "json",
        "body": {
            "code": 0,
            "credit_amount": 802400,
            "credit_term": 120,
            "interest_rate": 13.9,
            "partnum": "CL3.15"
        },
        "headers": {"Content-Type": "application/json"},
        "delay": "1 second"
    }
}

Полное совпадение, режим raw

{
    "name": "Sample stub",
    "method": "POST",
    "path": "/pos-loans/api/evil/soap/service"
    "state": {
      // Предикаты
    },
    "request": {
        "headers": {"Content-Type": "application/xml"},
        "mode": "raw"
        "body": "<xml><request type=\"rqt\"></request></xml>"
    },
    "persist": {
      // Модификации состояния
    },
    "response": {
        "code": 200,
        "mode": "raw"
        "body": "<xml><response type=\"rqt\"></response></xml>",
        "headers": {"Content-Type": "application/xml"},
        "delay": "1 second"
    }
}

Валидация по условиям, режим jlens

{
    "name": "Sample stub",
    "method": "POST",
    "path": "/pos-loans/api/cl/get_partner_lead_info",
    "state": {
      // Предикаты
    },
    "request": {
        "headers": {"Content-Type": "application/json"},
        "mode": "jlens",
        "body": {
            "meta.id": {"==": 42}
        }
    },
    "persist": {
      // Модификации состояния
    },
    "response": {
        "code": 200,
        "mode": "json",
        "body": {
            "code": 0,
            "credit_amount": 802400,
            "credit_term": 120,
            "interest_rate": 13.9,
            "partnum": "CL3.15"
        },
        "headers": {"Content-Type": "application/json"},
        "delay": "1 second"
    }
}

Валидация по условиям, режим xpath

ВНИМАНИЕ! НЕ ИСПОЛЬЗУЙТЕ НЕЙМСПЕЙСЫ В XPATH ВЫРАЖЕНИЯХ

{
    "name": "Sample stub",
    "method": "POST",
    "path": "/pos-loans/api/cl/get_partner_lead_info",
    "state": {
      // Предикаты
    },
    "request": {
        "headers": {"Content-Type": "application/xml"},
        "mode": "xpath",
        "body": {
            "/payload/response/id": {"==": 42}
        },
        "extractors": {"name": {...}, ...} //опционально
    },
    "persist": {
      // Модификации состояния
    },
    "response": {
        "code": 200,
        "mode": "raw"
        "body": "<xml><response type=\"rst\"></response></xml>",
        "headers": {"Content-Type": "application/xml"},
        "delay": "1 second"
    }
}

Валидация по условиям, режим multipart

ВНИМАНИЕ! multipart запросы необходимо выполнять на отдельный метод - /api/mockingbird/execmp

Режимы валидании part:

any - значение никак не валидируется
raw - полное соответствие
json - полное соответствие, значение парсится как Json
xml - полное соответствие, значение парсится как XML
urlencoded - аналогично режиму web_form для валидации всего тела
jlens - проверка Json по условиям
xpath - проверка XML по условиям

{
    "name": "Sample stub",
    "method": "POST",
    "path": "/test/multipart",
    "state": {
      // Предикаты
    },
    "request": {
        "headers": {},
        "mode": "multipart",
        "body": {
            "part1": {
              "mode": "json", //режим валидации
              "headers": {}, //заголовки part
              "value": {} //спецификация значения для валидатора
            },
            "part2": {
              ...
            }
        },
        "bypassUnknownParts": true //флаг, позволяющий игнорировать все partы, отсутвующие в спецификации валидатора
                                   //по умолчанию флаг включен, можно передавать только для отключения (false)
    },
    "persist": {
      // Модификации состояния
    },
    "response": {
        "code": 200,
        "mode": "json",
        "body": {
            "code": 0,
            "credit_amount": 802400,
            "credit_term": 120,
            "interest_rate": 13.9,
            "partnum": "CL3.15"
        },
        "headers": {"Content-Type": "application/json"},
        "delay": "1 second"
    }
}

Простое проксирование запроса

{
  "name": "Simple proxy",
  "method": "POST",
  "path": "/pos-loans/api/cl/get_partner_lead_info",
  "state": {
      // Предикаты
  },
  "request": {
    // Спецификация запроса
  },
  "response": {
    "mode": "proxy",
    "uri": "http://some.host/api/cl/get_partner_lead_info"
  }
}

Проксирование с модификацией JSON ответа

{
  "name": "Simple proxy",
  "method": "POST",
  "path": "/pos-loans/api/cl/get_partner_lead_info",
  "state": {
      // Предикаты
  },
  "request": {
    // Спецификация запроса, mode json или jlens
  },
  "response": {
    "mode": "json-proxy",
    "uri": "http://some.host/api/cl/get_partner_lead_info",
    "patch": {
      "field.innerField": "${req.someRequestField}"
    }
  }
}

Проксирование с модификацией XML ответа

{
  "name": "Simple proxy",
  "method": "POST",
  "path": "/pos-loans/api/cl/get_partner_lead_info",
  "state": {
      // Предикаты
  },
  "request": {
    // Спецификация запроса, mode xml или xpath
  },
  "response": {
    "mode": "xml-proxy",
    "uri": "http://some.host/api/cl/get_partner_lead_info",
    "patch": {
      "/env/someTag": "${/some/requestTag}"
    }
  }
}

DSL предикатов валидации JSON и XML

в режимах jlens и xpath поддерживается следующее:

{
  "a": {"==": "some value"}, //полное соответствие
  "b": {"!=": "some value"}, //не равно
  "c": {">": 42} | {">=": 42} | {"<": 42} | {"<=": 42}, //сравнения, только для чисел, комбинируются
  "d": {"~=": "\d+"}, //сопоставление с regexp,
  "e": {"size": 10}, //длина, для массивов и строк
  "f": {"exists": true} //проверка существования
}

Ключами в таких объектах является либо путь в json ("a.b.[0].c") либо xpath ("/a/b/c") Замечание: в данный момент функции сравнения могут некорректно работать с xpath, указывающими на XML атрибуты. Обойти проблему можно проверкой на существование/несуществование: /tag/otherTag/[@attr='2']": {"exists": true}

в режиме jlens дополнительно поддерживаются следующие операции:

{
    "g": {"[_]": ["1", 2, true]}, //поле должно содержать одно из перечисленых значений
    "h": {"![_]": ["1", 2, true]}, //поле НЕ должно содержать ни одно из перечисленых знаечний
    "i": {"&[_]": ["1", 2, true]} // поле должно быть массивом и содержать все перечисленные значения (при этом порядок не важен)
}

в режиме xpath дополнительно поддерживаются следующие операции:

  "/some/tag": {"cdata": {"==": "test"}}, //валидация на полное совпадение CDATA, аргумент должен быть СТРОКОЙ
  "/some/tag": {"cdata": {"~=": "\d+"}}, //валидация DATA регуляркой, аргумент должен быть СТРОКОЙ
  "/some/tag": {"jcdata": {"a": {"==": 42}}}, //валидируем содержимое CDATA как JSON, поддерживаются все доступные предикаты
  "/other/tag": {"xcdata": {"/b": {"==": 42}}} //валидируем содержимое CDATA как XML, поддерживаются все доступные предикаты

в режиме web_form поддерживаются ТОЛЬКО следующие операции: ==, !=, ~=, size, [_], ![_], &[_]

Эмуляция GRPC сервисов

Как это устроено под капотом: При создании мока вложеные в запрос proto файлы парсятся и преобразуются в json-представление protobuf схемы. В базе хранится именно json-представление, а не оригинальный proto файл. Первое срабатывание мока может занимать немного больше времени, чем последующие, т.к. при первом срабатывании из json-представляения генерируется декодер protobuf сообщений. После декодирования данные преобразуются в json, который проверяется json-предикатами, задаными в поле requestPredicates. Если условия выполняются - то json из response.data (в режиме fill) сериализуется в protobuf и отдаётся в качестве ответа.

Алгоритм работы:

Поиск мока(-ов) по имени метода
Валидация body
Поиск state по предикату
Подстановка значений в шаблон ответа
Модификация state
Отдача response

Конфигурация GRPC заглушек

{
    "name": "Sample stub",
    "scope": "..",
    "service": "test",
    "methodName": "/pos-loans/api/cl/get_partner_lead_info",
    "seed": {
        "integrationId": "%{randomString(20)}" //пример
    },
    "state": {
      // Предикаты
    },
    "requestCodecs": "..", //proto-файл схемы запроса в base64
    "requestClass": "..", //имя типа запроса из proto файла
    "responseCodecs": "..", //proto-файл схемы ответа в base64
    "responseClass": "..", //имя типа ответа из proto файла
    "requestPredicates": {
        "meta.id": {"==": 42}
    },
    "persist": {
      // Модификации состояния
    },
    "response": {
        "mode": "fill",
        "data": {
            "code": 0,
            "credit_amount": 802400,
            "credit_term": 120,
            "interest_rate": 13.9,
            "partnum": "CL3.15"
        },
        "delay": "1 second"
    }
}

Эмуляция шинных сервисов

Алгоритм работы:

Поиск мока по source
Поиск state по предикату
Валидация входящего сообщения
Подстановка значений в шаблон ответа
Модификация state
Отправка response
Выполнение колбеков (см. раздел "конфигурация колбеков")

Конфигурация

Работа с очередями

Конфигурация мока

Для input поддерживаются режимы:

raw
json
xml
jlens
xpath

Для output поддерживаются режимы:

raw
json
xml

{
  "name": "Пришла весна", 
  "service": "test",
  "source": "rmq_example_autobroker_decision", //source из конфига
  "input": {
    "mode": .. //как для HTTP заглушек
    "payload": .. //как body для HTTP заглушек
  },
  "state": {
    // Предикаты
  },
  "persist": { //Опционально
    // Модификации состояния
  },
  "destination": "rmq_example_q1", // destination из конфига, опционально
  "output": { //Опционально  
    "mode": "raw",
    "payload": "..",
    "delay": "1 second"
  },
  "callback": { .. }
}

Конфигурация колбеков

Для имитации поведения реального мира иногда нужно выполнить вызов HTTP сервиса (пример - забрать GBO когда приходит сообщение) или отправлять дополнительные сообщения в очереди. Для этого можно использовать колбеки. Результат вызова сервиса можно при необходимости распарсить и сохранить в состояние. Коллбеки используют состяние вызвавшего.

Вызов HTTP метода

Для request поддерживаются режимы

no_body
raw
json
xml

Для response поддерживаются режимы

json
xml

Обратите внимание! В всю цепочку колбеков передаётся первоначальный стейт, он не изменяется блоком perist (!!!)

{
  "type": "http",
  "request": {
    "url": "http://some.host/api/v2/peka",
    "method": "POST",
    "headers": {"Content-Type": "application/json"},
    "mode": "json",
    "body": {
      "trace_id": "42",
      "account_number": "228"
    }
  },
  "responseMode": "json" | "xml", //Обязательно только при наличии блока persist
  "persist": { //Опционально
    // Модификации состояния
  },
  "delay": "1 second", //Задержка ПЕРЕД выполнением колбека, опционально
  "callback": { .. } //Опционально
}

Отправка сообщения

Для output поддерживаются режимы:

raw
json
xml

{
  "type": "message",
  "destination": "rmq_example_q1", // destination из конфига
  "output": {
    "mode": "raw",
    "payload": ".."
  },
  "callback": { .. } //Опционально
}

Name		Name	Last commit message	Last commit date
Latest commit History 70 Commits
.github		.github
backend		backend
examples		examples
frontend		frontend
img		img
.gitignore		.gitignore
CODEOWNERS		CODEOWNERS
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE.txt		LICENSE.txt
configuration.md		configuration.md
confluent.md		confluent.md
deployment.md		deployment.md
docker-compose.yml		docker-compose.yml
message-brokers.md		message-brokers.md
readme.md		readme.md

License

Tinkoff/mockingbird

Folders and files

Latest commit

History

Repository files navigation

mockingbird

Общие принципы работы

Сервисы

Шаблонизатор JSON

Шаблонизатор XML

Состояния (state)

Манипуляции со state

Поиск state

Seeding

Резолвинг заглушек/сценариев

Эмуляция REST сервисов

Конфигурация HTTP заглушек

Экстрация данных из URL

Экстракторы

Экстрактор xcdata

Экстрактор jcdata

CDATA inlining

Примеры

Полное совпадение, режим json

Полное совпадение, режим raw

Валидация по условиям, режим jlens

Валидация по условиям, режим xpath

Валидация по условиям, режим multipart

Простое проксирование запроса

Проксирование с модификацией JSON ответа

Проксирование с модификацией XML ответа

DSL предикатов валидации JSON и XML

Эмуляция GRPC сервисов

Конфигурация GRPC заглушек

Эмуляция шинных сервисов

Конфигурация

Конфигурация мока

Конфигурация колбеков

Вызов HTTP метода

Отправка сообщения

About

Resources

License

Stars

Watchers

Forks

Languages