# Test Results (/docs/agent-ui/components/test-results)

Use test results when the agent runs a test suite, so readers see how many tests passed, failed and were skipped, and why a test failed. It's a step: a header with the counts and the run's duration, over a filter and a tree of suites and tests, in which a failed test opens to its message and a [Stack Trace](./stack-trace.mdx).

<Example caption="Choose Failed to show only the failing tests. Focus a row and use the arrow keys to move between rows, Right Arrow and Left Arrow to open and close one, then press Tab to reach the stack trace inside a failure.">
<h />

```tsx
import type { TestSuite } from "@kind-ui/agent-ui";
import { TestResults } from "@/components/ui/test-results";

const suites: TestSuite[] = [
  {
    id: "auth",
    name: "auth.test.ts",
    tests: [
      { id: "login", name: "logs in with a password", status: "pass", durationMs: 42 },
      {
        id: "lockout",
        name: "locks the account after five attempts",
        status: "fail",
        durationMs: 18,
        error: {
          message: "AssertionError: expected 423, got 401",
          stack: `AssertionError: expected 423, got 401
    at Context.<anonymous> (/app/test/auth.test.ts:58:31)
    at callFn (/app/node_modules/mocha/lib/runnable.js:366:21)
    at processImmediate (node:internal/timers:483:21)`,
        },
      },
      { id: "sso", name: "signs in with SSO", status: "skip" },
    ],
  },
  {
    id: "cart",
    name: "cart.test.ts",
    tests: [
      { id: "add", name: "adds an item", status: "pass", durationMs: 7 },
      { id: "total", name: "totals the items", status: "pass", durationMs: 3 },
    ],
  },
];

export default function TestResultsExample() {
  return <TestResults suites={suites} defaultOpen className="w-full max-w-xl" />;
}
```
</Example>

## Installation [#installation]

```bash tab="React"
npx shadcn@latest add @kind-ui/test-results
```

```bash tab="Web Components"
npx shadcn@latest add @kind-ui/test-results-web
```

## Composition [#composition]

```text
TestResults
├── TestResultsTrigger
│   ├── TestResultsIcon
│   ├── TestResultsTitle
│   └── TestResultsMeta
└── TestResultsContent
    └── div[data-test-results-panel]
        ├── TestResultsFilter
        ├── TestResultsTree
        │   └── TestResultsRows
        │       ├── TestResultsItem
        │       │   └── TestResultsItemStatus
        │       └── TestResultsFailure
        └── TestResultsEmpty
```

`TestResultsTrigger` opens and closes the run, with its status mark in `TestResultsIcon`, the `label` in `TestResultsTitle`, and the counts and duration in `TestResultsMeta`. `TestResultsContent` holds the panel, a `div` with `data-test-results-panel`. In it, `TestResultsFilter` renders a UI SDK Segmented Control, and `TestResultsTree` a UI SDK Tree whose rows `TestResultsRows` draws. Each row's `TestResultsItem` shows its name, its status mark in `TestResultsItemStatus` and its duration. A failed test holds a `TestResultsFailure`, which renders a Stack Trace. `TestResultsEmpty` shows when the filter lets no test through.

## Usage [#usage]

### Suites and Tests [#suites-and-tests]

Pass `suites`, each with an `id`, a `name` and its `tests`. A test has an `id`, a `name`, a `status` of `"pass"`, `"fail"` or `"skip"`, an optional `durationMs`, and for a failure an `error` with its `message` and `stack`. The header counts each status and shows the run's duration: `durationSeconds` if you pass it, else the tests' total.

```tsx
<TestResults
  suites={[{ id: "math", name: "math.test.ts", tests: [{ id: "sum", name: "adds", status: "pass", durationMs: 2 }] }]}
/>
```

Rows are kept by object, so a test you don't replace doesn't render again.

### Status and a Live Run [#status-and-a-live-run]

The status is `error` once a test failed, else `complete`, or `pending` with no tests. While tests run, pass `status="running"` and new `suites` as each test finishes: the step opens, rows come in where they belong, and the header keeps its place. When you pass `complete`, the step closes to its header; an `error` keeps it open. Either outcome is announced with the counts, like "Tests failed, 12 passed, 1 failed, 0 skipped".

### Failures [#failures]

A failed test is a row that opens to its error, shown as a Stack Trace with the message as its title and the frames of its `stack`, library frames folded. Failing suites and their failed tests start open, and a suite or test that starts failing during a run opens too. Pass `defaultExpanded` with suite ids and `suiteId/testId` values to choose what starts open, or control it with `expanded` and `onExpandedChange`.

### Filtering [#filtering]

**All**, **Failed**, **Passed** and **Skipped** show every test or only those with that status. A suite with no test to show is left out, and "No failed tests" or the like shows when none is left. Pass `defaultFilter` to start on one, or control it with `filter` and `onFilterChange`.

### Keyboard and Motion [#keyboard-and-motion]

