Tui QA
Testing & Qualitytui-qaTui QA is an Agent Skill for testing & quality published in the dagger/dagger repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
QA CLI and TUI applications with asciinema recordings, timestamped terminal snapshots, and hang/timing analysis. Use when validating terminal output, progress behavior, delays, or what a user would see at a given moment.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/dagger/dagger/blob/HEAD/skills/tui-qa/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/tui-qa, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
TUI QA
Use this skill for operator-style QA of terminal applications.
Prefer the bundled helper at scripts/tui_qa.py over ad hoc shell pipelines. It standardizes artifacts, snapshot capture, and timing analysis so follow-up sessions can inspect the same evidence.
Backend
This skill requires asciinema.
Artifact meanings:
.cast: source of truth for timing and terminal behaviorfinal.txt: final rendered screen as plain textsnapshots/*.txt: rendered screen at specific timestamps.raw: optional low-level byte stream for terminal-control debuggingreport.json: machine-readable timings, findings, and artifact pathsreport.md: short human-readable QA summary
Use .cast for time-sensitive behavior. Use text snapshots for "what the user saw at time T". If terminal control behavior itself is suspect, inspect the .cast replay rather than relying on .txt.
Workflow
-
State the operator expectation before recording.
- expected first visible response
- expected milestones
- expected final screen or files written
- acceptable delays
-
Record and analyze in one step when possible:
python3 skills/tui-qa/scripts/tui_qa.py run \
--name workspace-install \
--command 'dagger install github.com/dagger/dagger/modules/wolfi@main' \
--workdir /path/to/repo \
--snapshot-at 0.5 \
--snapshot-at 2 \
--milestone 'Initialized workspace' \
--milestone 'Installed module'
-
Review:
report.mdfor the summarysnapshots/*.txtfor point-in-time screenssession.castwithasciinema playwhen timing or redraw behavior matters
-
Classify issues:
- content bug
- timing bug
- hard hang: no output for too long
- semantic hang: output continues but no meaningful milestone progress
- polish issue
Commands
record
- Use for manual or interactive sessions.
- Stores
session.castandmeta.json. - If the current shell is not attached to a tty, the helper automatically records in headless mode.
python3 skills/tui-qa/scripts/tui_qa.py record \
--name interactive-playground
python3 skills/tui-qa/scripts/tui_qa.py record \
--name module-init \
--command 'dagger sdk install go && dagger module init go demo' \
--workdir /tmp/playground
snapshot
- Produces a plain-text screen at a chosen timestamp.
- The helper truncates the cast at the last full event at or before
--at, then converts that truncated cast to text.
python3 skills/tui-qa/scripts/tui_qa.py snapshot \
.qa/tui/module-init-20260404-120000/session.cast \
--at 1.25
analyze
- Parses the event stream.
- Generates
final.txt, snapshots,report.json, andreport.md. - Detects startup delay and hard hangs from periods with no output.
- If milestones are supplied, also reports semantic-hang candidates.
Default thresholds:
- startup warning: 2s
- startup failure: 5s
- idle warning: 10s
- idle failure: 30s
- semantic-hang warning: 120s
run
- Runs
record, thenanalyze. - This is the default path for non-interactive QA.
Guidance
- Treat
.castas the authority for timing. - Treat
final.txtas the authority for final rendered text. - When low-level terminal control bytes matter, export
.rawdirectly withasciinema convert -f raw session.cast session.raw. - Use milestones for higher-level progress checks. Without milestones, semantic-hang analysis is intentionally reported as not evaluated.
- Input events do not count as progress.
- Output events that only repaint the terminal still count for hard-hang timing. Use milestone timing and snapshots to decide whether that output felt meaningfully progressive.
- For commands that write files, inspect the filesystem after the run in addition to the terminal artifacts.
Examples
Batch CLI:
python3 skills/tui-qa/scripts/tui_qa.py run \
--name help-output \
--command 'dagger --help' \
--snapshot-at 0.1
Progress UI:
python3 skills/tui-qa/scripts/tui_qa.py run \
--name generate \
--command 'dagger generate' \
--milestone 'Generated' \
--milestone 'done'
Manual recording, then analysis:
python3 skills/tui-qa/scripts/tui_qa.py record --name manual-flow
python3 skills/tui-qa/scripts/tui_qa.py analyze .qa/tui/manual-flow-*/session.cast
Specific screen sample:
python3 skills/tui-qa/scripts/tui_qa.py snapshot \
.qa/tui/generate-20260404-120000/session.cast \
--at 12.3 \
--label before-finish