Tests

AssertionError: expected 3 to be 4
    at pond.test.ts:12:20

::tests{title="Pond census tests"}
```xml
<testsuites time="4.21">
  <testsuite name="pond.test.ts">
    <testcase classname="pond.test.ts" name="counts the ducks" time="0.01"/>
    <testcase classname="pond.test.ts" name="counts the geese" time="0.02">
      <failure message="expected 3 to be 4">AssertionError: expected 3 to be 4
    at pond.test.ts:12:20</failure>
    </testcase>
    <testcase classname="pond.test.ts" name="maps the herons"><skipped/></testcase>
  </testsuite>
</testsuites>
```
::

::tests{title="Pigeon map tests"}
```xml
<testsuite time="1.8">
  <testcase name="draws the plaza"/>
  <testcase name="pins each pigeon"/>
  <testcase name="clusters the flock"/>
</testsuite>
```
::

A pull request that says the tests pass reads better with the run next to it. The plugin reads the report while parsing, so the page shows the counts with no script, and each failure opens to its message and stack.

::tests{src="reports/junit.xml" title="Unit tests"}
::

src is a path relative to the document's folder, or to root when it starts with /. It can't leave root or be a URL.

Paste the report into an ```xml fence inside the block:

::tests
```xml
<testsuite><testcase name="counts the ducks"/></testsuite>
```
::

• Passed, failed, and skipped. Counted from the <testcase> elements, so the totals always match the cases. A case with <failure> or <error> failed, and one with <skipped> was skipped. Failed and skipped show only when there are any.
• Duration. The time of <testsuites>, else the sum of the suites', else the sum of the cases', as 250 ms, 4.2 s, or 1 min 21 s.
• Failures. Each one is a <details> named classname › name, with the failure's message and its stack in a code block. With comark-code, the stack gets a Copy button.

The root can be <testsuites> or a single <testsuite>.

The plugin adds every problem to meta.issues, as Validation describes: a missing src, a prop it doesn't read, a file that's missing, outside the root, or a URL, XML that isn't well-formed (with the line), and a document that isn't a JUnit report. The block renders nothing then. Each issue names the block and says how to fix it, and each has its own rule in Doctor:

`::tests` 1 ("junit.xml"): its XML is malformed at line 3: `</testsuite>` closes `<testcase>`. Fix the report, or run the tests again to rewrite it.
`::tests` 2: it isn't a JUnit report: its root is `<coverage>`, not `<testsuites>` or `<testsuite>`.

Most runners write JUnit XML with a flag:

Have CI write the report next to the review document, then point the block at it:

::tests{src="./reports/junit.xml" title="CI run"}
::

The summary is one line, and the failures stay closed until a reader opens one, so a long report doesn't push the rest of the review down. In print, every failure prints open.

JUnit XML uses a small part of XML: elements, attributes, text, CDATA, and the five entities. The plugin reads it with a parser of its own, about a hundred lines with no dependency, rather than pulling in a general XML library many times its size. It refuses what isn't well-formed and says on which line, and it skips doctypes without reading them, so a report can't make it load anything.

These options go under tests in comarkUi(), or to tests() when you use the plugin alone. In comarkUi(), a ::tests block reads no files until you pass options, such as comarkUi({ tests: { root: "." } }).

root is the folder src can't leave, and base the document's folder under it, as in comark-include. In a browser or an edge runtime, pass read, a function that takes a path under the root and returns the file's text.

comark-ui brings comark-tests and registers it. To use it alone, install it with Comark and a renderer:

pnpm add comark @comark/html comark-tests

Register the plugin and pass the renderer's components:

import { createHtmlRenderer } from "@comark/html";
import tests, { components } from "comark-tests/html";

const render = createHtmlRenderer({ plugins: [tests({ root: "." })], components });

The renderer inlines the styles once per document, and the output needs no script. For Vue, React, or Svelte, import from comark-tests/vue, comark-tests/react, or comark-tests/svelte; the components add the styles when they mount. Import comark-tests/style.css with your styles so a server-rendered page doesn't shift. Renderers covers using it with other plugins.

Results sit in a bordered card. Each count is a badge tinted in its color, green for passed, red for failed, and muted for skipped, and each failure is a disclosure with its stack. The rules sit in a comark CSS layer, so any plain rule of your own wins.

The results read these shared tokens:

Set them on .ctr:

The block is section.ctr, with data-status set to passed or failed. The parts are .ctr-summary, .ctr-title, .ctr-count with data-kind, .ctr-time, and each details.ctr-failure with .ctr-message and pre.ctr-stack.