Files
java-word-pdf/docs/agent/testing.md
T
Pjandro 733662770b
PR checks / web (pull_request) Successful in 39s
PR checks / java (pull_request) Successful in 1m37s
feat(xlsx): REST + фронт + документация (шаг 8)
- ConvertController: расширение .xlsx, текст 400 «только .docx, .doc и .xlsx»
  (контракт с фронтом), @Operation — флаг errorOnSmartArt на .xlsx не
  срабатывает; safeBaseName срезает .xlsx
- фронт: DropZone accept/подпись, подзаголовок App, api.ts фолбэк-имя режет
  .xlsx; web build+lint зелёные
- app-тесты: xlsxFile_convertsToPdf (200, PDF, filename* Отчёт.pdf, текст
  доехал), nonDocxFilename_rejected — .xlsx в тексте, safeBaseName .XLSX
- прод-автотест test_convert_xlsx (32 проверки)
- docs: новая docs/agent/xlsx-bridge.md (классы, единицы, деградации,
  соглашения PrintLayout↔валидатора); AGENTS.md — роутинг входа, секция
  моста .xlsx, REST/фронт/счётчики (75 классов/1095 тестов, 32 фикстуры);
  pipeline.md (ContainerKind, estimateXlsxPages), repo-map.md (пакет,
  DocxPackageWriter, генераторы, пересоздание xlsx), testing.md,
  doc-bridge.md (DocxWriter → internal/DocxPackageWriter)

Сквозная проверка java -jar + curl: xlsx→PDF 200 (filename* RFC5987),
chart-fixture 200 с отрисованными PNG, errorOnCharts=true → 422 контрактный
текст, .txt → 400 новый текст, .doc-регресс 200
2026-11-03 02:37:43 +00:00

17 KiB
Raw Blame History

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

Пиксели, метрики шрифтов, стенд без 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 + samples/*.xlsx (13 + 12 + 7; в тестах не генерировать; .docx все ECMA-conformant по docs/standards/docx/validate-fixtures.py — фикстура невалидна, правится фикстура, не код; .doc — эталоны заказчика, конвертируются мостом; .xlsx генерирует SampleXlsxGenerator (POI), их содержимое — контракт: тексты ячеек запинены, assertions только по целым словам широких колонок — узкие режутся переносом FOP): 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).

  • Юниты моста .xlsx (internal/xlsx/): синтетические книги — XlsxTestZips (литеральные XML в ZipOutputStream: workbook/sheet/rels/sst/styles/theme; лист обязан ссылаться на рисунок элементом <drawing r:id> в XML листа — SheetModel резолвит drawingPath по элементу, не по релсам); POI в юнитах моста не используется. PDF-слой — корневой XlsxPdfConverterTest по фикстурам (текст, imageCount/distinctImageCount, 422 Kind.CHARTS/Kind.OLE).

  • 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, 32 проверка — 28 под маркером needs_key (SKIP без ключа; включая .doc/.xlsx-фикстуры обоих путей — растры/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 обязан быть побайтно равен стилисту из jar'а docx4j-export-fo (при апгрейде 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, xlsxFile_convertsToPdf, oversizedOverCoreLimit_rejected, drawingsAlwaysRendered, cyrillicAndPathInFilename_sanitizedResponseName, docsOpenWithoutKey/forwardedPrefix_healthStaysOpen/forwardedPrefix_docsOpenWithoutKey, dotSegmentOpenPrefix_rejected, errorFlagNotBoolean_rejected, methodNotSupportedReturns405/badContentTypeReturns415.