Test Plan
This document maps the test suite to the requirements it verifies.
Each test file is a traceable [item] referencing the requirements it covers.
Test Coverage
Test file: test/v2-unified-item-architecture.test.ts
Tests the RequirementsTraceabilityExtension orchestrator — initialization, processing, query methods, role statistics, lifecycle.
Covers the public API surface of the main extension class.
Includes verbatim block handling (listing, literal, and backtick code spans).
Relation |
ID |
Title |
verifies |
REQ-087 — Items inside verbatim blocks are not parsed |
|
verifies |
REQ-088 — Inline macros inside verbatim blocks are not parsed |
|
verifies |
REQ-090 — Verbatim block detection handles standard AsciiDoc fences |
|
verifies |
REQ-091 — Inline macros inside verbatim blocks are preserved in rendered output |
|
verifies |
REQ-092 — Inline macros inside backtick code spans are not parsed |
Test file: test/antora-extension.test.ts
Tests the AntoraTraceabilityExtension — initialization with default config, preset, config path, and disabled state.
Tests event handler registration, content processing via contentClassified event (in-memory only, never touches disk), matrix generation via sitePublished event and matrix registration in the content catalog via contentClassified, and API access patterns.
Also tests traceability:outgoing[], traceability:incoming[], and traceability:links[] macro expansion with configurable display style, sort order, collapsible sections, empty-state messages (:traceability-empty:), and opt-in behavior.
Tests incoming macro display styles, sort orders, reverse labels, PDF compatibility, and collapsible support.
Tests traceability:graph[], traceability:graph-coverage[], and traceability:config-graph[] macro expansion with configurable Kroki image format and Kroki server URL (extension config option and KROKI_SERVER_URL env var override), graph-enabled and graph-disabled modes, including global coverage, explicit target IDs, and header exclusion.
Tests automatic matrix registration in the content catalog during contentClassified.
Tests partial file processing including item registration from partials, view URL as sourceFile, and macro expansion in Pass 2.
Tests cross-module and cross-component xref prefix generation.
Relation |
ID |
Title |
verifies |
QA-058 — No side effects on source files |
|
verifies |
QA-060 — PDF compatibility of generated output |
|
verifies |
REQ-040 — Matrix links resolve correctly from site output location |
|
verifies |
REQ-041 — Source file paths are normalized |
|
verifies |
REQ-044 — traceability:outgoing[] macro renders outgoing links |
|
verifies |
REQ-045 — Opt-in via AsciiDoc attribute |
|
verifies |
REQ-047 — Configurable display style |
|
verifies |
REQ-048 — Configurable sort order |
|
verifies |
REQ-051 — Relationship graph via image::https://kroki.io/graphviz/svg/eJydmM9u4zYQxu_7FAP3GgNiIlF2CxcwmvQPum13s-kp2QMtjW0iNCmQlBNvUaAP0SfskxQSxVSMncLkKYYz4k_D-ebj0DXfaNZs4U6zCtmKC24P8Mc7AM3kY8314v3tN-8ApKoR7s2WNbhYqecLMPYgcDHRqpU11hdrLgTWkwtYK2kl2-Fi8iOKPVpescnnbgWsNwj3p_7tHjL8Cy5I1sdO7j7dTbPscgL33cKVEkovJl9dz_Nlvhzi3ZdPW27xAgRboVj4xx7k8AH—etvWEqrNIObZ4vScCXhDo017qUmtzcfp1mevQLly3l2Pf8f0PDYgxw-9KBfmNX8GQSXjwY0GiX2CJXSGisrDgGQpAGJB5Ie-Em1ukJYc4HQMLs1wDSCVHrHBP8SAPM0YO6BeQ-0I5F8rVq7UVxu7j_DjlVaQQAs0oCFBxY98LfGTrmEPWewNBXn16oCZq3mq9ZiwCvTeKXnlT3vOyXXfNNqthIINTeNYAcn9QA2S4PNPGx2DDNKW1C6Rj0mFWlCKbxQCieUWxTMciXNljfg-r3b0qGcAfB1z50JvPTAyyG1PWq2Qai2TNsxrNPOCEiKeQqQFHMHJMU83MsuzaMUgwzTlFl4ZRbFcStwWandW61Ar5KA9GoA0qtjtfys1SMHvuu2eN31-3hL86QaknyoIckv3wIa1HvU8PvtewiASRmS_MoDXYZHjK6AKPdcK7kLGpCm2Rn1dkadnf00lG0omkbTYGUN1KpqXwHTREO9aGhxChgYTHAiUZrGo55HT_FOewxNs07qrZOWIWujVdsYaA2C3SJo3KMOkivTjtvSH7dldjK5tmmUtgYqJQRrAmCai5beRcvQRV_q1g0y7sytlBw3BE0CEjoACXXAa1yzVtiAB9z027ptA2Bay1Pf8tS1_K8KKrVruMCp5TuENRNixarHMSpLqh7JhuqRzFdPcImudqYvnkZjsIanLcrAXY7GwDOBPrfM21knC8M7NxPc2GnfdaBa27Q2BKbZWebtLHN29kN_CHGjBtU0qPvdVRLlK2CSnZEs98AT01k_hb6cRxoDfWZJAwzJZh44Gw-83fzZDbwbbixqrIHLTqJjIEkTDfGiIYNoLO4M1Ljm0mEapi1nwjVhAEwyUEKoB9IRsGJaH0a1Y7KGnaqDDiRJLkpI6YHDAKqVMdNucYE9p-q_GNgBMG1wIn5wIvNIYNodgvg7BBnuEB9cyYD3W9udEnuOT_15z0w4ViQdusTfIchwh1gKAY1WFRrTnRYNM6Zz7aYRB7AqAKaJJveiyZ1obnaNPUyNZRZhh8Z0Q1rval3KPsOPy2lWRLehe-pBur_esw2vEXC97ocXJcH8dy80IxyNbkL3lMNR14Ifrr_vO4FZPvxYoNawQYmaWax9di_39-m34zv2sOweNV_zl3c7EUxigvOY4CImuIwJnkUEFzEJ9neyM4PdferslWN2o7_HnPsaecw75xEru9n_7OCoBGlMcIw2yhjxlxHacJPm2cExRcki3tnNaGcHxwgpiyi3m2vODSYxCZIIbbhZ4OzgiIYlMV5HYrzOnX1nBL-cW2fG0jd2-c9_ARV01mA[Relationship graph for TST-002] macro |
|
verifies |
REQ-052 — Coverage chart via image::https://kroki.io/vegalite/svg/eJx1kU1TgzAQhu_8ip3UYy0dp3WUW61XL7Y3p4ctbNNVSCpZGDsd_ruTgAh-XAjZj2ffvHuJANSVS49UoEpAHUVOLonjmjTONMux2s_Yxm1BiF7nLBTXy9mrs0ZNfb-w5OS717amEjUlsN1sr-fzmzafoXj4JQIAUDXmFTmVwEu4QxcPuWfKUdga2J5PgVhTyQcmF0Bd0UZQKg9QGxR2B6ZMddkmnLsIoAmTCyzffOEey1YKmdRmbPS3nI_-F0AdmPLMN4yFfA1X0skytmCDeTu2adPqPCSh1iVplFCe2srIb8p7hUZYULimMSq1uS3_FNY9_l9FfcKlGJYycDezBbIZON_a2Zs4HYaf2DlvVB_bDVZQotH0EzRZzh_ubtdjzOTxfrFarAaY0ar8t4maT-0snvs[Coverage chart for TST-002] macro |
|
verifies |
REQ-055 — traceability:incoming[] macro renders incoming links |
|
verifies |
REQ-063 — Configurable Kroki image format |
|
verifies |
REQ-064 — Incoming macro respects document attributes |
|
verifies |
REQ-065 — Incoming macro display styles |
|
verifies |
REQ-066 — Incoming macro sort order |
|
verifies |
REQ-067 — Incoming groups use the reverse relation type |
|
verifies |
REQ-070 — Incoming macro supports collapsible output |
|
verifies |
REQ-071 — Relation display names are config-driven |
|
verifies |
REQ-100 — Inline macros suppressed when links macros are active |
|
verifies |
REQ-102 — Collapsible list-style output via document attribute |
|
verifies |
REQ-103 — Graph isolation per component version |
|
verifies |
REQ-104 — traceability:links[] macro renders combined outgoing and incoming links |
|
verifies |
REQ-108 — Matrix files registered in the content catalog |
|
verifies |
REQ-110 — Items defined in partials are registered in the graph |
|
verifies |
REQ-116 — Items carry component and module context from Antora |
|
verifies |
REQ-117 — Cross-module and cross-component xref includes correct prefix |
|
verifies |
REQ-119 — Cross-module and cross-component xref resolution |
|
verifies |
REQ-142 — Configurable Kroki server URL via extension config |
|
verifies |
REQ-143 — Kroki server URL via environment variable |
|
verifies |
REQ-144 — Partial items use view URL as source reference |
|
verifies |
REQ-145 — All processing passes apply to partial files |
|
verifies |
REQ-146 — Empty-state message when item has no outgoing relationships |
|
verifies |
REQ-159 — Configuration graph via image::https://kroki.io/graphviz/svg/eJyFkUFLwzAYhu_7FaFeK0yY4pAKdTt48CTehpQsedt-mCU1X7Y5xf8uW0uHpe1yTPI8-fK-mgovq1K8eakg12QoHBbO5lSIn4kQXtoPTT55eX2YCGGdhlhxKSska_cVCw4HgyTybms1dJyTMdBRLHJng5UbJNEzzA6BlIzejwboAmLVd1xDTN9Ibqanu5HH55Y8NrAhEqujXDnjfBJdzdL5dDlvmHpzX1JALIxcwyT_0FqmwVTYjud2-nR_txjxNFStCODuIMv5LJ2lI4ITU-NbRqYko6NIT2tE0XK1pvJOgTkbTueisU_RE_n1Y7eDNt2cLDgWGhWs5szZWChnc0MqcLanUHZSH1RJrT2YwT1AW1lbxvm1ZoQeqmmpYXbSkJYBOlsf_tU4ONEOnnJq1efWBgkDqTkLbqyg4eeaAfkS3U1DOcuk4duv_f4BgYdG4Q[Traceability configuration graph] macro |
|
verifies |
REQ-161 — Default display name is the humanized type |
|
verifies |
REQ-162 — No compile-time fallback |
Test file: test/cli.test.ts
Tests the Commander-based CLI — process command (valid content, empty content, invalid paths, malformed macros), matrix command (generation, empty graph), validate command (invalid graph state), export command (empty graph), stats command (empty statistics), preset commands (invalid names, init, listing), help command, and next-id command (sequential ID generation, padding preservation, prefix matching).
Relation |
ID |
Title |
verifies |
REQ-056 — CLI next-id command returns next available ID |
Test file: test/config-loader.test.ts
Tests the ConfigLoader — initialization, built-in preset listing and loading, preset structure validation (including pairwise matrix definitions), configuration loading from file, missing file handling, invalid YAML handling, role and relation validation, matrix definition retrieval, configuration merging (including label overrides), and error messages for invalid configurations and preset names.
Relation |
ID |
Title |
verifies |
REQ-083 — Preset defines pairwise requirements-to-design matrix |
|
verifies |
REQ-084 — Preset defines pairwise design-to-implementation matrix |
|
verifies |
REQ-085 — Preset defines pairwise requirements-to-tests matrix |
|
verifies |
REQ-086 — Preset does not define wide multi-column matrices |
|
verifies |
REQ-170 — Preset extends a parent by top-level |
|
verifies |
REQ-171 — Merge semantics match config-file |
|
verifies |
REQ-172 — Transitive inheritance |
|
verifies |
REQ-173 — Missing parent is reported |
|
verifies |
REQ-174 — Circular inheritance is rejected |
|
verifies |
REQ-175 — Relations are declared keyed with a mandatory reverse |
|
verifies |
REQ-177 — Reverse direction is derived for validation |
Test file: test/graph-and-api.test.ts
Tests the TraceabilityGraph (extended queries: merge, getRelatedItems, getItemsWithRelationTo, getRelationshipsByRoles, findPath, getImpactAnalysis) and graph visualization methods (toDot, toVegaLite, toConfigDot).
Tests graph integrity validation including circular reference detection (direct, indirect, self-referencing cycles, bidirectional pair exclusion), orphaned relationship detection with source location and expected-role hints, and invalid relation type reporting with allowed-relations hints.
Tests bidirectional relationship merge.
Also tests RequirementsTraceabilityExtension API methods (processFiles, validate, export, coverage, config access, preset management, lifecycle).
Relation |
ID |
Title |
verifies |
REQ-053 — Graph model supports traversal-bounded subgraph and coverage queries |
|
verifies |
REQ-109 — Circular reference detection in graph validation |
|
verifies |
REQ-129 — Bidirectional relationship pairs are merged into a single edge |
|
verifies |
REQ-160 — Config graph generator renders configuration as DOT |
|
verifies |
REQ-176 — Authoring the reverse name canonicalizes to the primary edge |
Test file: test/matrix-generator.test.ts
Tests the MatrixGenerator — basic matrix generation with empty graph, matrix generation with default and named configurations, role-based matrix rows and columns, coverage percentage calculation and status determination (done/partial/missing), coverage relation filtering, CSV export, HTML export, JSON export, coverage report generation, and edge cases (no matching items, missing titles, missing source files, unknown matrix names).
Relation |
ID |
Title |
verifies |
REQ-037 — Matrix displays row items as clickable links |
|
verifies |
REQ-038 — Matrix displays cell items as clickable links |
|
verifies |
REQ-039 — Links include source file tooltip |
|
verifies |
REQ-042 — Matrix renders correctly without link resolution configured |
|
verifies |
REQ-043 — Non-HTML matrix outputs unchanged |
|
verifies |
REQ-105 — Use-case role extends self-traceability preset |
|
verifies |
REQ-128 — Matrix links include module path for module-aware items |
|
verifies |
REQ-130 — Matrix links are compatible with Antora indexify URL style |
|
verifies |
REQ-167 — Matrix renders one status column per row |
|
verifies |
REQ-168 — Coverage summary remains |
|
verifies |
REQ-169 — CSV output is unchanged |
|
verifies |
REQ-178 — Matrix coverage matches the canonical primary type |
Test file: test/neo4j-exporter.test.ts
Tests the Neo4jExporter — empty graph CSV export, items and relationships in CSV, all attributes in export, special character escaping, empty graph Cypher export, items and relationships in Cypher, includeContent option, includeAllAttributes option, output directory creation, multiple role types, and export result counts and file paths.
Test file: test/relationship-link-substitution.test.ts
Tests the in-memory regex substitution that replaces relationship macros with Asciidoctor xrefs. Covers same-page xref generation, cross-page xref generation with basename path resolution, orphan reference handling, non-relationship text preservation, hyphenated/dotted IDs, missing sourceFile fallback, and surrounding text preservation.
Test file: test/query-command.test.ts
Tests the query CLI subcommand end-to-end — reverse (inbound relationships, empty results, unknown ID), impact (connected items, disconnected items), orphaned (relationship-less items, role filter), path (chain output, no path, unknown ID), and the --json flag (valid JSON, empty array).
Spawns the compiled CLI binary against a temporary fixture directory.
Relation |
ID |
Title |
verifies |
REQ-136 — CLI exposes a query subcommand |
|
verifies |
REQ-137 — query reverse — find all items that point at a given ID |
|
verifies |
REQ-138 — query impact — find all items connected to a given ID |
|
verifies |
REQ-139 — query orphaned — find items with no relationships |
|
verifies |
REQ-140 — query path — find the shortest path between two items |
|
verifies |
REQ-141 — JSON output flag |
Test file: test/antora-vale-extension.test.ts
Tests the bundled Vale prose-lint extension with fake vale and asciidoctor executables on PATH — page and partial findings with source path and line, severity gating (at-or-above fails the build, below is logged), opt-in behavior with no .adoc files, missing-executable failure messages, and that a multi-sentence source line produces no Vale finding.
Relation |
ID |
Title |
verifies |
REQ-151 — Vale lints page and partial source content during the build |
|
verifies |
REQ-152 — The build gates on a configurable minimum severity |
|
verifies |
REQ-154 — Missing executables fail with an actionable message |
|
verifies |
REQ-155 — The extension is opt-in |
|
verifies |
REQ-156 — Source layout is out of scope |