Установка Агента тестирования

Не хотите читать всё это?

Просто скиньте в любой ИИ-чат (Claude, ChatGPT и т.д.) ссылку на https://pastukhov.com/agents/test/install.md или на https://pastukhov.com/llms.txt и попросите сгенерировать конфигурационные файлы и команды. Он прочитает документацию, задаст несколько вопросов о вашей настройке и выдаст готовую конфигурацию. Экономьте время — пусть модель читает за вас.

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

Агент тестирования — программа, которая проверяет ваш сайт, приложение или внутреннюю систему. Живёт она на вашем сервере и разворачивается одним контейнером Docker, а постоянные данные лежат в томе /apps/test. Отдельную базу ставить не нужно: встроенная работает сразу, а PostgreSQL подключается по желанию. Прогоны и снимки визуальных сборок выполняет встроенный исполнитель прямо в контейнере — держать рядом отдельный компьютер с Chrome для этого не нужно. Chrome с дополнением остаётся для ручной съёмки экранов, записей действий и прогонов в живом окне.

Что понадобится

Сервер или компьютер с Docker — подойдёт Windows, Linux или macOS, а для постоянной работы достаточно недорогого сервера.
Около 2 ГБ памяти и постоянное хранилище под данные (том): без него всё пропадёт при первом же пересоздании контейнера. В простое продукт не тратит процессор и возвращает занятую память, поэтому держать сервер «про запас» большим не нужно. Снимки визуальных сборок и эталоны тоже хранятся в базе, поэтому место стоит закладывать с запасом.
По желанию — Chrome с нашим дополнением. Для прогонов по расписанию и снимков визуальных сборок он не нужен: страницы открывает встроенный исполнитель в контейнере, и отдельный компьютер держать включённым не приходится. Дополнение пригодится, только если хотите снимать экраны вручную, записывать действия или смотреть, как тест идёт в живом окне. Подробнее — в разделе Встроенный исполнитель.
По желанию — адрес и ключ вашего Pastukhov Agent: без него всё работает, кроме разбора замечаний, создания действий и автоисправления (подробнее об этом — ниже).

Установка в один контейнер

Создайте файл compose.yml с таким содержимым:

services:
  test-agent-ru:
    image: maxpastukhov/test-agent:min-latest
    container_name: test-agent-ru
    ports:
      - "3979:80"
    volumes:
      - test-agent-data-ru:/apps/test
      - test-agent-config-ru:/project/apps/tests
    environment:
      - ASPNETCORE_ENVIRONMENT=Production
      - ASPNETCORE_URLS=http://+:80
      - TEST_APP_BRAND=pastukhov
      - TEST_APP_DATA=/apps/test
      - TEST_APP_PROJECTS_FOLDER=/project/apps/tests
      # TEST_APP_BASE_PATH=/tests  # serve from a first-level subfolder (see ../subfolder-hosting.md)
      # Runtime memory posture overrides — the image ships the minimal idle floor (see the
      # Dockerfile ENV block / dev/configuration.md); uncomment to opt a busy box back into
      # Server GC (compose wins over the image):
      # DOTNET_gcServer=1
    restart: unless-stopped
    sysctls:
      fs.inotify.max_user_watches: "524288"
      fs.inotify.max_user_instances: "512"

volumes:
  test-agent-data-ru:
  test-agent-config-ru:

Затем запустите:

docker compose up -d

После запуска интерфейс будет доступен на порту 3979: http://<адрес-сервера>:3979. Строка TEST_APP_BRAND=pastukhov включает русский язык и оформление бренда, а две строки sysctls повышают системные лимиты отслеживания изменений файлов — без них часть правок в папке проекта может не подхватываться на ходу.

