Requirements Traceability with Aqua ALM

Requirements traceability answers one question: if this requirement fails, which tests will catch it? Without a formal traceability model, the answer is usually "hope so." Aqua ALM's traceability system lets you answer it precisely -- linking each requirement to the test cases that verify it, tracking execution status against those links, and generating audit-ready reports that show coverage gaps before they become production incidents.

How Aqua ALM Models Requirements

Requirements in Aqua ALM are first-class objects with their own fields, status workflows, and hierarchy. They are not just tags on a test case -- they are records you can import, edit, and version separately from tests.

A requirement record includes:

• ID and title -- system-assigned ID plus a human-readable title
• Description -- rich text describing what the system must do
• Status -- workflow state (Draft, Under Review, Approved, Obsolete)
• Type -- Functional, Non-Functional, Business Rule, etc. (configurable)
• Version -- requirements can have versions, useful when specs change over time
• Custom fields -- priority, source document, owner, risk level

Requirements live in a folder hierarchy, mirroring the test case folder structure. A typical project might organize requirements by feature area or by specification document section.

Importing Requirements

Most teams start with requirements in some external format -- a Word doc, a Confluence page, or a spreadsheet. Aqua ALM supports importing requirements from:

• Excel/CSV -- map columns to Aqua fields during import
• Word documents -- with the document import add-on
• Jira -- via the Jira connector (covered separately)
• REST API -- for custom integrations with requirement management tools

For a CSV import, prepare columns for at minimum: title, description, and status. Run the import under a specific folder to keep imported requirements organized.

Linking Requirements to Test Cases

Once requirements exist, linking them to test cases is straightforward. Open a test case, go to the Requirements tab, and click Add Requirement. Search by ID or title, select the requirement, and save.

The link is bidirectional -- you can also navigate from a requirement to see all linked test cases. A single test case can link to multiple requirements, and a single requirement can have multiple test cases linked to it.

Aqua enforces no rules about what ratio is "correct," but common patterns include:

• One-to-one -- each acceptance criterion maps to exactly one test case. Clean, but can create many test cases.
• One-to-many -- one requirement covered by a happy path test, a negative test, and an edge case test. More complete.
• Many-to-many -- cross-cutting requirements (like "all forms must validate input") linked to multiple test cases across different features.

The Coverage Matrix

The coverage matrix is the central traceability view. It shows requirements as rows and linked test cases as columns, with execution status in each cell.

Navigate to Reports > Requirements Coverage to open it. Configure it by:

1. Selecting which requirements folder to include
2. Selecting which test run or test run group to evaluate execution against
3. Optionally filtering by requirement status (only show Approved requirements)

The matrix output shows each requirement with a coverage indicator:

• Covered -- has at least one linked test case
• Not Covered -- no linked test cases at all
• Passed -- all linked test cases passed in the selected run
• Failed -- at least one linked test case failed
• Not Executed -- linked test cases exist but have not been run

A requirement marked "Not Covered" is a gap in your test suite. A requirement marked "Not Executed" means you have written the test but not run it -- a different kind of gap. The matrix makes both visible at once.

Impact Analysis When Requirements Change

When a requirement changes -- scope shifts, acceptance criteria update, behavior changes -- you need to know which tests are affected. Aqua's traceability links give you this automatically.

Open the changed requirement and look at its linked test cases. Those are the tests you must review and potentially update. Aqua does not automatically flag test cases as "needs review" when a requirement changes, but you can add a custom field to test cases (like "Review Required" with a boolean value) and set it manually when changes occur.

A more systematic approach:

1. When a requirement changes, update its status to "Under Review"
2. Find all linked test cases (visible from the requirement record)
3. Update each test case's "Review Required" field to Yes
4. After reviewing and updating the test case, set "Review Required" back to No
5. Update the requirement status back to "Approved" once all linked tests are reviewed

This creates an audit trail: you can filter test cases by "Review Required = Yes" to see what still needs attention after a requirement change batch.

Traceability Reports

Beyond the coverage matrix, Aqua provides several traceability-specific reports:

Requirement Traceability Report -- For each requirement, lists all linked test cases with their current execution status. Export to PDF for audit submissions or sign-off meetings.

Untested Requirements Report -- Filters to requirements with no executed test cases. Run this at the end of each test cycle to identify coverage gaps before releasing.

Defect-to-Requirement Traceability -- If defects are logged against test cases, this report traces from requirement through test case to defect. Useful for root cause analysis and understanding which requirements are generating the most bugs.

For regulated industries, Aqua's traceability reports can satisfy audit requirements like IEC 62304 (medical software), DO-178C (aviation), or ISO 26262 (automotive). The report format is typically configured during initial setup to match what the auditor expects.

Integrating External Requirement Sources

Teams that manage requirements in Confluence or a dedicated ALM tool like IBM DOORS can integrate with Aqua through the REST API. The general pattern:

1. Export requirements from the source tool as JSON or CSV
2. POST to Aqua's requirement API endpoint to create or update records
3. Include a custom field storing the external requirement ID
4. Sync on a schedule (nightly or on change event) to keep Aqua updated

This keeps Aqua as the test management layer while the authoring team continues working in their preferred requirements tool. The traceability links live in Aqua; the requirement content syncs from the source.

For Jira specifically, Aqua's native connector handles this synchronization without custom scripting -- Jira stories or epics appear as requirements in Aqua, linked to test cases, with status flowing back to Jira.

Build and review your coverage matrix before each release cycle. Requirements with no test coverage or with only failing tests are the risk items that need attention first.