Golden tests for CLI applications, written in Markdown.
Tryscript runs shell commands embedded in Markdown, captures their output, and compares it with readable expected results. The test files double as executable documentation for humans and coding agents.
pnpm add -D tryscript
pnpm exec tryscript run 'tests/**/*.tryscript.md'When an intentional behavior change makes a golden result stale, review the new behavior and update the file:
pnpm exec tryscript run --update 'tests/**/*.tryscript.md'---
env:
NO_COLOR: "1"
sandbox: true
---
# Test: CLI help
```console
$ my-cli --help
Usage: my-cli [options] <command>
Options:
--version Show version
--help Show this help
...
? 0
```
# Test: Version output
```console
$ my-cli --version
my-cli v[..]
? 0
```
# Test: Error handling
```console
$ my-cli unknown-command 2>&1
Error: unknown command 'unknown-command'
? 1
```
# Test: Check output file contents
```console
$ my-cli process data.json > output.txt && grep "success" output.txt
[..]success[..]
? 0
```The [..] pattern matches any text on one line.
The ... pattern matches zero or more lines.
Commands run in a real shell, so pipes, redirects, environment variables, and other
shell features work directly.
- Readable tests: Commands and expected results stay together in valid Markdown.
- Process-level coverage: Tests exercise the installed CLI and its shell behavior, not only internal functions.
- Controlled variation: Named and generic patterns keep dynamic output readable without discarding the stable parts of a result.
- Reviewable updates:
--updateand--expandrewrite only the relevant expected output after the author reviews the executed command.
Tryscript began as a TypeScript port of trycmd, with additional workflows for agent-authored tests and executable documentation. For more background on golden tests, see tbd’s pinned guidance:
npx --yes get-tbd@0.4.1 guidelines golden-testing-guidelinesUse the most specific pattern that fits the output:
- Named patterns (
[HASH],[VERSION],[CWD]): typed dynamic values with a specific meaning. - Unknown wildcards (
[??],???): temporary placeholders to replace with--expandbefore finalizing a test. - Generic wildcards (
[..],...): intentional omissions for output whose exact value is irrelevant or unpredictable.
| Command | Purpose |
|---|---|
tryscript run [files...] |
Run Markdown golden tests |
tryscript coverage <commands...> |
Run commands with merged V8 coverage |
tryscript docs |
Print the syntax reference |
tryscript readme |
Print this README |
tryscript --help |
Print all commands and global options |
Common run options:
| Option | Purpose |
|---|---|
--update |
Replace expected output with actual output |
--expand |
Replace unknown wildcards (??? and [??]) with actual output |
--expand-generic |
Replace unknown and generic wildcards |
--expand-all |
Replace all wildcards, including named patterns |
--capture-log <path> |
Write wildcard captures to a YAML file |
--fail-fast |
Stop after the first failure |
--filter <pattern> |
Run named tests matching a regular expression |
--verbose |
Include captured output for passing tests |
--coverage |
Collect V8 coverage with an installed c8 package |
Coverage support is experimental. Install its optional dependencies before using it:
pnpm add -D c8
# Add monocart when merging tryscript and Vitest coverage.
pnpm add -D monocart-coverage-reportsClaude Code produced the implementation and specifications under Joshua Levy’s design, prompting, and review, using tbd workflows. The project documentation records the architecture and implementation decisions; the general documentation contains the shared Speculate-era research and guidance used during development.
git clone https://github.com/jlevy/tryscript.git
cd tryscript
pnpm install
pnpm exec lefthook install
pnpm verifySee the development guide for toolchain requirements, individual checks, and release links.
MIT