Gonkey — инструмент тестирования микросервисов

Gonkey тестирует наши микросервисы в Lamoda, и мы подумали, что он может протестировать и ваши, поэтому выложили его в open source. Если функциональность ваших сервисов реализована преимущественно через API, и используется JSON для обмена данными, то почти наверняка Gonkey подойдет и вам.

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

Как родился Gonkey

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

Когда мы поняли, что сервисов становится много, а дальше их будет еще больше, то разработали внутренний документ, описывающий стандартный подход к проектированию API, и взяли как инструмент описания Swagger (и даже написали утилиты для генерации кода на основе swagger-спецификации). Если интересно узнать об этом подробнее, посмотрите доклад Андрея с Highload++.

Стандартный подход к проектированию API закономерно навел на мысль о стандартном подходе к тестированию. Вот чего хотелось добиться:

1. Тестировать сервисы через API, потому что через него и реализуется почти вся функциональность сервиса
2. Возможность автоматизировать запуск тестов, чтобы встроить его в наш процесс CI/CD, как говорится, “запускать по кнопке”
3. Написание тестов должно быть отчуждаемым, то есть, чтобы тесты мог писать не только программист, в идеале — человек, не знакомый с программированием.

Так родился Gonkey.

Итак, что же это?

Gonkey — библиотека (для проектов на Golang) и консольная утилита (для проектов на любых языках и технологиях), с помощью которой можно проводить функциональное и регрессионное тестирование сервисов, путем обращения к их API по заранее составленному сценарию. Сценарии тестов описываются в YAML-файлах.

Попросту говоря, Gonkey умеет:

• обстреливать ваш сервис HTTP-запросами и следить, чтобы его ответы соответствовали ожидаемым. Он предполагает, что в запросах и ответах используется JSON, но, скорее всего, сработает и на несложных случаях с ответами в другом формате;
• подготавливать базу данных к тесту, заполнив ее данными из фикстур (тоже задаются в YAML-файлах);
• имитировать ответы внешних сервисов с помощью моков (эта фича доступна, только если вы подключаете Gonkey как библиотеку);
• выдавать результат тестирования в консоль или формировать Allure-отчет.

Репозиторий проекта
Docker-образ

Пример тестирования сервиса с Gonkey

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

Давайте набросаем маленький сервис на Go, который будет имитировать работу светофора. Он хранит цвет текущего сигнала: красный, желтый или зеленый. Получить текущий цвет сигнала или установить новый можно через API.

// возможные состояния светофора const (     lightRed    = "red"     lightYellow = "yellow"     lightGreen  = "green" )  // структура для хранения состояния светофора type trafficLights struct {     currentLight string       `json:"currentLight"`     mutex        sync.RWMutex `json:"-"` }  // экземпляр светофора var lights = trafficLights{     currentLight: lightRed, }  func main() {     // метод для получения текущего состояния светофора     http.HandleFunc("/light/get", func(w http.ResponseWriter, r *http.Request) {         lights.mutex.RLock()         defer lights.mutex.RUnlock()          resp, err := json.Marshal(lights)         if err != nil {             log.Fatal(err)         }          w.Write(resp)     })      // метод для установки нового состояния светофора     http.HandleFunc("/light/set", func(w http.ResponseWriter, r *http.Request) {         lights.mutex.Lock()         defer lights.mutex.Unlock()          request, err := ioutil.ReadAll(r.Body)         if err != nil {             log.Fatal(err)         }          var newTrafficLights trafficLights         if err := json.Unmarshal(request, &newTrafficLights); err != nil {             http.Error(w, err.Error(), http.StatusBadRequest)             return         }          if err := validateRequest(&newTrafficLights); err != nil {             http.Error(w, err.Error(), http.StatusBadRequest)             return         }          lights = newTrafficLights     })      // запуск сервера (блокирующий)     log.Fatal(http.ListenAndServe(":8080", nil)) }  func validateRequest(lights *trafficLights) error {     if lights.currentLight != lightRed &&         lights.currentLight != lightYellow &&         lights.currentLight != lightGreen {         return fmt.Errorf("incorrect current light: %s", lights.currentLight)     }     return nil }

Полностью исходный код main.go здесь.

Запустим программу:

go run .

Набросал очень быстро, за 15 минут! Наверняка где-нибудь ошибся, поэтому напишем тест и проверим.

Скачаем и запустим Gonkey:

mkdir -p tests/cases docker run -it -v $(pwd)/tests:/tests lamoda/gonkey -tests tests/cases -host host.docker.internal:8080

Эта команда запускает образ с gonkey через докер, монтирует директорию tests/cases внутрь контейнера и запускает gonkey с параметрами -tests tests/cases/ -host.

Если вам не нравится подход с докером, то альтернативой такой команде было бы написать:

