difr

Golden-file testing for command-line programs.

You write down a command and the output it should produce. difr runs the command and diffs its output against the expected file. When the new output is correct, difr run --update accepts it for review in version control.

$ difr run tests
ok   greet
ok   shout
FAIL sort-names
     --- expected
     +++ actual
      adam
     -miri
      zoe
     +miri

2 passed, 1 failed

Install

go install github.com/vetr0s/difr@latest

Quick start

A test case is a directory. Its files say what to run and what to expect.

File	Required	Meaning
cmd	yes	Command to run. One line
input	no	Standard input for the command
expected	no	Expected standard output

A case with no expected file fails until you accept its output. This is how I add a test: write cmd, run with --update, read the golden file, and keep it when it is correct.

difr run tests      # defaults to ./tests when the path is omitted

Cases can be nested for grouping. A directory containing cmd owns everything below it, including fixture files.

Accepting new output

difr run --update tests

Update mode overwrites every expected file with the command's current output. It does not compare anything. Review the result with git diff before keeping it.

How commands run

Each cmd runs through sh -c. Pipes, redirects, and variable expansion work the same way they do in a shell.

The working directory is the case directory. Fixture files can sit beside the test and use relative paths.

• Windows needs a POSIX shell such as WSL or Git Bash.
• Version 1 compares standard output only.
• Exit codes and standard error appear in failure output but are not assertions.

See TODO.md for planned exit-code and standard-error assertions.

CI

- run: go install github.com/vetr0s/difr@latest
- run: difr run tests

Exit	Meaning
0	Every case passed or update mode completed
1	At least one case failed
2	difr could not load or run the suite

Color is on for a terminal and off for a pipe. --color=always, --color=never, and NO_COLOR override that choice.

Status

Version 1 discovers cases by directory convention and compares exact standard output. It does not assert exit codes or standard error.

Run the project tests with:

go test ./...

License

MIT. See LICENSE.