Traceability Matrix#

Matrix generation and format rendering.

Generator#

jamb.matrix.generator.build_test_records(coverage, manual_tc_ids=None, tc_id_prefix='TC')[source]#

Transform coverage data to test-centric records.

Collects all tests linked to items in the coverage data and produces a list of TestRecord objects sorted by the first requirement UID (alphabetically), with nodeid as tiebreaker.

For parameterized tests, all parameter variations share a base TC number with alphabetic suffixes (TC001a, TC001b, etc.).

Parameters:

  • coverage (dict[str, ItemCoverage]) – Coverage data mapping UIDs to ItemCoverage.

  • manual_tc_ids (dict[str, str] | None) – Optional dict mapping nodeid to manual TC ID.

  • tc_id_prefix (str) – Prefix for auto-generated TC IDs (default: “TC”).

Returns:

list[TestRecord] – List of TestRecord objects, one per unique test.

Return type:

list[TestRecord]

jamb.matrix.generator.build_test_id_mapping(coverage, manual_tc_ids=None, tc_id_prefix='TC')[source]#

Build a mapping from test nodeid to TC ID.

Uses the same sorting logic as build_test_records to ensure consistent TC numbering across test records and trace matrices.

For parameterized tests, all parameter variations share a base TC number with alphabetic suffixes (TC001a, TC001b, etc.).

Manual TC IDs (from @pytest.mark.tc_id) take precedence. IDs matching the configured prefix pattern reserve that number from auto-generation.

Parameters:

  • coverage (dict[str, ItemCoverage]) – Coverage data mapping UIDs to ItemCoverage.

  • manual_tc_ids (dict[str, str] | None) – Optional dict mapping nodeid to manual TC ID.

  • tc_id_prefix (str) – Prefix for auto-generated TC IDs (default: “TC”).

Returns:

dict[str, str] – Dict mapping test nodeid to TC ID (e.g., “test.py::test_foo” -> “TC001”).

Return type:

dict[str, str]

jamb.matrix.generator.generate_test_records_matrix(records, output_path, output_format='html', metadata=None)[source]#

Generate test records matrix in specified format.

Parameters:

  • records (list[TestRecord]) – List of TestRecord objects to render.

  • output_path (str) – Path to write the output file.

  • output_format (str) – Output format: “html”, “markdown”, “json”, “csv”, or “xlsx”.

  • metadata (MatrixMetadata | None) – Optional matrix metadata for IEC 62304 5.7.5 compliance.

Return type:

None

jamb.matrix.generator.generate_full_chain_matrix(coverage, graph, output_path, output_format, trace_from, include_ancestors=False, tc_mapping=None, trace_to_ignore=None, all_test_links=None)[source]#

Generate full chain trace matrix starting from a document prefix.

Creates a matrix showing complete traceability from a starting document through the hierarchy to tests. When the starting document has multiple child paths (diverging hierarchy), generates multiple tables.

Parameters:

  • coverage (dict[str, ItemCoverage]) – Coverage data for test spec items.

  • graph (TraceabilityGraph) – The full traceability graph for traversal.

  • output_path (str) – Path to write the output file.

  • output_format (str) – Output format: “html”, “markdown”, “json”, “csv”, or “xlsx”.

  • trace_from (str) – Starting document prefix (e.g., “UN”, “SYS”, “PRJ”).

  • include_ancestors (bool) – If True, add “Traces To” column showing ancestors.

  • tc_mapping (dict[str, str] | None) – Optional mapping from test nodeid to TC ID for display.

  • trace_to_ignore (set[str] | None) – Set of document prefixes to exclude from the matrix.

  • all_test_links (dict[str, list[LinkedTest]] | None) – Optional dict mapping UIDs to LinkedTest lists for tests linked to higher-order items not in coverage.

Raises:

ValueError – If trace_from prefix is not found or format is unknown.

Return type:

None

Chain Builder#

jamb.matrix.chain_builder.build_full_chain_matrix(graph, coverage, start_prefix, include_ancestors=False, trace_to_ignore=None, all_test_links=None)[source]#

Build full chain matrices from starting document.

Returns one FullChainMatrix per unique document path from the starting document to leaf documents.

Parameters:

  • graph (TraceabilityGraph) – The traceability graph.

  • coverage (dict[str, ItemCoverage]) – Coverage data mapping UIDs to ItemCoverage.

  • start_prefix (str) – Document prefix to start tracing from.

  • include_ancestors (bool) – Whether to include “Traces To” column.

  • trace_to_ignore (set[str] | None) – Set of document prefixes to exclude from output. Documents in this set will be filtered from the hierarchy columns and from the “Traces To” ancestor UIDs.

  • all_test_links (dict[str, list[LinkedTest]] | None) – Optional dict mapping UIDs to LinkedTest lists for tests linked to higher-order items not in coverage.

