Агенты > Агент тестирования > Документация Агента тестирования > Внешний доступ для агентов

Внешний доступ для агентов

Проблемы удобно смотреть глазами, но чинить их — работа программиста. Чтобы не пересказывать ему список вручную, у продукта есть отдельный вход для программ: по ключу доступа агент-программист забирает проблемы, читает доказательства, правит код и отмечает, что исправлено. Ниже — что доступно и как не выстрелить себе в ногу с ключом.

Зачем это нужно

Агент тестирования находит проблемы, но не правит сайт — это работа того, кто пишет код. Замкнутый цикл получается, когда чинить тоже умеет программа: тогда проверка сама сообщает о поломке, исправление приходит, а следующий запуск подтверждает результат. Так работают связки с агентами-программистами, например с Pastukhov Agent.

Что доступно по ключу

  • Список проблем — с отбором по проекту и статусу.
  • Карточка проблемы — всё то же, что видите вы: снимок, элемент, сообщение, история, число повторов. Снимок доступен и отдельной ссылкой.
  • Смена статуса — закрыть или открыть заново.
  • Отчёт по экрану — целиком вся история страницы: замечания, проверки, типы экранов. Удобно, когда разбираться надо не в отдельной ошибке, а в целой странице.
  • Всё остальное, что умеет интерфейс — проекты, экраны, правила, действия, тесты, запуски, расписания и разбор сборок. Отдельным семейством идёт визуальная часть: сборки, снимки, сравнения, эталоны, список «что ждёт решения», общие ссылки и чтение визуальных настроек.
  • Скрипты — список скриптов проекта со сведениями о среде исполнения, чтение одного скрипта с кодом, запись (код и запись в описи сохраняются вместе), удаление, журнал запусков с отборами и пробный запуск с переданными аргументами и данными. Удаление используемого скрипта отклоняется и перечисляет, кто на него ссылается.

Пример запроса — просто чтобы показать, что это обычный текстовый вызов, а не какое-то особое устройство:

curl -H "X-API-Key: КЛЮЧ" https://ваш-сервер/api/ext/issues?project=shop&status=open

Долгоживущие ключи

Кроме ключа из настроек сервера есть долгоживущие ключи. Такой ключ выпускают в интерфейсе, показывают один раз и подставляют в заголовок Authorization: Bearer taj_… вместо X-API-Key. Он нужен там, где ключ окружения неудобен: в сборке CI, в командной строке, у внешнего клиента модели.

Права у ключа два: «только чтение» — читать и помечать, и «чтение и запись» — ещё и менять. Отзывается мгновенно: все, кто им пользовался, сразу перестают проходить проверку. Подробности — в разделе Ключи API.

Что будет без ключа

Ключ задаётся при установке переменной окружения TEST_APP_KEY — он один на всю установку, и он же открывает дополнение Chrome. Если ключ не задан, эти адреса отвечают «не настроено» — то есть доступ просто выключен. Если ключ неверный — отказ. Вход по логину и паролю здесь не работает вообще: это разные способы доступа, и браузерная сессия для программ не годится. Так и задумано: внешний доступ существует для машин, и у него своя дверь.

Рабочий цикл

  1. Агент-программист забирает открытые проблемы проекта.
  2. По каждой смотрит доказательства: сообщение, элемент, снимок — и понимает, что сломалось.
  3. Правит код сайта и отмечает проблему закрытой.
  4. Следующий запуск проверяет то же место и подтверждает, что проблема ушла.

Если правка не помогла, проблема откроется снова сама — тут продукт и замыкает круг, и не даёт обмануть себя отчётом «исправлено».

Тесты и автоисправление

Тесты по ключу читаются и записываются так же, как через конструктор. В описании теста есть поле autoFix — это та самая галочка «автоисправление», и по умолчанию она выключена. Трогать чужие проверки без спроса нельзя, поэтому очередь починки собирается только из тестов с этой галочкой: сломалась проверка или действие — агент получит код, ошибку и снимок и вернёт исправление.

curl -X PUT -H "X-API-Key: КЛЮЧ" -H "Content-Type: application/json" \
     -d '{"title":"Дымовой тест","description":"Вход и проверка главной",
          "autoFix":true,
          "steps":[{"kind":"navigate","url":"https://ваш-сайт/login"},
                   {"kind":"rules","types":["login"]}]}' \
     https://ваш-сервер/api/ext/projects/shop/tests/smoke

