Тестирование документированного API с помощью утилиты Dredd от Apiary

Все мы любим ничего не делать работать с хорошо документированным API. С помощью стандартов API Blueprint или Swagger можно получить читаемую машиной и человеком документацию, а значит и инструменты проверки API на основе этой документации.

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

В этом tutorial поговорим о утилите Dredd на примере API от GitHub.

Bootstrap

Я предполагаю, что у вас уже локально установлен Vagrant и Git. Я работаю в MacOS, все команды ниже выполнялись в ней.

Подготовим необходимые аккаунты и разрешения.

Зарегистрируйтесь и создайте новый проект в сервисе Apiary.

В созданном проекте откройте вкладку Tests > Tutorial. Здесь вам нужно записать значения переменных apiaryApiName и apiaryApiKey , которые пригодятся далее.

В настройках GitHub создайте токен для доступа к API со следующими разрешениями (scopes): gist, user:email. Подробнее про доступные разрешения можно почитать в документации к API GitHub.

Не забудьте скопировать токен. Он виден только один раз.

Создадим рабочий каталог.

/dredd_test && git init

Virtual environment

Подготовим виртуальное окружение, чтобы не засорять свою ОС, а также чтобы задокументировать каждый сделанный шаг.

mkdir vagrant && touch vagrant/Vagrantfile && git add vagrant/

В корневом каталоге создадим файл .gitignore и добавим туда исключения:

echo 'vagrant/.vagrant' >> .gitignore && git add .gitignore

Отредактируем vagrant/Vagrantfile , добавим туда конфигурацию следующего содержания:

Теперь нужно подготовить файл с набором инструкций для подготовки виртуальной машины.

touch vagrant/provision.sh && git add vagrant/provision.sh

Поместим в него текст:

Как можно заметить, кроме желаемого Dredd, также будет установлен менеджер зависимостей PHP Composer. PHP нам пригодится в качестве примера для написания хуков при тестировании API. Вы можете воспользоваться и другими языками для этого, например тем же NodeJs, чтобы не плодить "зоопарк" технологий. Поскольку мой основной язык PHP, я покажу ниже как интегрировать dredd в Composer, чтобы не запоминать команды вызова.

Итак, у нас готово виртуальное окружение.

Blueprint for GitHub API

Настал черёд подготовить документацию к API. В качестве подопытной зверушки использовались следующие интерфейсы:

Dredd поддерживает два вида документации: API Blueprint и Swagger. Воспользуемся первым из них, так как этот стандарт базируется на Markdown-разметке и вы можете читать документацию к API в любимом git-сервисе: Gitlab, Github, Bitbucket etc. Кроме того, поддержка Swagger заявлена пока в beta-режиме.

В корне проекта создадим файл touch github-api.md && git add github-api.md и поместим в него документацию. Описывать в деталях каждую строчку я не стану, но сделаю некоторые пояснения к структуре данного ниже листинга.

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

Заголовки 1-го, 2-го,… уровней могут использоваться вариативно. Для анализаторов важно то, что вы укажете в квадратных скобках, например [GET /users/technoweenie] . Этот текст будет использован для составления интерактивных форм, например в Apiary:

После такой конструкции анализатор разметки будет ожидать детали ожидаемого запроса и ответа на данном интерфейсе. Для этого используем конструкции + Request ПроизвольноеНазвание (ожидаемый формат запроса) и + Response http-status-code (ожидаемый формат ответа)

Далее следуют вложенные уровни:

• Headers — Примеры заголовков и их значений, которые могут приниматься или возвращаться.
• Body — Пример тела запроса или ответа прежде всего для людей, которые будут читать документацию. Здесь вы можете приводить полный copy-n-paste из реального API, убирая лишь чувствительные данные. Для автоматизированного тестирования правильнее использовать Schema или Attributes.
• Schema — Этот раздел уже важен для автоматического анализа и для автотестирования, но также может пригодиться для разработчиков. И Blueprint, и Swagger используют стандарт json-schema.org для описания типов данных.
• Parameters — Это альтернативный, упрощенный способ описания полей, если вам хочется просто быстро набросать простые примеры.
• Attributes — На этом уровне Blueprint позволяет сослаться на уже составленную ранее общую структуру. В нашем примере это структура Gist и она описана в конце документа в виде вложенного уровня к заголовку Data Structures .

Таким образом, в приведённом примере показаны два различных способах описания структур данных в теле запросов и ответов: «навороченная» Schema и упрощенные Parameters и Attributes.

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

Подготовка проекта composer

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

В файл исключений git добавим новую строчку: echo 'vendor/' >> .gitignore

Создадим файл composer.json , а также папку для Dredd hooks с файлом будущих хуков внутри.

