diff

func Files ¶

func Files(expPath, gotPath string) (ds string, err error)

Files diffs expPath with gotPath and prints a git style diff header.

It uses git under the hood.

func JSON ¶

func JSON(exp, got interface{}) (string, error)

func Runes ¶

func Runes(exp, got string) error

Runes is like Strings but formats exp and got with each unicode codepoint on a separate line and generates a diff of that. It's useful for autogenerated UTF-8 with xrand.String as Strings won't generate a coherent diff with undisplayable characters.

func Strings ¶

func Strings(exp, got string) (ds string, err error)

Strings diffs exp with got in a git style diff.

The git style diff header will contain real paths to exp and got on the file system so that you can easily inspect them.

This behavior is particularly useful for when you need to update a test with the new got. You can just copy and paste from the got file in the diff header.

It uses Files under the hood.

func Testdata ¶

func Testdata(path, ext string, got []byte) error

ext includes period like path.Ext()

func TestdataDir ¶

func TestdataDir(testName, dir string) (err error)

func TestdataJSON ¶

func TestdataJSON(path string, got interface{}) error

TestdataJSON is for when you have JSON that is too large to easily keep embedded by the tests in _test.go files. As well, it makes the acceptance of large changes trivial unlike say fs/embed.

TestdataJSON encodes got as JSON and diffs it against the stored json in path.exp.json. The got JSON is stored in path.got.json. If the diff is empty, it returns nil.

Otherwise it returns an error containing the diff.

In order to accept changes path.got.json has to become path.exp.json. You can use ./ci/testdata/accept.sh to rename all non stale path.got.json files to path.exp.json.

You can scope it to a single test or folder, see ./ci/testdata/accept.sh --help

Also see ./ci/testdata/clean.sh --help for cleaning the repository of all path.got.json and path.exp.json files.

You can also use $TESTDATA_ACCEPT=1 to update all path.exp.json files on the fly. This is useful when you're regenerating the repository's testdata. You can't easily use the accept script without rerunning go test multiple times as go test will return after too many test failures and will not continue until they are fixed.

You'll want to use -count=1 to disable go test's result caching if you do use $TESTDATA_ACCEPT.

TestdataJSON will automatically create nonexistent directories in path.

Here's an example that you can play with to better understand the behaviour:

err = diff.TestdataJSON(filepath.Join("testdata", t.Name()), "change me")
if err != nil {
	t.Fatal(err)
}

Normally you want to use t.Name() as path for clarity but you can pass in any string. e.g. a single test could persist two json objects into testdata with:

err = diff.TestdataJSON(filepath.Join("testdata", t.Name(), "1"), "change me 1")
if err != nil {
	t.Fatal(err)
}
err = diff.TestdataJSON(filepath.Join("testdata", t.Name(), "2"), "change me 2")
if err != nil {
	t.Fatal(err)
}

These would persist in testdata/${t.Name()}/1.exp.json and testdata/${t.Name()}/2.exp.json

It uses Files under the hood.

note: testdata is the canonical Go directory for such persistent test only files.

It is unfortunately poorly documented. See https://pkg.go.dev/cmd/go/internal/test
So normally you'd want path to be filepath.Join("testdata", t.Name()).
This is also the reason this function is named "TestdataJSON".