houseplan-card/docs/TESTING.md

Testing

Действующая инструкция: правила для новых тестов, гейты, локальный набор и матрицы релизной проверки. Ручных чек-листов по поверхностям и приложений по отдельным issue больше нет (#681, после #634): поведение держат тесты, смоки и golden, а то, чего автоматика не видит, собрано в разделе «Чего не проверяет автоматика». Сюда пишется только то, что действует для любой задачи; маркер [auto: …] у пункта обещает падающую проверку в том же коммите (docs/DEVELOPMENT.md).

Правила для новых тестов (issue #85) — обязательны

Зелёный тест в этом проекте несколько раз означал «ничего не проверено»: смок непрерывности не заметил удаления механизма, который защищает; golden-сцена, заведённая под #71, была пустой; смок теней был зелёным, пока тени физически не рисовались. Общее у всех случаев — тест ни разу не проверяли на способность падать. Отсюда правила.

1. Наличие атрибута, класса или узла — не проверка поведения. Такой ассерт допустим только рядом с пиксельным либо поведенческим: атрибут доказывает, что код выполнился, а не что механизм сработал.
2. Golden-сцена, заведённая под конкретную задачу, несёт семантический ассерт (warmPixelRegion и родственные в demo/golden/run.mjs): сцена обязана падать, если перестала показывать то, ради чего заведена. Пиксельный дифф с эталоном этого не заменяет — пустая сцена совпадает со своим пустым эталоном идеально.
3. Фикстура содержит слои, которые тест защищает. Смок непрерывности без подложки, Glow и декора проверяет пустую страницу; солнце с азимутом, при котором луч не достигает единственного окна (#89), — та же ошибка в геометрии.
4. Тест, охраняющий механизм, сопровождается мутантом в scripts/mutation-registry.mjs: 2–5 строк патча, воспроизводящего поломку, против которой тест заведён, и тест обязан на ней краснеть. Чистым функциям с обычными юнитами мутант не нужен.
5. Тавтологический ассерт — читающий то же свойство, которое код только что выставил, — не пишется вовсе. Он может упасть только при удалении строки, но не при её неработоспособности.
6. Смок входит в сценарий через публичную поверхность (#629): DOM с контрактными хуками (docs/data-hp-contract.json), события HA и фикстуры, тестовый фасад window.__hpTest. Приватное поле карточки допускается только для чтения в ассертах. Смок, открывший диалог присваиванием c._roomDialog = …, зелёный и при сломанной кнопке, — это тот же «ничего не проверено», что в правилах 1–5. Новые записи держит гейт no-new-private-writes, остальное — ревью (раздел ниже).

Проверка: node scripts/mutation-gate.mjs --check — якоря патчей живы; полный прогон — workflow mutation-gate.yml (шесть чересполосных шардов --shard=i/6 — при четырёх шард упёрся в потолок 60 минут на 810 мутантах, #604; один зафиксированный commit/tree для всего прогона; каждый артефакт несёт identity и исход шага прогона, а отдельный агрегатор fail-closed отвергает смешанные, неполные или прерванные по таймауту evidence даже при частичном rerun; лог шарда считается зелёным только с итоговой строкой поймано N из M) каждую ночь по расписанию (00:43 UTC); в релизном гейте он не участвует — проверяет тесты, а не продукт; отказ сам заводит issue с отчётом (#472, #513). С #620 ночь по расписанию на дереве, уже доказанном зелёным полным прогоном, шарды не гоняет: зелёный агрегатор оставляет маркер в кэше Actions (tree материала, github.workflow_sha, номер прогона), следующая ночь с тем же tree и тем же workflow принимает его и пишет в сводку reused from run N. Маркер старше семи суток не принимается (tree фиксирует код, а не раннер), ручной dispatch гоняет реестр всегда, а красный прогон маркера не оставляет — следующая ночь гонит реестр заново и снова заводит issue. Решение — чистая функция scripts/mutation-nightly-reuse.mjs (test/mutation-nightly-reuse.test.mjs). Дешёвая половина идёт с юнитами: test/mutation-gate.test.mjs. Локально для дельты задачи — node scripts/mutation-gate.mjs --changed origin/dev..HEAD: гоняются только мутанты, чьи patch-файлы или входы гарда задеты диффом (#332, #475, #492). Входы гарда — это не только файлы, названные в команде: обёртка (scripts/*-guard.mjs) объявляет запускаемые тесты в export const GUARD_INPUTS (умолчание backend-test-guard.mjs — tests_backend/test_ha_import_export.py, действует без третьего аргумента), а от каждого файла гарда берётся замыкание импортов и путей: смок тянет demo/serve.mjs, compat-хелперы и фикстуры, pytest-модуль — conftest.py. src/** в замыкание не входит — это сторона патча (§6.4 ТЗ #492). Дифф, трогающий сам реестр, дополнительно отбирает добавленные и изменённые определения относительно реестра базы (git show <base>:scripts/mutation-registry.mjs; для commit до #558 используется прежний scripts/mutation-gate.mjs). В одном CLI-вызове замыкание входов вычисляется один раз на уникальную строку guard и переиспользуется отбором и fingerprint; строка plan-metrics показывает число запросов/вычислений/чтений и время построения плана. Бандл собирается только мутантам с браузерным гвардом; компиляция тестов в worktree стартует с тёплого test-build/ основного дерева.

С #550 ненулевой exit сам по себе не означает «мутант пойман». Цепочка setup && ... && oracle разбирается по шагам: ошибки компиляции, сборки, загрузки/collection теста дают setup-failure; неприменимый патч — invalid-mutation; timeout, signal и отсутствие exit status — infrastructure-interruption; зелёный oracle — survived. Только падение последнего заявленного oracle даёт assertion-killed и может попасть в ledger. Compile-time проверка допустима как самостоятельный свидетель лишь с явным полем определения oracle: 'compile'; прятать её в префиксе обычного browser/backend guard нельзя. Все недоказанные исходы завершают гейт кодом 2 и отдельно называются в ночном отчёте. Гвард с --test-name-pattern, не исполнивший ни одного теста, — тоже setup-failure (#650).

С #568 setup-failure в дифф-режиме атрибутируется: раннер прогоняет ОПРЕДЕЛЕНИЕ БАЗЫ диапазона на дереве базы и говорит, чей это отказ. Предсуществующий (не готовится и на базе) гейт задачи не красит — автор не чинит чужое, — но называется строкой pre-existing-setup-failures=<id,…> и обязан покраснеть в ночном полном прогоне, у которого есть адресат (#472). Отказ, внесённый диффом, краснит как раньше; свидетеля, которого в базе нет, оправдывать нечем по построению. Сравнение именно подобного с подобным: с определением из головы своя же сломанная правка реестра выглядела бы предсуществующей.

Приём, который делает мутанта мёртвым молча, один и тот же: статически мёртвая ветка в .ts — if (false), false &&, безусловный return в начале функции. TypeScript перестаёт помнить сужения, сделанные выше (profile снова | null), компиляция падает до заявленного теста. Писать ложь, ложную в рантайме, но не статически: if (eps < 0), String(mode) === 'mutant-never-…', if (walls.length >= 0) return walls.slice();. В .mjs этого ограничения нет.

В CI changed_mutants бежит не на каждом пуше, а по явному запросу (#510, сужено в #601): workflow_dispatch validate.yml -f mutants=true (его делают ревью-конвейер на материале ревью и слияние на кандидате) и PR. full=true (ночь, кнопка), кандидат беты (трейлер Release:) и обычный push мутантов не запрашивают: за 08–09.09 мутанты на промежуточных пушах стоили 48 из 56 часов job-минут и в основном отменялись следующим пушем, а к бете каждая задача уже прогнана ими на ревью и на слитом кандидате; ночь покрыта полным реестром (mutation-gate.yml). Доказательство мутантов для ревью — именно dispatch-прогон на точном SHA; зелёный push-прогон им не является. Релизный гейт mutant-jobs не требует (CI_PROOF_POLICIES.release.mutants = false).

План шарда (--plan-only) считается до установки окружения (#518) и с #620 называет окружение своих гардов строками plan-browser= и plan-python= (scripts/mutation-environment.mjs). Python с зависимостями бэкенда ставится только шарду с pytest-гардами (в графе исполнения гарда есть .py или запуск 'python3'/pytest), Chromium — только шарду, чей граф исполнения импортирует Playwright (смоки, golden, юниты через demo/serve.mjs). Граф исполнения — не замыкание входов для отбора: файлы из строки гарда, объявленные входы обёрток, пути, названные в этих точках входа, и их относительные импорты. Шард без таких гардов окружение не ставит, но исполняется и отчитывается — шесть mutant-jobs в доказательстве ревью (#541) не меняются. Ошибка признака ложной зелени не даёт: гард без своей среды краснеет уже чистым прогоном.

changed_mutants добавляет --ledger=<файл> — журнал доказанных свидетелей (#481, #550): после каждого пойманного мутанта в файл пишутся тип доказательства (assertion или явно объявленный compile) и отпечаток его входов (файлы патча, все входы гарда по замыканию выше, объявление мутанта; строка версии продукта нормализована), и мутант с тем же отпечатком в следующем прогоне не гоняется. Схема 2 намеренно не читает старые записи без типа доказательства: setup failure из прежнего раннера нельзя унаследовать как зелёный результат. Журнал живёт в кэше Actions по шарду, сохраняется при любом исходе шага, так что отменённый пуш или таймаут не пропадают даром. Полный прогон и --id журнал не читают; --ledger без --changed — ошибка.

Пустое совпадение --test-name-pattern (#650)

Зелёный node --test с --test-name-pattern, который не исполнил ни одного теста: TAP называет только сам файл (ok 1 - test/x.test.mjs), ассертов не было ни в чистом прогоне, ни на мутанте. Так бывает, когда задача переименовала тест, а гвард реестра остался со старым именем. Шаблон — это RegExp: (, +, ? в имени экранируются (в команде гварда \(отбор\), в JS-строке реестра \\(отбор\\)). mutation-gate --check проверяет то же статически: шаблон обязан совпасть хотя бы с одним литеральным именем test(/it(/describe( в файлах гварда; если в файле есть имена ${…}, несовпадение — WARN, иначе FAIL. Это setup-failure (#550) и атрибутируется как любой другой (#568): переименование теста в задаче даёт introduced, старый пустой шаблон — pre-existing. Свидетель — test/mutation-guard-outcome.test.mjs (тесты #650 …).

Новый код не добавляет any (#342)

node scripts/no-new-any.mjs                              # origin/dev...HEAD
node scripts/no-new-any.mjs --base origin/dev --head HEAD
node scripts/no-new-any.mjs --diff patch.diff            # или `-` для stdin
node scripts/no-new-any.mjs --total                      # весь долг src/**

Правило — PROCESS.md §8 «Новый код не добавляет any»: судятся только добавленные строки, исключение — // any-ok: <конкретная причина> на той же строке, текст разбирает парсер TypeScript. Здесь — только механика: причина короче 12 символов или из списка заглушек скрипта (todo, hack, потом…) не проходит; код, дословно перенесённый блоком в другой файл того же диапазона, новым не считается (#592). В CI гейт вызывается в job frontend; её checkout получил полную историю без блобов, потому что diff-aware проверке нужен диапазон, а содержимое старых ревизий — нет.

Тестовый фасад и приватное состояние (#629)

На 22.09 смоки писали в приватное состояние карточки больше двух тысяч раз и поэтому не видели обработчиков ввода и путей закрытия: шестерёнку, поле имени, Escape и крестик не нажимал никто. Фасад харнесса window.__hpTest (demo/helpers/hp-test.mjs) делает то же, что человек или другой клиент HA. Он ставится launch(), launchColdView() и launchPanelCold(); смок, перезагрузивший страницу, зовёт installHpTestOnPage(page) заново. Кода фасада в бандле нет — window.__hpTest.preinstalled обязан быть false.

Операция	Что нажимает или шлёт	Готово, когда
setMode(m)	[data-hp="mode-tab"][data-mode=m]; для view — [data-hp="editor-close"]	ha-card[data-hp-mode=m]
setTool(t)	[data-hp="toolbar"] [data-hp="tool"][data-tool=t]	кнопка нажата, updateComplete
switchSpace(id)	[data-hp="space-tab"][data-id=id]	вкладка aria-current="page"
openRoomEdit(roomId)	[data-hp="room-settings"][data-room=roomId] (режим plan)	открыт [data-kind="room"], возвращается он
openMarkerDialog(id?)	без id — add-device; с id — [data-hp="device"][data-id] в режиме devices	открыт [data-kind="marker"]
openSpaceDialog('create' | 'edit', id?)	space-add / create-space; space-settings[data-id]	открыт [data-kind="space"]
setServerConfig(next | fn)	фикстура __pushServerConfig: событие houseplan_config_updated, карточка сама читает houseplan/config/get	карточка приняла ревизию (тайм-аут 5 с)
setLayout(next | fn)	то же через houseplan_layout_updated (у карточки дебаунс 200 мс)	ревизия раскладки принята
input(el, text, {clear})	keydown → значение → InputEvent(insertText) → keyup на символ, в конце change	updateComplete
close(dialog?, {via})	escape — keydown на активном элементе; x — крестик окна; cancel — [data-hp="dialog-cancel"] содержимого	диалог отсоединён или открыт [data-kind="confirm"]; {closed, confirm}

settled() — updateComplete и два кадра, общий шаг ожидания.

Правила фасада:

• элемент ищется только по таблице SELECTORS, и каждый её селектор объявлен в JSON-контракте с аудиторией test (test/hp-test-facade.test.mjs). Если элемента нет — именованная ошибка с селектором и режимом, без отката на приватный метод;
• фасад ничего не пишет в карточку и читает только _cfgRev, _layoutRev, _serverCfg, _layout — то, что читает и сам продукт;
• setServerConfig/setLayout означают «план изменили на сервере», а не «несохранённая правка»: функциональный аргумент получает structuredClone текущего конфига карточки. Правку в редакторе смок делает через UI. Фикстура, как настоящий сервер, отвечает conflict на запись с expected_rev старше доставленной ревизии — только после первой доставки, чтобы смоки без фасада видели прежнюю фикстуру;
• крестик ha-dialog HA живёт в его приватном shadow root: via: 'x' там — ошибка, Escape и cancel работают.

Гейт и счётчик:

node scripts/no-new-private-writes.mjs                              # origin/dev...HEAD
node scripts/no-new-private-writes.mjs --base origin/dev --head HEAD
node scripts/no-new-private-writes.mjs --diff patch.diff            # или `-`
node scripts/no-new-private-writes.mjs --count                      # остаток на HEAD, не гейт

Судятся добавленные строки demo/smoke_*.mjs и demo/helpers/**. Записью считаются присваивание любым оператором, ++/-- и delete, если в цепочке левой части есть сегмент _x: c._serverCfg.model_version = 7 — запись в _serverCfg, а window.__card = …, o.ok = … и цепочки от this — нет. Вызовы ._setMode(, ._openRoomEdit(, ._openMarkerDialog(, ._openSpaceDialog( — тоже нарушение, с подсказкой операции фасада. Правка строки зачитывается удалённой записью в то же поле того же файла; перенос непрерывного куска — как у no-new-any. Исключение — на той же строке:

c._drag = { id, sx, sy }; // private-ok: #NNN состояние жеста, операции фасада для него нет

с теми же требованиями к причине, что у any-ok. Мутации через вызовы (c._serverCfg.spaces.push(…)) и через локальный псевдоним гейт не видит — их ловит ревью по правилу №6 выше. Гейт идёт в gate:small и в шаге job frontend рядом с no-new-any, с той же базой.

HP_SMOKE_CHECKS=1 node demo/smoke_<имя>.mjs печатает в finish() отсортированный список имён проверок — так перевод смока доказывается «без потери утверждений»: список до и после сравнивается построчно.

Локальный набор перед пушем (#343)

Красный CI — дорогой способ узнать о проблеме: пять минут ожидания, а при код-ревью ещё и лишний раунд. Прецедент назван в задаче: находка r2-H1 в #329 стоила целого раунда и ловилась локальным npm test.

node scripts/pre-push-gate.mjs                       # origin/dev..HEAD
node scripts/pre-push-gate.mjs --base origin/dev --head HEAD
node scripts/pre-push-gate.mjs --no-smokes --no-mutants
node scripts/pre-push-gate.mjs --max-smokes=3 --max-mutants=1

Что прогоняется: проверка, что ветка приведена к origin/dev, npx tsc --noEmit, npm test, смоки, выбранные scripts/smoke-select.mjs по диффу, и мутанты, выбранные scripts/mutation-gate.mjs --changed по тем же файлам.

Отставание от dev — предупреждение, а не провал набора: гейтом остаётся конвейер, который приводит ветку сам (#257) и забыть не может. Смысл локальной проверки в другом: после любого ребейза разбор на ревью становится полным, а не по дельте (PROCESS §2.10), а конфликт всё равно чинится на машине автора — дешевле узнать об этом до пуша, чем из комментария через сорок минут (#364). Отключается флагом --no-rebase-check. Замер на реальном диапазоне (953f675~1..953f675, правка src/houseplan-card.ts): типы 5 с, юниты 17–19 с, два смока 22 с — 46 секунд на всё.

Три свойства, без которых такой набор бесполезен:

• не останавливается на первом упавшем — иначе автор узнаёт о втором нарушении следующим кругом, то есть ровно то, от чего набор защищает;
• громко перечисляет, чего не проверял — молчаливый пропуск дважды стоил проекту дня (#171, #207), а «Verified» без названной команды и её результата доказательством не является;
• не претендует на полноту. Golden, полная матрица смоков, HA-харнесс — heavy-набор Validate на кандидате; весь мутационный реестр — ночное расписание (#513), а не этот набор.

Бандл не собирается: bundle-sync.mjs раскладывает закоммиченный dist, а свежесть проверяет сам продукт — assertFreshDemoBundle внутри каждого смока сверяет вшитый отпечаток с исходниками дерева и скажет, если нужна пересборка.

Лимиты по умолчанию — шесть смоков и два мутанта. Мутант дорог: каждый пересобирает бандл, а правка src/houseplan-card.ts задевает их 62. Превышение лимита не проглатывается — набор печатает точную команду для полного прогона.

Три вида ответа smoke-select различаются и здесь: дифф без исполняемого кода — «смоки не требуются»; прямое совпадение или зарегистрированная связь — прогоняется; связь не доказана — отдельная громкая строка, потому что это не «проверять нечего»: молчание стоило #234 бета-блокирующего регресса.

В хуке — по умолчанию для веток задач (#633)

Прежде набор включался только переменной HP_PREPUSH_GATE=1, и ошибки, которые ловит gate:small, находил Validate с конвейером через полчаса после пуша. Теперь .githooks/pre-push сам вызывает node scripts/pre-push-gate.mjs --hook, и тот для каждой пушимой ветки решает:

Случай	Что делает хук
ветка issue/*, в диффе от merge-base с origin/dev есть хоть один файл не класса C/D	npm run gate:small (scripts/gate-small.mjs --base=<merge-base>); красный — push отклонён
дифф ветки — только класс C/D (документы ревью, changelog, бандл) или пуст	набор не гонится, причина печатается
ветка не issue/*, тег, удаление	набор не гонится
исполняемый дифф, но пушится не HEAD	push отклонён: набор проверяет рабочее дерево, а оно не совпадает с пушимым коммитом
HP_PREPUSH_GATE=0	выключен явно
HP_PREPUSH_GATE=1	гонится для любой ветки и любого диффа

Процессный гейт идёт первым — он отвечает за секунды; набор — после, и прогоняются оба, чтобы все провалы были видны одним кругом. gate:small идёт минуты: в песочнице агента, где команда живёт ≈ 3 минуты, набор гоняют отдельной командой, а пушат с HP_PREPUSH_GATE=0 — и пишут об этом в хендоффе.

Ручной режим выше (node scripts/pre-push-gate.mjs без --hook) остался как был: tsc, юниты, смоки и мутанты по диффу. Решение хука покрыто test/pre-push-gate.test.mjs, включая настоящий .githooks/pre-push на временном репозитории.

Обойти, как и процессный гейт, можно через git push --no-verify — и тогда то же самое найдёт Validate, уже после того как код окажется в dev.

Браузерные проверки до ревью: свежесть бандла и где снимать кадры

• Смоки из AC — локально до S7-code-review (#151): node demo/smoke_<имя>.mjs. Красный смок, доехавший до ревью, стоит цикла; на своей машине — минуту (на #89 ошибка фикстуры прожила целый раунд ревью).
• Свежесть бандла (#236). Отпечаток, вшитый сборкой, покрывает src/, конфигурацию Rollup и TypeScript и package-lock.json; бенчмарки, golden и съёмка документации зовут assertFreshDemoBundle сами, смоки получают его из launch() в demo/serve.mjs. Несовпадение — жёсткий отказ, а не предупреждение: смок на несвежем бандле краснеет частично и читается как дефект логики. HP_ALLOW_STALE_BUNDLE=1 отключает проверку для отладки и говорит об этом вслух.
• Сверять и снимать — разные вещи (#455). golden:verify — совещательный и законный где угодно, Windows включительно: он сообщает разницу и ничего не принимает. Съёмка кадров вне Linux отказывает ещё до запуска браузера — golden:capture через demo/golden/policy.mjs, скриншоты документации через npm run docs:capture (именно скрипт, не голый node demo/docs/capture.mjs: правка скрипта съёмки сама обесценивает индекс скриншотов). Причина — физика, а не политика: Windows растеризует текст через DirectWrite, и кадр байт в байт не совпадёт ни с одним эталоном. Осознанный обход — HP_ALLOW_FOREIGN_CAPTURE="причина", причина уходит в вывод и манифест. Принимаются эталоны только npm run golden:accept -- --reviewed по полному артефакту (demo/golden/README.md); единственный локальный короткий путь — npm run docs:accept -- --identical (раздел про версию в кадрах ниже).

Manifest входов: какие job запускать и что хешировать (#492)

Один модуль, scripts/check-inputs.mjs, объявляет каждую проверку Validate (preflight, frontend, changed_mutants, integration, smoke, golden, performance_smoke, backend) через корни и точки входа, а остальное вычисляет: от точек входа берётся замыкание — импорты транзитивно, строковые пути как листья, каталог по строке — все текстовые файлы под ним. Из этого manifest читают и classify-changes.mjs (job changes: job запускается, если дифф задел хотя бы один её вход), и gate-reuse.mjs (ключ реюза = хеш содержимого всех входов job). Два места не могут разойтись: до #492 у бэкенда ключ не знал relay, converter и schema, а golden/perf — serve.mjs, demo.html и compat-хелперов.

Правила, которые стоит знать:

• validate.yml — вход toolchain каждой job: правка workflow гоняет всё;
• src/** — вход только браузерных job, кроме точных cross-runtime входов src/plan-optimizer.ts и src/logic.ts, которые backend pytest читает для parity-контрактов; demo/fixtures/large-house.mjs и demo/fixtures/visual-matrix.mjs так же явно входят в backend, потому что pytest запускает их через Node dynamic import. Точные исключения не делают весь UI или каталог fixtures входом backend (#542); backend от остального UI не зависит, а custom_components/houseplan/manifest.json (версия) держит правило «кандидат релиза прогоняет всё» и для него;
• assets/furniture/** — вход frontend (#671); assets/fonts/** — явное исключение ручного generate-pdf-font.mjs;
• неизвестный охраняемый вход — исполняемый файл под scripts/, demo/, test/, tests_backend/, .github/, custom_components/, src/ либо tracked-файл под assets/**, которого нет в manifest ни одной проверки, — расширяет прогон до полного набора и называется в summary. Лист покрытия (node scripts/check-inputs.mjs --coverage, test/check-inputs.test.mjs) требует, чтобы каждый такой файл был чьим-то входом либо стоял в NOT_AN_INPUT с причиной: новый скрипт или asset без записи — красный юнит, не вечное расширение прогонов;
• overlay принятых эталонов (demo/golden/baselines/**, #573) — вход только golden, у которой он стоит явным корнем. Раскрытие каталога по строке его не выдаёт: корпус отпечатка называет demo/golden каталогом, но берёт из него только *.mjs, а до #573 индекс эталонов через это раскрытие становился входом smoke, perf и 181 из 183 браузерных свидетелей — приёмка 13 кадров на beta.3 (ad4000f9) сменила их ключи и отпечатки, и второй полный Validate повторил 22 минуты уже сделанной работы. Явная ссылка на файл индекса (как в test/check-inputs.test.mjs) входом остаётся;
• --check=<job> печатает входы, --why=<файл> — цепочку, по которой файл стал входом.

Отрицательные пробы (test/gate-reuse.test.mjs, test/classify-changes.test.mjs, test/check-inputs.test.mjs) держат представителей каждой категории входов и обратную пробу для UI ↔ backend; мутанты manifest-drops-workflow-input, classify-unknown-input-is-unaffected, reuse-backend-hashes-ui, backend-dynamic-inputs-dropped, baseline-overlay-leaks-into-every-key, guard-inputs-ignore-wrapper-defaults, registry-diff-not-selected, merge-pushes-unvalidated-candidate, merge-ignores-lease-rejection, nightly-does-not-wait держат сам протокол.

Чистые Python-контракты канонизации, которым не нужен Home Assistant, находятся в tests_backend/test_coordinate_canonicalization_pure.py. Они обязаны реально исполняться в локальном pytest tests_backend, а не исчезать за module-level importorskip; schema/store/virtual-light проверки остаются в HA-зависимом test_coordinate_canonicalization.py. Поведение static-card capability доказывается unit/smoke-счётчиками и состоянием runtime, а не regex по исходнику (#440).

Без установленного Home Assistant (нативная Windows, песочница) HA-харнесс tests_backend/test_ha_*.py не собирается вовсе — conftest.py исключает эти файлы через collect_ignore_glob, поэтому их нет ни в passed, ни в skipped, и зелёная итоговая строка про них ничего не говорит. С #630 pytest в таком прогоне печатает в шапке и в итоге строку HA harness NOT collected: N test_ha_*.py files (M tests) со ссылкой на канон — Linux CI или WSL (bash scripts/wsl-setup.sh --verify). N и M считаются при каждом запуске по тому же glob (объявления def test_*/async def test_*, без размножения параметризацией), в документах их не переписывают. Проверка — tests_backend/test_conftest_harness_notice.py, мутанты ha-harness-notice-silent и ha-harness-notice-count-frozen.

Версия в кадрах и попиксельная приёмка (#512)

Golden-кадры и скриншоты документации не должны меняться от bump версии. Для golden отображаемая версия идёт через seam displayVersion() (src/card-version.ts, глобальная __HP_VERSION_OVERRIDE__ — только для харнесов; продукт её не задаёт), и харнес фиксирует 0.0.0-golden. Для docs-скриншотов есть локальная приёмка npm run docs:accept -- --identical: кадры сравниваются по декодированным пикселям, и при полном совпадении обновляется только отпечаток исходников.

Ядра фронтенда растут только осознанно (#425, заменяет #34)

• node --test test/core-file-budget.test.mjs — потолки на src/houseplan-card.ts и src/houseplan-editor-runtime.ts.

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

Вторая половина правила (уменьшение ниже потолка на 250 строк тоже краснеет) нужна затем, что без неё вынос двух тысяч строк ничего не меняет: потолок остаётся прежним, и ядро дорастает до него обратно «в рамках бюджета».

Локальный CI-совместимый toolchain (#557)

• test/toolchain-pins.test.mjs проверяет, что явно выбранный Python используется и для version probe, и для pip show, без fallback к python/python3/py из PATH; строки результата содержат пути Node, Python, Playwright package и Chromium executable.
• Тот же unit запрещает Windows setup менять persistent PATH или удалять существующий venv, требует SHA-256 проверки portable Node и подтверждает, что WSL verify запускает настоящий HA subset и одну Linux golden-съёмку.
• На Windows два последовательных pwsh -File scripts/windows-toolchain.ps1 setup проходят: первый ставит изолированные runtimes, второй переиспользует их; check после каждого зелёный и печатает фактические версии/пути.
• Из свежего ext4 checkout WSL команда bash scripts/wsl-setup.sh --verify проходит test_ha_setup.py без skip, создаёт непустой panel-wide-view-light-en.png и печатает длительность. Это ранняя обратная связь; независимый exact-SHA Validate остаётся каноном.

Backend quality gates (#42)

• tests_backend/requirements.txt is the single source of backend CI dependencies; validate.yml and mutation-gate.yml install from it (#392; #42 added ruff and mypy).
• pyproject.toml configures ruff (E/F/B/I, E501 ignored by decision) and strict mypy for a grow-only allowlist of pure modules; tests_backend/test_backend_quality.py guards completeness. The CI typing step derives its module list from that allowlist, refuses an empty list and is guarded by a test plus the typing-gate-stops-running mutant — a configured but unexecuted gate measures nothing.
• test/backend-test-hygiene.test.mjs refuses any write into sys.modules from a backend test by the fact of the write, not its spelling (#398). Exemptions: conftest.py (stub only when Home Assistant is absent) and pure_imports.py (registers a module only for exec_module, then removes the whole custom_components difference — proven by an executable test).
• The backend job measures branch coverage (pure + HA harness combined), fails below scripts/backend-coverage-baseline.txt and refuses to run when the HA harness would silently skip.
• The clean-runner geometry_parity job (#548) compiles only the TypeScript graph rooted at src/junction-limits.ts, loads the production Python module without Home Assistant and compares both over test/fixtures/junction-limits-parity.json. It fails closed on missing prerequisites, announces the number of executed scenarios and reuses a result only when both mirrors, the fixture, toolchain pins and harness inputs are byte-identical.
• The error-code scanner proves every emitted code (send_error literals, exception class attributes, literal and variable-passed MarkerControlError codes, f-string families) is in const.ERROR_CODES / ERROR_CODE_FAMILIES and localized.

E2E на реальном Home Assistant (#514)

Репозиторий Matysh/houseplan-e2e: настоящий HA в docker, House Plan из релиза или из дерева коммита, 13 сценариев Playwright (боковая панель, дашборды, роли, телефон, PDF, рестарт HA, первый запуск, обновление). Ночью — по расписанию на последней бете; для стабильного релиза release.yml запускает его на SHA кандидата (scripts/e2e-gate.mjs --ref=<sha>, #540: ставится custom_components/houseplan из tarball коммита — то же дерево, из которого git archive строит houseplan.zip) и ждёт зелёного: красный — релиз остаётся черновиком, ассеты не публикуются. В цикле разработки и на бетах не участвует.

Environments matrix

Run View/kiosk core flows in every applicable touch environment. Run editor core flows in desktop environments; touch editors only need the safety floor and separately promised workflows:

• Chrome / Edge (desktop, Windows or Linux) — View + all editors
• Firefox (desktop) — View + all editors; SVG viewBox math and container queries differ historically
• Safari (macOS) — View + all editors; pointer events / pinch behavior
• HA Companion app, Android — View only as the parity contract; cold start is mandatory
• HA Companion app, iOS — View only as the parity contract
• Tablet in kiosk/panel mode — View/kiosk, landscape, touch gestures
• Phone portrait, narrow ≤400 px — View and View dialogs/actions
• Dark theme and light theme (badges, dialogs, plan contrast)
• RU, EN and DE profile locales (+ language: card option forcing each); de-DE, de-AT and de-CH resolve to German, while an unknown locale falls back to English [unit: i18n, i18n-runtime]
• German cold start requests exactly one locale chunk, shows only a neutral busy frame before commit and never flashes English; a second card reuses the page cache. EN/RU request no locale chunk [auto: German locale smoke]
• German locale download failure retries the content-hashed asset once and then unblocks the card in English with one warning [unit: i18n-runtime; auto: German locale smoke fault injection]
• German View and a representative settings/device dialog fit at desktop and 390 px without horizontal overflow or clipped actions [golden: German desktop/mobile scenarios; auto: dialog footer width at desktop and 320 px]

Touch support and release gates

The product contract is defined in docs/TOUCH-SUPPORT.md:

Surface	Touch release status
View and View dialogs/actions	Required and release-blocking
Kiosk/wall tablet	Required and release-blocking
Editor entry/exit and no accidental mutation during multi-touch	Safety floor; release-blocking
Feature parity of Plan/Device/Background editors	Best effort; not a general release gate

All editors remain fully tested on desktop with mouse/keyboard. A touch-editor failure may be accepted only as a deliberate scope change with updated user documentation and test classification in the same change. “Best effort” cannot be used to waive data corruption, unsafe service calls, permission failures, missing destructive confirmation or an editor exception that breaks View.

Golden-image regression matrix

npm run golden:capture records the data-only scenarios from demo/golden/matrix.mjs into ignored artifacts/golden/actual/; it never changes a reviewed image and fails if any scenario itself errors. golden:verify always compares the complete matrix (a diagnostic --scenario is capture-only) with demo/golden/baselines/, writes high-contrast pixel diffs and fails on a missing image, changed dimensions, excessive diff, scenario error or stale matrix manifest. It also refuses a different Chromium build and baseline PNGs whose hashes no longer match the reviewed manifest. golden:accept -- --reviewed is the only baseline write path and also requires a complete, error-free report captured from the current source fingerprint; the entire set is validated before any reference is copied.

What each scene covers — junctions, boundaries, openings, Glow and sun, fills, hover, all three editors, themes, zoom levels, warm remount, dialogs — is declared next to the scene in demo/golden/matrix.mjs; semantic assertions (enclosedHoles, isPointInFill() containment, opening-symbol contracts) run before the raster comparison, so a scene fails on meaning before pixels. A dialog scene whose screenshot shows only a heading instead of the block it exists for is a scenario error, not an acceptable baseline. In the canonical Linux CI profile Chromium, viewport, DPR, locale, timezone, colour profile, font rendering, animations and caret are deterministic. The separate CI job captures review candidates until the first baseline is accepted; after that it automatically runs blocking verification. Review and accept the golden-images CI artifact rather than treating a developer OS raster as the canonical set. See demo/golden/README.md.

Large-house performance gate

npm run benchmark:large-house runs a deterministic fictional three-floor fixture with 60 rooms, 200 devices, 100 openings, 60 partitions, 40 columns and 500 decor objects. It records model readiness, first stable render, space switch, HA state update, shared-wall resize preview, pan/zoom, settings-dialog render, repeated navigation, Long Tasks, warmed hot-cache growth and post-GC heap growth.

Validate carries a performance_smoke: one warm-up and three measured samples of the heaviest 60-source Glow state. It enforces absolute timing, Long Task, heap, cache and 200-device ceilings, but does not claim to detect small relative regressions. Together with the browser smokes and golden it runs on the beta candidate (a head commit with a Release: trailer), on the nightly full=true dispatch of dev and on pull requests — not on every push (#479).

The dedicated Full Performance workflow builds the candidate and base SHA, then captures seven measured samples for each sequentially on the same Node 22, Playwright Chromium and hosted runner. It runs on main, weekly and by manual dispatch. demo/performance/compare.mjs applies the tighter of the approved absolute ceiling and baseline-relative allowance. Stable release assets additionally need an exact-SHA green Full Performance run; every release, including a prerelease, needs the full exact-SHA Validate proof. Raw reports and comparisons are uploaded as CI artifacts, and the check tables are written to the job summary. Local measurements remain diagnostic. See demo/performance/README.md for commands and the budget-review contract.

Installation / upgrade / removal

• A successful entry setup registers /houseplan as houseplan-panel only after store migrations/repairs complete. The panel is visible to admin and read-only users; actual editor/write access still follows can_write and admin_only [auto backend: panel registration/permission tests].
• Missing houseplan-panel.js, static registration failure, foreign path collision or panel API exception leaves the integration, WS API and dashboard card usable. Unload removes only the exact panel object owned by this setup generation; reload/reconnect cannot duplicate or delete a replacement [auto backend: panel lifecycle + mutation tests].
• Wide View/editor and 320 px read-only/empty /houseplan have no horizontal overflow or duplicate product title. Menu activation emits bubbling and composed hass-toggle-menu; hass, narrow, route and panel updates preserve one child card; leaving the route keeps only the space and returns in View [auto: smoke_houseplan_panel; golden: panel matrix].
• The dashboard full card advertises {columns:"full",rows:10,min_rows:6} to Sections; the compact card has no grid default. Fixed 6/10/14-row slots, all editors and a 30-step storm stay bounded and preserve camera intent; other layouts stay unchanged [browser: smoke_sections_resize, smoke_houseplan_panel; unit/mutation: houseplan-panel, four grid witnesses].
• README and User Guide in EN/RU each separate Storage mode, HA 2026.2+ resource_mode: yaml and legacy HA 2024.6–2026.1 full-YAML dashboard setup; both hard-reload shortcuts are present and a flat top-level resources: block is rejected [auto: check-docs].
• Fresh Storage-mode install from the HACS default catalog (plain search) → integration appears; the exact ?v= URL is created or adopted in the Lovelace resource registry without an extra_module_url fallback or a duplicate. An upgrade updates the one canonical entry [auto backend: tests_backend/test_ha_frontend_registration.py].
• single_config_entry: adding a second entry is impossible [manual]
• A pending or transient registry installs the fallback immediately, then retries exactly once after HA started plus the fixed one-second delay. Success removes only this setup's exact fallback when supported; unload before the listener, during the delay or during the task prevents all late side effects, and reloads do not accumulate listeners [auto backend: tests_backend/test_ha_frontend_registration.py; mutation gate].
• HA 2026.2+ YAML resources and a legacy 2024.6–2026.1 full-YAML dashboard use the truthful extra_module_url fallback without a registry write or polling loop. A Storage dashboard is never instructed to switch to legacy mode: yaml just for House Plan [auto backend: tests_backend/test_ha_frontend_registration.py; auto: check-docs].
• A missing frontend bundle or failed static-path registration does not fail integration setup, does not report a successful loader and does not consume the one-time notification; System Health reports file/static/loader/outcome honestly [auto backend: tests_backend/test_ha_frontend_registration.py, tests_backend/test_ha_setup.py::test_missing_frontend_bundle_does_not_skip_backend_setup].
• The first available frontend registration creates one localized persistent hard-reload notification. Repeated setup, retry completion and a new House Plan version create no duplicate; uninstall dismisses it best effort [auto backend: tests_backend/test_ha_frontend_registration.py; mutation gate].
• System Health preserves existing plan statistics and reports card file, static path, typed resource outcome, final loader, exact versioned URL, retry state, safe error and first-notice state without traceback, tokens or external paths [auto backend: tests_backend/test_ha_frontend_registration.py].
• In a full card, every successful config/get authoritatively replaces the backend version. Equal versions and unknown/malformed values show nothing; a known symmetric mismatch shows one direction-neutral manual-reload banner in ordinary View/editor/dialog states and never reloads without a trusted click [unit: version-recovery; auto: smoke_version_recovery].
• In kiosk, an unsafe mismatch preserves the current frame. The first fully safe idle state stores the backend target before exactly one reload; the same target after reload/remount or in a second full card gets no second attempt, a new target gets one, and unavailable sessionStorage is manual-only [unit: version-recovery; auto: smoke_version_recovery; mutation gate].
• custom:houseplan-space-card loads the shared bundle/config but never owns the version banner, safety timer or automatic reload [unit: version-recovery; auto: smoke_version_recovery].
• Removal deletes every House Plan Lovelace resource entry with the canonical base URL and dismisses the notification; .storage/houseplan.* survives and reinstall picks the old config up [auto backend: tests_backend/test_ha_frontend_registration.py].
• Diagnostics download works; personal fields (name/link/description/pdfs) are **REDACTED** [manual]

Edge cases

• HA instance with zero devices/areas → onboarding works, rooms can be drawn, no crashes [manual]
• Space with zero rooms → renders; markup hint visible
• Room without HA area + borders OFF → still has a transparent View hit surface, highlights on hover, reports geometric floor area, click does nothing
• No zigbee devices anywhere → no LQI badges, lqi fill leaves all rooms unfilled [manual]
• 100+ devices in one space → build under ~50 ms [manual], drag stays smooth
• Very long device/room names → ellipsis/wrap, no layout explosion
• HTML/emoji in names (<b>xss</b>, 🚿) → rendered as text, never as markup [manual]
• Plan file deleted from disk → Repairs issue appears after config save/restart; re-upload clears it [auto backend]
• Corrupted .storage/houseplan.config → entry retries (ConfigEntryNotReady), no crash loop [auto backend]
• HA restart while a dialog is open → next save gets a clean error/conflict, no data loss
• Legacy layout entries (v1 {x,y} without space) are ignored gracefully
• Kiosk cold start on mobile app: the card is defined before dashboard render; a version mismatch follows the one-safe-attempt contract from the installation section instead of flashing or entering a reload loop [auto: smoke_version_recovery].

Чего не проверяет автоматика

Сводка того, что удалённые чек-листы testing-notes/ (#681) помечали [manual] без автоматического свидетеля. Проверяется на кандидате беты руками — на демо-стенде (demo/stand/README.md, там же «чего на стенде нет») или у владельца:

• Реальный Home Assistant. Пользователь без прав администратора не видит «+» пространства и шестерёнок (_canEdit); мастер импорта этажей на экземпляре с настоящими этажами HA (порядок по уровню, Skip/Cancel); фильтрация мостов, групп и сцен, нумерация дублей и свёртка групп света на настоящих реестрах; лампа, чья сущность скрыта в реестре (свёрнута в группу), переключает и показывает лампу; правило card-mod по data-hp действует в установленном card-mod.
• Сенсорный экран на устройстве. Долгое нажатие 600 мс, pointercancel без фантомной карточки, свайп пространств в киоске, панорама, начатая на значке в View, — на планшете или телефоне, не в эмуляции.
• Ресурсы сервера. Файл ~50 МБ скачивается дважды параллельно без роста памяти HA; перепривязка маркера переносит /files/<id>/ с PDF; удаление пространства снимает предупреждение Repairs о пропавшем плане.
• Несколько клиентов и представлений. Статическая карточка на том же дашборде следует за перетаскиванием на полной без записи конфига; два представления одного дашборда не делят viewport и диалоги; перезагрузка во время записи не предлагает «Сохранить» повторно.
• Визуальная оценка. Центровка подложки и глифа значка (без сдвига на 1 px), читаемость рамок и подписей на белой бумаге, цвета и градиенты заливок «Свет», «Температура» и LQI, свет через туннель двери в толстой стене, кромка солнечного луча на тёмной сцене (тонкий край, не контур), раскладка карточки комнаты.
• Пользовательское содержимое. javascript: в поле ссылки маркера не становится ссылкой.

Остальные пункты с пометкой [manual] описывали обычное поведение режимов, редакторов, диалогов, правил значков и houseplan-space-card. Для них нужен смок, а не ручная проверка: задача, которая трогает такую поверхность без смока, пишет его в том же коммите (правило [auto: …] выше). Пункты [manual] разделов ниже остаются как есть.

Release regression quickies

• Browser console has zero errors from houseplan-card.js on: dashboard load, markup, dialogs, zoom
• HA log has zero houseplan errors/warnings after restart
• npm test (frontend), pytest tests_backend (pure only without HA: test_ha_*.py are not collected, the run prints how many — #630), CI HA-harness — all green
• README screenshots/GIF still match the current UI (synthetic home only)