Как Framework проверяет себя

Этот раздел описывает, какие проверки проходит каждый изданный выпуск Framework и что они гарантируют проекту. Проверки устроены слоями: каждый слой ловит то, чего не видят другие, и ни один не заменяет остальные.

Гейт владельца

Гейт владельца — все слои проверок из таблицы выше, через которые проходит изменение Framework. Ни одна команда не покрывает его целиком.

Ядро гейта — npm test в исходниках Framework. Он запускает:

• все контрактные тесты (npm run test:unit, файлы tests/*.test.mjs);
• проверку публичной документации (npm run test:public-docs) против исходников сайта документации на точно закреплённой ревизии, а не против соседней рабочей папки или ветки.

Эта часть гейта запускается в GitHub Actions на каждое изменение. Сверка манифестов (npm run contract:verify), браузерные пробы и проверка воспроизводимости в npm test не входят и запускаются отдельно.

Контрактный тест читает исходник или контракт и проверяет правило: схему манифеста, наследование стандартов, записи журнала, объявленные токены, контраст из примитивов, ключи порта. Контрактные тесты быстрые и детерминированные, но проверяют механизм, а не изображение.

Браузерные пробы

Браузерная проба открывает настоящую страницу в браузере и измеряет то, что нарисовано: расстояния, высоты, оси, контраст, фокус, число событий на одно действие, поведение при добавлении, удалении и повторном добавлении элемента.

Правила запуска проб:

• пробы запускаются против собранного кандидата, а не против исходника и не против уже опубликованного выпуска. Иначе проверка подтверждает опубликованное и пропускает выпускаемое;
• проверки, которые читают поставку, по умолчанию смотрят на опубликованный выпуск; перед изданием им явно передают корни кандидата;
• пробы запускает общий исполнитель scripts/run-browser-probes.mjs. Он сам определяет, какие аргументы нужны каждой пробе, и не угадывает и не пропускает молча: проба, аргументы которой он не распознал, роняет запуск так же, как упавшая; пробы, которым нужен отдельный стенд, перечисляются по имени с причиной.

Отдельно существуют пробы на стендах — страницах-образцах, где одновременно показаны все виды, размеры и оформления компонента и его соседей: поле рядом со списком, кнопки рядом с полем, флажок рядом с полем.

Воспроизводимость выпуска

Поставка ui не правится вручную: она собирается из исходников сборщиком Framework.

• Перед изданием выпуск собирают дважды из чистой копии исходников.
• Издание допустимо, только если обе сборки дали побайтно одинаковый результат для всех частей поставки: Core, компонентов, утилит, Smart-компонентов.
• Пакет продукта собирается так же дважды, поверх той ревизии исходников Framework, из которой собран выпуск, названный в его квитанции.

Так поставка становится функцией исходника: любой может повторить сборку и получить те же байты.

Выпуск получает идентификатор вида ui-<ревизия>, сборка пакета продукта — квитанцию. Проект закрепляет выпуск целиком, а пакет — по квитанции (см. Выпуск и запись о выпуске и Версии: как закрепить выпуск).

Гейт документации

Гейт документации — правило, по которому любое изменение публичного токена, поведения компонента, контракта, прежнего имени или поддерживаемого состояния обновляет документацию в той же поставке.

Порядок обновления:

1. Меняется машинный контракт в исходниках Framework.
2. Из него генерируется проекция для документации с хешем содержимого.
3. Проекция копируется в исходники сайта документации без правок; рядом обновляются объяснение, примеры и заметки о совместимости.
4. Проверка свежести в исходниках Framework сверяет проекцию с точной ревизией сайта документации.
5. Сайт документации проходит свои проверки.

Правила:

• документация не ведёт второй, написанной вручную таблицы значений;
• значение, найденное в другой строке таблицы или в тексте, не засчитывается;
• отсутствие обновления документации — препятствие к выпуску, а не задача «на потом».

Сайт документации проверяет и себя: существование каждого упомянутого класса утилиты, атрибутов Smart-компонентов, примеров и токенов, связность страниц и согласованность AI-выдачи (Машиночитаемые источники).

Что гарантирует изданный выпуск

Изданный выпуск — это выпуск, который прошёл все слои проверок и получил идентификатор и запись о выпуске. Зелёные проверки — необходимое, но не достаточное условие издания.

Изданный выпуск гарантирует:

• пройденный гейт владельца, включая сверку манифестов и реестра;
• браузерные пробы на собранных байтах именно этого выпуска;
• две побайтно одинаковые сборки;
• документацию, обновлённую в той же поставке.

Правила, которые из этого следуют:

• результаты проверок принимаются по самим результатам, а не по отчёту о проделанной работе;
• зелёный тест одного проекта не доказывает общую совместимость;
• готовность к промышленной эксплуатации заявляется только после совместной приёмки выпуска всеми обязательными потребителями;
• main и latest релизом не считаются никогда. Релиз — изданный выпуск с идентификатором.

Смотрите также

• Принципы качества для всего Framework — принципы, которые держат эти проверки.
• Как проект проверяет своё использование Framework — что проверяет сам проект.
• Что такое поставка, Версии: как закрепить выпуск — выпуск и его закрепление в проекте.
• Проверки — проверки Smart-компонентов.