Project: Grafana Loki (Observability and Analysis / Observability)
File: testing.md

The Go client libraries generated as a part of `cloud.google.com/go` all take the approach of returning concrete types instead of interfaces. That way, new fields and methods can be added to the libraries without breaking users. This document will go over some patterns that can be used to test code that depends on the Go client libraries. Note: You can see the full . The clients found in `cloud.google.com/go` are gRPC based, with a couple of notable exceptions being the and clients. Interactions with gRPC services can be faked by serving up your own in-memory server within your test. One benefit of using this approach is that you dont need to define an interface in your runtime code; you can keep using concrete struct types. You instead define a fake server in your test code. For example, take a look at the following function: ```go import ( "context" "fmt" "log" "os" translate "cloud.google.com/go/translate/apiv3" "github.com/googleapis/gax-go/v2" translatepb "google.golang.org/genproto/googleapis/cloud/translate/v3" ) func TranslateTextWithConcreteClient(client *translate.TranslationClient, text string, targetLang string) (string, error) { ctx := context.Background() log.Printf("Translating %q to %q", text, targetLang) req := &translatepb.TranslateTextRequest{ Parent: fmt.Sprintf("projects/%s/locations/global", os.Getenv("GOOGLECLOUDPROJECT")), TargetLanguageCode: "en-US", Contents: []string{text}, } resp, err := client.TranslateText(ctx, req) if err != nil { return "", fmt.Errorf("unable to translate text: %v", err) } translations := resp.GetTranslations() if len(translations) != 1 { return "", fmt.Errorf("expected only one result, got %d", len(translations)) } return translations[0].TranslatedText, nil } ``` Here is an example of what a fake server implementation would look like for faking the interactions above: ```go import ( "context" translatepb "google.golang.org/genproto/googleapis/cloud/translate/v3" ) type fakeTranslationServer struct { translatepb.UnimplementedTranslationServiceServer } func (f fakeTranslationServer) TranslateText(ctx context.Context, req translatepb.TranslateTextRequest) (*translatepb.TranslateTextResponse, error) { resp := &translatepb.TranslateTextResponse{ Translations: []*translatepb.Translation{ &translatepb.Translation{ TranslatedText: "Hello World", }, }, } return resp, nil } ``` All of the generated protobuf code found in contains a similar `package.UnimplmentedFooServer` type that is useful for creating fakes. By embedding the unimplemented server in the `fakeTranslationServer`, the fake will inherit all of the RPCs the server exposes. Then, by providing our own `fakeTranslationServer.TranslateText` method you can override the default unimplemented behavior of the one RPC that you would like to be faked. The test itself does require a little bit of setup: start up a `net.Listener`, register the server, and tell the client library to call the server: ```go import ( "context" "net" "testing" translate "cloud.google.com/go/translate/apiv3" "google.golang.org/api/option" translatepb "google.golang.org/genproto/googleapis/cloud/translate/v3" "google.golang.org/grpc" ) func TestTranslateTextWithConcreteClient(t *testing.T) { ctx := context.Background() // Setup the fake server. fakeTranslationServer := &fakeTranslationServer{} l, err := net.Listen("tcp", "localhost:0") if err != nil { t.Fatal(err) } gsrv := grpc.NewServer() translatepb.RegisterTranslationServiceServer(gsrv, fakeTranslationServer) fakeServerAddr := l.Addr().String() go func() { if err := gsrv.Serve(l); err != nil { panic(err) } }() // Create a client. client, err := translate.NewTranslationClient(ctx, option.WithEndpoint(fakeServerAddr),

option.WithGRPCDialOption(grpc.WithInsecure()), ) if err != nil { t.Fatal(err) } // Run the test. text, err := TranslateTextWithConcreteClient(client, "Hola Mundo", "en-US") if err != nil { t.Fatal(err) } if text != "Hello World" { t.Fatalf("got %q, want Hello World", text) } } ``` Note: You can see the full . When mocking code you need to work with interfaces. Lets create an interface for the `cloud.google.com/go/translate/apiv3` client used in the `TranslateTextWithConcreteClient` function mentioned in the previous section. The `translate.Client` has over a dozen methods but this code only uses one of them. Here is an interface that satisfies the interactions of the `translate.Client` in this function. ```go type TranslationClient interface { TranslateText(ctx context.Context, req translatepb.TranslateTextRequest, opts ...gax.CallOption) (translatepb.TranslateTextResponse, error) } ``` Now that we have an interface that satisfies the method being used we can rewrite the function signature to take the interface instead of the concrete type. ```go func TranslateTextWithInterfaceClient(client TranslationClient, text string, targetLang string) (string, error) { // ... } ``` This allows a real `translate.Client` to be passed to the method in production and for a mock implementation to be passed in during testing. This pattern can be applied to any Go code, not just `cloud.google.com/go`. This is because interfaces in Go are implicitly satisfied. Structs in the client libraries can implicitly implement interfaces defined in your codebase. Lets take a look at what it might look like to define a lightweight mock for the `TranslationClient` interface. ```go import ( "context" "testing" "github.com/googleapis/gax-go/v2" translatepb "google.golang.org/genproto/googleapis/cloud/translate/v3" ) type mockClient struct{} func (mockClient) TranslateText(_ context.Context, req translatepb.TranslateTextRequest, opts ...gax.CallOption) (*translatepb.TranslateTextResponse, error) { resp := &translatepb.TranslateTextResponse{ Translations: []*translatepb.Translation{ &translatepb.Translation{ TranslatedText: "Hello World", }, }, } return resp, nil } func TestTranslateTextWithAbstractClient(t *testing.T) { client := &mockClient{} text, err := TranslateTextWithInterfaceClient(client, "Hola Mundo", "en-US") if err != nil { t.Fatal(err) } if text != "Hello World" { t.Fatalf("got %q, want Hello World", text) } } ``` If you prefer to not write your own mocks there are mocking frameworks such as which can generate mocks for you from an interface. As a word of caution though, try to not . Some of the client libraries provided in `cloud.google.com/go` support running against a service emulator. The concept is similar to that of using fakes, mentioned above, but the server is managed for you. You just need to start it up and instruct the client library to talk to the emulator by setting a service specific emulator environment variable. Current services/environment-variables are: bigtable: `BIGTABLEEMULATORHOST` datastore: `DATASTOREEMULATORHOST` firestore: `FIRESTOREEMULATORHOST` pubsub: `PUBSUBEMULATORHOST` spanner: `SPANNEREMULATORHOST` storage: `STORAGEEMULATORHOST` Although the storage client supports an emulator environment variable there is no official emulator provided by gcloud. For more information on emulators please refer to the .