А прямая просьба «починить вот это правило» или «починить это действие» работает независимо от галочки: она адресована конкретной поломке, а не очереди. Пределы по частоте при этом общие, и обойти их нельзя.

Скрипты по ключу

Скрипт — это файл с кодом на Python, которым проект дописывают под себя (подробности — на странице Скрипты и расширение). По ключу доступно то же, что и руками во вкладке «Скрипты»: посмотреть состав, прочитать и записать код, удалить, посмотреть журнал запусков и запустить скрипт пробно.

Если выполнение скриптов выключено — общим выключателем сервера TEST_APP_SCRIPTS_ENABLED или выключателем проекта, — запуск не пройдёт: попытка попадёт в журнал с причиной «выполнение отключено».

Список скриптов проекта отдаётся вместе с состоянием среды исполнения: есть ли Python, готово ли окружение, какая была последняя ошибка установки, сколько запусков и сбоев за сутки.

curl -H "X-API-Key: КЛЮЧ" https://ваш-сервер/api/ext/projects/shop/scripts

Запись скрипта идёт одним запросом: заголовок, заметка «зачем нужен», свой таймаут, переменные и код. Код и запись в описи сохраняются вместе. Значения с «секретными» именами читаются замаскированными; чтобы оставить уже сохранённое значение, отправьте маску обратно.

curl -X PUT -H "X-API-Key: КЛЮЧ" -H "Content-Type: application/json" \
     -d '{"title":"Проверка /health","notes":"Следит за договором адреса /health",
          "timeoutSec":30,"env":{"API_TOKEN":"$МОЙ_КЛЮЧ"},
          "code":"import json, sys\ndata = json.load(sys.stdin)\nprint(json.dumps({\"ok\": True}))"}' \
     https://ваш-сервер/api/ext/projects/shop/scripts/check-api-health

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

curl -X DELETE -H "X-API-Key: КЛЮЧ" https://ваш-сервер/api/ext/projects/shop/scripts/check-api-health

Журнал запусков читается с отборами по статусу, точке подключения и времени; свежие записи — сверху.

curl -H "X-API-Key: КЛЮЧ" "https://ваш-сервер/api/ext/projects/shop/scripts/check-api-health/runs?status=error&pageSize=50"

Пробный запуск выполняется сразу, с переданными аргументами и данными. Удачный запуск возвращает запись журнала и то, что скрипт напечатал; неудачный отвечает ошибкой с видом сбоя и номером записи в журнале.

curl -X POST -H "X-API-Key: КЛЮЧ" -H "Content-Type: application/json" \
     -d '{"args":{"min":5},"payload":{"url":"https://api.example.com/health"}}' \
     https://ваш-сервер/api/ext/projects/shop/scripts/check-api-health/test

Встроенное руководство по адресу GET /api/ext тоже содержит раздел про скрипты: там договор запуска, переменные, ограничения и виды сбоев. Правило «машинное одобрение невозможно» действует и здесь: ответ скрипта никогда не одобряет эталон.

Ключ — как пароль

Ключ доступа можно посмотреть и скопировать в разделе Настройки → Тестирование UI — он же используется дополнением Chrome. Относитесь к нему как к паролю: он даёт доступ к списку проблем и к снимкам страниц. Выдавайте его только тем, кто действительно должен видеть эти данные, и не выкладывайте в общедоступные места.

И одно честное ограничение: одобрить эталон через внешний доступ нельзя. Ни один ключ, с любыми правами, не может принять визуальное отличие — решение всегда остаётся за человеком в браузере. Так сделано нарочно: одобрение меняет то, с чем сравниваются все будущие сборки.

По тому же ключу работают и MCP-инструменты: их девять, и они закрывают визуальный цикл — запустить сборку, получить список «что ждёт решения», посмотреть отличие, сравнить заново, предложить решение по группе, запустить починку теста, опубликовать доказательства, получить справку. Одобрить эталон инструменты тоже не могут. Как это устроено — в разделе Живая страница и MCP.

А для сборки CI есть готовый инструмент командной строки viz: он запускает сборку и ждёт результат, отвечая кодом выхода 0 — успех, 7 — требуется решение человека, 8 — провал. Он ничего не одобряет: команды «одобрить» в нём просто нет. Подробности — в разделе CI и уведомления.

Дальше: как агент чинит сломавшиеся проверки сам — в разделе Автоисправление.

← Оглавление документации