https://github.com/rogerchappel/clisnapshot
Stable snapshots for terminal output without the confetti drift
https://github.com/rogerchappel/clisnapshot
cli fixtures snapshot-testing terminal testing typescript
Last synced: about 1 month ago
JSON representation
Stable snapshots for terminal output without the confetti drift
- Host: GitHub
- URL: https://github.com/rogerchappel/clisnapshot
- Owner: rogerchappel
- License: mit
- Created: 2026-05-15T20:38:53.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-26T19:53:16.000Z (about 1 month ago)
- Last Synced: 2026-05-26T21:24:06.167Z (about 1 month ago)
- Topics: cli, fixtures, snapshot-testing, terminal, testing, typescript
- Language: TypeScript
- Size: 44.9 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Roadmap: ROADMAP.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# clisnapshot
Stable snapshots for terminal output without the confetti drift 📸
`clisnapshot` is a local-first CLI snapshot runner for people who build command-line tools. It runs named fixture commands, scrubs noisy output, and compares stdout, stderr, and exit codes against plain text snapshots you can review in git.
## Why it exists
CLI output drifts for boring reasons: ANSI color, UUIDs, dates, temp paths, home directories, durations, and platform-specific paths. `clisnapshot` keeps the useful signal while sanding down the confetti.
## Install
```sh
npm install --save-dev clisnapshot
```
Or try the repo locally:
```sh
npm install
npm run build
node dist/cli.js --help
```
## Quick start
```sh
npx clisnapshot init
npx clisnapshot run --update
npx clisnapshot run
```
A minimal `clisnapshot.config.json`:
```json
{
"snapshotDir": "__snapshots__",
"cases": {
"help-output": {
"command": "node",
"args": ["fixtures/bin/example-cli.mjs", "--help"],
"snapshot": "help-output.snap"
}
}
}
```
## Commands
- `clisnapshot init [dir]` — create a starter config, fixture CLI, and snapshot directory.
- `clisnapshot run [--update] [--case name]` — compare configured cases or intentionally rewrite snapshots.
- `clisnapshot list` — print configured case names.
- `clisnapshot inspect` — show resolved config metadata as JSON.
- `clisnapshot scrub [text]` — normalize noisy terminal text from an argument or stdin.
## Scrubbing
Built-in scrubbers normalize:
- ANSI escape codes
- CRLF line endings
- home and current working directories
- temp paths
- ISO-like dates/timestamps
- UUIDs
- common durations such as `42ms` or `1.2s`
Add project-specific scrubbers:
```json
{
"scrubbers": [
{ "pattern": "api_[A-Za-z0-9]+", "replacement": "api_" }
],
"cases": {}
}
```
## Local-first safety
`clisnapshot run` is read-only unless you pass `--update`. Snapshot writes are constrained to the configured snapshot directory, and unsafe path traversal is rejected. There is no hosted service, telemetry, or account requirement.
Avoid snapshotting secrets. Scrubbers are a guardrail, not a vault.
## Developer workflow
```sh
npm test
npm run check
npm run build
npm run smoke
bash scripts/validate.sh
```
For a real fixture smoke:
```sh
node dist/cli.js run --update --case help-output
node dist/cli.js run --case help-output
```
## Examples
See [`examples/clisnapshot.config.json`](examples/clisnapshot.config.json) and [`fixtures/bin/example-cli.mjs`](fixtures/bin/example-cli.mjs).
For a focused noisy-output walkthrough, see [`docs/tutorials/stabilize-noisy-cli-output.md`](docs/tutorials/stabilize-noisy-cli-output.md) and the runnable config in [`examples/noisy-demo.config.json`](examples/noisy-demo.config.json).
## Contributing and security
Small, atomic PRs are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md), and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
## License
MIT