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


image


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


Как родился 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

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


Заключение


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


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

Комментарии (12)


  1. shrimpsizemoose
    21.08.2019 18:05

    На go есть инструмент [hoverfly](https://hoverfly.readthedocs.io/), который регулярно советуют использовать для тестирования API в микросервисных архитектурах. А как он в сравнении с gonkey, они в принципе аналог друг друга или как?


    1. livinbelievin Автор
      21.08.2019 21:25

      Спасибо за ссылку, посмотрю и постараюсь сравнить.


    1. livinbelievin Автор
      22.08.2019 11:12
      +1

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

      Gonkey, в отличие от goverfly, ставит перед собой цель тестировать сам сервис, то есть имитировать клиентскую нагрузку на него. А чтобы заменять ответы внешних сервисов, в gonkey есть моки.


  1. Vadem
    21.08.2019 18:59

    Интересный инструмент. Спасибо.
    Но почему README на русском?


    1. livinbelievin Автор
      21.08.2019 21:24

      Так проще было мысли изложить. Перевод в планах :)


    1. baskins
      21.08.2019 21:53

      Видимо потому что issue №1 не закрыто еще


  1. time2rfc
    21.08.2019 20:22

    Спасибо огромное! очень жду примера с работой с бд


  1. DmitriyTitov
    22.08.2019 06:09

    Что-то у вас странное написано в самом же начале.

    // структура для хранения состояния светофора
    type trafficLights struct {
        currentLight string       `json:"currentLight"`
        mutex        sync.RWMutex `json:"-"`
    }
    
    // экземпляр светофора
    var lights = trafficLights{
        currentLight: lightRed,
    }


    и потом внезапно:

            resp, err := json.Marshal(lights)
            if err != nil {
                log.Fatal(err)
            }
    
            w.Write(resp)


    Я даже запустил программу у себя и естественно метод get возвращает пустой объект, а VSCode справедливо подчёркивает ваши поля структур, которые не экспортируются.
    Короче ваш пример не может работать в принципе, но он выложен на Github.
    Дальше не читал.


    1. livinbelievin Автор
      22.08.2019 09:27

      А, так он специально с ошибкой. Там же ниже он тестируется и косяки исправляются.

      (но, признаюсь, я действительно сделал эту ошибку, когда писал этот демо-код)


      1. DmitriyTitov
        22.08.2019 12:17
        +1

        Ну ОК, если вы такие синтаксические по факту ошибки тестируете внешними средствами — дело ваше. На мой взгляд это просто ошибка и проверять внешними средствами тут нечего. Тут рулят внутренние автотесты. IDE ошибку подсвечивает, unit-тест ошибку подтверждает. Что ещё надо?
        Странный пример.


  1. Urgen
    22.08.2019 13:18

    чем Apache Jmeter не подошёл?


    1. anjensan
      23.08.2019 10:51
      +1

      Простите, конечно, но вы сравниваете несравнимые вещи: Jmeter не на Go, и там нету Yaml!