API-тесты в Jenkins, GitLab CI и командной строке

Как это устроено

Схема из трёх частей: запросы выполняются на вашем агенте сборки. Для онлайн-входа раннеру нужен доступ к серверу лицензий Checkcraft:

1. Набор проверок. В приложении есть панель CI/CD: отмечаете галочками нужные проверки и получаете один JSON-файл. В нём запросы, тест-кейсы, переменные коллекций, папок и проверок, настройки поиска логов — всё, что нужно для повторяемого прогона.
2. Консольный раннер. Рядом с приложением ставится checkcraft-cli — на Linux это bin/checkcraft-cli в распакованном архиве, на Windows checkcraft-cli.exe рядом с программой. Он читает набор, выполняет запросы и правила и пишет отчёты. Интерфейс ему не нужен, поэтому он работает на агенте без графической среды.
3. Отчёт для сборки. На выходе JUnit XML, который умеют читать Jenkins, GitLab, GitHub Actions и TeamCity, плюс JSON для своих дашбордов. Сборка падает по коду выхода, а не по разбору логов.

Полный пример для GitLab CI

Ниже весь путь целиком, от кнопки в приложении до вкладки Tests в GitLab. Займёт минут десять, писать код не нужно нигде.

Шаг 1: выгрузить набор из приложения

Кнопка CI/CD в верхней панели открывает окно «Интеграция с CI/CD». Слева дерево коллекций, папок и проверок с галочками, справа — настройки. Отметьте нужные проверки, в поле «Система сборки» выберите «GitLab CI», при необходимости укажите окружение, и нажмите «Сохранить набор…». Получится один файл, по умолчанию checks.ccbundle.json.

Положите его в репозиторий по тому пути, который указан в поле «Путь к набору в репозитории» — по умолчанию checkcraft/checks.ccbundle.json. Файл текстовый и нормально показывается в диффе: видно, какую проверку изменили в этом коммите.

Шаг 2: поставить раннер на агент

Проверки в пайплайне выполняет checkcraft-cli — та же программа без интерфейса. Взять его можно двумя способами.

• Из архива для Linux. Распакуйте Checkcraft-Portable-Linux.tgz на агенте, например в /opt/checkcraft. Рядом с обычным запуском CheckCraft/bin/Checkcraft в той же папке bin лежит checkcraft-cli. Внутри архива своя Java, ставить её отдельно не нужно.
• В образе контейнера. Тот же архив распаковывается на этапе сборки образа, которым пользуется раннер. Так путь до раннера не зависит от конкретной машины.

Проверить, что всё на месте, можно одной командой на агенте: /opt/checkcraft/bin/checkcraft-cli --help. Она печатает список ключей и завершается кодом 0.

Шаг 3: задать переменные в проекте

В актуальном приложении откройте CI/CD → Доступ раннера, задайте имя и срок, нажмите «Создать токен» и затем «Скопировать токен». Секрет показывается только при создании; потерянный токен нужно отозвать и выпустить заново.

В GitLab откройте Settings → CI/CD → Variables. Секреты добавляйте как masked; ограничьте их доступ нужными ветками и окружениями проекта:

• CHECKCRAFT_CI_TOKEN — созданный токен раннера. Это рекомендуемый способ входа; пароль аккаунта в CI при этом не нужен. Значение хранится только в секретах CI, не в YAML и не в наборе.
• CHECKCRAFT_DEVICE_ID — постоянный идентификатор агента, особенно полезный для временных машин: от 16 до 128 символов из букв, цифр и ._:-, например gitlab-runner-stage-01. Это идентификатор, а не секрет и не замена токена.
• CHECKCRAFT_VAR_ИМЯ — значения переменных самого набора. Их имена панель CI/CD показывает строкой «Задайте на агенте значения: …» — там перечислено ровно то, что нужно этому набору.

Вход создаёт отдельную CI-сессию: запуск и завершение раннера не завершают сессию открытого приложения. Используйте согласованные актуальные версии раннера и сервера. Доступ можно отозвать кнопкой «Отозвать выбранный» в окне «Доступ раннера».

Совместимость со старыми настройками: CHECKCRAFT_USER и CHECKCRAFT_PASSWORD оставлены как legacy-вход, если токен не задан. Для нового пайплайна используйте CHECKCRAFT_CI_TOKEN; ошибочный или отозванный токен не заменяется входом по паролю.

Шаг 4: добавить задачу в .gitlab-ci.yml

Этот кусок панель формирует сама, кнопка «Скопировать сниппет». Перед запуском сверьте путь раннера и набор переменных на своём агенте.

checkcraft:
  stage: test
  script:
    - /opt/checkcraft/bin/checkcraft-cli --bundle checkcraft/checks.ccbundle.json --report-junit checkcraft/report-junit.xml --report-json checkcraft/report.json --report-html checkcraft/report.html
  artifacts:
    when: always
    paths:
      - checkcraft/report.json
      - checkcraft/report.html
    reports:
      junit: checkcraft/report-junit.xml

when: always здесь принципиально: отчёт нужен именно тогда, когда задача упала. Без него GitLab выбросит артефакты при неуспешном прогоне, и разбираться придётся по консоли.

