Настройка Codex под тестирование

Без настройки Codex будет угадывать: как запускать тесты, где стенд, какие данные можно трогать, что считать готовым. Каждая догадка — лишний круг правок. Полчаса на настройку окупаются в первый же день: агент перестаёт спрашивать очевидное и начинает работать по правилам вашей команды.

AGENTS.md: раздел о тестах

AGENTS.md — файл с инструкциями проекта, Codex читает его в начале каждой сессии (подробно — в уроке «AGENTS.md: инструкции проекта»). Гайд OpenAI по лучшим практикам советует держать в нём команды сборки, тестов и линтера, а также описание того, что значит «готово» и как это проверить (Best practices). Для QA это главный рычаг.

## Тесты

- Стенд: http://localhost:8001 (поднимается `docker compose up -d`).
- E2E: Playwright + TypeScript, спеки в `tests/e2e/*.spec.ts`, имя файла — по странице или фиче.
- Один файл: `npx playwright test tests/e2e/home.spec.ts`; весь регресс: `npx playwright test`.
- Юнит-тесты плагина: `vendor/bin/phpunit` в `src/plugins/<vendor>/<plugin>`.

### Правила для тестов

- Локаторы: `getByRole`, `getByLabel`, `getByText`; CSS-селекторы — только если других нет.
- Запрещено: `page.waitForTimeout`, увеличение таймаутов и `retries` как способ «починить» тест.
- Тест, который отправляет форму или пишет в базу, работает только на localhost.
- Тестовые данные — через фикстуры из `tests/e2e/fixtures`, не через захардкоженные строки.
- Если задача — написать или починить тест, код продукта не меняй без явного разрешения.

### Готово, когда

- Новый тест прогнан и зелёный; запуск приложен в ответе.
- Показано, что тест падает, если откатить исправление в коде продукта.

Последние два пункта — ключевые. Без них агент вполне может отчитаться «тест написан», не запустив его ни разу. Подробно о проверке «падает без фикса» — в уроке «Как проверять тесты, написанные агентом».

Для мобильного проекта раздел тот же, меняются команды: ./gradlew testDebugUnitTest для Android, xcodebuild test со схемой и симулятором для iOS. Впишите точную команду, которой пользуется ваша команда, — агенту не придётся подбирать её методом проб.

Песочница и доступ к стенду

По умолчанию локальный Codex работает в песочнице (sandbox) workspace-write: пишет в пределах рабочей папки и спрашивает одобрения на выход за её пределы. Сеть в этом режиме по умолчанию выключена (Approvals & security). Для e2e это важно: прогон тестов против стенда — сетевой запрос. Codex либо попросит одобрения на запуск вне песочницы, либо тест упадёт с сетевой ошибкой, и агент начнёт «чинить» то, что не сломано.

Удобный выход — отдельный профиль для QA-работы. Профиль — это файл ~/.codex/<имя>.config.toml с ключами верхнего уровня (старый формат [profiles.x] внутри config.toml с версии 0.134.0 не читается — подробнее в уроке «Профили»).

sandbox_mode = "workspace-write"
approval_policy = "on-request"

[sandbox_workspace_write]
network_access = true

network_access = true открывает агенту всю сеть, а не только стенд. Это удобно на учебном проекте, но в рабочем репозитории сеть лучше сузить до адреса стенда списком разрешённых доменов — как это сделать, разобрано в уроке «Песочница всерьёз». И не открывайте сеть в сессии, где агент читает недоверенные данные (тексты задач, внешние страницы) рядом с секретами.

Запуск — codex --profile qa. Для исследования требований и чужого кода, где агенту ничего не нужно менять, подойдёт обычный запуск с --sandbox read-only. Посмотреть, какие настройки реально действуют, можно командами /status и /debug-config.

Команды без вопросов: rules

Если одобрять каждый прогон npx playwright test надоело, Codex позволяет описать правила (rules) для команд. Они живут в ~/.codex/rules/default.rules и пишутся на Starlark:

prefix_rule(
    pattern = ["npx", "playwright", "test"],
    decision = "allow",
    justification = "Прогон e2e против локального стенда",
    match = ["npx playwright test tests/e2e/home.spec.ts"],
)

Учтите две вещи. Во-первых, allow означает запуск вне песочницы без вопроса, а тесты — это код, который агент сам и написал. Разрешайте так только то, что гоняется против локального стенда. Во-вторых, rules в документации помечены как экспериментальные, синтаксис может измениться; после правки файла перезапустите Codex. Подробнее — в уроке «Rules» и в документации.

Навыки для повторяемой работы

Баг-репорт по шаблону, чек-лист регресса, разбор упавшего прогона — всё это повторяется, и описывать формат в каждом промпте утомительно. Такие процедуры упаковываются в навыки (skills): каталог .agents/skills/<имя>/ с файлом SKILL.md. Codex видит только имя и описание навыка и загружает полный текст, когда задача подходит, либо когда вы вызываете его явно через $имя.

---
name: bug-report
description: Оформить баг-репорт для Kaiten по результатам воспроизведения. Использовать, когда баг воспроизведён и нужно описание; не использовать для идей и доработок.
---

Собери репорт по шаблону: заголовок (где + что не так), окружение, шаги,
ожидаемый и фактический результат, частота, доказательства (скриншот, консоль,
сетевой запрос), предполагаемая область кода. Не пиши догадки как факты.

Навык лежит в репозитории, значит, вся команда пользуется одним шаблоном. Как писать хорошие навыки — в курсе «Настройка и расширение Codex».

Браузер

Для исследования страниц агенту нужен браузер. В ChatGPT desktop app он встроен, в CLI его подключают через Playwright MCP — одной командой:

codex mcp add playwright -- npx "@playwright/mcp@latest"

Что это даёт и где границы безопасности — в уроке «Браузер в руках агента».