mkdir hooks && touch composer.json composer.lock hooks/github-api.php && echo '' > composer.lock && git add composer.* hooks/github-api.php

В файл composer.json поместим описание проекта:

Здесь стоит обратить внимание на следующие моменты:

• В зависимостях уровня dev (посколько в production мы врядли будем запускать эти тесты) добавлен пакет ddelnano/dredd-hooks-php . Это часть проекта Dredd позволит нам перехватывать различные этапы выполнения тестов и манипулировать данными, чтобы, к примеру, передавать некий контекст выполнения между разными тестами (данные, полученные в одном тесте передавать в другой тест).
• В разделе scripts добавлены две операции: test и test-mock , обе из которых будут выполнены при вызове команды composer check
• Ниже приведены команды консольного запуска. Таким образом мы получаем упрощенный вызов этих обеих команд, заворачивая их в composer check , в котором у нас также могут вызываться юнит-тесты, проверка качества кода и так далее.
• Команды консольного запуска будут вызывать утилиту dredd и передавать ей заголовок, который будет добавлен во все API. В него будет подставляться значение переменной окружения GITHUB_API_TOKEN, благодаря чему нам не нужно коммитить её значение в сам код, а хранить её где-нибудь в защищенном месте.
• Два отдельных вызова dredd используют разные конфигурационные файлы. Правильнее было бы просто подменять некоторые параметры из этих файлов, но мир такой не идеальный. Одна из конфигураций обратиться напрямую на github. Вторая будет вызывать заглушку (мы напишем её ниже), которая например может являться вашим прототипом API ещё до того, как backend developers его имплементировали на практике. И вы сможете играть в TDD.

Конфигурируем dredd

Теперь создадим два файла конфигурации — для production и для макета API.

touch dredd.yml dredd-local.yml && git add dredd.yml dredd-local.yml

В первый файл dredd.yml запишем следующие параметры, назначение которых можно почитать в документаци:

В файл dredd-local.yml нужно поместить тот же самый текст, но в конце заменить параметр endpoint и добавить дополнительный параметр server , вот так:

В таком варианте Dredd изучит содержимое файла github-api.md и запустит все интерфейсы один за другим. Но этого недостаточно. В документации мы выполняем следующие операции:

• GET для Users Collection
• GET для списка Gists
• POST, GET и DELETE для отдельного Gist.

Для первых двух случаев все хорошо "из коробки", однако для получения и удаления конкретного Gist нужно передавать идентификатор созданного ресурса в следующие запросы. Для этого нам пригодятся Dredd hooks.

Откроем файл hooks/github-api.php и добавим туда следующий код:

Теперь у нас готово практически всё, но для полноты картины добавим ещё один шаг.

Подготовка прототипа API с помощью Express JS

В файл исключений git добавим новую строчку: echo 'node_modules/' >> .gitignore

Создадим файл будущего «сервера API»: touch app.js && git add app.js

В этот файл добавим следующее содержание, которое будет просто симулировать поведение github. Я не буду останавливаться на деталях.

Также в корень добавим файл с описанием проекта nodejs, чтобы можно было вызывать установку пакетов отдельно от виртуального окружения:

touch package.json && git add package.json

Добавим достаточно очевидное содержимое:

(Впрочем, стоит упомянуть, что без флага "private": true, npm начнёт проверять package.js на предмет соответствия требованиям и упадёт с великолепной ошибкой npm ERR! code 1. Хорошо, хоть перед ней следует WARN, который оказывается фатальной ошибкой.)

Запуск тестов

После выполнения вы должны увидеть в конце примерно такой «выхлоп»:

Как можно видеть выше, успешно завершились два вида тестов: сначала на локальном прототипе, затем на полноценном production. При этом на gist.github.com был создан, загружен и удалён один документ.

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

Если вместо этого вы видите какие-то ошибки, возможно provision.sh не смог установить какие-то пакеты (чаще всего бывают проблемы с npm, ему иногда не хватает памяти). Зайдите в vagrant ssh , перейдите под sudo и проверьте, доступны ли команды dredd и express. Если нет — повторите их установку вручную. Альтернативно, можно попробовать перезапустить provision-скрипт вот так (provision вместо up в конце): DREDD_GITHUB_TEST_PATH=

/dredd_test GITHUB_API_TOKEN=<your-token> APIARY_API_KEY=<your-key> APIARY_API_NAME=<your-project-name> vagrant provision

После первого запуска можно заходить внутрь vagrant ssh , затем переходить к проекту и тестировать его cd /var/dredd_test && composer check .

Осталось закоммитить результат и переработать под собственные цели.

git add . && git commit -m 'Dredd testing project initial state'

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