Все мы любим ничего не делать работать с хорошо документированным API. С помощью стандартов API Blueprint или Swagger можно получить читаемую машиной и человеком документацию, а значит и инструменты проверки API на основе этой документации. Apiary предлагает интерактивные инструменты для проверки API вручную, подставляя нужные параметры в формы, генерируемые на основе документации. Но можно извлечь гораздо больше пользы, если API будет проверяться автоматически. Это избавляет от необходимости писать отдельные тесты на каждый интерфейс, но накладывает определенные ограничения на структуру и качество самой документации.  В этом tutorial поговорим о утилите Dredd на примере API от GitHub.  Я предполагаю, что у вас уже локально установлен Vagrant и Git. Я работаю в MacOS, все команды ниже выполнялись в ней. Подготовим необходимые аккаунты и разрешения. Зарегистрируйтесь и создайте новый проект в сервисе Apiary.  В созданном проекте откройте вкладку Tests > Tutorial. Здесь вам нужно записать значения переменных apiaryApiName и apiaryApiKey, которые пригодятся далее.  В настройках GitHub создайте токен для доступа к API со следующими разрешениями (scopes): gist, user:email. Подробнее про доступные разрешения можно почитать в документации к API GitHub. Не забудьте скопировать токен. Он виден только один раз.  Создадим рабочий каталог. mkdir ~/dredd_test && cd ~/dredd_test && git init Подготовим виртуальное окружение, чтобы не засорять свою ОС, а также чтобы задокументировать каждый сделанный шаг. 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, чтобы не запоминать команды вызова. Итак, у нас готово виртуальное окружение. Настал черёд подготовить документацию к 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-го,… уровней могут использоваться вариативно. Для анализаторов важно то, что вы укажете в квадратных скобках, например . Этот текст будет использован для составления интерактивных форм, например в Apiary:  После такой конструкции анализатор разметки будет ожидать детали ожидаемого запроса и ответа на данном интерфейсе. Для этого используем конструкции + Request ПроизвольноеНазвание (ожидаемый формат запроса) и + Response http-status-code (ожидаемый формат ответа) Далее следуют вложенные уровни: Таким образом, в приведённом примере показаны два различных способах описания структур данных в теле запросов и ответов: «навороченная» Schema и упрощенные Parameters и Attributes. После того, как мы сохранили документ, его можно проверить в Apiary и Github на предмет читаемости и адекватности использования в ручном режиме. Этот шаг необязателен, но здесь он присутствует для более комплексного подхода, когда тестирование является неотъемлемой частью самого проекта. В файл исключений 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 поместим описание проекта: Здесь стоит обратить внимание на следующие моменты: Теперь создадим два файла конфигурации — для 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 и запустит все интерфейсы один за другим. Но этого недостаточно. В документации мы выполняем следующие операции: Для первых двух случаев все хорошо "из коробки", однако для получения и удаления конкретного Gist нужно передавать идентификатор созданного ресурса в следующие запросы. Для этого нам пригодятся Dredd hooks. Откроем файл hooks/github-api.php и добавим туда следующий код: Теперь у нас готово практически всё, но для полноты картины добавим ещё один шаг. В файл исключений 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. https://app.apiary.io/githubtest5/tests/run/625c2477-7384-48fa-8bb9-25e27af2a908
 Если вместо этого вы видите какие-то ошибки, возможно 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'  Правки, дополнения и замечания приветствуются.
Вы можете найти весь исходный код в репозитории. User