Как пользоваться HybridQA

Требования

Внешние ключи (ANTHROPIC_API_KEY, CAPSOLVER_API_KEY, TWOCAPTCHA_API_KEY) в CI задаются только через CI/CD Variables GitLab (protected + masked). Без них пайплайн работает в replay-режиме.

Быстрый старт

Три команды от чистого репозитория до зелёного прогона:

1. 1

   Поднять стек

   Runner, fixture-site, Redis, OmniParser, браузерный sidecar и метрики:

   docker compose up -d

2. 2

   Прогнать демо-сценарий

   Ожидаемый вывод — [PASS], exit code 0:

   docker compose run --rm -T runner run dsl/examples/fixture_site.yml

3. 3

   Проверить свои сценарии

   Валидация DSL без запуска браузера — удобно для быстрой итерации:

   docker compose run --rm -T runner run dsl/my_scenario.yml --dry

Без Docker (локально, только валидация и отчётность):

bundle install
bundle exec ruby bin/orchestrator run dsl/examples/fixture_site.yml --dry
bundle exec rubocop && bundle exec rspec --tag '~external'

Команды CLI

Единая точка входа — bin/orchestrator (в контейнере: docker compose run --rm -T runner <команда>).

Параллельный прогон

docker compose run --rm -T runner run dsl/ -j 20

Воркеры живут в форках родительского процесса (copy-on-write), результаты собираются в единый отчёт атомарным append в JSONL. Падение воркера не роняет прогон — сценарий помечается ошибкой, остальные продолжают.

Структура DSL-сценария

Сценарий — YAML-файл: шапка с таргетом, список шагов. Валидация — dry-schema, ошибки ловятся до запуска движка.

name: Login smoke
target: web                # web → Playwright, apk → Appium
start_url: https://example.com

steps:
  - action: navigate
    url: /login
  - action: fill
    selector: { test_id: email }
    value: "user@example.com"
  - action: click
    selector: { test_id: submit }
    description: sign in button   # подпись для AI-healing, если селектор устарел
  - action: assert
    selector: { test_id: dashboard }
    expectation:
      contains: Welcome

Self-healing селекторов

Если селектор перестал находить элемент, оркестратор не падает сразу, а идёт вниз по цепочке эвристик:

• L1 — мгновенно: координаты/локатор из кэша, suggested_at в истории.
• L2 — OmniParser sidecar: скриншот → детект элементов, сопоставление по описанию (coverage/jaccard/levenshtein, порог 0.40).
• L3 — Vision-модель, когда L2 не нашёл: получаем точку/селектор, клик по координатам.
• Успех L2/L3 кэшируется и попадает в отчёт как suggestion — разработчику предлагается новый селектор.
• Circuit breaker: N подряд неудач подряд → слой отключается на cooldown, тесты живут на детерминированном уровне.

# отчёт suggestions за неделю (кладётся в MR автоматически)
docker compose run --rm -T runner heal-report logs/heal_events.jsonl --days 7

Режимы AI

Режим задаётся флагом --mode или переменной AI_MODE:

run dsl/ --mode replay

run dsl/ --mode record
fixtures-export ai_fixtures/responses.jsonl

run dsl/ --mode live

AI_BUDGET_USD_PER_JOB=0.50 run dsl/

Flaky-детекция и quarantine

Сценарий считается flaky, если за окно наблюдения он собрал достаточно прогонов (--min-runs, default 5) и показал и pass, и fail — осцилляция при достаточной выборке.

1. 1

   Собрать историю

   Каждый прогон пишет строку в logs/scenario_runs.jsonl (атомарный append, работает и из параллельных воркеров).

2. 2

   Запустить детектор

   flaky-detect logs/scenario_runs.jsonl --days 7 --min-runs 5

   Результат — logs/flaky_quarantine.json со статистикой по каждому flaky-сценарию (runs/passes/fails/pass_rate).

3. 3

   Карантин применяется автоматически

   На следующем прогоне ScenarioRunner помечает такие сценарии quarantine: падение выводится как [QUARANTINE-FAIL], попадает в отчёт, но exit code остаётся 0 — CI не падает.

# gate в CI: уронить пайплайн, если доля flaky выше порога
flaky-detect logs/scenario_runs.jsonl --max-rate 0.05

Метрики и мониторинг

Экспортёр читает JSONL-логи и отдаёт Prometheus-метрики; Prometheus скрейпит его каждые 15 секунд, Grafana рисует дашборд HybridQA.

curl -s localhost:9100/metrics | grep hybridqa_
docker compose run --rm -T runner metrics

Порты публикуются на 127.0.0.1 хоста. Grafana — на 3001, потому что 3000 может быть занят другим сервисом. Подробнее — docs/metrics.md.

CI/CD (GitLab)

# e2e-прогон такой же, как в CI (тесты):
./bin/ci/run_tests.sh all
# или по шагам: ./bin/ci/run_tests.sh lint | spec | dsl

• MR-пайплайны: только стадия test — без сборки образов и деплоя.
• Деплой — ручная кнопка deploy:server на default-ветке/теге; .env на сервере не перезаписывается.
• Переменные CI/CD: HARBOR_HOST/PROJECT/USERNAME/PASSWORD, DEPLOY_PATH, TELEGRAM_BOT_TOKEN, TELEGRAM_SOCKS5_PROXY.

Web-UI: тесты через браузер

Сервис web (тот же образ, что и runner, порт 8090) — создание и редактирование DSL, запуск прогонов и cron-расписание без консоли.

# на стенде
docker compose up -d web            # http://<стенд>:8090/
# локально
bundle exec ruby bin/web           # WEB_PORT=8090

• Пользовательские тесты живут в dsl/user/ — при деплое исключены из rsync --delete и не вычищаются.
• Примеры репозитория (dsl/examples/) правятся только через «Копию» (copy-on-write); сценарий с невалидным DSL можно открыть кнопкой «Править» и починить.
• Удаление сценариев — только администратору: войдите через /login (пароль ADMIN_TOKEN из .env), на дашборде появится кнопка «Удалить» (для dsl/user/). Вместе со сценарием счищаются его cron-расписания.
• Cron — data/schedules.json (rufus-scheduler в процессе web); запуск — отдельный процесс bin/orchestrator, логи в logs/web_runs/.
• API для других сервисов — /api/v1/* на том же порту: Bearer $API_TOKEN, приём DSL (POST /scenarios), запуск (POST /runs), удаление (DELETE /scenarios/<path>), расписания (/schedules); ответы JSON.

Решение проблем