Files
java-word-pdf/docs/agent/testing.md
T
Pjandro 8529b6877b
PR checks / web (pull_request) Successful in 38s
PR checks / java (pull_request) Successful in 18m31s
Слияние docx4j 17.3.5 в wordpdf-core и форк FO-рендерера 2.11-docx4j.8 в реактор
- wordpdf-core/src/main/java впитаны исходники docx4j-core, -export-fo,
  -chart-render, -JAXB-ReferenceImpl, -copy, -generated-objects (17.3.5) +
  сгенерированная XJC JAXB-модель; ресурсы — тем же путём; артефакты группы
  org.docx4j из внешних репозиториев больше не подключаются
- vendor/fop: форк docx4j-fo-renderer 2.11-docx4j.8 (util/events/core/fop)
  собирается в реакторе вместо jar из Nexus
- docx2fo.xslt перевендорен со стилем 17.3.5, оба AUDIT-FIX-патча перенесены;
  дрейф-гейт vendoredXsltTracksJarCopy зелёный
- upstream-тесты docx4j перенесены в src/test/java/org (658 классов, вне гейта);
  execution upstream-docx4j-tests в профиле upstream-tests (./mise.sh run
  upstream-tests, в pr.yml non-blocking шаг): 3470 тестов, 3457 зелёных,
  13 красных — категории окружения/калибровки хоста и следствий слияния
  classpath задокументированы в docs/agent/testing.md
