Testing

Installation

Terminal

bun add -D @gridland/testing

Terminal

npm install --save-dev @gridland/testing

Terminal

yarn add -D @gridland/testing

Terminal

pnpm add -D @gridland/testing

Creating a Test Screen

The createScreen function renders your component to a virtual buffer that you can inspect:

example.test.ts

import { createScreen } from "@gridland/testing"

const screen = await createScreen(
  <box border padding={1}>
    <text>Hello World</text>
  </box>,
  { cols: 40, rows: 10 }
)

Querying Content

Use screen.getByText() to find text in the rendered output:

example.test.ts

const match = screen.getByText("Hello World")
expect(match).toBeTruthy()
expect(match.row).toBeGreaterThan(0)

Simulating Input

Send keystrokes to test interactive components:

input.test.ts

import { createScreen, keys } from "@gridland/testing"

const screen = await createScreen(<MyInputComponent />, {
  cols: 40,
  rows: 10,
})

screen.sendKeys(keys.type("hello"))
screen.sendKeys(keys.enter)

Available Key Helpers

Helper	Description
`keys.type(str)`	Type a string character by character
`keys.enter`	Press Enter
`keys.escape`	Press Escape
`keys.tab`	Press Tab
`keys.backspace`	Press Backspace
`keys.up` / `keys.down`	Arrow keys
`keys.left` / `keys.right`	Arrow keys

Waiting for Updates

Use waitFor to wait for async state changes:

async.test.ts

import { createScreen, waitFor } from "@gridland/testing"

const screen = await createScreen(<AsyncComponent />)

await waitFor(() => {
  expect(screen.getByText("Loaded")).toBeTruthy()
})

Snapshot Testing

Capture the rendered buffer as a string for snapshot comparisons:

snapshot.test.ts

const output = screen.toString()
expect(output).toMatchSnapshot()

Test Runner Compatibility

@gridland/testing works with any test runner that supports ESM:

Bun - Recommended, used in the Gridland test suite
Vitest - Works with proper module resolution
Jest - Works with ESM transforms configured

Bun is the recommended test runner for Gridland projects. It has native ESM support and is used for the Gridland test suite itself.

Tips

Set explicit cols and rows for deterministic layout
Run tests multiple times with randomized order to catch state leaks
Use screen.debug() to print the buffer to the console during development

On this page