Skip to content
Tutorials Center
My learning

Topics

Lesson 46 of 50 ยท Projects

Project: A Requirements Traceability Tool

Build a small Node.js tool that links requirements to tests, finds coverage gaps and orphans, prints a report and answers change impact questions.

A requirement that nobody tests is a promise nobody checks. A test that matches no requirement may be testing something nobody wanted. Traceability is the practice of linking each requirement to the design elements, code and tests that deal with it, so that you can answer questions like "is everything we promised actually verified?" and "what must we re-test if this requirement changes?" In this project you will build the smallest useful traceability tool: it reads requirements and tests, computes the links, finds the gaps and prints a report.

You met the idea in the SRS lesson and the matrix in configuration and change management. Here you implement it. The programs run as Node.js examples on the site (single file, no packages). The requirements and tests are invented sample data, not a real project, and the tool is a teaching sketch: real teams get the same answers from a tracker such as Jira, a test management tool or annotations in a test framework.

Step 1: what the tool must do

Write the requirements for the tool itself first, in the style you have practiced. A good first list:

  1. Link: every test can declare which requirements it verifies; one test may cover several requirements, and one requirement usually needs several tests.
  2. Find gaps: list requirements with no test.
  3. Find orphans: list tests that cover no requirement, and links that point to a requirement that does not exist (a typo or a deleted requirement).
  4. Report status: per requirement, VERIFIED (all linked tests pass), FAILING (at least one fails) or UNTESTED.
  5. Gate a release: fail if any "must have" requirement is not VERIFIED.
  6. Report impact: given a changed requirement, list the tests to re-run.

Requirement priorities follow the MoSCoW idea (must, should, could); the gate cares most about the musts. Notice that the tool does not judge whether the tests are good. A requirement covered by one weak test shows as VERIFIED, so traceability measures links, never quality, and it should be combined with reviews and the techniques in test design.

What traceability connects

Requirement What was promised.
Design and code Where it is built.
Test How it is verified.
Release What shipped and when.

Links in both directions, forward from requirements and backward from tests.

1 / 2

Step 2: the data model

You need very little. A requirement has an id, a priority and a text. A test has a name, the list of requirement ids it covers, and a last result. Everything else (the matrix, the gaps, the status) is computed from those, which is a good rule for tools like this: store facts, derive reports. A derived value that is stored can go stale; a derived value that is computed cannot.

flowchart LR
    R1["REQ-1"] --- T1["test A"]
    R1 --- T2["test B"]
    R2["REQ-2"] --- T2
    R3["REQ-3"]
    T3["test C"]
    T4["test D"] --- R9["REQ-9 (does not exist)"]

Links form a many-to-many graph. REQ-3 has no test (a gap), test C has no requirement (an orphan) and test D points at a requirement that was never defined (a dangling link).

The three problem shapes in the picture are exactly what the tool must find. All three are common in real projects. Gaps appear when requirements are added without tests; orphans appear when features are built without a requirement (or when requirements are rewritten and the tests are not updated); dangling links appear after a requirement is renamed or deleted.

Step 3: build the matrix and the report

The first program holds the data inline and implements the checks. buildTrace goes through every test once and records which requirements it touches, collecting orphans and dangling links on the way. statusOf is a small decision function: no tests means untested, any failing test means failing, otherwise verified. The output is a table, a summary and a release gate.

Node.js Build the traceability matrix and report

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Read the output like a project manager. Only half of the requirements are verified. The gate fails, and it names the cause: REQ-3 is a "must" and one of its two tests fails (the reset link expiry). REQ-5 and REQ-6 are untested, but they are "should" and "could", so they do not block this release; a team might still decide to schedule them. The orphan test is "footer shows the year": harmless, but worth a look, since it may show that a requirement is missing or that the test is not needed. The dangling link REQ-9 is probably a typo or a requirement someone forgot to write down.

Now try changing things. Mark "reset link expires" as "pass" and the gate turns to PASS even though two requirements are untested. Add REQ-5 coverage with a new test and the verified count rises. Remove "REQ-9" from that login test's covers list and the dangling link disappears. Each change shows how the report responds, which is exactly how a team would use it before a release.