go get github.com/lamoda/gonkey go run github.com/lamoda/gonkey -tests tests/cases -host localhost:8080

Запустили и получили результат:

Failed tests: 0/0

Нет тестов — нечего проверять. Напишем первый тест. Создадим файл tests/cases/light_get.yaml с минимальным содержимым:

- name: WHEN currentLight is requested MUST return red   method: GET   path: /light/get   response:     200: >         {             "currentLight": "red"         }

На первом уровне — список. Это означает, что мы описали один тест-кейс, но в файле их может быть много. Вместе они составляют тестируемый сценарий. Таким образом, один файл — один сценарий. Можно создать сколько угодно файлов со сценариями тестов, если удобно, разложить их по поддиректориям — gonkey считывает все yaml и yml файлы из переданной директории и глубже рекурсивно.

Ниже в файле описаны детали запроса, который будет отправлен на сервер: метод, путь. Еще ниже — код ответа (200) и тело ответа, которые мы ожидаем от сервера.

Полный формат файла описан в README.

Запустим еще раз:

docker run -it -v $(pwd)/tests:/tests lamoda/gonkey -tests tests/cases -host host.docker.internal:8080

Результат:

       Name: WHEN currentlight is requested MUST return red  Request:      Method: GET        Path: /light/get       Query:         Body: <no body>  Response:      Status: 200 OK        Body: {}       Result: ERRORS!  Errors:  1) at path $ values do not match:      expected: {     "currentLight": "red" }         actual: {}  Failed tests: 1/1

Ошибка! Ожидалась структура с полем currentLight, а вернулась пустая структура. Это плохо. Первая проблема — это то, что результат был интерпретирован как строка, об этом говорит нам то, что в качестве проблемного места gonkey подсветил весь ответ целиком, без деталиции:

     expected: {     "currentLight": "red" }

Причина простая: я забыл написать, чтобы сервис в ответе указывал тип содержимого application/json. Исправляем:

// метод для получения текущего состояния светофора http.HandleFunc("/light/get", func(w http.ResponseWriter, r *http.Request) {     lights.mutex.RLock()     defer lights.mutex.RUnlock()      resp, err := json.Marshal(lights)     if err != nil {         log.Fatal(err)     }      w.Header().Add("Content-Type", "application/json") // <-- добавилось     w.Write(resp) })

Перезапускаем сервис и прогоняем тесты еще раз:

       Name: WHEN currentlight is requested MUST return red  Request:      Method: GET        Path: /light/get       Query:         Body: <no body>  Response:      Status: 200 OK        Body: {}       Result: ERRORS!  Errors:  1) at path $ key is missing:      expected: currentLight        actual: <missing>

Отлично, есть прогресс. Теперь gonkey распознает структуру, но она по-прежнему неверная: ответ пустой. Причина в том, что я в определении типа использовал неэкспортируемое поле currentLight:

// структура для хранения состояния светофора type trafficLights struct {     currentLight string       `json:"currentLight"`     mutex        sync.RWMutex `json:"-"` }

В Go поле структуры, названное со строчной буквы считается неэкспортируемым, то есть, недоступным из других пакетов. Сериализатор JSON его не видит и не может включить его в ответ. Исправляем: делаем поле с заглавной буквы, что означает, что оно экспортируемое:

// структура для хранения состояния светофора type trafficLights struct {     СurrentLight string       `json:"currentLight"` // <-- изменилось название     mutex        sync.RWMutex `json:"-"` }

Перезапускаем сервис. Снова запускаем тесты.

Failed tests: 0/1

Тесты прошли!

Напишем еще один сценарий, который проверит метод set. Заполним файл tests/cases/light_set.yaml следующим содержимым:

- name: WHEN set is requested MUST return no response   method: POST   path: /light/set   request: >     {         "currentLight": "green"     }   response:     200: ''  - name: WHEN get is requested MUST return green   method: GET   path: /light/get   response:     200: >         {             "currentLight": "green"         }

Первый тест задает новое значения для сигнала светофора, а второй проверяет состояние, чтобы убедиться, что оно поменялось.

Запустим тесты все той же командой:

docker run -it -v $(pwd)/tests:/tests lamoda/gonkey -tests tests/cases -host host.docker.internal:8080

Результат:

Failed tests: 0/3

Успешный результат, но нам повезло, что сценарии выполнились в нужном нам порядке: сначала light_get, а потом light_set. Что было бы, если бы они выполнились наоборот? Давайте переименуем:

mv tests/cases/light_set.yaml tests/cases/_light_set.yaml

И запустим заново:

Errors:  1) at path $.currentLight values do not match:      expected: red        actual: green  Failed tests: 1/3

Сначала выполнился set и оставил светофор в состоянии зеленого, поэтому запущенный следом тест get обнаружил ошибку — он ждал красный.

