Golang testing — gotest.tools introduction

Published on Jul 28, 2018 by Vincent Demeester.

Introduction

I already wrote 2 previous posts about golang and testing. It’s something I care deeply about and I wanted to continue writing about it. It took me a bit more time than I thought, but getting back to it. Since the last post, Daniel Nephin and I worked (but mainly Daniel 🤗) on bootstrapping a testing helper library.

Let me introduce it to you this library : gotest.tools. As described in the godoc package comment, gotest.tools is a collection of packages to augment testing and support common patterns. It’s an enhanced and growing version of the initial helpers we (the docker/moby maintainers) wrote initially in docker/docker repository. We are using in quite some project here at Docker.

There is a bunch of packages that will all have their own post (linked here when available) :

  • assert (with assert/cmp and assert/opt) that provides assertions for comparing expected values to actual values.
  • env that provides functions to test code that read environment variable or the current working directory.
  • fs that provides tools for creating temporary files, and testing the contents and structure of a directory.
  • golden that provides tools for comparing large multi-line strings.
  • icmd that executes binaries and provides convenient assertions for testing the results.
  • poll that provides tools for testing asynchronous code.
  • skip that provides functions for skipping a test and printing the source code of the condition used to skip the test.

There is also experimental package, using the x notation (as the golang team uses, for example with golang.org/x/sync) :

  • x/subtest that provides a TestContext to subtests which handles cleanup and provides a testing.TB and context.Context.

There is already some good testing helpers in the Go ecosystem : testify, gocheck, ginkgo and a lot more — so why create a new one ? There is multiple reason for it, most of them can be seen in the following GitHub issue.

Daniel also wrote a very useful converter if your code base is currently using testify : gty-migrate-from-testify.

$ go get -u gotest.tools/assert/cmd/gty-migrate-from-testify
# […]
$ go list \
     -f '{{.ImportPath}} {{if .XTestGoFiles}}{{"\n"}}{{.ImportPath}}_test{{end}}' \
     ./... | xargs gty-migrate-from-testify

In the next post, let’s dig into the assertion part of the library, package assert 👼.