Skip to content

Expose successful run output in HTML reports #26

@spilist

Description

@spilist

Problem

Specdown's HTML report currently renders ordinary run:shell blocks as executable source plus pass/fail status, but not the successful stdout/output returned by the adapter.

That is fine for smoke checks where the output is only an internal assertion input, but it is awkward for acceptance specs whose claim is "under this condition, this command shows this state." In those cases the report should let a human inspect the actual output, ideally collapsed by default.

Observed Behavior

A run:shell block such as:

```run:shell
# Show the discovery boundary from the latest selected claim status packet.
node -e 'console.log(JSON.stringify({sourceCount: 44}, null, 2))'

renders in HTML as a passed executable block with the summary and command source. The JSON stdout is not visible in the report.

The shell adapter does return an `output` field on success, and adapter protocol docs define output as a first-class exec response. However, `CaseResult.Code` currently stores rendered source, stderr, exit code, doctest steps, and bindings, but not successful stdout/output for ordinary code cases. The HTML renderer therefore cannot show it.

## Why It Matters

For human-facing executable specs, especially acceptance criteria, the difference between these two statements matters:

- "this command ran"
- "this command produced the state the user should see"

Doctest blocks cover command/output pairs when expected output is stable enough to inline. But for larger JSON, status packets, or dynamic summaries, authors may want ordinary `run:shell` to expose actual output without turning the block into a brittle doctest.

## Desired Behavior

Add an opt-in way for successful `run:*` output to appear in HTML reports, preferably collapsed by default.

Possible shapes:

- block flag such as `!show-output` or `!output`
- render output for all successful `run:*` blocks that produce stdout, behind a `<details>` section
- store output in JSON report always, but only render in HTML when the block opts in

The report should distinguish:

- source command
- stdout/output
- stderr, if any
- failure diff/message

## Non-Goals

- Do not make every successful command dump large output into the visible page by default.
- Do not replace doctest blocks; doctest is still the better fit for small stable command/output examples.
- Do not require domain-specific adapters just to show successful stdout from a built-in shell run.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions