tests: Make examples (for not client) to be both: documentation and integration-runnable

This CL tries to connect 2 objectives:
  - Examples should be close (the same package) to the original code,
    such that they can participate in documentation.
  - Examples should be runnable - such that they are not getting out of
    sync with underlying API/implementation.

In case of etcd-client, the examples are assuming running 'integration'
style, i.e. thay do connect to fully functional etcd-server.
That would lead to a cyclic dependencies between modules:
  - server depends on client (as client need to be lightweight)
  - client (for test purposes) depend on server.
Go modules does not allow to distingush testing dependency from
prod-code dependency.

Thus to meet the objective:
  - The examples are getting executed within testing/integration packages against real etcd
  - The examples are symlinked to 'unit' tests, such that they included in documentation.
  - Long-term the unit examples should get rewritten to use 'mocks' instead of real integration tests.

client/example_keys_test.go

@@ -0,0 +1 @@
+../tests/integration/client/examples/example_keys_test.go

client/main_test.go

@@ -0,0 +1,37 @@
+// Copyright 2017 The etcd Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package client_test
+
+import (
+	"net/http"
+	"testing"
+
+	"go.etcd.io/etcd/v3/pkg/testutil"
+)
+
+var exampleEndpoints []string
+var exampleTransport *http.Transport
+
+func forUnitTestsRunInMockedContext(mocking func(), example func()) {
+	mocking()
+	// TODO: Call 'example' when mocking() provides realistic mocking of transport.
+
+	// The real testing logic of examples gets executed
+	// as part of ./tests/integration/client/example/...
+}
+
+func TestMain(m *testing.M) {
+	testutil.MustTestMainWithLeakDetection(m)
+}

pkg/testutil/leak.go

@@ -130,18 +130,23 @@ func interestingGoroutines() (gs []string) {
 	return gs
 }
 
-// MustTestMainWithLeakDetection expands standard m.Run with leaked
+func MustCheckLeakedGoroutine() {
-// goroutines detection.
-func MustTestMainWithLeakDetection(m *testing.M) {
-	v := m.Run()
-
 	http.DefaultTransport.(*http.Transport).CloseIdleConnections()
 
 	// Let the other goroutines finalize.
 	runtime.Gosched()
 
-	if v == 0 && CheckLeakedGoroutine() {
+	if CheckLeakedGoroutine() {
 		os.Exit(1)
 	}
+}
+
+// MustTestMainWithLeakDetection expands standard m.Run with leaked
+// goroutines detection.
+func MustTestMainWithLeakDetection(m *testing.M) {
+	v := m.Run()
+	if v == 0 {
+		MustCheckLeakedGoroutine()
+	}
 	os.Exit(v)
 }

tests/integration/client/examples/example_keys_test.go

@@ -23,7 +23,16 @@ import (
 	"go.etcd.io/etcd/v3/client"
 )
 
+func mockKeysAPI_directory() {
+	// TODO: Replace with proper mocking
+	fmt.Println(`Key: "/myNodes/key1", Value: "value1"`)
+	fmt.Println(`Key: "/myNodes/key2", Value: "value2"`)
+}
+
 func ExampleKeysAPI_directory() {
+	forUnitTestsRunInMockedContext(
+		mockKeysAPI_directory,
+		func() {
 			c, err := client.New(client.Config{
 				Endpoints: exampleEndpoints,
 				Transport: exampleTransport,
@@ -60,13 +69,21 @@ func ExampleKeysAPI_directory() {
 			for _, n := range resp.Node.Nodes {
 				fmt.Printf("Key: %q, Value: %q\n", n.Key, n.Value)
 			}
+		})
 
 	// Output:
 	// Key: "/myNodes/key1", Value: "value1"
 	// Key: "/myNodes/key2", Value: "value2"
 }
 
+func mockKeysAPI_setget() {
+	fmt.Println(`"/foo" key has "bar" value`)
+}
+
 func ExampleKeysAPI_setget() {
+	forUnitTestsRunInMockedContext(
+		mockKeysAPI_setget,
+		func() {
 			c, err := client.New(client.Config{
 				Endpoints: exampleEndpoints,
 				Transport: exampleTransport,
@@ -88,6 +105,7 @@ func ExampleKeysAPI_setget() {
 			}
 
 			fmt.Printf("%q key has %q value\n", resp.Node.Key, resp.Node.Value)
+		})
 
 	// Output: "/foo" key has "bar" value
 }

tests/integration/client/examples/main_test.go

@@ -18,8 +18,6 @@ import (
 	"fmt"
 	"net/http"
 	"os"
-	"regexp"
-	"strings"
 	"testing"
 	"time"
 
@@ -31,26 +29,13 @@ import (
 var exampleEndpoints []string
 var exampleTransport *http.Transport
 
+func forUnitTestsRunInMockedContext(mocking func(), example func()) {
+	// For integration tests runs in the provided environment
+	example()
+}
+
 // TestMain sets up an etcd cluster if running the examples.
 func TestMain(m *testing.M) {
-	useCluster, hasRunArg := false, false // default to running only Test*
-	for _, arg := range os.Args {
-		if strings.HasPrefix(arg, "-test.run=") {
-			exp := strings.Split(arg, "=")[1]
-			match, err := regexp.MatchString(exp, "Example")
-			useCluster = (err == nil && match) || strings.Contains(exp, "Example")
-			hasRunArg = true
-			break
-		}
-	}
-	if !hasRunArg {
-		// force only running Test* if no args given to avoid leak false
-		// positives from having a long-running cluster for the examples.
-		os.Args = append(os.Args, "-test.run=Test")
-	}
-
-	var v int
-	if useCluster {
 	tr, trerr := transport.NewTransport(transport.TLSInfo{}, time.Second)
 	if trerr != nil {
 		fmt.Fprintf(os.Stderr, "%v", trerr)
@@ -60,18 +45,15 @@ func TestMain(m *testing.M) {
 	clus := integration.NewClusterV3(nil, &cfg)
 	exampleEndpoints = []string{clus.Members[0].URL()}
 	exampleTransport = tr
-		v = m.Run()
+	v := m.Run()
 	clus.Terminate(nil)
 	if err := testutil.CheckAfterTest(time.Second); err != nil {
 		fmt.Fprintf(os.Stderr, "%v", err)
 		os.Exit(1)
 	}
-	} else {
-		v = m.Run()
-	}
 
-	if v == 0 && testutil.CheckLeakedGoroutine() {
+	if v == 0 {
-		os.Exit(1)
+		testutil.MustCheckLeakedGoroutine()
 	}
 	os.Exit(v)
 }