noot

Test interactive CLIs. Think Stagehand, but for the terminal.

• f.step("Select 'pyright' from dropdown"): Define CLI interactions in plain English.
• f.expect("Linting options must contain 'pyright'"): Define expected CLI states in plain English too.
• assert "pyright" in f.screen().lower(): Or make assertions on CLI state in good ol' Python.
• Record with LLM once, replay locally and in CI/CD.

Installation

pip install noot

Requires tmux and an ANTHROPIC_API_KEY environment variable.

Quick Start

Scaffold a new project:

noot init

Or add noot to an existing project:

from noot import Flow

def test_create_web_project():
    with Flow.spawn('python setup_wizard.py') as f:
        f.expect('Welcome to Project Setup Wizard')

        f.step("Enter project name 'mywebapp' and press enter")

        # `expect` parses assertions from natural language
        f.expect('Web Application project option is available')

        f.step('Press enter to select Web Application')

        # or specify assertions on screen state directly
        assert "author name" in f.screen()

        f.step("Enter author name 'Alice' and press enter")

Run your tests:

pytest tests/test_cli.py

The first run records LLM responses to the cassette file. Subsequent runs replay from the cassette, so no API calls are made.

API

Recording Modes

Control recording behavior with the RECORD_MODE environment variable:

By default you don't have to think about recording and replay:

pytest tests/test_cli.py
# Subsequent runs will use cache

Example - force re-recording:

RECORD_MODE=all pytest tests/test_cli.py

Example - CI mode (fail if cassette is missing):

RECORD_MODE=none pytest tests/test_cli.py

Cassettes are stored in <project_root>/.cassettes/:

• CLI cassettes (LLM responses): .cassettes/cli/
• HTTP cassettes (API recordings): .cassettes/http/

CI/CD

Run tests in CI with RECORD_MODE=none to replay from cached cassettes (no API key needed):

# .github/workflows/test.yml
name: Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - name: Install tmux
        run: sudo apt-get install -y tmux
      - name: Install dependencies
        run: pip install -e ".[dev]"
      - name: Run tests
        run: RECORD_MODE=none pytest

Commit your .cassettes/ directory to version control so CI can replay recordings.

Contributing

Issues and PRs welcome.

License

Apache 2.0