pytest Plugin#

pytest integration for requirements traceability.

Plugin Hooks#

jamb.pytest_plugin.plugin.pytest_addoption(parser)[source]#

Register jamb command-line options with pytest.

Registers the following options: --jamb, --jamb-fail-uncovered, --jamb-test-matrix, --jamb-trace-matrix, and --jamb-documents.

Parameters:

parser (Parser) – The pytest argument parser to add options to.

Return type:

None

jamb.pytest_plugin.plugin.pytest_configure(config)[source]#

Register the requirement marker and initialize the jamb collector plugin.

Registers the requirement marker for linking tests to requirement UIDs and creates a RequirementCollector instance when --jamb is enabled.

Parameters:

config (Config) – The pytest configuration object.

Return type:

None

jamb.pytest_plugin.plugin.pytest_sessionfinish(session, exitstatus)[source]#

Generate reports and check coverage after the test session completes.

Generates test records matrix when --jamb-test-matrix or the test_matrix_output config option is set. Generates traceability matrix when --jamb-trace-matrix or the trace_matrix_output config option is set. Sets the exit status to failure when --jamb-fail-uncovered or fail_uncovered in the config is enabled and any test spec items lack coverage.

For all options, CLI flags take precedence over [tool.jamb] config values, which take precedence over hardcoded defaults.

Parameters:

  • session (Session) – The pytest session object.

  • exitstatus (int) – The exit status of the test run.

Return type:

None

jamb.pytest_plugin.plugin.jamb_log(request)[source]#

Fixture to log custom messages for the traceability matrix.

Example:

@pytest.mark.requirement("SRS001")
def test_validation(jamb_log):
    jamb_log.note("Verified input validation with boundary values")
    assert validate_input(-1) is False
Return type:

JambLog

Parameters:

request (FixtureRequest)

Collector#

class jamb.pytest_plugin.collector.RequirementCollector[source]#

Collects test-to-requirement mappings during pytest execution.

pytest_config#

The pytest configuration object.

Type:

pytest.Config

jamb_config#

Loaded jamb configuration (JambConfig).

Type:

JambConfig

graph#

The traceability graph built from stored documents, or None if loading failed.

Type:

TraceabilityGraph | None

Accumulated test-to-requirement links recorded during collection and execution.

Type:

list[LinkedTest]

unknown_items#

UIDs referenced in test markers that do not exist in the traceability graph.

Type:

set[str]

__init__(config)[source]#

Initialize the requirement collector.

Loads the jamb configuration and the traceability graph from the native storage layer.

Parameters:

config (Config) – The pytest configuration object.

Return type:

None

pytest_collection_modifyitems(items)[source]#

Collect requirement markers from all test items.

Extracts requirement UIDs from markers on each test item and records them as LinkedTest entries. Yields control for collection to complete first.

Parameters:

items (list[Item]) – The list of pytest test items collected for the session.

Return type:

Generator[None, None, None]

pytest_runtest_makereport(item, call)[source]#

Record test outcomes, notes, test actions, and expected results.

Captures the test outcome and data from the jamb_log fixture, including failure messages and skip reasons, and updates all LinkedTest entries for the test.

Parameters:

  • item (Item) – The pytest test item that was executed.

  • call (CallInfo[None]) – The call information for the test phase.

Return type:

Generator[None, Any, None]

get_coverage()[source]#

Build coverage report for all items in test documents.

Returns:

dict[str, ItemCoverage] – A dict mapping item UIDs to ItemCoverage objects for items in the configured test documents.

Return type:

dict[str, ItemCoverage]

all_test_items_covered()[source]#

Check if all normative items in test documents have test coverage.

When require_all_pass is enabled (the default), an item is only considered covered if it has linked tests and all of those tests passed.

Returns:

bool – True if every active requirement item meets the coverage criteria, False otherwise.

Return type:

bool

generate_test_records_matrix(path, output_format, tester_id='Unknown', software_version=None)[source]#

Generate test records matrix.

Parameters:

  • path (str) – The output file path for the generated matrix.

  • output_format (str) – The output format (html, markdown, json, csv, or xlsx).

  • tester_id (str) – Identification of the tester or CI system.

  • software_version (str | None) – Software version override (takes precedence over config).

Return type:

None

generate_trace_matrix(path, output_format, trace_from=None, include_ancestors=False)[source]#

Generate traceability matrix.

Parameters:

  • path (str) – The output file path for the generated matrix.

  • output_format (str) – The output format (html, markdown, json, csv, or xlsx).

  • trace_from (str | None) – Starting document prefix for trace matrix. If not provided, auto-detects the root document.

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

Return type:

None

save_coverage_file(output_path='.jamb', tester_id='Unknown', software_version=None)[source]#

Save coverage data to .jamb file for later matrix generation.

This allows running tests once and generating multiple matrix views without re-running the tests.

Parameters:

  • output_path (str) – Path to write the coverage file (default: .jamb).

  • tester_id (str) – Identification of the tester or CI system.

  • software_version (str | None) – Software version override.

Return type:

None

Markers#

jamb.pytest_plugin.markers.get_requirement_markers(item)[source]#

Extract requirement item UIDs from a test item’s markers.

Supports @pytest.mark.requirement(‘UT001’, ‘UT002’, …).

Parameters:

item (Item) – A pytest test item.

Returns:

list[str] – List of requirement item UIDs found in requirement markers. Duplicates within the same test are removed while preserving order.

Raises:

  • TypeError – If a marker argument is not a string.

  • ValueError – If a marker argument is empty or whitespace-only.

Return type:

list[str]

JambLog#

class jamb.pytest_plugin.log.JambLog[source]#

Collector for custom test messages to include in traceability matrix.

Usage in tests:

@pytest.mark.requirement("SRS001")
def test_something(jamb_log):
    jamb_log.note("Custom verification note")
    jamb_log.test_action("Entered valid credentials")
    jamb_log.expected_result("Login succeeds")
    result = do_something()
    jamb_log.actual_result(f"Got: {result}")
    assert something
__init__()[source]#
Return type:

None

note(msg)[source]#

Log a custom note to be included in the traceability matrix.

Parameters:

msg (str) – The note to log. Will appear in the matrix output for any requirement markers on this test.

Return type:

None

test_action(action)[source]#

Log a test action to be included in the traceability matrix.

Parameters:

action (str) – Description of a test action performed. Will appear in the “Test Actions” column.

Return type:

None

expected_result(result)[source]#

Log an expected result to be included in the traceability matrix.

Parameters:

result (str) – Description of an expected result. Will appear in the “Expected Results” column.

Return type:

None

actual_result(result)[source]#

Log an actual result to be included in the traceability matrix.

Parameters:

result (str) – Description of an actual result observed during test execution. Will appear in the “Actual Results” column.

Return type:

None

property notes: list[str]#

Return all logged notes.

property test_actions: list[str]#

Return all logged test actions.

property expected_results: list[str]#

Return all logged expected results.

property actual_results: list[str]#

Return all logged actual results.