Hand-typed arrays do not scale. In real projects the information lives in text: a requirements document, comments or annotations in test files, and a test report. The second program parses all three with regular expressions:

  • requirement lines of the form - REQ-10 [must] The system shall ...;
  • a // covers: REQ-10, REQ-11 comment in front of each test;
  • result lines such as PASS test name or FAIL test name.

It then prints a Markdown table (the report output could go straight into a pull request or wiki page) and adds an impact query: given a changed requirement, which tests must be re-run, and which other requirements share those tests? The test source here is only a string and is never executed; real tools read it from files, and annotation styles differ between frameworks.

Node.js Parse requirements and tests, then ask about impact

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Notice a subtle result: REQ-10 shows as failing even though its own card test passes, because the receipt test also lists it and that test fails. This is correct (a test that covers a requirement and fails is evidence against it), but it also shows a weakness of linking tests loosely: a test that covers many requirements is a coarse tool. Teams often fix this by keeping tests small and focused, with one or two requirements each.

The impact query also shows why traceability pays off during change management. If REQ-11 changes, you know to re-run the receipt test and that REQ-10 shares it, so a change to the receipt may disturb the payment story. If REQ-13 changes, the tool tells you there is nothing to re-run, which is a warning in itself: change a requirement with no test and nobody will notice if the new behavior breaks.

Step 5: harden and extend

The tool is intentionally small. These extensions turn it into something you could use, and each is a good small project:

  1. Strict parsing: report requirement lines that look like - REQ- but do not match the pattern, and duplicate requirement ids. Silent skipping is the worst failure of a parser.
  2. Design and code links: add implementedBy links from requirements to source files or modules, then find requirements without implementation and modules without requirement. Compare this with the class diagrams from the library project.
  3. Status over time: store each run's result and print a trend: how many musts were verified at each release?
  4. Parent and child requirements: a high-level requirement is verified only when all its children are. Compute this recursively and watch for cycles.
  5. Exit codes: in a real pipeline the tool should end the process with a non-zero exit code when the gate fails, so a CI pipeline can block the release automatically.
  6. Staleness: flag requirements changed after their tests last ran. This needs dates, so decide where they come from (the version control history is a good source).

Limits of traceability

Traceability is easy to do badly. Heavy formal matrices that nobody reads cost effort without value, and teams sometimes link tests to requirements just to turn the report green. A few guidelines keep it honest:

  • Automate the links. If a person must update a spreadsheet after every change, it will fall out of date. Derive links from annotations, naming conventions or the tracker.
  • Trace what matters. Safety, legal and security requirements justify strict traceability; a cosmetic setting may not.
  • Distrust a perfect score. 100% coverage of links says every requirement has a test, not that the tests are good, or that the requirements are right.
  • Keep requirements testable. A vague requirement ("the system shall be fast") cannot be covered by any single test. Rewrite it, as shown in functional and non-functional requirements.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What is an orphan test in a traceability report?

    An orphan test is not linked to any requirement. It may be testing something nobody asked for, or a requirement may be missing.
  2. 2. Why should reports such as the matrix and the status be computed rather than stored?

    Store the facts (requirements, tests, results, links) and derive the rest, so the report cannot disagree with the data.
  3. 3. A requirement shows 100% VERIFIED in the report. What does that prove?

    Traceability measures links and results. It says nothing about test quality or whether the requirement is the right one.
  4. 4. In the second program, why does REQ-10 show as failing although its card payment test passes?

    Any failing test linked to a requirement makes its status failing. A test that covers several requirements spreads its failure to all of them.
  5. 5. A dangling link is best described as which of these?

    Dangling links usually come from typos or from requirements that were renamed or deleted without updating the tests.

Summary

  • Traceability links requirements to design, code and tests in both directions, so you can find gaps, orphans and the impact of a change.
  • Store the facts (requirements, tests, links, results) and compute the rest: status per requirement, coverage, gaps, orphan tests and dangling links.
  • A release gate can require every "must" requirement to be verified; the tool reports links and results, not the quality of the tests.
  • Parsing links from text (requirement lines, covers annotations, test reports) keeps the matrix current without manual spreadsheets.
  • Impact queries tell you which tests to re-run after a requirement changes, and warn you when none exist.

Next: Project: An Architecture Review and ADR.