В этом файле объявлены два постоянных тома. Первый — данные (/apps/test): база, лицензия, ключи, журналы и индекс поиска по всему приложению. Второй — настройки проектов (/project/apps/tests): правила, действия, тесты и знания проектов. Оба переживают пересоздание контейнера, и именно второй том делает проекты обычными файлами: папку можно целиком положить в git (хранилище версий файлов) и перенести на другой сервер простым копированием.

Запуск без Compose

Можно обойтись и одной командой docker run:

docker run -d \
  --name test-agent-ru \
  -p 3979:80 \
  -v test-agent-data-ru:/apps/test \
  -v test-agent-config-ru:/project/apps/tests \
  -e TEST_APP_BRAND=pastukhov \
  -e TEST_APP_DATA=/apps/test \
  -e TEST_APP_PROJECTS_FOLDER=/project/apps/tests \
  --sysctl fs.inotify.max_user_watches=524288 \
  --sysctl fs.inotify.max_user_instances=512 \
  --restart unless-stopped \
  maxpastukhov/test-agent:min-latest

Остальные переменные окружения удобно передать файлом через флаг --env-file .env — так их проще менять, не переписывая длинную команду. Внутри контейнера продукт и сам подхватывает файл /project/.env (переменная TEST_APP_ENV_FILE указывает другое место), причём следит за его изменениями — перезапуск для новых значений не нужен.

Основные переменные окружения

Настройки задаются переменными окружения — их прописывают один раз в compose.yml и меняют без правки кода. Почти все имена начинаются с TEST_APP_; исключения — подключение к агенту (AGENT_API_URL, AGENT_API_KEY) и вход через общий прокси (SSO_PROXY_TOKEN).

Переменная	Что задаёт	По умолчанию
`TEST_APP_BRAND`	бренд и язык: `pastukhov` (русский) или `xedant` (английский)	`xedant`
`TEST_APP_DATA`	папка постоянных данных (в контейнере — `/apps/test`)	`/apps/test`
`TEST_APP_SEARCH_INDEX_FOLDER`	папка с индексом поиска по всему приложению (⌘K); если её удалить, индекс соберётся заново	`{TEST_APP_DATA}/search-index`
`TEST_APP_IDLE_TRIM_MINUTES`	через сколько минут простоя возвращать занятую память; `0` — не возвращать	`15`
`TEST_APP_KEY`	секретный ключ, который охраняет всё машинное: связь с дополнением Chrome, внешний доступ для агентов, адрес живой страницы, команды для модели и визуальные машинные адреса; без него эти адреса отвечают «не настроено», с неверным — отказ	— (не настроено)
`AGENT_API_URL`	адрес вашего Pastukhov Agent: через него работают чат, разбор замечаний, создание действий и автоисправление	— (чат скрыт)
`AGENT_API_KEY`	ключ доступа к вашему Pastukhov Agent	—
`TEST_APP_URL`	адрес этого сервера, по которому модель скачивает снимки и открывает живую страницу, а также строятся публичные ссылки и уведомления визуальных сборок; если не задан, ссылки на снимок в запросах к модели не будет, а ссылки в уведомлениях станут относительными	—
`TEST_APP_PROJECTS_FOLDER`	папка, в которой лежат проекты с правилами, действиями, скриптами и тестами	`/project/apps/tests`
`TEST_APP_SCRIPTS_ENABLED`	выключатель выполнения скриптов: значение `0` останавливает все запуски разом	включено
`TEST_APP_PYTHON`	какой интерпретатор Python использовать: от него создаётся окружение для скриптов	`python3`
`TEST_APP_RUNNER_ENABLED`	встроенный исполнитель: `0` — выключить совсем (подробнее — Встроенный исполнитель)	`1`
`TEST_APP_RUNNER_ON_DEMAND`	`1` — в простое процесса исполнителя нет, он запускается к прогону и завершается сам; `0` — постоянный исполнитель, перезапускается после простоя	`1` (в образе)
`TEST_APP_RUNNER_NAME`	имя встроенного исполнителя в списке исполнителей	`Playwright (built-in)`
`TEST_APP_RUNNER_HEADLESS`	`1` — безоконный режим (образ несёт только такую сборку браузера); `0` — оконный, нужна полная сборка	`1`
`TEST_APP_RUNNER_SANDBOX`	изоляция браузера: `0` — выключена (так нужно для работы в контейнере), `1` — включена	`0`
`TEST_APP_RUNNER_BROWSER_IDLE_SEC`	через сколько секунд без прогонов закрывать браузер и возвращать память; `0` — не закрывать	`600`
`TEST_APP_DB`	база данных: строка подключения PostgreSQL; пустое значение — встроенная SQLite	SQLite (`/apps/test/data.db`)
`TEST_APP_BASE_PATH`	размещение в подпапке первого уровня (например, `/tests`)	— (работа в корне домена)
`TEST_APP_LOGIN`	логин готового администратора; вместе с паролем создаёт пользователя при старте	— (первый зарегистрировавшийся)
`TEST_APP_PASSWORD`	строчная сумма SHA-256 пароля, не сам пароль	—
`TEST_APP_SSL`	свой самоподписанный HTTPS: `auto` — включить	— (только HTTP)
`TEST_APP_SSL_PORT`	порт для HTTPS (по умолчанию — следующий за портом HTTP)	—
`TEST_APP_SSL_DOMAINS`	имена через запятую, на которые выписывается сертификат	—
`TEST_APP_ENV_FILE`	файл с переменными: продукт читает его при старте и следит за изменениями	`/project/.env`
`TEST_APP_ERROR_REPORTING`	`0` — выключить отправку сведений об ошибках	— (адрес приёма не задан, ничего не отправляется)
`SSO_PROXY_TOKEN`	вход через общий прокси с другими продуктами на том же сервере	— (обычный вход по логину)

