gotestdiff

README

gotestdiff

gotestdiff shows a line-by-line comparison of a go Example function's generated and expected output.

When testing Example functions in go, if there is any difference between the output generated by an Example function and the function's expected output, go test dumps both outputs in total, like this:

% go test
--- FAIL: ExampleFoo (0.0s)
got:
... output generated by the function
want:
... output that should have been generated by the function

If the output is more than a few lines long, this makes finding errors... difficult.

gotestdiff filters the above output and produces a diff of the form:

% go test | gotestdiff
--- FAIL: ExampleFoo (0.0s)
changed lines 1 .. 3
         +
    got  | bad
    want | good
         +
    got  | foo
    want | bar
         +
...

This allows a one-on-one comparison between individual lines which should be identical.

Full Example

Assuming we have an Example function like this:

func ExampleNonObvious() {
	terms := []string{
		"neccesary",
		"dictionary",
		"dilligence",
		"discrepancy",
		"UPPER case",
		"Title case",
		"mixEd case",
		"lower case",
	}

	for _, t := range terms {
		fmt.Println(t)
	}

	// Output:
	// necessary
	// dictionary
	// dilligence
	// UPPER case
	// Title case
	// mIxEd case
	// lower case
}

Let's see what go test says...

% go test
--- FAIL: ExampleNonObvious (0.00s)
got:
neccesary
dictionary
dilligence
discrepancy
UPPER case
Title case
mixEd case
lower case
want:
necessary
dictionary
dilligence
UPPER case
Title case
mIxEd case
lower case

OK, so it failed, but where exactly?

Now run go test again, this time adding | gotestdiff to the command:

% go test | gotestdiff
--- FAIL: ExampleNonObvious (0.00s)
changed line 1
         +
    got  | neccesary
    want | necessary
         +
extra output at line 4
         +
    got  | discrepancy
         +
changed line 6
         +
    got  | mixEd case
    want | mIxEd case
         +

Better :-)

Usage

go test | gotestdiff

• filter the output of go test
• --- FAIL: headers of failing Examples are printed verbatim
• the got: and want: blocks are reduced to a minimal set of diffs
• all reported line numbers are relative to the expected output
  • i.e. the // Output: comments within the Example function

gotestdiff -v

• show the installed version and exit

Tip

If the difference between a function's output and its expected output is not apparent, even when using gotestdiff, try adding | cat -vte to show hidden whitespaces.

e.g.

% go test -run Whitespace
--- FAIL: ExampleWithWhitespace (0.00s)
got:
Name   [        ]
Color  [        ]
want:
Name   [	]
Color  [        ]
FAIL

% go test -run Whitespace | gotestdiff
--- FAIL: ExampleWithWhitespace (0.00s)
changed line 1
         +
    got  | Name   [        ]
    want | Name   [	]
         +

% go test -run Whitespace | gotestdiff | cat -vte
--- FAIL: ExampleWithWhitespace (0.00s)$
changed line 1$
         +$
    got  | Name   [        ]$
    want | Name   [^I]$
         +$

References

• Examples - go.dev blog
• #41980 - testing: show diffs for incorrect output from Example tests

Copyright

Copyright 2025, Stephen Riehm