docs: add examples on how to test libraries (#818)

This is the based off the doc added to the gapic libraries. Because
of the design of the api and the fact these clients use HTTP and
not gRPC it is useful to see how testing is done here as well.

Related: googleapis/google-cloud-go#2921

internal/examples/fake/fake.go

@@ -0,0 +1,29 @@
+// Copyright 2021 Google LLC.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// Package fake demonstrates how to use concrete services and fake the
+// interactions with them in tests.
+package fake
+
+import (
+	"fmt"
+	"os"
+
+	"google.golang.org/api/translate/v3"
+)
+
+// TranslateText translates text to the given language using the provided
+// service.
+func TranslateText(service *translate.Service, text, language string) (string, error) {
+	parent := fmt.Sprintf("projects/%s/locations/global", os.Getenv("GOOGLE_CLOUD_PROJECT"))
+	req := &translate.TranslateTextRequest{
+		TargetLanguageCode: language,
+		Contents:           []string{text},
+	}
+	resp, err := service.Projects.Locations.TranslateText(parent, req).Do()
+	if err != nil {
+		return "", fmt.Errorf("unable to translate text: %v", err)
+	}
+	return resp.Translations[0].TranslatedText, nil
+}

internal/examples/fake/fake_test.go

@@ -0,0 +1,45 @@
+// Copyright 2021 Google LLC.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package fake
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"google.golang.org/api/option"
+	"google.golang.org/api/translate/v3"
+)
+
+func TestTranslateText(t *testing.T) {
+	ctx := context.Background()
+	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		resp := &translate.TranslateTextResponse{
+			Translations: []*translate.Translation{
+				{TranslatedText: "Hello World"},
+			},
+		}
+		b, err := json.Marshal(resp)
+		if err != nil {
+			http.Error(w, "unable to marshal request: "+err.Error(), http.StatusBadRequest)
+			return
+		}
+		w.Write(b)
+	}))
+	defer ts.Close()
+	svc, err := translate.NewService(ctx, option.WithoutAuthentication(), option.WithEndpoint(ts.URL))
+	if err != nil {
+		t.Fatalf("unable to create client: %v", err)
+	}
+	text, err := TranslateText(svc, "Hola Mundo", "en-US")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if text != "Hello World" {
+		t.Fatalf("got %q, want Hello World", text)
+	}
+}

internal/examples/mock/highlevel.go

@@ -0,0 +1,54 @@
+// Copyright 2021 Google LLC.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// Package mock demonstrates how to use interfaces to mock interactions with
+// service in tests.
+package mock
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"os"
+
+	"google.golang.org/api/option"
+	"google.golang.org/api/translate/v3"
+)
+
+// TranslateService is a facade of a `translate.Service`, specifically used to
+// for translating text.
+type TranslateService interface {
+	TranslateText(text, language string) (string, error)
+}
+
+// TranslateTextHighLevel translates text to the given language using the
+// provided service.
+func TranslateTextHighLevel(service TranslateService, text, language string) (string, error) {
+	return service.TranslateText(text, language)
+}
+
+type translateService struct {
+	svc *translate.Service
+}
+
+// NewTranslateService creates a TranslateService.
+func NewTranslateService(ctx context.Context, opts ...option.ClientOption) TranslateService {
+	svc, err := translate.NewService(ctx, opts...)
+	if err != nil {
+		log.Fatalf("unable to create translate service, shutting down: %v", err)
+	}
+	return &translateService{svc}
+}
+
+func (t *translateService) TranslateText(text, language string) (string, error) {
+	parent := fmt.Sprintf("projects/%s/locations/global", os.Getenv("GOOGLE_CLOUD_PROJECT"))
+	resp, err := t.svc.Projects.Locations.TranslateText(parent, &translate.TranslateTextRequest{
+		TargetLanguageCode: language,
+		Contents:           []string{text},
+	}).Do()
+	if err != nil {
+		return "", fmt.Errorf("unable to translate text: %v", err)
+	}
+	return resp.Translations[0].TranslatedText, nil
+}

internal/examples/mock/highlevel_test.go

@@ -0,0 +1,24 @@
+// Copyright 2021 Google LLC.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package mock
+
+import "testing"
+
+// mockService fulfills the TranslateService interface.
+type mockService struct{}
+
+func (*mockService) TranslateText(text, language string) (string, error) {
+	return "Hello World", nil
+}
+func TestTranslateTextHighLevel(t *testing.T) {
+	svc := &mockService{}
+	text, err := TranslateTextHighLevel(svc, "Hola Mundo", "en-US")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if text != "Hello World" {
+		t.Fatalf("got %q, want Hello World", text)
+	}
+}

internal/examples/mock/lowlevel.go

@@ -0,0 +1,27 @@
+// Copyright 2021 Google LLC.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package mock
+
+import (
+	"fmt"
+
+	"google.golang.org/api/googleapi"
+	"google.golang.org/api/translate/v3"
+)
+
+// TranslateTextCall is used to translate text and is fullfilled by a
+// `translate.ProjectsTranslateTextCall`.
+type TranslateTextCall interface {
+	Do(opts ...googleapi.CallOption) (*translate.TranslateTextResponse, error)
+}
+
+// TranslateTextLowLevel executes the call and returns the translated text.
+func TranslateTextLowLevel(call TranslateTextCall) (string, error) {
+	resp, err := call.Do()
+	if err != nil {
+		return "", fmt.Errorf("unable to translate text: %v", err)
+	}
+	return resp.Translations[0].TranslatedText, nil
+}

internal/examples/mock/lowlevel_test.go

@@ -0,0 +1,36 @@
+// Copyright 2021 Google LLC.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package mock
+
+import (
+	"testing"
+
+	"google.golang.org/api/googleapi"
+	"google.golang.org/api/translate/v3"
+)
+
+// mockCall fullfills the TranslateTextCall and matches the `Do` call on
+// `translate.ProjectsTranslateTextCall`.
+type mockCall struct{}
+
+func (*mockCall) Do(opts ...googleapi.CallOption) (*translate.TranslateTextResponse, error) {
+	resp := &translate.TranslateTextResponse{
+		Translations: []*translate.Translation{
+			{TranslatedText: "Hello World"},
+		},
+	}
+	return resp, nil
+}
+
+func TestTranslateTextLowLevel(t *testing.T) {
+	call := &mockCall{}
+	text, err := TranslateTextLowLevel(call)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if text != "Hello World" {
+		t.Fatalf("got %q, want Hello World", text)
+	}
+}