Architecture Note: Designing qTest Requirement Traceability for Reliable Impact Analysis

Requirements

The primary goal of qTest's requirement traceability matrix (RTM) is to maintain a bidirectional link between each requirement and the test cases that verify it. This enables impact analysis when a requirement changes, supports audit trails, and helps teams avoid orphaned test cases. The RTM must:

• Store a foreign‑key relationship from test_case.id to requirement.id.
• Allow a test case to be linked to zero, one, or many requirements (optional links).
• Provide fast lookup of all test cases for a given requirement and vice‑versa.
• Support pagination for result sets that may exceed typical page sizes.

Smallest Suitable Design

A minimal implementation satisfies the above with three tables:

1. requirement (id, …)
2. test_case (id, …)
3. requirement_test_case (requirement_id, test_case_id) – a join table with foreign keys to both parent tables.

The join table enforces referential integrity; each row represents a single link. Indexes on both foreign‑key columns enable efficient look‑ups in either direction. For pagination, the platform’s REST API uses cursor‑based tokens returned in the Link header, avoiding costly OFFSET scans on large join tables.

Trust/Data Boundaries

Data entering the RTM originates from two trusted sources:

• Requirement creation/editing via the qTest UI or approved integration scripts.
• Test case creation/editing through the same channels.

All modifications must pass through the qTest service layer, which validates that referenced IDs exist before inserting rows into requirement_test_case. The service layer is the trust boundary; external callers (e.g., CI pipelines) interact only via the REST API and cannot bypass integrity checks.

Operational Checks

To detect drift, a nightly sync job runs the following steps:

1. Query the join table for rows where either foreign key points to a non‑existent parent (using LEFT JOIN and filtering for NULL).
2. Log any orphaned rows and raise an alert if the count exceeds a configurable threshold (e.g., >0).
3. Optionally, automatically delete orphaned rows after a manual review window.

Administrators can verify the job’s output by inspecting the qTest audit log for entries labeled RTM_INTEGRITY_CHECK. A successful run returns zero orphaned entries.

Failure Modes

Despite the design, several failure modes can appear:

• Missing requirement IDs: If a requirement is deleted without first removing its links, the join table retains orphaned rows, causing test execution gaps when impact analysis assumes the requirement still exists.
• Performance degradation: With >10,000 links, cursor‑based pagination still incurs extra network round‑trips; UI latency may rise noticeably.
• API rate‑limit throttling: Bulk updates (e.g., mass re‑linking after a requirement refactor) can hit the platform’s per‑minute request limit, leading to HTTP 429 responses.

Mitigations include:

• Enabling the "requirement‑less" test mode, which allows test cases to exist without any link, preventing forced deletions.
• Archiving requirements older than a defined retention period (e.g., 18 months) and removing their links before deletion.
• Implementing exponential backoff and jitter in client‑side retry logic when encountering 429 responses.

Conditions That Would Change the Design

The current design would be revisited if any of the following conditions become true:

• The organization adopts a many‑to‑many relationship where a single test case must be linked to multiple requirement versions (e.g., baseline vs. variant). This would require version‑aware foreign keys or a separate linking table.
• Regulatory audits demand immutable traceability history, necessitating an append‑only log of link changes rather than mutable joins.
• Performance testing shows that cursor‑based pagination still exceeds acceptable latency at >100,000 links, prompting a shift to a specialized graph store or materialized view tables.

Practical Verification Example

To confirm that the RTM returns correctly paginated data for a given requirement, run the following request from a workstation with API access:

curl -H "Authorization: Bearer $QTEST_TOKEN" \
     "https://yourcompany.qtest.com/api/v1/traceability?requirementId=REQ-1234" \
     -i

Required permissions: the token must belong to a user with the "View Requirements" and "View Test Cases" roles. Expected checks:

• Response status 200.
• Presence of a Link header with rel="next" if more rows exist.
• Body JSON containing an array of test case objects, each with id and name fields.
• If the header indicates a next page, repeat the request using the cursor token from that header and verify that no duplicate test case IDs appear across pages.

Risks: issuing many rapid requests may trigger rate‑limit throttling; mitigate by pausing between pages or using the backoff strategy described earlier.

As a complementary check, export the full RTM to CSV via the UI (Reports → Export Traceability Matrix) and verify that every test_case_id appears alongside its corresponding requirement_id with no missing or extra rows.