Шаг 5: что появится в GitLab после прогона

Во вкладке Tests у пайплайна каждое правило станет отдельным тестом с текстом расхождения: видно, какое поле не сошлось и что ожидалось. В артефактах будет report.html — тот же наглядный отчёт, что и в приложении, одним файлом; его можно открыть прямо из GitLab и приложить к задаче. report.json остаётся для своих дашбордов.

Для Jenkins и GitHub Actions

В Jenkins сохраните токен как Secret text с идентификатором checkcraft-ci-token. Для этого типа секрета используйте:

stage('API-проверки') {
  steps {
    withCredentials([string(credentialsId: 'checkcraft-ci-token',
                     variable: 'CHECKCRAFT_CI_TOKEN')]) {
      sh '/opt/checkcraft/bin/checkcraft-cli --bundle checkcraft/checks.ccbundle.json \
          --report-junit checkcraft/report-junit.xml --report-json checkcraft/report.json'
    }
  }
}
post { always { junit 'checkcraft/report-junit.xml' } }

Для GitHub Actions добавьте CHECKCRAFT_CI_TOKEN в Actions secrets и передайте его в env шага как CHECKCRAFT_CI_TOKEN: ${{ secrets.CHECKCRAFT_CI_TOKEN }}. Остальные переменные набора задаются отдельно. Отдельный плагин Checkcraft не нужен.

Понять результат без чтения консоли

Раннер возвращает коды выхода, по которым сборка отличает разные ситуации:

• 0 — все проверки прошли;
• 1 — есть расхождения: непройденные правила или сорванные запросы;
• 2 — проблема с аргументами, файлом набора или не заданы переменные;
• 3 — не подтверждён доступ к приложению;
• 4 — внутренняя ошибка;
• 5 — на этой машине уже идёт другой прогон.

Если задача упала не на проверках

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

• Код 2 и строка про переменные. Набору нужны значения, которых нет на агенте. Имена перечислены в самом сообщении и в панели CI/CD; добавьте их в Variables с префиксом CHECKCRAFT_VAR_.
• Код 3 при входе по токену. Проверьте наличие секрета на этой ветке, срок действия и отзыв токена, действительность лицензии и доступность сервера. Код из письма для CI-токена не требуется; при ограничении числа одновременных раннеров выполняйте задачи последовательно.
• Код 3 и просьба ввести код из письма при legacy-входе. Агент выглядит новой машиной. Задайте постоянный CHECKCRAFT_DEVICE_ID, а первый вход подтвердите разово ключом --login-code с кодом из письма. Не сохраняйте одноразовый код в пайплайне; затем перейдите на CI-токен.
• Код 5. Две задачи запустились на одном агенте одновременно. Прогон на машину допускается один, поэтому такие задачи ставятся последовательно.
• Долгий прогон из-за журналов. Если с агента нет доступа к Kibana, добавьте --skip-logs: останутся только HTTP-проверки.

Разделение важное: сломанный пайплайн и найденный дефект — разные события, и на дашборде они не должны выглядеть одинаково. В JUnit-отчёте каждая проверка становится набором тестов, а каждое правило — отдельным тестом с текстом расхождения, поэтому на странице сборки сразу видно, что именно не совпало.

Что попадает под проверку в пайплайне

Раннер выполняет те же правила, что и приложение: статусы и заголовки, поля JSON и XML, размеры массивов, белые списки полей, вычисляемые выражения и сравнения сумм. Если у проверки настроен поиск логов, раннер берёт идентификатор трассировки из ответа, подтягивает записи и сверяет их с телом ответа — то есть в сборку уезжает не только «ответ 200», но и «в журнале списана та же сумма».

Полезные ключи для пайплайна: --filter запускает только проверки с подходящим именем (удобно для быстрого смоука на каждый коммит), --stop-on-failure обрывает прогон на первом падении, --skip-logs оставляет только HTTP, когда журналы недоступны из сети агента, а --var ИМЯ=значение подменяет адреса и учётные данные под конкретный стенд.

Сценарий из нескольких запросов подряд

Один запрос закрывает не всё: платёж создают, ждут обработки и только потом читают статус. Для этого у проверки есть последовательность запросов — кнопка «Последовательность…» на вкладке прогона. В таблице шагов выбираются запрос, вариант тела и те тест-кейсы, которые нужны именно этому шагу, а в колонке паузы задаётся задержка перед отправкой: например, второй запрос через 30 секунд, третий — через минуту. Значения, извлечённые предыдущим шагом, подставляются в следующие, поэтому идентификатор из ответа на создание сам попадает в запрос статуса.

Отчёт по прогону показывает запросы списком: где проверки прошли, где нет и на каком шаге всё остановилось. Клик по запросу открывает его тест-кейсы и подробный разбор шагов правил, так что искать причину падения по общему логу не нужно.

Та же настройка уезжает в сборку: в панели CI/CD для каждой проверки с последовательностями выбирается, что запускать — один основной запрос или конкретную последовательность. В JUnit-отчёте тесты подписаны номером и именем шага, а в JSON-отчёте у проверки появляется список шагов с кодами ответов, паузами и причиной обрыва.