Adding Fixtures

Fixtures are reproducible terminal scenarios used for capturing screenshots and generating simulated rendering data. Each fixture lives in its own subdirectory under fixtures/.

Directory Structure

fixtures/
  {fixture-id}/
    setup.sh      # (required) Creates files/state in $FIXTURE_WORK_DIR
    command.sh    # (required) Runs the actual command to be captured
    teardown.sh   # (optional) Cleanup after capture
    output.json   # (generated) Parsed ANSI output for simulated rendering

Script Interface

The capture tool sets FIXTURE_WORK_DIR to an existing temp directory before running scripts.

setup.sh

Creates any files, git repos, or state the command needs. Must be idempotent. Runs once per capture.

#!/usr/bin/env bash
set -euo pipefail
cd "$FIXTURE_WORK_DIR"

git init -b main -q
git config user.email "demo@litmus.dev"
git config user.name "Litmus Demo"
# ... create files, make commits, etc.

command.sh

Produces the terminal output that gets screenshotted. Must exit when done — the terminal emulator is kept open via --hold.

#!/usr/bin/env bash
set -euo pipefail
cd "$FIXTURE_WORK_DIR"
git --no-pager diff --color=always HEAD

Colors must use ANSI escape codes, not hardcoded RGB. Use --color=always for tools that auto-detect.

output.json

Auto-generated by litmus-capture parse-fixtures. Contains the parsed ANSI output as structured TermOutput data. Don’t edit by hand.

Writing Good Fixtures

Pin versions and timestamps. Use fixed author names, dates, and deterministic data so output is reproducible:

GIT_AUTHOR_DATE="2024-01-15T10:00:00" \
GIT_COMMITTER_DATE="2024-01-15T10:00:00" \
git commit -q -m "Initial commit"

Exercise many ANSI colors. Good fixtures use a range of the 16 ANSI colors so themes can be compared meaningfully.

Stay within 80×32. The capture terminal is 80 columns × 32 rows. Output that wraps or scrolls past this boundary will be cut off.

Test locally:

export FIXTURE_WORK_DIR=$(mktemp -d)
bash fixtures/{id}/setup.sh
cd "$FIXTURE_WORK_DIR" && bash /path/to/fixtures/{id}/command.sh
rm -rf "$FIXTURE_WORK_DIR"

Registration

After creating the fixture scripts:

Parse the ANSI output: litmus-capture parse-fixtures
Register the fixture in crates/litmus-web/src/fixtures.rs
Capture screenshots: mise run capture-kitty && mise run capture-wezterm
Rebuild the manifest: mise run capture-manifest

The fixture will automatically appear in all views — theme detail, scene-across-themes, and compare.

Keyboard shortcuts

Litmus