Import a traceability matrix with plune requirements links

Requirements documents often end with a table of requirement key to test. plune requirements links <file.md> imports that table as links between requirements and cases. It works in two steps, like plune requirements import: the file goes to Plune as it is, and you say which table and which two columns.

plune requirements links matrix.md                                                                      # lists the tables, exit 0
plune requirements links matrix.md --table 0 --requirement-column "Requirement" --test-column "Test"    # dry run
plune requirements links matrix.md --table 0 --requirement-column "Requirement" --test-column "Test" --yes

Step 1: list the tables

With no flags the command lists the tables in the file, each with its number, line, heading, headers and row count, and exits 0. Nothing is written.

Step 2: dry run, then apply

With --table <n>, --requirement-column <header> and --test-column <header> it is a dry run: the report is the one you get on --yes, and nothing is written. --yes applies it.

The report counts link (to make), unchanged (already linked) and unmatched, then lists the rows of each kind, unmatched first, with the line, the key, the test and the reason. A second import changes nothing.

How rows are matched

• A requirement is matched by its key. Import the requirements first. A cell with several keys is split by --separator (1 to 3 characters, default ,); nothing else is guessed.
• A test is matched by the exact title of a case. An automated case is also matched by its source path, e2e/login.spec.ts or e2e/login.spec.ts#title. Put several tests in one cell on separate lines (<br>).

A row that matches nothing is listed with a reason: an unknown key, an archived requirement, no such case, or a title that names several cases. Unmatched rows are an answer, not an error: the exit code is 0 unless you pass --fail-on-unmatched.

Limits: at most 2,000 rows after splitting, and a file of at most 1 MiB.

Note

It only links. A requirement’s coverage still comes from each case’s last result, not from the links.

Flags

Flag	Effect
--table <n>	The number of the table in the list. Needs the two column flags.
--requirement-column <header>	The column with the requirement keys.
--test-column <header>	The column with the tests: a case title or a source path.
--separator <text>	Splits a requirement cell into several keys. 1 to 3 characters, default ,. Needs --table.
--project <id>	The project. Default PLUNE_PROJECT, else the only project of the account.
--yes	Apply. Without it the import is a dry run.
--json	Print the platform’s answer as JSON. It lists every row; the text report shows the first 50 of each kind.
--fail-on-unmatched	Exit 1 when any row is unmatched.

Like pull and push, it needs a saved login or PLUNE_TOKEN.

Exit codes

Code	When
0	The tables or the report were printed, also with unmatched rows unless --fail-on-unmatched is set.
1	--fail-on-unmatched and at least one row is unmatched.
2	A bad flag, a file that cannot be read or is too large, or no token (run plune login or set PLUNE_TOKEN).