The filter and the tree are one Tab stop each. In the filter, the arrow keys choose a status. In the tree, Up Arrow and Down Arrow move between rows, Right Arrow and Left Arrow open and close a suite or failure, Home and End go to the first and last row, and typing a name moves to it. Tab from an open failure's row reaches its stack trace, whose keys stay its own. Rows fade in as they arrive and suites open by height; under `prefers-reduced-motion`, or with `motion="reduced"`, they fade over 120 ms and the filter's mark stops sliding, and with `motion="none"` nothing moves.

## API Reference [#api-reference]

### TestResultsOptions

| Prop                | Type                                                                                                        | Description                                                                                                                                                                                                                                             |
| ------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `kind?`             | `string \| undefined`                                                                                       | Written as `data-kind`, for styling by step type.                                                                                                                                                                                                       |
| `open?`             | `boolean \| undefined`                                                                                      | Whether the content shows. Passing it controls it: change it in `onOpenChange`.                                                                                                                                                                         |
| `defaultOpen?`      | `boolean \| undefined`                                                                                      | Whether the content shows at first, when `open` isn't passed. Defaults to open while `status` is `running` or `awaiting-input`, unless `autoOpen` is `"never"`.                                                                                         |
| `onOpenChange?`     | `((open: boolean, details: ChangeDetails<StepOpenChangeReason>) => void) \| undefined`                      | Called when the step opens or closes, with what caused it.                                                                                                                                                                                              |
| `autoOpen?`         | `"never" \| "running"`                                                                                      | With `"running"`, the step opens while running or awaiting input and closes on completion, until someone toggles it. With `"never"`, only a person or your code opens it. Default: `"running"`                                                          |
| `durationSeconds?`  | `number \| undefined`                                                                                       | Written as `--kind-step-duration`.                                                                                                                                                                                                                      |
| `motion?`           | `"auto" \| "none" \| "reduced"`                                                                             | `"auto"` follows `prefers-reduced-motion`. Default: `"auto"`                                                                                                                                                                                            |
| `suites?`           | `TestSuite[] \| undefined`                                                                                  | The suites and their tests, as they finish. Pass new arrays and objects for what changed, and keep the rest: rows are kept by object, so a suite you keep keeps its row's state. Ids can't hold `/`, which joins a test's to its suite's. Default: `[]` |
| `label?`            | `string \| undefined`                                                                                       | The title, which also names it in announcements. Default: `"Tests"`                                                                                                                                                                                     |
| `status?`           | `"awaiting-input" \| "cancelled" \| "complete" \| "error" \| "pending" \| "running"`                        | What the run is doing. Defaults to `error` once a test failed, else `complete`, or `pending` with no tests.                                                                                                                                             |
| `filter?`           | `"all" \| "fail" \| "pass" \| "skip"`                                                                       | Which tests show. Passing it controls it: change it in `onFilterChange`.                                                                                                                                                                                |
| `defaultFilter?`    | `"all" \| "fail" \| "pass" \| "skip"`                                                                       | Which tests show at first, when `filter` isn't passed. Default: `"all"`                                                                                                                                                                                 |
| `onFilterChange?`   | `((filter: TestResultsFilter, details: ChangeDetails<TestResultsFilterChangeReason>) => void) \| undefined` | Called when a person or `setFilter` chooses a filter, with why.                                                                                                                                                                                         |
| `expanded?`         | `string[] \| undefined`                                                                                     | The open suites' ids and failed tests' `suiteId/testId` values. Passing it controls them: change them in `onExpandedChange`.                                                                                                                            |
| `defaultExpanded?`  | `string[] \| undefined`                                                                                     | The open suites and failed tests at first, when `expanded` isn't passed. Defaults to every failing suite and failed test. A suite or test that starts failing later opens too.                                                                          |
| `onExpandedChange?` | `((expanded: string[], details: ChangeDetails<TestResultsExpandedChangeReason>) => void) \| undefined`      | Called when suites or failed tests open or close, with why.                                                                                                                                                                                             |

### Agent [#agent]

An agent connected with `createAgent` finds the run by its title and reads `open`, `status`, `filter` and `expanded`. It can `setFilter` to `"all"`, `"fail"`, `"pass"` or `"skip"`, and `expand` or `collapse` a suite or failed test by its value or name; without one, they open and close the run. A suite or test that isn't there is refused.

### TestResultsAgentActions

| Prop        | Type                                     | Description                                                                                                                                           |
| ----------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `expand`    | `(id?: string) => boolean`               | With an id, opens that suite, or that failed test and its suite; returns `false` for anything else, or a refused change. Without one, opens the step. |
| `collapse`  | `(id?: string) => boolean`               | With an id, closes that suite or failed test; returns `false` for anything else. Without one, closes the step.                                        |
| `setFilter` | `(filter: TestResultsFilter) => boolean` | Shows every test, or those that failed (`"fail"`), passed (`"pass"`) or were skipped (`"skip"`).                                                      |

<Caption>
Runs in React and Web Components. On `<kind-test-results>`, set `suites` as a property; the other props are kebab-case attributes. `onOpenChange` is the `openchange` event, `onFilterChange` is `filterchange` and `onExpandedChange` is `expandchange`.
</Caption>