Files
java-word-pdf/docs/development/testing.md
T
Pjandro b3511f8b74 docs: сайт документации на MkDocs Material
- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура,
  разработчику, эксплуатация; навигация обязательна (strict-сборка).
- docs/agent/ и docs/standards/ из сайта исключены (exclude_docs),
  ссылки на них — внешние, на Gitea.
- Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
2026-11-22 21:39:08 +03:00

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-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 (репозиторий).