Одним из способов избавится от того, что тест зависит от контекста — это в начале сценария (то есть в начале файла) проинициализировать сервис, что мы в общем-то и делаем в тесте set — сначала задаем известное значение, которое должно произвести известный эффект, а потом проверяем, что эффект возымел действие.

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

Пока же я предлагаю следующее решение. Так как в сценарии set мы фактически тестируем и метод light/set, и light/get, то сценарий light_get, который зависим от контекста, нам попросту не нужен. Я его удаляю, а оставшийся сценарий переименовываю, чтобы название отражало суть.

rm tests/cases/light_get.yaml mv tests/cases/_light_set.yaml tests/cases/light_set_get.yaml

Следующим шагом я хотел бы проверить некоторые негативные сценарии работы с нашим сервисом, например, корректно ли он отработает, если отправить некорректный цвет сигнала? Или не отправить цвет вовсе?

Создам новый сценарий tests/cases/light_set_get_negative.yaml:

- name: WHEN set is requested MUST return no response   method: POST   path: /light/set   request: >     {         "currentLight": "green"     }   response:     200: ''  - name: WHEN incorrect color is passed MUST return error   method: POST   path: /light/set   request: >     {         "currentLight": "blue"     }   response:     400: >         incorrect current light: blue  - name: WHEN color is missing MUST return error   method: POST   path: /light/set   request: >     {}   response:     400: >         incorrect current light:   - name: WHEN get is requested MUST have color untouched   method: GET   path: /light/get   response:     200: >         {             "currentLight": "green"         }

Он проверяет, что:

• когда передан неверный цвет, возникает ошибка;
• когда цвет не передали, возникает ошибка;
• передача неверного цвета не меняет внутреннее состояние светофора.

Запустим:

Failed tests: 0/6

Все отлично 🙂

Подключаем Gonkey как библиотеку

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

Но для наших собственных приложений, написанных на go, есть более удобный способ запускать gonkey — подключить его к проекту как библиотеку. Это позволит, не компилируя ничего заранее — ни gonkey, ни сам проект — прогонять тест простым запуском go test.

При таком подходе мы как будто начинаем писать юнит-тест, а в теле теста делаем следующее:

• инициализируем веб-сервер точно так же, как это делается при запуске сервиса;
• запускаем тестовый сервер приложения на localhost и случайном порту;
• вызываем функцию из библиотеки gonkey, передавая ей адрес тестового сервера и другие параметры. Ниже я это проиллюстрирую.

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

Я выношу следующий код в отдельную функцию:

func initServer() {     // метод для получения текущего состояния светофора     http.HandleFunc("/light/get", func(w http.ResponseWriter, r *http.Request) {         // без изменений     })      // метод для установки нового состояния светофора     http.HandleFunc("/light/set", func(w http.ResponseWriter, r *http.Request) {         // без изменений     }) }

Функция main тогда будет такой:

func main() {     initServer()      // запуск сервера (блокирующий)     log.Fatal(http.ListenAndServe(":8080", nil)) }

Измененный файл main go полностью.

Это развязало нам руки, поэтому приступим к написанию теста. Я создаю файл func_test.go:

func Test_API(t *testing.T) {     initServer()      srv := httptest.NewServer(nil)      runner.RunWithTesting(t, &runner.RunWithTestingParams{         Server:   srv,         TestsDir: "tests/cases",     }) }

Вот файл func_test.go полностью.

Вот и все! Проверяем:

go test ./...

Результат:

ok      github.com/lamoda/gonkey/examples/traffic-lights-demo   0.018s

Тесты прошли. Если у меня будут и юнит-тесты, и тесты gonkey, они запустятся все вместе — довольно удобно.

Формируем отчет Allure

Allure — это формат отчета о тестировании для отображения результатов в наглядном и красивом виде. Gonkey умеет записывать результаты прохождения тестов в таком формате. Активировать Allure очень просто:

docker run -it -v $(pwd)/tests:/tests -w /tests lamoda/gonkey -tests cases/ -host host.docker.internal:8080 -allure

Отчет будет помещен в поддиректорию allure-results текущей рабочей директории (поэтому я указал -w /tests).

При подключении gonkey как библиотеки Allure-отчет активируется установкой дополнительной переменной окружения GONKEY_ALLURE_DIR:

GONKEY_ALLURE_DIR="tests/allure-results" go test ./…

Результаты тестов, записанные в файлы, превращаются в интерактивный отчет командами:

allure generate allure serve

Как выглядит отчет:

Заключение

В следующих статьях я подробнее остановлюсь на использовании фикстур в gonkey и на имитации ответов других сервисов с помощью моков.

Приглашаю вас попробовать gonkey в своих проектах, поучаствовать в его разработке (пул-реквесты приветствуются!) или отметить звездочкой на гитхабе, если этот проект может пригодиться вам в будущем.