# @mwillbanks/tuil-testing

Source: /tuil/docs/reference/packages/testing
Locale: en

Semantic assertions, screens, and portable story contracts for testing tuil applications.



## Overview [#overview]

Semantic assertions, screens, and portable story contracts for testing tuil applications.

`@mwillbanks/tuil-testing` is independently installable and also participates in the
umbrella `@mwillbanks/tuil` runtime where applicable.

## Installation [#installation]

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @mwillbanks/tuil-testing
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @mwillbanks/tuil-testing
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @mwillbanks/tuil-testing
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @mwillbanks/tuil-testing
    ```
  </CodeBlockTab>
</CodeBlockTabs>

## How it operates [#how-it-operates]

Testing contracts query semantic output instead of terminal coordinates, define portable stories, and provide screen-style role, label, state, and text assertions.

<Mermaid
  chart="flowchart LR
  S0[&#x22;render&#x22;]
  S1[&#x22;query semantics&#x22;]
  S2[&#x22;interact&#x22;]
  S3[&#x22;assert&#x22;]
  S4[&#x22;cleanup&#x22;]
  S0 --> S1
  S1 --> S2
  S2 --> S3
  S3 --> S4"
/>

## API [#api]

| API                                                                                                    | Signature                               | Description                                   |
| ------------------------------------------------------------------------------------------------------ | --------------------------------------- | --------------------------------------------- |
| [`defaultTerminalStoryControls`](/tuil/docs/reference/packages/testing/api/default-terminal-story-controls) | `constant defaultTerminalStoryControls` | Public constant defaultTerminalStoryControls. |
| [`defineTuilStories`](/tuil/docs/reference/packages/testing/api/define-tuil-stories)                        | `function defineTuilStories`            | Public function defineTuilStories.            |
| [`normalizeTerminalFrame`](/tuil/docs/reference/packages/testing/api/normalize-terminal-frame)              | `function normalizeTerminalFrame`       | Public function normalizeTerminalFrame.       |
| [`QueryableSemanticNode`](/tuil/docs/reference/packages/testing/api/queryable-semantic-node)                | `interface QueryableSemanticNode`       | Public interface QueryableSemanticNode.       |
| [`SemanticQuery`](/tuil/docs/reference/packages/testing/api/semantic-query)                                 | `interface SemanticQuery`               | Public interface SemanticQuery.               |
| [`SemanticScreen`](/tuil/docs/reference/packages/testing/api/semantic-screen)                               | `class SemanticScreen`                  | Public class SemanticScreen.                  |
| [`SemanticSnapshot`](/tuil/docs/reference/packages/testing/api/semantic-snapshot)                           | `interface SemanticSnapshot`            | Public interface SemanticSnapshot.            |
| [`TerminalStoryControls`](/tuil/docs/reference/packages/testing/api/terminal-story-controls)                | `interface TerminalStoryControls`       | Public interface TerminalStoryControls.       |
| [`TuilStory`](/tuil/docs/reference/packages/testing/api/tuil-story)                                         | `interface TuilStory`                   | Public interface TuilStory.                   |
| [`TuilStoryDefinition`](/tuil/docs/reference/packages/testing/api/tuil-story-definition)                    | `interface TuilStoryDefinition`         | Public interface TuilStoryDefinition.         |

## Events and lifecycle [#events-and-lifecycle]

Story and test results expose captured runtime events for deterministic assertions.

All subscriptions and registrations return a disposer or belong to an owning
runtime that disposes them in reverse order.

## Example [#example]

```tsx
expect(screen.getByRole("button", { name: "Run" })).toBeEnabled();
```

## Related [#related]

* [Package architecture](/tuil/docs/concepts/packages)
* [Events](/tuil/docs/concepts/events)
* [Testing](/tuil/docs/guides/testing)