Returns:

list[FullChainMatrix] – List of FullChainMatrix objects, one per unique path. If start document has diverging children, returns multiple matrices.

Raises:

ValueError – If start_prefix is not found in document hierarchy.

Return type:

list[FullChainMatrix]

HTML Format#

jamb.matrix.formats.html.render_test_records_html(records, metadata=None)[source]#

Render test records as HTML test records matrix.

Parameters:

  • records (list[TestRecord]) – List of TestRecord objects to render.

  • metadata (MatrixMetadata | None) – Optional matrix metadata for IEC 62304 5.7.5 compliance.

Returns:

str – A string containing a complete HTML document with embedded CSS, including a summary statistics banner and a styled table of all test records.

Return type:

str

jamb.matrix.formats.html.render_full_chain_html(matrices, tc_mapping=None)[source]#

Render full chain trace matrices as HTML.

Parameters:

  • matrices (list[FullChainMatrix]) – List of FullChainMatrix objects to render.

  • tc_mapping (dict[str, str] | None) – Optional mapping from test nodeid to TC ID for display.

Returns:

str – A string containing a complete HTML document with all matrices.

Return type:

str

Markdown Format#

jamb.matrix.formats.markdown.render_test_records_markdown(records, metadata=None)[source]#

Render test records as Markdown.

Parameters:

  • records (list[TestRecord]) – List of TestRecord objects to render.

  • metadata (MatrixMetadata | None) – Optional matrix metadata for IEC 62304 5.7.5 compliance.

Returns:

str – A string containing a Markdown document with a metadata section, summary section, and a pipe-delimited table of all test records.

Return type:

str

jamb.matrix.formats.markdown.render_full_chain_markdown(matrices, tc_mapping=None)[source]#

Render full chain trace matrices as Markdown.

Parameters:

  • matrices (list[FullChainMatrix]) – List of FullChainMatrix objects to render.

  • tc_mapping (dict[str, str] | None) – Optional mapping from test nodeid to TC ID for display.

Returns:

str – A string containing Markdown with all matrices.

Return type:

str

JSON Format#

jamb.matrix.formats.json.render_test_records_json(records, metadata=None)[source]#

Render test records as JSON for machine processing.

Parameters:

  • records (list[TestRecord]) – List of TestRecord objects to render.

  • metadata (MatrixMetadata | None) – Optional matrix metadata for IEC 62304 5.7.5 compliance.

Returns:

str – A string containing pretty-printed JSON with a metadata object (if provided), a summary object (totals and pass rate), and a tests array.

Return type:

str

jamb.matrix.formats.json.render_full_chain_json(matrices, tc_mapping=None)[source]#

Render full chain trace matrices as JSON.

Parameters:

  • matrices (list[FullChainMatrix]) – List of FullChainMatrix objects to render.

  • tc_mapping (dict[str, str] | None) – Optional mapping from test nodeid to TC ID for display.

Returns:

str – A string containing pretty-printed JSON with all matrices.

Return type:

str

CSV Format#

jamb.matrix.formats.csv.render_test_records_csv(records, metadata=None)[source]#

Render test records as CSV.

Parameters:

  • records (list[TestRecord]) – List of TestRecord objects to render.

  • metadata (MatrixMetadata | None) – Optional matrix metadata for IEC 62304 5.7.5 compliance.

Returns:

str – A string containing CSV data with metadata rows (if provided), a header row, and one row per test record.

Return type:

str

jamb.matrix.formats.csv.render_full_chain_csv(matrices, tc_mapping=None)[source]#

Render full chain trace matrices as CSV.

Parameters:

  • matrices (list[FullChainMatrix]) – List of FullChainMatrix objects to render.

  • tc_mapping (dict[str, str] | None) – Optional mapping from test nodeid to TC ID for display.

Returns:

str – A string containing CSV data with all matrices.

Return type:

str

XLSX Format#

jamb.matrix.formats.xlsx.render_test_records_xlsx(records, metadata=None)[source]#

Render test records as Excel test records matrix.

Parameters:

  • records (list[TestRecord]) – List of TestRecord objects to render.

  • metadata (MatrixMetadata | None) – Optional matrix metadata for IEC 62304 5.7.5 compliance.

Returns:

bytes – Bytes containing an XLSX workbook with a styled header, metadata section, summary section, and color-coded outcome cells.

Return type:

bytes

jamb.matrix.formats.xlsx.render_full_chain_xlsx(matrices, tc_mapping=None)[source]#

Render full chain trace matrices as Excel workbook.

Parameters:

  • matrices (list[FullChainMatrix]) – List of FullChainMatrix objects to render.

  • tc_mapping (dict[str, str] | None) – Optional mapping from test nodeid to TC ID for display.

Returns:

bytes – Bytes containing an XLSX workbook with all matrices.

Return type:

bytes