What is useful for t.Cleanup?

Question

Questions

I would like to know the use case of t.Cleanup introduced in Go1.14. What is the convenience of t.Cleanup as compared to using defer?

https://golang.org/pkg/testing/#T.Cleanup.

• Sample

For example, let's say we create a temporary directory, and when we test it, we want to delete the temporary directory we created.

t.Cleanup can be used to write a test as follows, but it also works as defer os.RemoveAll(tempDir).

package mypkg

import (
    "io/ioutil"
    "os"
    "testing"
)

func TestDirwalk(t *testing.T) {
    tempDir, err := ioutil.TempDir(".", "temp")
    if err != nil {
        t.Errorf("create tempDir: %v", err)
    }
    t.Cleanup(func() { os.RemoveAll(tempDir) })

    // something...
}

Answer 1

t.Cleanup is useful for cleaning up resources allocated by a helper function when the test does not care about the resource itself.

Example

Consider testing a service layer. The service uses a *sql.DB but does not create it itself.

package testutils

import (
  "testing"

  "my/db"
  "my/domain"
)

func NewTestSubject(t *testing.T) *domain.Service {
  t.Helper()  
  sqldb := newDatabase(t)
  s, _ := domain.NewService(sqldb)
  return s
}

func newDatabase(t *testing.T) *sql.DB {
  t.Helper()
  d, _ := db.Create()
  t.Cleanup(func() {
    d.Close()
  })
}

Without t.Cleanup newTestSubject would have to return (*domain.Service, *sql.DB), leaking details about domain.Service's construction.

Answer 2

Besides what others have pointed out, t.Cleanup() is also useful when dealing with parallel subtests, where the cleanup should only run after all subtests have completed. Consider

func TestSomething(t *testing.T){
   setup()
   defer cleanup()
   t.Run("parallel subtest 1", func(t *testing.T){
      t.Parallel()
      (...)
   })
   t.Run("parallel subtest 2", func(t *testing.T){
      t.Parallel()
      (...)
   })
}

which doesn't work because the test function will return while the the subtests are still running, causing the resources required by the subtests to get wiped out by defer cleanup().

Before t.Cleanup() a way to solve this was to wrap the subtests on another test

func TestSomething(t *testing.T){
   setup()
   defer cleanup()
   t.Run("parallel tests", func(t *testing.T){
      t.Run("subtest 1", func(t *testing.T){
         t.Parallel()
         (...)
      })
      t.Run("subtest 2", func(t *testing.T){
         t.Parallel()
         (...)
      })
   })
}

which looks ok, but with t.Cleanup() it gets way better

func TestSomething(t *testing.T){
   setup()
   t.Cleanup(cleanup)
   t.Run("parallel subtest 1", func(t *testing.T){
      t.Parallel()
      (...)
   })
   t.Run("parallel subtest 2", func(t *testing.T){
      t.Parallel()
      (...)
   })
}