Headings and Prose

Heading hierarchy (#, ##, ###, ...) is converted into a test suite hierarchy. Prose paragraphs are preserved in the HTML report but are not execution targets.

Executable Blocks

Executable blocks are fenced code blocks whose info string starts with a recognized prefix.

The <target> is defined by the adapter, not the core. Blocks whose content starts with $ lines are auto-detected as doctest-style and run each command individually with inline output comparison.

The parser must recognize run as the executable block kind.

Other prefixes (e.g. verify:, test:) are not recognized and produce plain, non-executable code blocks. A spec containing only unrecognized blocks has zero cases. Unrecognized prefixes emit a warning to stderr so typos like runn:shell are caught early.

To suppress warnings for specific prefixes, add ignorePrefixes to specdown.json. Plain info strings without a colon (e.g. json, go, python) never warn.

Summary Lines

If the first line of a run: block is a comment, specdown extracts it as the block's summary line.

Consecutive comment lines at the start of a block are joined with a space into a single summary. The summary ends at the first non-comment line or blank line.

In the HTML report, blocks with a summary are rendered collapsed: only the summary text and pass/fail indicator are visible. A > marker on the right side lets readers expand the block to see the full code. Failed blocks auto-expand so failures are never hidden.

This makes specs readable for non-technical stakeholders without removing any detail for developers.

The comment prefixes recognized are # , // , and -- . Only the text after the prefix becomes the summary; the prefix itself and leading/trailing whitespace are stripped.

Blocks with doctest content ($ lines) never get summaries — they use a different rendering model with command/output pairs.

Here is an example: the following block's first line is a comment, so the report will render it collapsed with the summary "Demonstrate summary line" and a pass/fail indicator.

Multiple comment lines are joined into one summary:

A block without a leading comment renders normally (not collapsed):

Variable Capture

A block can capture its output into one or more variables with -> $varName. Multiple captures use comma-separated names: -> $var1, $var2. Each output line is bound to the corresponding capture name in order.

Variables captured this way are referenced in subsequent blocks and tables using ${variableName}.

When the adapter returns structured (non-string) output, the value is stored as-is and fields are accessible via dot-path syntax: ${result.field}. Nested access works to arbitrary depth: ${result.outer.inner}. Accessing a missing key or indexing into a non-object value is a compile-time error.

module varscope

sig Section {
  parent: lone Section
}

sig Var {
  definedIn: one Section
}

-- heading hierarchy is a tree
fact tree {
  no s: Section | s in s.^parent
}

-- a variable is visible in its defining section and all descendants
pred visible[v: Var, s: Section] {
  v.definedIn in (s + s.^parent)
}

-- variables from child sections are never visible in ancestors
assert noUpwardLeak {
  all v: Var, s: Section |
    v.definedIn in s.^(~parent) implies not visible[v, s]
}

check noUpwardLeak for 6

Doctest Blocks

A run:<target> block whose content starts with $ lines is auto-detected as doctest-style. Lines starting with $ are commands; subsequent lines until the next $ or end of block are the expected output.

Commands are executed sequentially. On the first output mismatch, the block fails with expected and actual values for diffing. Commands without expected output lines are executed but only checked for exit status.

A doctest-style block with no expected output still verifies the command succeeds.

Multi-line expected output is matched exactly.

Arithmetic and pipelines work as expected.

Commands that produce no output show only the prompt line.

Expected Failures

Any executable block can be marked with !fail to indicate that failure is the expected outcome. When the adapter reports failure as expected, the case is rendered identically to a regular failure — red styling, failure stats, and red dot markers in the ToC all apply. The only difference is the exit code: a spec run exits 0 when expected failures are the only failures present. If the adapter unexpectedly succeeds, the case is a real failure.

!fail blocks do not support variable capture (-> $name).

Check Tables

A Markdown table becomes executable when preceded by a check directive.

The directive is a blockquote of the form > check:name. The first row is the header. Each subsequent row is an independent test case. Check names are defined by the adapter, not the core.

> check:api(endpoint=/api/users, mode=object)
| field | expected |
| name  | alice    |

> check:api(endpoint=/api/orders, mode=array, count=2)
| index | status  |
| 0     | SUCCESS |
| 1     | PENDING |

> check:check-user(field=plan, expected=STANDARD)

Inline Elements

Prose text can contain inline executable elements embedded in backtick code spans. These are evaluated during the spec run and rendered with pass/fail status in the HTML report.

The greeting is ${greeting} and it was captured successfully.

The count is `expect: ${count} == 3` items.

The file `check:file-check(path=/tmp/data.txt, exists=yes)` was created.

Setup and Teardown Hooks

Hooks run adapter commands at section boundaries. A hook directive must be followed by an executable code block.

Hooks are not counted as test cases. Their results do not appear in the case list, but a hook failure marks the document as failed.

Frontmatter

An optional YAML frontmatter can be placed at the top of a spec file.

If frontmatter is absent, the global defaultTimeoutMsec from specdown.json applies (default: 30 seconds).

A spec with a timeout must still pass when the adapter responds quickly.