Браузерный плейтест через Orca CLI

tests/orca-playtest.js — плейтест игры в настоящем браузере: он открывает вкладку встроенного браузера Orca app, прогоняет полный геймплей (меню → бросок → клёв → подсечка → улов → лавка (дневник, 🎯, 🏅) → shiny → near-miss → ночь → фонарик в лавке → босс-рыба) через Orca CLI и проверяет состояния, DOM и консоль.

В отличие от puppeteer-теста (tests/test.js), здесь нет отдельного headless Chromium — управление идёт командами CLI против браузера, которым пользуются люди. Это ловит то, что headless пропускает: отличия среды Orca-браузера, троттлинг фоновых вкладок, реальные CLI-нюансы.

Когда запускать

Перед коммитом, рядом с остальными проверками (см. AGENTS.md, раздел «Проверка»):
1. node --check на вынутый из index.html JS;
2. cd tests && node test.js — главный рубеж (headless, всегда доступен);
3. node tests/orca-playtest.js — браузерный плейтест (требует запущенный Orca app);
4. node shots.js — скриншоты.
В отличие от puppeteer-теста, требует запущенный Orca app. Если Orca не запущен — скрипт честно падает на шаге 0 с понятной ошибкой; в таком случае шаг пропускается и не блокирует коммит (главный рубеж — tests/test.js).

Требования

Что	Зачем	Как проверить
Запущенный Orca app (desktop)	Вкладка создаётся в его встроенном браузере	`orca-ide status --json` → `result.runtime.state === "ready"`
`orca-ide` в PATH или переменная `ORCA_CLI_COMMAND`	Скрипт вызывает CLI через `process.env.ORCA_CLI_COMMAND \|\| 'orca-ide'`	`which orca-ide`

На Linux голое имя orca может резолвиться в GNOME screen reader — НЕ используйте его; в терминалах Orca алиас orca работает, но скрипт намеренно берёт orca-ide (или переопределение через ORCA_CLI_COMMAND).

Запуск (из каталога репо):

node tests/orca-playtest.js     # скриншоты orca-*.png кладутся в CWD

Только встроенные модули Node (child_process, fs, path) — npm install не нужен.

Таблица шагов

#	Шаг	Что проверяется (ok())
0	`status`	runtime готов; иначе «запусти Orca app» и exit 1
1	`tab create --url file://…/index.html`	получился `browserPageId`
1b	установка error-хуков (`window.__errs`, `error` + `unhandledrejection`)	хуки стоят до старта геймплея (polling переживает eval-ошибки грузящейся страницы)
2	ожидание DOM	меню (`#menu`) показано
3	клик «Играть» (`.click()` в DOM)	`state === "IDLE"`
4	`pointerdown` на canvas → polling `CHARGE` → удержание ~0.7 c → `pointerup`	`CHARGE`, затем `WAIT` (бросок)
5	`biteTimer = 0.05` → polling `BITE` (через APPROACH) с расширением окна `biteT = 5` в том же eval → скриншот → тап	`BITE`, затем `REEL` (подсечка)
6	`reel.d = 0.5` + удержание ~2 c → polling `CARD` (30 c) → скриншот	`CARD`, в карточке имя вида и «+N»
7	«Отлично!» → «🛒» → polling `#shop` → скриншот → вкладка «📔» → скриншот → вкладка «🎯» → скриншот → вкладка «🏅» → скриншот → «×»	лавка открыта/закрыта, дневник/квесты/достижения рендерятся
8	`SHINY_CHANCE = 1` → полный цикл → скриншот → проверка DOM → `SHINY_CHANCE = 0.03`	бейдж «ЗОЛОТАЯ» (gold-вариант, M6: `#cardVariant`) показан, золотая карточка `gold-card`
9	цикл до `REEL` → `reel.d = reel.d0 * 1.4 + 2` → polling `WAIT` с чтением тоста в том же eval	тост содержит «Сбежала»
10	`setDayTime(0.85)` с чтением `dayPhase` в том же eval → скриншот	`dayPhase === "night"`
11	«🛒» → вкладка «🎣» → поиск «фонарик» в `#shopBody`	в снастях есть апгрейд-фонарик (⬆ 400 🪙, пометка про ночь)
12	`forceBoss = true` + `pickSpecies` → осётр → полный цикл: `REEL` (старт боя: `stateBoss`, `bossPhase=1`) → 3 фазы (в каждой `reel.d = 0.4` → `SNAP` со сбросом `holding` в том же eval → авто-`REEL` следующей фазы; фаза 3 → `CARD`) → скриншот → `forceBoss = false` в `finally`	старт босс-боя, карточка после 3 фаз (`stateBoss=false`), имя «Осётр-БОСС» с бейджем
13	`console --limit 100`	нет сообщений уровня `error`
13b	чтение `window.__errs`	нет pageerror за прогон (JS-ошибки и unhandledrejection)
14	`tab close` (в `finally`, 2 попытки — close идемпотентен)	вкладка закрыта при любом исходе

