docs: сайт документации на MkDocs Material
- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура, разработчику, эксплуатация; навигация обязательна (strict-сборка). - docs/agent/ и docs/standards/ из сайта исключены (exclude_docs), ссылки на них — внешние, на Gitea. - Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
This commit is contained in:
@@ -0,0 +1,71 @@
|
||||
# Тесты
|
||||
|
||||
## Гейты
|
||||
|
||||
Полный гейт перед 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-Hamcrest
|
||||
`org.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 (репозиторий)](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/testing.md).
|
||||
Reference in New Issue
Block a user