docs: add examples on how to test libraries

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)
+	}
+}