Итог — сводка ИТОГ: N/N и exit code: 0 все PASS, 1 есть FAIL, 2 краш сценария, 3 глобальный таймаут (~4 мин).

Пример вывода

PASS | Orca runtime готов
PASS | вкладка с игрой открыта | pageId=d94df318
PASS | меню показано
PASS | старт: state=IDLE
PASS | зарядка: state=CHARGE
PASS | бросок: state=WAIT
PASS | клёв: state=BITE (через APPROACH)
PASS | скриншот orca-bite.png
PASS | подсечка: state=REEL
PASS | улов: state=CARD
PASS | скриншот orca-card.png
PASS | карточка улова: имя вида и «+N» | {"hidden":false,"name":"Карась","val":"+2 🪙"}
PASS | лавка открыта (вкладка Снасти)
PASS | скриншот orca-shop.png
PASS | дневник показан
PASS | скриншот orca-journal.png
PASS | 🎯 вкладка: стрик и квесты дня
PASS | скриншот orca-rewards.png
PASS | 🏅 вкладка: список достижений
PASS | скриншот orca-ach.png
PASS | лавка закрыта
PASS | зарядка: state=CHARGE
PASS | бросок: state=WAIT
PASS | клёв: state=BITE (через APPROACH)
PASS | подсечка: state=REEL
PASS | шини: улов получен (state=CARD)
PASS | скриншот orca-shiny.png
PASS | шини: бейдж «ШИНИ» и золотая карточка | {"badge":"✨ ШИНИ!","gold":true,"hidden":false}
PASS | зарядка: state=CHARGE
PASS | бросок: state=WAIT
PASS | клёв: state=BITE (через APPROACH)
PASS | подсечка: state=REEL
PASS | near-miss: тост «Сбежала» после схода | Сбежала! 🐠 Окунь 0.2 кг
PASS | скриншот orca-escape.png
PASS | ночь: dayPhase=night при dayTime 0.85 | night
PASS | скриншот orca-night.png
PASS | лавка: «Фонарик» в снастях (id=4, пометка «ночь»)
PASS | зарядка: state=CHARGE
PASS | бросок: state=WAIT
PASS | клёв: state=BITE (через APPROACH)
PASS | подсечка: state=REEL
PASS | босс: старт боя (stateBoss=true, bossPhase=1, reel.boss) | {"b":true,"ph":1,"rb":true}
PASS | босс: карточка после 3 фаз (stateBoss=false)
PASS | скриншот orca-boss.png
PASS | босс: карточка «Осётр-БОСС» с бейджем 🏆 | Осётр-БОСС | 🏆 БОСС!
PASS | нет ошибок в консоли (console --limit 100)
PASS | нет pageerror за прогон (window.onerror / unhandledrejection) | []

===== ИТОГ: 47/47 =====

Подводные камни