В TEST_APP_PASSWORD попадает не пароль, а его сумма — «отпечаток», по которому пароль не восстановить. Получить её можно командой printf '%s' 'вашпароль' | sha256sum и вставить в переменную; при входе приложение считает сумму от введённого пароля и сравнивает с заданной. Так же устроен и ключ TEST_APP_KEY — он хранится в открытом виде намеренно: интерфейс показывает его, чтобы вы могли скопировать ключ в настройки дополнения.

У этого ключа есть ограничение: он один на всю установку и не подходит, когда доступ нужен сборочному конвейеру или стороннему исполнителю. Для этого в интерфейсе выпускаются долгоживущие ключи API («Настройки → API-токены»): ключ показывается один раз и больше не восстанавливается, при работе подставляется заголовком Authorization: Bearer taj_… и бывает двух прав — «только чтение» (readonly) и «чтение и запись» (full). Любой такой ключ можно отозвать мгновенно, и, что важно, ни один из них не может одобрить эталон. Подробнее — в разделе Ключи API.

У встроенного исполнителя есть свои переменные — TEST_APP_RUNNER_ENABLED, TEST_APP_RUNNER_ON_DEMAND, TEST_APP_RUNNER_NAME, TEST_APP_RUNNER_HEADLESS, TEST_APP_RUNNER_SANDBOX и TEST_APP_RUNNER_BROWSER_IDLE_SEC: ими включают и выключают исполнителя, выбирают режим работы, задают имя в списке и распоряжаются памятью. Менять их обычно не нужно: прогоны работают сразу после установки. Подробнее — в разделе Встроенный исполнитель.

Где хранятся данные

Постоянные данные живут в томе /apps/test и переживают пересоздание контейнера:

