ek9_anchor_test

Rewrites the @Test directive line above the program to '@Test: "REQ:x"' (the execution group kept); answers status, edits[] and summary, an unchanged directive as conflicts[] (already-anchored).

Category: Editor · Compare: Anchor Test to Requirement

When to use it

'Anchor test VelocityBreachesAboveFive to REQ:velocity-limit' is one call with file, symbol (the @Test program) and requirementId - omit it to clear.

When not to use it

The test does not exist yet - use ek9_add_program (isTest:true, requirementId:…) to create it already anchored, rather than create-then-anchor.
You want to change the requirement itself, not which test proves it - use ek9_update_requirement (anchors live on the @Test; requirement nodes never list their tests).
The requirement node does not exist - use ek9_create_requirement (you may anchor first; it reports as a dangling anchor until created).

Details

Cursor-free: symbol is resolved through the symbol table, not by searching source text. The execution group survives — @Test: "database" becomes @Test: "REQ:x": "database" (id first, group second), read from the compiler's parsed TEST_DIRECTIVE so a serialised test is never silently rescheduled to the parallel pool. The requirement need not exist yet (dangling anchor, not faulted), but a mistyped prefix like RREQ:foo is rejected — it would otherwise pass as a legal execution GROUP name and silently drop the anchor; status:'error' when no such @Test in the file or no directive line above it (recompile); a directive that already reads as requested is conflicts[] kind 'already-anchored'.

Arguments

Argument	Type	Required	What it is
`file`	string	yes	The dev source holding the @Test program (workspace-relative; an absolute path inside the workspace is accepted).
`requirementId`	string		Requirement id to anchor to, e.g. 'REQ:velocity-limit'. Omit to CLEAR the anchor, leaving a plain @Test.
`symbol`	string	yes	The @Test program's name, e.g. 'VelocityBreachesAboveFive' - a @Test program declared in this file.

It also takes the arguments every tool takes.

Recorded calls

Real calls, recorded against small projects and checked on every build - a changed answer fails it. 3 of the 5 recorded are shown.

Anchor malformed rejected

Request

{
  "file" : "dev/tests.ek9",
  "requirementRef" : "RREQ:velocity-limit",
  "symbol" : "PlainTest"
}

Response

{
  "conflicts" : [ ],
  "edits" : [ ],
  "error" : {
    "message" : "'RREQ:velocity-limit' is not a valid requirement id. Expected <PREFIX>:<slug> with PREFIX one of REQ, CTRL, CAP, CON and slug matching [a-z0-9-]+, e.g. 'REQ:velocity-limit'."
  },
  "meta" : {
    "serverMs" : "<timing>"
  },
  "status" : "error",
  "summary" : "'RREQ:velocity-limit' is not a valid requirement id. Expected <PREFIX>:<slug> with PREFIX one of REQ, CTRL, CAP, CON and slug matching [a-z0-9-]+, e.g. 'REQ:velocity-limit'.",
  "wouldBeDiagnostics" : [ ],
  "written" : false
}

Anchor unknown test rejected

Request

{
  "file" : "dev/tests.ek9",
  "requirementRef" : "REQ:velocity-limit",
  "symbol" : "NoSuchTest"
}

Response

{
  "conflicts" : [ ],
  "edits" : [ ],
  "error" : {
    "message" : "No @Test program named 'NoSuchTest' is declared in dev/tests.ek9. Anchoring rewrites an existing test's directive — to create a new anchored test use ek9_add_program with isTest: true."
  },
  "meta" : {
    "serverMs" : "<timing>"
  },
  "status" : "error",
  "summary" : "No @Test program named 'NoSuchTest' is declared in dev/tests.ek9. Anchoring rewrites an existing test's directive — to create a new anchored test use ek9_add_program with isTest: true.",
  "wouldBeDiagnostics" : [ ],
  "written" : false
}

Anchor plain test apply

Request

{
  "file" : "dev/tests.ek9",
  "requirementRef" : "REQ:velocity-limit",
  "symbol" : "PlainTest"
}

Response

{
  "conflicts" : [ ],
  "edits" : [ {
    "after" : "    @Test: \"REQ:velocity-limit\"",
    "before" : "    @Test",
    "endLine" : 9,
    "file" : "dev/tests.ek9",
    "startLine" : 9,
    "type" : "replace"
  } ],
  "meta" : {
    "serverMs" : "<timing>"
  },
  "resolvedPath" : "<workspace-root>/dev/tests.ek9",
  "risk" : {
    "crossesModuleBoundary" : false,
    "estimatedSeverity" : "trivial",
    "fileCount" : 1,
    "lineCount" : 1,
    "touchesPublicApi" : false,
    "touchesTests" : true
  },
  "status" : "applied",
  "summary" : "Anchor PlainTest to REQ:velocity-limit",
...

Cut short here: 4 more lines. The whole recorded call.