Repterm

Terminal-first test framework for CLI/TUI apps — run tests in a real PTY, not just stdout.

---

import { test, expect } from 'repterm';

test('greet the world', async ({ $ }) => {
  const result = await $`echo "Hello, Repterm!"`;
  expect(result).toSucceed();
  expect(result).toHaveStdout('Hello, Repterm!');
});

$ bunx repterm tests/
 PASS  greet the world (120ms)

Why Repterm?

Write tests the way your users use your CLI. Simple commands run via Bun.spawn for precise stdout/stderr/exitCode. When you need interactive testing — prompts, TUI redraws, progress bars — flip on { interactive: true } and Repterm spawns a real PTY with full send/expect control.

Familiar, structured API. If you've used Playwright or Vitest, you already know how to use Repterm. test(), describe(), expect() — plus a $ tagged template for running commands with automatic shell escaping.

Tests become documentation. Run with --record and every test produces an asciinema recording. Your test suite generates always-up-to-date terminal demos — no manual recording sessions.

Parallel and fast. Scale with --workers N. Each test gets its own isolated session.

Extensible by design. Build plugins to add domain-specific commands and matchers. The official kubectl plugin adds Kubernetes-aware testing with assertions like toBeRunning() and toHaveReplicas().

Features

• Dual execution modes — precise Bun.spawn by default; opt into a real PTY with { interactive: true } for colors, cursor control, and TUI testing
• Playwright-style API — familiar expect() assertions, proc.send() / proc.expect() for interactive flows
• $ tagged templates — run commands with automatic shell escaping: await $`echo ${userInput}`
• Parallel test runner — execute tests concurrently with --workers N
• Terminal recording — generate asciinema recordings with --record
• Plugin system — extend test contexts with custom helpers, matchers, and lifecycle hooks
• Multi-terminal — spin up multiple PTY sessions in a single test for client-server scenarios

Quick Start

Install

bun add -d repterm

Or install the standalone binary:

curl -fsSL https://cdn.tensor-fusion.ai/archive/repterm/install.sh | sh

Windows (PowerShell)

iwr https://cdn.tensor-fusion.ai/archive/repterm/install.ps1 -UseBasicParsing | iex

Write a Test

Create tests/demo.ts:

import { test, expect, describe } from 'repterm';

describe('my CLI', () => {
  test('exits with code 0', async ({ $ }) => {
    const result = await $`echo "it works"`;
    expect(result).toSucceed();
    expect(result).toHaveStdout('it works');
  });

  test('handles stderr', async ({ $ }) => {
    const result = await $`echo "oops" >&2`;
    expect(result).toHaveStderr('oops');
  });
});

Run

bunx repterm tests/

Interactive Testing

Test interactive programs like prompts, editors, or TUI apps:

test('interactive prompt', async ({ $ }) => {
  const proc = $({ interactive: true })`bash -c 'read -p "Name: " n; echo "Hi $n"'`;

  await proc.expect('Name:');
  await proc.send('Alice');
  await proc.expect('Hi Alice');
});

Parallel Execution

Run tests across multiple workers:

bunx repterm --workers 4 tests/

Recording

Generate terminal recordings for docs or CI artifacts:

bunx repterm --record tests/

Produces asciinema-compatible .cast files you can embed or replay.

Plugins

Repterm has a plugin system for domain-specific testing. The first official plugin adds Kubernetes support:

import { defineConfig, createTestWithPlugins, expect } from 'repterm';
import { kubectlPlugin, pod } from '@nexusgpu/repterm-plugin-kubectl';

const config = defineConfig({
  plugins: [kubectlPlugin({ namespace: 'default' })] as const,
});

const test = createTestWithPlugins(config);

test('pod is running', async (ctx) => {
  const { kubectl } = ctx.plugins;
  await kubectl.apply('manifests/nginx.yaml');
  await kubectl.waitForPod('nginx', 'Running');
  await expect(pod('nginx')).toBeRunning();
});

Build your own plugins with repterm-api — see the Plugin Guide.

Packages

Package	Description
repterm	Core framework + CLI runner
repterm-api	Plugin/matcher API for extension authors
@nexusgpu/repterm-plugin-kubectl	Kubernetes testing plugin

Documentation

Full documentation is available at repterm.ai.

• Getting Started
• Writing Tests
• Interactive Commands
• Recording
• Plugin API
• Kubectl Plugin
• API Reference

Contributing

See the Plugin Development Guide to build your own plugins.

License

Apache-2.0