/apps/test/data.db — база данных (когда не используется PostgreSQL);
/apps/test/auth/ — ключи, которыми подписываются сессии входа;
/apps/test/.pastukhov/ — лицензия (у бренда xedant папка называется .xedant);
/apps/test/logs/addon-errors.log — журнал ошибок дополнения Chrome, полезный при разбирательствах;
/apps/test/keys/visual-creds.key — ключ шифрования учётных данных визуальных проверок: логины и пароли стендов хранятся в базе зашифрованными (шифрование AES-256-GCM);
/apps/test/scripts/… — окружения Python и рабочие каталоги скриптов: сам код лежит в папке проекта, а всё, что нужно ему для работы, продукт держит здесь, в данных;
/apps/test/search-index/ — индекс поиска по всему приложению: переживает перезапуск и пересобирается сам, когда содержимое устарело;
папка проектов (по умолчанию /project/apps/tests) — правила, действия, скрипты, тесты и знания проекта.

Динамика — снимки экранов, запуски, проблемы и расписания, а также снимки визуальных сборок, эталоны с их версиями и опубликованные общие ссылки — живёт в базе. А вот правила, действия и тесты лежат обычными файлами в папке проекта, и это важное преимущество: папку можно целиком положить в git (хранилище версий файлов), видеть историю правок и перенести проект на другой сервер простым копированием. Комиты в git делает человек — сервер сам их не создаёт и ничего не отправляет в внешние хранилища.

Первый вход

Откройте интерфейс в браузере. Пока в базе нет ни одного пользователя, форма регистрации открыта сама — первый зарегистрировавшийся становится администратором. Если логин и пароль заданы переменными TEST_APP_LOGIN и TEST_APP_PASSWORD, входите под ними (в переменной хранится сумма, при входе вводите сам пароль). Сессия входа живёт 90 дней, то есть заново вводить пароль каждый день не придётся. Когда рядом работают другие продукты, вход может идти через общий прокси — он настраивается переменной SSO_PROXY_TOKEN.

Дальше пользователей заводит сам администратор: указывает логин, имя и начальный пароль, который человек сменит при первом входе. Роли такие: наблюдатель (только смотрит), рецензент (выносит вердикты и ведёт задачи), участник (запускает прогоны и правит тесты), администратор (настройки проекта и пользователи) и владелец (ключи API и передача владения). Отдельной отметкой назначается дизайн-ревьюер — тот, кто одобряет изменения дизайн-системы. Почтовых приглашений нет: логин и пароль передаются лично. Отключённый аккаунт войти не может, но его след в журнале аудита сохраняется. Подробнее — в разделе Пользователи и роли.

Что сделать после запуска

Когда интерфейс открылся, до первой проверки остаётся несколько шагов:

Задайте ключ доступа — переменную TEST_APP_KEY. По нему дополнение Chrome и встроенный исполнитель подключаются к серверу, а модель получает доступ к живой странице.
Создайте проект: название, базовый адрес сайта и часовой пояс. Проект — это папка, в которой будут копиться правила, действия и тесты.
Подключите Pastukhov Agent — укажите AGENT_API_URL и AGENT_API_KEY. После этого появляются чат с ИИ-агентом, разбор замечаний, создание действий словами и автоисправление.
Если нужна ручная съёмка экранов, записи действий или прогоны в живом окне — установите дополнение Chrome в один клик, как описано ниже. Для прогонов по расписанию и снимков визуальных сборок оно не требуется.
Загляните в «Операции» и убедитесь, что в списке исполнителей есть строка «Встроенный исполнитель», а в «Настройках → Тестирование UI» горит отдельная строка встроенного исполнителя: значит, прогоны будет кому выполнять. Подробнее — в разделе Встроенный исполнитель.
Настройте визуальные проверки: выберите пресет, пороги чувствительности и стабилизацию съёмки — иначе сравнение сборок с эталоном будет давать шум. Подробнее — в разделе Настройки визуального тестирования.
Заведите среды и учётные данные, если тесты ходят на защищённый стенд: адрес стенда, логины и пароли хранятся в базе зашифрованными и подставляются в действия только на время прогона. Подробнее — в разделе Среды, учётные данные и переменные.
Выпустите ключ API для сборочного конвейера — «Настройки → API-токены». По нему конвейер запускает проверки и получает результат; инструмент viz читает ключ из переменной TEST_APP_KEY.
Снимите первый экран и напишите замечание словами: «кнопка не видна на тёмном фоне». Отправьте замечание агенту — он превратит его в правило, и дальше это замечание будет находить обычный код.
Если планируете дописывать свои проверки, загляните во вкладку «Скрипты» и убедитесь, что сверху не висит предупреждение о среде исполнения: оно появляется, когда на сервере нет Python или окружение не собралось. Подробнее — в разделе Скрипты и расширение.
Пройдите чек-лист настройки — короткий перечень шагов, он показывает, что уже готово.

