- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура, разработчику, эксплуатация; навигация обязательна (strict-сборка). - docs/agent/ и docs/standards/ из сайта исключены (exclude_docs), ссылки на них — внешние, на Gitea. - Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
4.6 KiB
Тесты
Гейты
Полный гейт перед push — ./mise.sh run verify (= mvn clean verify); на verify
висят и валят сборку:
| Гейт | Порог |
|---|---|
| surefire (тесты) | все зелёные, -Djava.awt.headless=true |
PMD (pmd-ruleset.xml) |
любой приоритет нарушения валит; includeTests=true; подавления запрещены — чинить кодом |
| JaCoCo LINE | ≥ 0.90 (оба модуля) |
| JaCoCo BRANCH | ≥ 0.85 (только wordpdf-core) |
Провал — HTML/XML-отчёт уже в target/site/jacoco/. CI-эквивалент без fontconfig —
./mise.sh run verify-nofontconfig. mvn test PMD/JaCoCo-гейты не запускает.
Стек и конвенции
- JUnit 6 (
org.junit.jupiter), толькоAssertions— Mockito/AssertJ запрещены, их нет в pom (в app-тестах допустим inline-Hamcrestorg.hamcrest.Matchers.containsStringвandExpect). - Только
@Test(исключения: два@BeforeAllпрогрева шрифтов,@AfterEach drainWorkerвConversionTimeoutTest); ни@Nested, ни@ParameterizedTest, ни@Disabled, ниassertAll. - Тестовые классы package-private, зеркалят main-пакеты.
- Именование: регрессионные —
объект_условие(pageNumbers_recomputedNotCached), юниты — camelCase (pageFieldBecomesFldSimple). - Сообщения ассертов — по-русски, с наблюдаемым значением; литерал слева.
- Тестовых утилит нет — хелперы намеренно дублируются в классах.
Фикстуры
Только закоммиченные wordpdf-core/src/test/resources/samples/: 13 .docx +
12 .doc (.doc — эталоны заказчика). В тестах фикстуры не генерировать;
XSD-невалидную .docx-фикстуру правят, а не код
(python3 docs/standards/docx/validate-fixtures.py …). Синтетика в памяти разрешена:
docx — ZipOutputStream из литеральных XML, .doc — крафт POIFSFileSystem.
Ловушка загрузки: core грузит classloader-ресурсом без ведущего слэша
(getResourceAsStream("samples/…")), app — class-relative со слэшем
(/samples/…, ресурсы из test-jar core; отсюда обязательный -am).
Как проверяется PDF
Текстом, не растеризацией: PDFBox 3 PDFTextStripper (нормализация пробелов);
негативные маркеры — # (.notdef) и Helvetica (фолбэк-шрифт FOP); имя шрифта
символа — приём fontNameOf; встроенные подмножества — обход ресурсов страниц
(EAAAAA+Carlito-Bold). Пиксели (BufferedImage, отношения к эталонам Word 300 dpi
с допусками) — только юниты chart-пейнтеров.
App-тесты
4 набора свойств = 4 Spring-контекста: ConvertControllerTest (пин пустого
wordpdf.api-key=), ApiKeyFilterTest, ConvertLimitsTest, ConversionTimeoutTest;
ConversionServiceTest/ApiExceptionHandlerTest — без Spring. Проверяют HTTP-код,
заголовки, текст ошибки. Ловушка: mise инжектирует корневой .env в окружение задач
— ambient WORDPDF_API_KEY дал бы 401 во всех MockMvc-тестах, поэтому ключ пинится
свойствами контекста.
Прод-автотесты
prod-autotests/ (pytest + requests): 31 проверка против живого стенда —
4 открытые + 27 needs_key (SKIP без ключа). Конфигурация только env:
WORDPDF_BASE_URL (обязателен), WORDPDF_API_KEY, WORDPDF_MAX_MB/MAX_PAGES,
WORDPDF_SAMPLES_DIR. Таймауты (10, 180) — больше серверных 2m. Запуск:
WORDPDF_BASE_URL=… ./mise.sh run prod-tests (в CI гоняются job'ом autotests
после deploy).
Глубина (счётчики, пары «нормализатор ↔ тест», пиксельные допуски) — testing.md (репозиторий).