https://github.com/jlevy/tryscript
Golden testing for CLI applications
https://github.com/jlevy/tryscript
Last synced: 4 months ago
JSON representation
Golden testing for CLI applications
- Host: GitHub
- URL: https://github.com/jlevy/tryscript
- Owner: jlevy
- License: mit
- Created: 2026-01-01T07:01:17.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-01-08T19:07:17.000Z (4 months ago)
- Last Synced: 2026-01-13T19:44:37.571Z (4 months ago)
- Language: TypeScript
- Homepage:
- Size: 929 KB
- Stars: 4
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# tryscript
[](https://github.com/jlevy/tryscript/actions/runs/20828507667)
[](https://github.com/jlevy/tryscript/actions/runs/20828507667)
[](https://www.npmjs.com/package/tryscript)
[](https://x.com/ojoshe)
Golden testing for CLI applications - a TypeScript port of [trycmd](https://github.com/assert-rs/trycmd).
> [!NOTE]
> 100% of the code and specs in this repository were written by Claude Code.
> The design and management and prompting was by me ([jlevy](https://github.com/jlevy)) supported by the workflows, agent rules,
> and other research docs in [Speculate](https://github.com/jlevy/speculate).
>
> You can see what you think, but I find the code quality higher than most agent-written code I've
> seen because of the spec-driven process.
> You can review the architecture doc and all of the specs all of the specs in [docs/project](docs/project).
> The general research, guideline, and rules docs I use are in [docs/general](docs/general).
## What It Does
Write CLI tests as Markdown. tryscript runs commands, captures output, and compares against expected results. Tests become documentation; documentation becomes tests.
````markdown
---
env:
NO_COLOR: "1"
sandbox: true
---
# Test: CLI help
```console
$ my-cli --help
Usage: my-cli [options]
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 `[..]` matches any text on that line. The `...` matches zero or more lines. These "elision patterns" let tests handle dynamic output gracefully. Any shell command works - pipes, redirects, environment variables, etc.
## Quick Start
```bash
# Install
pnpm add -D tryscript
# For coverage support (optional)
pnpm add -D c8
# For accurate line counts when merging with vitest (optional)
pnpm add -D c8 monocart-coverage-reports
# Run tests
npx tryscript run tests/
# Update expected output when behavior changes
npx tryscript run --update tests/
```
## Features
- **Markdown format** - Tests are readable documentation
- **Elision patterns** - Handle variable output: `[..]`, `...`, `[CWD]`, `[ROOT]`, `[EXE]`
- **Custom patterns** - Define regex patterns for timestamps, versions, UUIDs
- **Update mode** - Regenerate expected output with `--update`
- **Sandbox mode** - Isolate tests in temp directories
- **Code coverage** - Track coverage from subprocess execution with `--coverage` (experimental; use `--coverage-monocart` for best accuracy)
## CLI Reference
```bash
tryscript run [files...] # Run golden tests
tryscript coverage # Run commands with merged coverage
tryscript docs # Show syntax quick reference
tryscript readme # Show this documentation
tryscript --help # Show all options
```
For complete syntax reference, run `tryscript docs` or see the [reference documentation](https://github.com/jlevy/tryscript/blob/main/docs/tryscript-reference.md).
### Common Options
| Option | Description |
| --- | --- |
| `--update` | Update test files with actual output |
| `--fail-fast` | Stop on first failure |
| `--filter ` | Filter tests by name |
| `--verbose` | Show detailed output |
| `--coverage` | Collect code coverage (requires c8) |
| `--coverage-monocart` | Use monocart for accurate line counts (requires monocart-coverage-reports) |
| `--coverage-exclude-node-modules` | Exclude node_modules from coverage (default: true) |
| `--coverage-exclude ` | Exclude patterns from coverage |
> **Note**: Coverage features are experimental. See the [reference documentation](packages/tryscript/docs/tryscript-reference.md#code-coverage) for details on merged coverage, monocart integration, and sourcemap requirements.
## Development
```bash
# Clone and install
git clone https://github.com/jlevy/tryscript.git
cd tryscript
pnpm install
# Build and test
pnpm build
pnpm test
```
## License
MIT