Троттлинг rAF в фоновой вкладке. Вкладка Orca обычно не на переднем плане → requestAnimationFrame троттлится → игровое время идёт медленнее реального (кадр = максимум 0.05 c игрового). Поэтому никаких фиксированных sleep в ожидании состояний: все ожидания — polling с таймаутом (waitCond/waitState, шаг ~300 мс, таймауты 10–30 с). Фиксированные sleep допустимы только как «удержание кнопки» (зарядка ~0.7 c, улов ~2 c).
Окно подсечки короче CLI-roundtrip. Окно BITE — 0.35–0.8 с, а один CLI-вызов стоит ~0.3–0.5 с. Рецепт стабильного перехвата: biteTimer = 0.05 → polling, где в том же eval, что детекция BITE, сразу выставляется biteT = 5 (отдельный eval не успевает: на первопланарной вкладке игра идёт в реальном времени, и окно закроется до его применения) → СНАЧАЛА скриншот, потом тап.
Цитирование: только execFile с массивом аргументов, без shell. JS-выражения содержат кавычки — при передаче одной строкой через shell (PTY) они ломаются. В скрипте все вызовы — child_process.execFile(ORCA, argsArray, …); никакого exec("orca-ide …").
Pointer Events с уникальным pointerId. Игра слушает pointerdown на canvas и pointerup на window. Каждое взаимодействие (down/up-пара) получает свой pointerId (счётчик в скрипте) — так события не путаются с реальными.
Тосты недолгие (1.6 с). Текст тоста near-miss читается в том же eval, что и ожидание WAIT (state === "WAIT" ? toast.textContent : "") — отдельный последующий вызов может опоздать. Скриншот orca-escape.png — best-effort (тост мог погаснуть); ok() ставится по тексту.
CLI может transient-повиснуть. Наблюдались единичные зависания eval (~1 мин), проходящие при повторе. Поэтому orca() ретраит вызовы (3 раза, линейный бэкофф 0.5/1 c; повторы пишутся в stderr, чтобы не мешать stdout с PASS/FAIL), а execFile жжёт зависший процесс таймаутом 20 с. Исключение — tab create: ретраить нельзя (получится дубль вкладки), он идёт через orcaCall один раз. tab close в finally ретраится 2 раза — вызов идемпотентен.
Эмодзи — квадраты без шрифта. Без font-noto-emoji эмодзи в скриншотах (и в окне Orca) рендерятся тофу. На скринах это ОК — проверка не по пикселям; для красивых скриншотов поставьте шрифт.
eval возвращает объекты JSON-строкой. result.result для объекта/массива — двойная сериализация (строка-JSON); evalPage в скрипте декодирует. Притом строка-«MENU» парсится как есть.
Босс-фазы: SNAP не сбрасывает reel.holding. onUp слушает только CHARGE/REEL — отпускание пальца в состоянии SNAP (босс-обрыв фазы) оставляет holding = true, и после авто-перехода в следующую фазу игра «втягивает» сама. Поэтому в шаге 12 сброс reel.holding = false делается в том же eval, что детекция SNAP (тот же приём, что biteT = 5 в п. 2). Сам босс-бой — цикл из 3 фаз с polling'ом (SNAP → авто-REEL → снова), forceCatch() тут не подходит: на фазах 1–2 вместо CARD будет босс-обрыв.

Как добавить новый шаг

В секции «Прогон» в нужном месте добавьте действия через хелперы (evalPage, waitCond/waitState, pointerDown/Up, clickByText, shot) — фиксированные sleep на ожидание состояний не писать (пункт 1 выше).
После каждого шага — ok('название', условие, extra).
Если шаг форсирует игру (например, SHINY_CHANCE = 1), возвращайте исходное значение в finally — иначе сломаете следующие циклы и сейв вкладки.
Скриншот — shot('orca-<имя>.png'): файл уходит в CWD, не путать с shot-*.png из tests/shots.js.
Обновите таблицу шагов в этом документе и число проверок в AGENTS.md, если менялось общее количество ok().

Справочник CLI (используемые команды)

Команда	Что даёт (в `--json`)
`orca-ide status --json`	`result.runtime.state === "ready"`
`orca-ide tab create --url <url> --json`	`result.browserPageId` (дальше везде `--page <id>`)
`orca-ide eval --expression <js> --page <id> --json`	`result.result` (объекты — JSON-строкой)
`orca-ide screenshot --page <id> --json`	`result.data` = base64 PNG
`orca-ide console --limit N --page <id> --json`	`result.messages: [{text, type}]`, `type: "error"` — ошибки
`orca-ide tab close --page <id> --json`	`result.closed`

15 KiB Raw Blame History Unescape Escape