37 lines
8.9 KiB
Markdown
37 lines
8.9 KiB
Markdown
# П65 · 2023-07 · Контрактные тесты API — три прохода саморевью
|
||
|
||
## Рамка пакета
|
||
|
||
- Slug: `editorial-2023-07-practice-contract-tests`, `editorial-2023-07-mechanism-contract-tests`, `editorial-2023-07-field-contract-tests`.
|
||
- Голос: М6, середина 2023 года. Системный практик говорит коротко и различает наблюдение, ожидание consumer, проверку provider и решение о выпуске.
|
||
- Sidecar содержит ровно пять новых файлов: этот review, один import-safe script и три локальных SVG. Registry, README, `articles.json`, очередь, Git и чужие файлы не менялись.
|
||
- Граница: это не запуск Pact, consumer, provider, CI, broker, HTTP-клиента или сети; не результат OpenAPI validation, production compatibility, browser trace или инцидента. Все service names, версии и responses в fixture имеют явный synthetic marker и создаются только в памяти Node.
|
||
|
||
## Проход 1 — источники, факты и границы
|
||
|
||
- Источники перепроверены 31.07.2026. Все были исторически доступны к июлю 2023: [OpenAPI Specification v3.1.0, 15.02.2021](https://spec.openapis.org/oas/v3.1.0), [Pact Docs: Introduction, обновлено 30.08.2022](https://docs.pact.io/) и [Pact Docs: Verifying Pacts, обновлено 11.08.2022](https://docs.pact.io/provider). OAS назван описанием HTTP-интерфейса и не выдан за гарантию прикладной семантики. Pact упомянут как процесс consumer-driven contract и отдельной provider verification, а не как реально запущенный инструмент.
|
||
- `createSyntheticContract()` принимает только `synthetic-contract-input-v1`; unmarked input отвергается. `inspectSyntheticProviderResponse()` требует `synthetic-provider-response-v1`, не читает файловую систему и возвращает отдельные `schemaMatch`, `semanticExpectationMatch`, `actualProviderVerification: not-run` и `productionCompatibility: not-claimed`.
|
||
- Fixture намеренно показывает разные учебные случаи: `active + ISO date` позже synthetic reference time проходит форму и expectation; `active + null` и прошедшая дата проходят форму, но не проходят expectation; несуществующая календарная дата и числовой `state` ломают форму. Это не утверждение о реальном API и не результат provider verification. Rollback восстанавливает лишь snapshot учебного contract и сообщает `deployment: not-performed`.
|
||
- В текстах и проверках явно отделены schema match, semantic expectation и успешная реальная provider verification. Для последней названы contract version, provider version, provider state, исполнение interactions и адресуемый результат; synthetic fixture не может подменить ни один из этих фактов.
|
||
|
||
## Проход 2 — голос, полнота и объём
|
||
|
||
- Первые два абзаца каждой статьи называют проблему и цену: структурно валидный JSON меняет смысл поля, consumer теряет действие, а команда рискует ошибочным выпуском или откатом. Маршрут везде фиксирован как «симптом → причина → проверка → действие».
|
||
- Все тексты соответствуют М6: прагматичны, не выдают учебную модель за личный production-опыт, не обещают универсальную совместимость и оставляют владельцу конкретный следующий шаг. Термины schema, semantic expectation, consumer, provider, provider state и verification раскрываются в связи с примером.
|
||
- В каждой ревизии есть одна доступная таблица, один исполнимый synthetic code/fixture, один упорядоченный маршрут, содержательная figure с alt/caption, разделы об ограничениях, rollback и следующем шаге. Источники стоят в отдельном разделе и не включены в объём.
|
||
- `audit:draft` посчитал основной текст: practice — 8 652, mechanism — 9 304, field — 9 229 знаков. Все значения внутри обязательного диапазона 5 000–15 000 и цели 8–10 тыс. знаков.
|
||
|
||
## Проход 3 — визуалы, безопасность и выпуск
|
||
|
||
- SVG разделяют роли: consumer/provider flow, matrix schema/meaning/verification и release gate. В них нет `script`, `foreignObject`, внешних URL, `data:image`, пользовательского ввода или интерактивного поведения. Их подписи прямо говорят, что это учебные схемы, а не сеть, CI или журнал выпуска.
|
||
- Sharp-review всех трёх SVG на ширине 375 px выполнен вручную: заголовки, блоки и стрелки не обрезаны и не перекрываются; ключевые статусы PASS/FAIL/not-run читаются. Для узкого экрана схема оставляет только существенные отношения, а подробность дублируется alt и caption в статье.
|
||
- До передачи главному редактору выполнены: `node --check web/scripts/upgrade-2023-07.mjs` — PASS; `node web/scripts/upgrade-2023-07.mjs --verify-fixture` — PASS 20/20 после независимого model review; `cd web && npm run audit:draft -- scripts/upgrade-2023-07.mjs` — PASS для трёх slug; import-safe export без `date`/`author` — PASS; `xmllint --noout` — PASS; SVG safety scan — чистый результат; Sharp 375 px — PASS.
|
||
- Пакет не интегрирован, не коммитился и не пушился. Строгий архивный аудит, registry, README и production build оставлены главному агенту для отдельной приёмки.
|
||
|
||
## Приёмка главного редактора
|
||
|
||
- Источники сверены по первичным страницам: OAS v3.1.0 фиксирует версию и дату 15.02.2021; Pact Introduction прямо различает статическую schema/specification и contract by example и имеет historical update 30.08.2022; Pact provider guide требует проверять локально работающий provider или CI и отмечен 11.08.2022. Эти страницы задают терминологию, но не являются доказательством запуска Pact здесь.
|
||
- Независимый model review нашёл, что «actionable date» была только строкой и regex: прошедшая дата могла пройти semantic expectation, а несуществующая дата — schema. Введено фиксированное synthetic reference time, `active` требует дату строго позже него, timestamp проверяется как календарный; fixture добавил past-date и impossible-date negative cases. Contract shape теперь тоже проверяет baseline semantic rule до inspection, чтобы произвольная подмена reference time не превращалась в accepted model. Fixture проходит 20/20.
|
||
- Визуальный review на 375 px подтвердил читаемость трёх схем. На consumer/provider flow подпись уточнена с «точной» до «будущей» даты, чтобы визуальная модель не расходилась с контрактом.
|
||
- После подключения трёх revision строгий audit подтвердил 8 868 / 9 515 / 9 459 знаков, по одной figure, table и code example; registry содержит 190 уникальных revision. Production build прошёл с 374 статическими страницами. `articles.json` и чужие изменения не затронуты.
|