Визуальные снимки делает тот исполнитель, который забрал прогон: встроенный (движок chromium) или Chrome с дополнением (движок chrome). У этих движков разные эталоны, и продукт никогда не сравнивает снимок одного с эталоном другого — поэтому движок выбирают на проект и не смешивают. Подробнее — в разделе Встроенный исполнитель и в разделе Эталоны.

Подробнее о первых шагах — в разделе Начало работы.

Дополнение Chrome: установка в один клик

Дополнение ставится из самого продукта. В интерфейсе откройте «Настройки → Тестирование UI → Установка в один клик» и выберите папку на диске — сервер запишет туда папку test-agent-addon с уже готовой привязкой (адрес сервера и ключ), настраивать ничего вручную не нужно. Дальше Chrome попросит три привычных шага:

Откройте chrome://extensions.
Включите «Режим разработчика» в правом верхнем углу.
Нажмите «Загрузить распакованное» и выберите папку test-agent-addon, которую создал сервер.

Скажем честно: дополнение приватное, в каталоге Chrome его нет. Так сделано намеренно — проверки не должны проходить проверку каталога, иначе каждое новое правило пришлось бы ждать неделями. Поэтому при обновлении сервера папку перезаписывают из того же диалога («Обновление в один клик») и нажимают кнопку «Обновить» у расширения на странице chrome://extensions. Если дополнение устанавливалось другим способом, его можно привязать вручную: указать адрес сервера и ключ на странице настроек дополнения и нажать «Проверить связь».

Установка через Pastukhov MultiAgent

Если у вас несколько серверов, удобнее ставить продукт из Pastukhov MultiAgent: он сам поднимает контейнер, выдаёт постоянный адрес и HTTPS, подключает базу. Для Агента тестирования в каталоге есть готовый шаблон «TestAgent» (по-русски — «Тест-агент», короткое имя «Тесты», порт 6070) — установка сводится к одному нажатию, а переменные MultiAgent подставит сам. Одна честная деталь: шаблон MultiAgent ещё не обновлён под текущие имена переменных — в нём настройки названы по-старому (прежний префикс вместо TEST_APP, а связанный агент подключается чужой переменной вместо AGENT_API_URL и AGENT_API_KEY), поэтому после установки через MultiAgent эти значения придётся поправить руками. Это расхождение самого шаблона, а не ошибка в этой инструкции. Подробнее о самом MultiAgent — на странице MultiAgent.

Лицензия

Лицензионный ключ активируется в диалоге лицензии в интерфейсе или передаётся переменной AGENT_LICENSE при запуске. Готовой лицензии в образе нет: свежий контейнер стартует без неё. Без лицензии работает почти всё — проекты, экраны, замечания, правила, действия, тесты, запуски, расписание, проблемы, автоисправление и сводка внимания. Лицензия нужна только для одной вещи: чтобы отправить сообщение агенту в чате. Пробный период — 30 дней; персональная лицензия стоит 19 700 ₽, корпоративная — 49 700 ₽, сервисная — 97 000 ₽. Ограничение одно и то же для всех: без лицензии визуальные проверки, ревью, отчёты, покрытие и сборочный конвейер тоже работают. Подробнее — на странице Лицензирование.

← Вернуться на главную раздела Агент тестирования