How to manage tests which require an API key

I have some hermetic tests, and those work fine. Code in foo.go gets tested in foo_test.go.

But also I have some tests which need an API key, and I want to keep these tests separate from the hermetic tests, since we don't run them in CI.

How can I effectively segregate and these tests in a way that works well with the Go tools and ecosystem?

There are several ways to skip tests. Most of them leverage testing.T.Skip(Now). Following are a few common use-cases for SkipNow. However, since this is just like any old function call you can get as creative as you want.

Using an environment variable

package main

import (
	"os"
	"testing"
)

func TestAlways(t *testing.T) {
}

func TestSometimes(t *testing.T) {
	key := os.Getenv("FOO_API_KEY")
	if key == "" {
		t.Skip("FOO_API_KEY is empty")
	}
}

Run one of:

go test -v
FOO_API_KEY=bar go test -v

Using the built-in short flag

package main

import (
	"testing"
)

func TestAlways(t *testing.T) {
	// ...
}

func TestSometimes(t *testing.T) {
	if testing.Short() {
		t.Skip("-short is set")
	}

	// ...
}

Run one of:

go test -v -short
go test -v

Using a custom flag

package main

import (
	"flag"
	"testing"
)

var withFoo = false // or true to run test by default

func init() {
	flag.BoolVar(&withFoo, "with-foo", withFoo, "Include foo tests")
}

func TestAlways(t *testing.T) {
	// ...
}

func TestSometimes(t *testing.T) {
	if !withFoo {
		t.Skip("-with-foo is not set")
	}

	// ...
}

Run one of:

go test -v
go test -v -with-foo

Using build constraints

// main_test.go
package main

import (
	"testing"
)

func TestAlways(t *testing.T) {
    // ...
}

// foo_test.go
//go:build foo
package main

import (
	"testing"
)

func TestSometimes(t *testing.T) {
    // ...
}

Run one of:

go test -v
go test -v -tags=foo

Note that with build tags the output will not indicate that tests have been skipped. The tagged .go files simply become invisible to the compiler unless the build tag is included on the command line (or in GOFLAGS).