- surefire: провайдер SLF4J фиксируется коротким slf4j.provider по execution;
  перенесён upstream logback.xml (root=DEBUG без конфига ломает visitor-экспорт
  VML); upstream-форки пинят JDK JAXP-фабрики; PMD/JaCoCo исключают org/**
- wordpdf-app: без изменений кода (зависит от слитого ядра); тесты 44/44
- документация синхронизирована (AGENTS.md, README, docs/agent/*), mise task
  upstream-tests
2026-11-08 02:54:49 +00:00

20 KiB
Raw Blame History

читать при правке/добавлении тестов. Авторитетно наравне с AGENTS.md.

Счётчики (2026-11)

  • 59 тестовых классов / 898 тестов гейта verify: core 53/849 (internal/doc/ 17/225, internal/chart/ 17/271, WordPdfConverterTest 77), app 6/49 (ConvertController 23, ApiKeyFilter 8, ConversionService 5, ApiExceptionHandler 5, ConvertLimits 5, ConversionTimeout 3). Обновлять при изменении набора.
  • Перенесённый upstream-набор docx4j (src/test/java/org, ~660 классов) — вне гейта: execution default-test ограничен includes ru/pjandro/wordpdf[/**]/*Test.java, execution upstream-docx4j-tests (профиль upstream-tests, ./mise.sh run upstream-tests) берёт org/{docx4j,pptx4j,xlsx4j}[/**]/*Test(s).java (кроме **/samples/**, AbstractNumberingTest — абстрактный базовый класс, и Docx4jPropertiesFoFileTest — читает docx4j.properties из корня classpath). Провайдер SLF4J фиксируется коротким -Dslf4j.provider в argLine каждого execution (simple / logback): длинный ключ org.slf4j.provider SLF4J 2.x не читает, фиксация молча игнорируется и побеждает service-discovery; часть upstream-тестов (IntegerRangeReportTest, FontReportLogTest, CssLengthRangeWarnTest, ChartExDefectsTest, InspectRangesTest) кастует логгер к logback — без пина они падали в simple-форке, и наоборот. Порта upstream-овского logback.xml (src/test/resources/logback.xml, из core-tests) обязателен: без конфига root logback = DEBUG, и DEBUG-only путь ломает visitor-экспорт VML textbox (CTTextbox marshal без @XmlRootElement); на тесты проекта конфиг не действует (пин simple), в test-jar не попадает (includes ru/pjandro|samples|geom). JAXP-фабрики upstream-форки пинят JDK-реализациями (как upstream docx4j.properties, который намеренно не портирован — он менял бы поведение всем тестам модуля): иначе xercesImpl из test-classpath перехватывает DocumentBuilderFactory.newInstance() и ExtractionConformanceTest падает на неподдерживаемом standalone-Xerces свойстве accessExternalDTD. Ловушка plexus-паттернов: ** не матчит ноль каталогов — классы пакетов ru/pjandro/wordpdf, org.docx4j, org.pptx4j, org.xlsx4j добавлены отдельными паттернами; молчаливое исчезновение классов из прогона проверять диффом «*Test.java в дереве ↔ in <класс> в логе surefire» (так терялись WordPdfConverterTest/WordPdfValidatorTest).
  • Триаж upstream-прогона (2026-11): 3470 тестов, 3457 зелёных, 54 skipped, 13 красных — гейтом не считаются (в CI continue-on-error, прогон отчётный). Категории: окружение/калибровка хоста — ChartRenderGateTest#gate (пиксельные метрики против эталонов Office на машине автора), ChartAnchorSizeTest ×3 и ChartImagesTest ×2 (размеры якорей из xlsx через метрики Calibri; на хосте подстановка Carlito/DejaVu), FopConfigFamilyTripletTest#noFaceIsDeclaredUnderAnotherFacesFamily (инвариант по системным шрифтам, ломает wqy-zenhei.ttc), Phase3ProbeWordTest#wordsShapeSurvivesTheUpdaterWithoutPages; следствия слияния classpath — TocUpdateFacadeTest#pageNumbersWithoutAPaginator (ждёт TocException «нет docx4j-export-fo», после слияния стилист всегда в ядре), ChartCreatorHostTest#workbookAuthorAndTimes и ChartBoxTest#pptxSvgKeepsTheChartsFrame (ждут docx4j.dc.write=true/docx4j.DPI=96 из неперенесённого docx4j.properties), MetafileHtmlTest#aDataUriHandlerEmbedsAPng и VmlObjectHtmlTest#aMetafilePreviewIsDrawn (data-URI-рейстеризация metafile в HTML-экспорте, путь проектом не используется; файловый image-handler тот же metafile рейстеризует — соседние методы зелёные). Метод-уровневые #-исключения surefire запрещает POM («Method filter prohibited»), поэтому точечные красные методы остаются в отчёте.

Пиксели, метрики шрифтов, стенд без fontconfig

  • Пиксели (BufferedImage) — только в unit-тестах chart-пейнтеров: безразмерные отношения к эталону Word (экспорт 300 dpi, числа зашиты в тесты), допуски assertRatio <0.06 (PiePainterTest, CartesianPainterTest) / <0.10 (Surface3dPainterTest, + assertRange ±6 pt для центров силуэта); пороги залитых px, перцентильные коридоры яркости, «серый» px — разброс каналов GRAY_MAX_SPREAD=25; исключение — структурная проверка чернил в GlyphFontTest. Эталонные файлы — develop/, вне git. Хелперы chart-тестов (render, countColor, assertRatio, paint) продублированы по классам — общего test-util нет.

  • GlyphFont (fontbox): метрики пиксельно-метрически эквивалентны AWT (ascent/descent/leading/advance совпадают до 4-го знака, кернинг-дрейф 0.0000 — DejaVu Sans, Carlito). Приёмочный стенд без-fontconfig: контейнер без libfontconfig.so.1* и /etc/fonts, mvn verify + java -jar. GlyphFontTest написан без единого java.awt.Font — обязан проходить на хосте без fontconfig.

Фикстуры

  • Фикстуры — закоммиченные samples/*.docx + samples/*.doc (13 + 12; в тестах не генерировать; .docx все ECMA-conformant по docs/standards/docx/validate-fixtures.py — фикстура невалидна, правится фикстура, не код; .doc — эталоны заказчика, конвертируются мостом): core грузит classpath-ресурсом → byte[], PDF для PDFBox — временный файл; app читает /samples/… из test-jar core (classifier tests) → mvn -pl wordpdf-app без -am не соберётся. In-memory docx — ZipOutputStream из литеральных XML или POI в byte[]; in-memory .doc — POIFS (POIFSFileSystem) вокруг крафтовых WordDocument/1Table/Data (DocToDocxFormattingTest). Ключевые: too-many-pages (150 явных разрывов → 151; .doc-пара — кэш PageCount=150 → 400 «не менее 151»), stale-cache (docx: кэш <Pages>1</Pages> + 110 lastRenderedPageBreak → 400; doc: кэш 5 → конвертируется — семантика запинена), charts-smartart (4 растра; SmartArt-одиночка = ровно 2 Image XObject; .doc-пара — 3 BLIP-fallback → 3 картинки), ole-embedded (осиротевший bin с ложным Default bin→footer+xml + настоящий w:object с честным Override → oleObject и VML-плейсхолдером media/fallback.png — ручная, генератором не перезаписывать; .doc-пара — OLE-fallback BLIP → 1 картинка), chart-types (14 графиков: 9 типов + ofPie-pie + lineChart stacked + c:wireframe + combo barChart+lineChart на вторичной c:valAx pos="r"; пересоздание — ChartTypesDocxGenerator; .doc-аналога нет), doc-formats.doc (2 страницы — лимит страниц на .doc-пути).

Юниты

  • Юниты нормализаторов работают строками (rewrite) + zip'ами из ZipOutputStream; обязательные контракты: «нечего менять → тот же массив» (assertSame) и неприкосновенность частей вне word/*.xml ([Content_Types].xml). Тесты бьют и в package-private API (GlyphCoverageNormalizer.split(text, family), ChartSpec.readTitle). Исключение — OleObjectNormalizerTest: многочастный нормализатор без rewrite-хука, тесты только через normalize на in-memory zip.

  • Юниты моста (internal/doc/): CfbReaderTest строит крафтовый CFB-байтстрим (сектор 512/mini 64: FAT/DIFAT/miniFAT/directory руками) и бьёт все guard-ветки (циклы FAT/DIFAT/MiniFAT, ссылки за файл, обрезанные потоки, root без mini stream, мусор в directory); SummaryInfoTest — крафтовый PropertySetStream (пинит относительность offset от начала PropertySet, реальные фикстуры её не различают); PieceTableTest/ChpxIndexTest/PapxIndexTest (в т.ч. istdFor: istd из UpxPapx, пустой grpprl ≠ null, bOffset=0 → дефолтные свойства при сохранённой границе)/SectionsTest/FibHeaderTest (пара fcStshf)/GrpprlTest (в т.ч. спец-длины: двухбайтовый cb у sprmTDefTable при operand >255 Б, у 0xC60D cb=0xFF — обрыв, у 0xC615 cb=0xFF — длина по формуле §2.9.182 (scan_pChgTabsSentinel_lengthByFormula))/FontTableTest/HeadersTest/OfficeArtTest/PrcDataTest — byte[]-конструкции in memory (PrcDataTest: разворачивание huge-PAPX/PTableProps на позиции указателя, union цепочки с легаси-зеркалом, guard'ы — cb-капа 0x3FA2, ptr за Data, цикл A→B→A); StylesTest — крафтовый STSH (LPStd/LPUpx): цепочка base→derived, цикл → пустая таблица, чужой stk/битый STSH нисходительны; TablesTest — крафтовый TAP: сетка TDefTable (XAS со знаком), границы Brc (cv fAuto) и Brc80 (ico, приоритет 0xD613), выравнивание sprmTJc/sprmTJc90 (u16, приоритет современного, 0 → null), деградация при битом TDefTable; ListsTest — крафтовые PlfLst/PlfLfo байтстримом (счёт LVL по fSimpleList 1/9, плейсхолдеры xst → %{n+1} и литеральный % → %%, MSONFC→ST_NumberFormat вкл. экзотика→decimal, ixchFollow→w:suff, grpprl уровня → w:ind/w:rFonts, LFOLVL fStartAt/fFormatting, обрыв LVL-массива, lsid без LSTF, нулевые lcb); DocToDocxFormattingTest — полный синтетический .doc через POIFS (крафтовые FIB/Clx/FKP-страницы: полные CHPX/PAPX-свойства, STSH-цепочка с переопределением и победой direct, spacing/tabs, таблица TTP+TDefTable+Brc с деградацией строки без сетки и многострочной ячейкой, колонтитук со стилевым jc, табы колонтитука из стиля sprmPChgTabs (styleTabsChg_reachesFooterPart/styleTabsChgDel_removesStop: прямой del с rgdxaClose вырезает stop стиля), таблица в odd footer со sprmTJc (footerTable_jcCenterEmitted: guard-¶ отдельным абзацем после строки, как в реальных Plcfhdd), знаки, поле в основном тексте, picLocation=0, 0Table, отсутствие табличного потока, списки: listParagraphs_getNumPrAndNumberingPart (sprmPIlfo/sprmPIlvl в PAPX → w:numPr + word/numbering.xml c w:num/Override/rels), listCancelledByDirectZero_noNumPr (ilfo стиля, перекрытый прямым 0), ilvlSkipValue_noNumPr (ilvl=0x0C), missingListTables_degradeToPlain (нулевые FIB-пары 73/74 — ни numbering-части, ни numPr)). Doc-регрессии конвертера — общие assert-хелперы docx-пар: assertCyrillicAndStyles/assertPageNumbers/assertTableImage/assertOleObjectsRemoved/assertDrawingsBecomeImages/assertTooManyPages/assertExoticGlyphs вызываются с ru-plain.doc/page-numbers.doc/ru-table-image.doc/ole-embedded.doc/charts-smartart.doc/too-many-pages.doc/exotic-glyphs.doc (тесты-пары называются по docx-имени, внутри зовут оба формата); WordPdfValidatorTest#checkPageCountDoc_* + ConvertControllerTest (.doc upload, nonDocxFilename_rejected).

  • App-тесты: @SpringBootTest + @AutoConfigureMockMvc (Boot 4: org.springframework.boot.webmvc.test.autoconfigure); четыре контекста — ConvertControllerTest (пустой ключ), ApiKeyFilterTest (properties = "wordpdf.api-key=…"), ConvertLimitsTest (@TestPropertySource max-mb/max-pages), ConversionTimeoutTest (@TestPropertySource convert-timeout=1ms) — четыре разных набора свойств = четыре кэшированных контекста (отдельные классы, не @Nested: @Nested + @TestPropertySource не даёт отдельного контекста); ConversionServiceTest/ApiExceptionHandlerTest — без Spring-контекста (прямые юниты).

  • UI-тестов нет; гейт SPA — npm run build (tsc -b) + npm run lint (oxlint, .oxlintrc.json: rules-of-hooks error, only-export-components warn). Прод-автотесты (pytest 9.1.1 + requests 2.34.2, 31 проверка — 27 под маркером needs_key (SKIP без ключа; включая .doc-фикстуры обоих путей — растры/OLE и границы страниц), 4 открытых: health/SPA-root/swagger/spec; env-конфиг, mise exec -- python -m pytest -q . из prod-autotests/) гоняются CI после deploy против живого прода.

Регрессивные записи, не выводимые из кода

Остальные пары XxxNormalizerTest↔тест-в-конвейере и юнит-перечисления воспроизводятся грепом по javadoc-ссылкам «Регрессия — Test#имя, фикстура …» (конвенция в AGENTS.md) и удалены отсюда намеренно. Здесь — только записи без javadoc-якорей:

  • lineRuleAuto_wordSingleLinePitch — пинит метрический шаг «single» (13.4277pt) от псевдофиксов раскладки; carlitoAutoBlock_untouched — блок без явного w:line не трогается.
  • vendoredXsltTracksJarCopy — дрейф-гейт: вне AUDIT-FIX-регионов вендорный docx2fo.xslt обязан быть побайтно равен стилисту слитого export-fo (org/docx4j/convert/out/fo/docx2fo.xslt из classpath ядра; при апгрейде docx4j — перевендорить и перенести патчи).
  • Крафт POIFS (закоммиченных фикстур нет, крафт продублирован в WordPdfConverterTest): ListsTest+DocToDocxFormattingTest#list*↔docLists_numberingAndBulletsRendered (синтетический .doc со списками → PDF: 1. 2. a) b) •, ни одного #; фикстур со списками нет — крафт POIFS продублирован в WordPdfConverterTest), PrcDataTest+DocToDocxFormattingTest#hugePapxRowMark_closesRowWithGridFromPrcData (TTP-абзац с grpprl в PrcData Data-потока → w:tbl/w:tr/сетка из цепочки; фикстуры нет — docTest.doc заказчика не коммитим, крафт POIFS продублирован), SectionsTest+HeadersTest+DocToDocxFormattingTest#twoSections*/sectionBreakInTable*↔docMultiSection_perSectionHeaders (двухсекционный .doc → PDF: стр. 1 — ШАПКА-1+ПОДВАЛ-1, стр. 2 — ШАПКА-2 + унаследованный ПОДВАЛ-1, ни одной #; крафт POIFS продублирован в WordPdfConverterTest), ChpxIndexTest#zeroOffset_defaultPropsBoundaryKept+DocToDocxFormattingTest#runFlags_*/keepNextKeepLines_*/sectLandscapePgNumCols_*/sectUnevenCols_*/cellVertAlign_*/drawnObject_*+SectionsTest#orientationPgNumColumns_applied/unevenColumns_perIndexWidths/restartWithoutStart_clampsToOne+TablesTest#vertAlign_*↔WordPdfConverterTest#docClassD_landscapeHiddenDelCaps/#docClassD_pageNumberRestartLowerRoman/#docClassD_twoColumnsBreak/#docClassD_drawnObjectBecomesImage (закрытие пробелов класса D: vanish-фильтр/правки/caps/position/keep, landscape+pgNumType, колонки+column break, vAlign, 0x08→inline-картинка; фикстур нет — крафт POIFS продублирован в обоих тестовых классах).
  • Синтетика через общий хелпер docx(docXmlns, body, sect, rels, overrides, parts): AUDIT-FIX-2↔movedRevision_textPrinted/bdoDir_textPrinted (фикстур нет — синтетический docx через общий хелпер docx(docXmlns, body, sect, rels, overrides, parts)); пиннинг аудита .docx↔footnote_rendersAtPageBottom, endnote_rendersAtDocumentEnd, docxHyperlink_uriAnnotation, pageRefField_liveNotCached (кэш 9001/7777 заменён живым номером), dateField_notStaleCache (кэш 01.02.2003 заменён текущей датой), titlePg_firstPageHeader, vMergeCell_spansRows, sdtContent_rendered, drawingTextBox_textPrinted, ommlMath_drawnAsVectors (пиксели: +150 тёмных px@150dpi сверх текста), highlightAndShading_backgroundDrawn (жёлтые px >0 против baseline 0), аудит [MS-DOC] моста 2026-11: GrpprlTest#tInsertOperand_skippedBySpra/tInsertOperand_truncated_aborts (sprmTInsert — 4 байта, хвост TAP не рассинхронизирован), TablesTest#cellPadding_* + DocToDocxFormattingTest#cellMargins_becomeTcMar ↔ WordPdfConverterTest#tableTcMar_textInsetLikeWord (CSSA→w:tcMar, пайплайн красит поля ячейки как tblCellMar — текст на margin+padding), StylesTest#characterStyle_stk3_chainViaCharChain/charChain_nonCharacterStk_empty + DocToDocxFormattingTest#charStyle_viaIstd_mergesUnderDirect (sprmCIstd: символьная chpx-цепочка между стилевой и прямыми, direct wins), DocToDocxFormattingTest#runHighlightAndShading_inRPr/runShadingPattern_degradesToBackFill/paraShd_inPPrBeforeJc ↔ docHighlightAndShading_yellowPixels (Ico→ST_HighlightColor; w:shd в форме FOP val="clear"+fill; паттерн→cvBack), SectionsTest#titlePage_flagFromSepx + DocToDocxFormattingTest#titlePage_emittedAfterCols ↔ docTitlePage_firstHeaderOnlyFirstPage (sprmSFTitlePage + first-слоты Plcfhdd → headerReference type="first", первая страница — только first-шапка)..
  • App-регрессии: requestLimitParams_areIgnored, nonPositiveLimits_failStartup, unknownPath_notFound, concurrentRequests_bothSucceed, corruptNotAZip_rejected, plainZipNotDocx_rejected, junkInsideValidZip_conversionError (500 на валидном .docx-контейнере с мусором), nonDocxFilename_rejected, oversizedOverCoreLimit_rejected, drawingsAlwaysRendered, cyrillicAndPathInFilename_sanitizedResponseName, docsOpenWithoutKey/forwardedPrefix_healthStaysOpen/forwardedPrefix_docsOpenWithoutKey, dotSegmentOpenPrefix_rejected, errorFlagNotBoolean_rejected, methodNotSupportedReturns405/badContentTypeReturns415.