clientv3: Expose clientv3/examples close to the code.

Many of the tests had missing '// Output:' comment, so were not
runnable. They required fining.

.words

@@ -108,6 +108,7 @@ uncontended
 unfreed
 unlisting
 unprefixed
+WatchProgressNotifyInterval
 WAL
 WithBackoff
 WithDialer

clientv3/example_auth_test.go

@@ -0,0 +1 @@
+../tests/integration/clientv3/examples/example_auth_test.go

clientv3/example_cluster_test.go

@@ -0,0 +1 @@
+../tests/integration/clientv3/examples/example_cluster_test.go

clientv3/example_kv_test.go

@@ -0,0 +1 @@
+../tests/integration/clientv3/examples/example_kv_test.go

clientv3/example_lease_test.go

@@ -0,0 +1 @@
+../tests/integration/clientv3/examples/example_lease_test.go

clientv3/example_maintenance_test.go

@@ -0,0 +1 @@
+../tests/integration/clientv3/examples/example_maintenance_test.go

clientv3/example_metrics_test.go

@@ -0,0 +1 @@
+../tests/integration/clientv3/examples/example_metrics_test.go

clientv3/example_test.go

@@ -0,0 +1 @@
+../tests/integration/clientv3/examples/example_test.go

clientv3/example_watch_test.go

@@ -0,0 +1 @@
+../tests/integration/clientv3/examples/example_watch_test.go

clientv3/main_test.go

@@ -0,0 +1,41 @@
+// 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 clientv3_test
+
+import (
+	"testing"
+	"time"
+
+	"go.etcd.io/etcd/v3/pkg/testutil"
+)
+
+const (
+	dialTimeout    = 5 * time.Second
+	requestTimeout = 10 * time.Second
+)
+
+func exampleEndpoints() []string { return nil }
+
+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/clientv3/integration/...
+}
+
+func TestMain(m *testing.M) {
+	testutil.MustTestMainWithLeakDetection(m)
+}

etcdserver/v3_server.go

@@ -303,6 +303,8 @@ func (s *EtcdServer) LeaseRenew(ctx context.Context, id lease.LeaseID) (int64, e
 				return ttl, err
 			}
 		}
+		// Throttle in case of e.g. connection problems.
+		time.Sleep(50 * time.Millisecond)
 	}
 
 	if cctx.Err() == context.DeadlineExceeded {

test

@@ -94,9 +94,6 @@ function unit_pass {
 
 function integration_extra {
   if [ -z "${PKG}" ] ; then
-    if [[ -z "${RUN_ARG[*]}" ]]; then
-      run_for_module "tests"  go_test "./integration/..." "keep_going" : -timeout="${TIMEOUT:-5m}" "${COMMON_TEST_FLAGS[@]}" --run=Example "$@" || return $?
-    fi
     run_for_module "."  go_test "./contrib/raftexample" "keep_going" :  -timeout="${TIMEOUT:-5m}" "${RUN_ARG[@]}" "${COMMON_TEST_FLAGS[@]}" "$@" || return $?
     run_for_module "tests"  go_test "./integration/v2store/..." "keep_going" : -tags v2v3 -timeout="${TIMEOUT:-5m}" "${RUN_ARG[@]}" "${COMMON_TEST_FLAGS[@]}" "$@" || return $?
   else

tests/integration/clientv3/examples/example_auth_test.go

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-package clientv3test
+package clientv3_test
 
 import (
 	"context"
@@ -22,9 +22,17 @@ import (
 	"go.etcd.io/etcd/v3/clientv3"
 )
 
+func mockAuth() {
+	fmt.Println(`etcdserver: permission denied`)
+	fmt.Println(`user u permission: key "foo", range end "zoo"`)
+}
+
 func ExampleAuth() {
+	forUnitTestsRunInMockedContext(
+		mockAuth,
+		func() {
 			cli, err := clientv3.New(clientv3.Config{
-		Endpoints:   endpoints,
+				Endpoints:   exampleEndpoints(),
 				DialTimeout: dialTimeout,
 			})
 			if err != nil {
@@ -66,7 +74,7 @@ func ExampleAuth() {
 			}
 
 			cliAuth, err := clientv3.New(clientv3.Config{
-		Endpoints:   endpoints,
+				Endpoints:   exampleEndpoints(),
 				DialTimeout: dialTimeout,
 				Username:    "u",
 				Password:    "123",
@@ -89,7 +97,7 @@ func ExampleAuth() {
 
 			// now check the permission with the root account
 			rootCli, err := clientv3.New(clientv3.Config{
-		Endpoints:   endpoints,
+				Endpoints:   exampleEndpoints(),
 				DialTimeout: dialTimeout,
 				Username:    "root",
 				Password:    "123",
@@ -108,6 +116,7 @@ func ExampleAuth() {
 			if _, err = rootCli.AuthDisable(context.TODO()); err != nil {
 				log.Fatal(err)
 			}
+		})
 	// Output: etcdserver: permission denied
 	// user u permission: key "foo", range end "zoo"
 }

tests/integration/clientv3/examples/example_cluster_test.go

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-package clientv3test
+package clientv3_test
 
 import (
 	"context"
@@ -22,9 +22,14 @@ import (
 	"go.etcd.io/etcd/v3/clientv3"
 )
 
+func mockCluster_memberList() {
+	fmt.Println("members: 3")
+}
+
 func ExampleCluster_memberList() {
+	forUnitTestsRunInMockedContext(mockCluster_memberList, func() {
 		cli, err := clientv3.New(clientv3.Config{
-		Endpoints:   endpoints,
+			Endpoints:   exampleEndpoints(),
 			DialTimeout: dialTimeout,
 		})
 		if err != nil {
@@ -37,12 +42,19 @@ func ExampleCluster_memberList() {
 			log.Fatal(err)
 		}
 		fmt.Println("members:", len(resp.Members))
+	})
 	// Output: members: 3
 }
 
+func mockCluster_memberAdd() {
+	fmt.Println("added member.PeerURLs: [http://localhost:32380]")
+	fmt.Println("members count: 4")
+}
+
 func ExampleCluster_memberAdd() {
+	forUnitTestsRunInMockedContext(mockCluster_memberAdd, func() {
 		cli, err := clientv3.New(clientv3.Config{
-		Endpoints:   endpoints[:2],
+			Endpoints:   exampleEndpoints(),
 			DialTimeout: dialTimeout,
 		})
 		if err != nil {
@@ -50,18 +62,34 @@ func ExampleCluster_memberAdd() {
 		}
 		defer cli.Close()
 
-	peerURLs := endpoints[2:]
-	mresp, err := cli.MemberAdd(context.Background(), peerURLs)
+		// Add member 1:
+		mresp, err := cli.MemberAdd(context.Background(), []string{"http://localhost:32380"})
 		if err != nil {
 			log.Fatal(err)
 		}
 		fmt.Println("added member.PeerURLs:", mresp.Member.PeerURLs)
+		fmt.Println("members count:", len(mresp.Members))
+
+		// Restore original cluster state
+		_, err = cli.MemberRemove(context.Background(), mresp.Member.ID)
+		if err != nil {
+			log.Fatal(err)
+		}
+	})
+	// Output:
 	// added member.PeerURLs: [http://localhost:32380]
+	// members count: 4
+}
+
+func mockCluster_memberAddAsLearner() {
+	fmt.Println("members count: 4")
+	fmt.Println("added member.IsLearner: true")
 }
 
 func ExampleCluster_memberAddAsLearner() {
+	forUnitTestsRunInMockedContext(mockCluster_memberAddAsLearner, func() {
 		cli, err := clientv3.New(clientv3.Config{
-		Endpoints:   endpoints[:2],
+			Endpoints:   exampleEndpoints(),
 			DialTimeout: dialTimeout,
 		})
 		if err != nil {
@@ -69,20 +97,31 @@ func ExampleCluster_memberAddAsLearner() {
 		}
 		defer cli.Close()
 
-	peerURLs := endpoints[2:]
-	mresp, err := cli.MemberAddAsLearner(context.Background(), peerURLs)
+		mresp, err := cli.MemberAddAsLearner(context.Background(), []string{"http://localhost:32381"})
 		if err != nil {
 			log.Fatal(err)
 		}
-	fmt.Println("added member.PeerURLs:", mresp.Member.PeerURLs)
+
+		// Restore original cluster state
+		_, err = cli.MemberRemove(context.Background(), mresp.Member.ID)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		fmt.Println("members count:", len(mresp.Members))
 		fmt.Println("added member.IsLearner:", mresp.Member.IsLearner)
-	// added member.PeerURLs: [http://localhost:32380]
+	})
+	// Output:
+	// members count: 4
 	// added member.IsLearner: true
 }
 
+func mockCluster_memberRemove() {}
+
 func ExampleCluster_memberRemove() {
+	forUnitTestsRunInMockedContext(mockCluster_memberRemove, func() {
 		cli, err := clientv3.New(clientv3.Config{
-		Endpoints:   endpoints[1:],
+			Endpoints:   exampleEndpoints(),
 			DialTimeout: dialTimeout,
 		})
 		if err != nil {
@@ -99,11 +138,21 @@ func ExampleCluster_memberRemove() {
 		if err != nil {
 			log.Fatal(err)
 		}
+
+		// Restore original cluster:
+		_, err = cli.MemberAdd(context.Background(), resp.Members[0].PeerURLs)
+		if err != nil {
+			log.Fatal(err)
+		}
+	})
 }
 
+func mockCluster_memberUpdate() {}
+
 func ExampleCluster_memberUpdate() {
+	forUnitTestsRunInMockedContext(mockCluster_memberUpdate, func() {
 		cli, err := clientv3.New(clientv3.Config{
-		Endpoints:   endpoints,
+			Endpoints:   exampleEndpoints(),
 			DialTimeout: dialTimeout,
 		})
 		if err != nil {
@@ -121,4 +170,12 @@ func ExampleCluster_memberUpdate() {
 		if err != nil {
 			log.Fatal(err)
 		}
+
+		// Restore to mitigate impact on other tests:
+		_, err = cli.MemberUpdate(context.Background(), resp.Members[0].ID, resp.Members[0].PeerURLs)
+		if err != nil {
+			log.Fatal(err)
+		}
+	})
+	// Output:
 }

tests/integration/clientv3/examples/example_kv_test.go

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-package clientv3test
+package clientv3_test
 
 import (
 	"context"
@@ -23,9 +23,12 @@ import (
 	"go.etcd.io/etcd/v3/clientv3"
 )
 
+func mockKV_put() {}
+
 func ExampleKV_put() {
+	forUnitTestsRunInMockedContext(mockKV_put, func() {
 		cli, err := clientv3.New(clientv3.Config{
-		Endpoints:   endpoints,
+			Endpoints:   exampleEndpoints(),
 			DialTimeout: dialTimeout,
 		})
 		if err != nil {
@@ -39,11 +42,18 @@ func ExampleKV_put() {
 		if err != nil {
 			log.Fatal(err)
 		}
+	})
+	// Output:
+}
+
+func mockKV_putErrorHandling() {
+	fmt.Println("client-side error: etcdserver: key is not provided")
 }
 
 func ExampleKV_putErrorHandling() {
+	forUnitTestsRunInMockedContext(mockKV_putErrorHandling, func() {
 		cli, err := clientv3.New(clientv3.Config{
-		Endpoints:   endpoints,
+			Endpoints:   exampleEndpoints(),
 			DialTimeout: dialTimeout,
 		})
 		if err != nil {
@@ -66,12 +76,18 @@ func ExampleKV_putErrorHandling() {
 				fmt.Printf("bad cluster endpoints, which are not etcd servers: %v\n", err)
 			}
 		}
+	})
 	// Output: client-side error: etcdserver: key is not provided
 }
 
+func mockKV_get() {
+	fmt.Println("foo : bar")
+}
+
 func ExampleKV_get() {
+	forUnitTestsRunInMockedContext(mockKV_get, func() {
 		cli, err := clientv3.New(clientv3.Config{
-		Endpoints:   endpoints,
+			Endpoints:   exampleEndpoints(),
 			DialTimeout: dialTimeout,
 		})
 		if err != nil {
@@ -93,12 +109,18 @@ func ExampleKV_get() {
 		for _, ev := range resp.Kvs {
 			fmt.Printf("%s : %s\n", ev.Key, ev.Value)
 		}
+	})
 	// Output: foo : bar
 }
 
+func mockKV_getWithRev() {
+	fmt.Println("foo : bar1")
+}
+
 func ExampleKV_getWithRev() {
+	forUnitTestsRunInMockedContext(mockKV_getWithRev, func() {
 		cli, err := clientv3.New(clientv3.Config{
-		Endpoints:   endpoints,
+			Endpoints:   exampleEndpoints(),
 			DialTimeout: dialTimeout,
 		})
 		if err != nil {
@@ -124,12 +146,20 @@ func ExampleKV_getWithRev() {
 		for _, ev := range resp.Kvs {
 			fmt.Printf("%s : %s\n", ev.Key, ev.Value)
 		}
+	})
 	// Output: foo : bar1
 }
 
+func mockKV_getSortedPrefix() {
+	fmt.Println(`key_2 : value`)
+	fmt.Println(`key_1 : value`)
+	fmt.Println(`key_0 : value`)
+}
+
 func ExampleKV_getSortedPrefix() {
+	forUnitTestsRunInMockedContext(mockKV_getSortedPrefix, func() {
 		cli, err := clientv3.New(clientv3.Config{
-		Endpoints:   endpoints,
+			Endpoints:   exampleEndpoints(),
 			DialTimeout: dialTimeout,
 		})
 		if err != nil {
@@ -155,15 +185,21 @@ func ExampleKV_getSortedPrefix() {
 		for _, ev := range resp.Kvs {
 			fmt.Printf("%s : %s\n", ev.Key, ev.Value)
 		}
+	})
 	// Output:
 	// key_2 : value
 	// key_1 : value
 	// key_0 : value
 }
 
+func mockKV_delete() {
+	fmt.Println("Deleted all keys: true")
+}
+
 func ExampleKV_delete() {
+	forUnitTestsRunInMockedContext(mockKV_delete, func() {
 		cli, err := clientv3.New(clientv3.Config{
-		Endpoints:   endpoints,
+			Endpoints:   exampleEndpoints(),
 			DialTimeout: dialTimeout,
 		})
 		if err != nil {
@@ -187,13 +223,17 @@ func ExampleKV_delete() {
 		}
 
 		fmt.Println("Deleted all keys:", int64(len(gresp.Kvs)) == dresp.Deleted)
+	})
 	// Output:
 	// Deleted all keys: true
 }
 
+func mockKV_compact() {}
+
 func ExampleKV_compact() {
+	forUnitTestsRunInMockedContext(mockKV_compact, func() {
 		cli, err := clientv3.New(clientv3.Config{
-		Endpoints:   endpoints,
+			Endpoints:   exampleEndpoints(),
 			DialTimeout: dialTimeout,
 		})
 		if err != nil {
@@ -215,11 +255,18 @@ func ExampleKV_compact() {
 		if err != nil {
 			log.Fatal(err)
 		}
+	})
+	// Output:
+}
+
+func mockKV_txn() {
+	fmt.Println("key : XYZ")
 }
 
 func ExampleKV_txn() {
+	forUnitTestsRunInMockedContext(mockKV_txn, func() {
 		cli, err := clientv3.New(clientv3.Config{
-		Endpoints:   endpoints,
+			Endpoints:   exampleEndpoints(),
 			DialTimeout: dialTimeout,
 		})
 		if err != nil {
@@ -255,12 +302,16 @@ func ExampleKV_txn() {
 		for _, ev := range gresp.Kvs {
 			fmt.Printf("%s : %s\n", ev.Key, ev.Value)
 		}
+	})
 	// Output: key : XYZ
 }
 
+func mockKV_do() {}
+
 func ExampleKV_do() {
+	forUnitTestsRunInMockedContext(mockKV_do, func() {
 		cli, err := clientv3.New(clientv3.Config{
-		Endpoints:   endpoints,
+			Endpoints:   exampleEndpoints(),
 			DialTimeout: dialTimeout,
 		})
 		if err != nil {
@@ -278,4 +329,6 @@ func ExampleKV_do() {
 				log.Fatal(err)
 			}
 		}
+	})
+	// Output:
 }

tests/integration/clientv3/examples/example_lease_test.go

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-package clientv3test
+package clientv3_test
 
 import (
 	"context"
@@ -22,9 +22,13 @@ import (
 	"go.etcd.io/etcd/v3/clientv3"
 )
 
+func mockLease_grant() {
+}
+
 func ExampleLease_grant() {
+	forUnitTestsRunInMockedContext(mockLease_grant, func() {
 		cli, err := clientv3.New(clientv3.Config{
-		Endpoints:   endpoints,
+			Endpoints:   exampleEndpoints(),
 			DialTimeout: dialTimeout,
 		})
 		if err != nil {
@@ -43,11 +47,18 @@ func ExampleLease_grant() {
 		if err != nil {
 			log.Fatal(err)
 		}
+	})
+	//Output:
+}
+
+func mockLease_revoke() {
+	fmt.Println("number of keys: 0")
 }
 
 func ExampleLease_revoke() {
+	forUnitTestsRunInMockedContext(mockLease_revoke, func() {
 		cli, err := clientv3.New(clientv3.Config{
-		Endpoints:   endpoints,
+			Endpoints:   exampleEndpoints(),
 			DialTimeout: dialTimeout,
 		})
 		if err != nil {
@@ -76,12 +87,18 @@ func ExampleLease_revoke() {
 			log.Fatal(err)
 		}
 		fmt.Println("number of keys:", len(gresp.Kvs))
+	})
 	// Output: number of keys: 0
 }
 
+func mockLease_keepAlive() {
+	fmt.Println("ttl: 5")
+}
+
 func ExampleLease_keepAlive() {
+	forUnitTestsRunInMockedContext(mockLease_keepAlive, func() {
 		cli, err := clientv3.New(clientv3.Config{
-		Endpoints:   endpoints,
+			Endpoints:   exampleEndpoints(),
 			DialTimeout: dialTimeout,
 		})
 		if err != nil {
@@ -106,13 +123,23 @@ func ExampleLease_keepAlive() {
 		}
 
 		ka := <-ch
+		if ka != nil {
 			fmt.Println("ttl:", ka.TTL)
+		} else {
+			fmt.Println("Unexpected NULL")
+		}
+	})
 	// Output: ttl: 5
 }
 
+func mockLease_keepAliveOnce() {
+	fmt.Println("ttl: 5")
+}
+
 func ExampleLease_keepAliveOnce() {
+	forUnitTestsRunInMockedContext(mockLease_keepAliveOnce, func() {
 		cli, err := clientv3.New(clientv3.Config{
-		Endpoints:   endpoints,
+			Endpoints:   exampleEndpoints(),
 			DialTimeout: dialTimeout,
 		})
 		if err != nil {
@@ -137,5 +164,6 @@ func ExampleLease_keepAliveOnce() {
 		}
 
 		fmt.Println("ttl:", ka.TTL)
+	})
 	// Output: ttl: 5
 }

tests/integration/clientv3/examples/example_maintenance_test.go

@@ -12,18 +12,20 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-package clientv3test
+package clientv3_test
 
 import (
 	"context"
-	"fmt"
 	"log"
 
 	"go.etcd.io/etcd/v3/clientv3"
 )
 
+func mockMaintenance_status() {}
+
 func ExampleMaintenance_status() {
-	for _, ep := range endpoints {
+	forUnitTestsRunInMockedContext(mockMaintenance_status, func() {
+		for _, ep := range exampleEndpoints() {
 			cli, err := clientv3.New(clientv3.Config{
 				Endpoints:   []string{ep},
 				DialTimeout: dialTimeout,
@@ -33,19 +35,20 @@ func ExampleMaintenance_status() {
 			}
 			defer cli.Close()
 
-		resp, err := cli.Status(context.Background(), ep)
+			_, err = cli.Status(context.Background(), ep)
 			if err != nil {
 				log.Fatal(err)
 			}
-		fmt.Printf("endpoint: %s / Leader: %v\n", ep, resp.Header.MemberId == resp.Leader)
 		}
-	// endpoint: localhost:2379 / Leader: false
-	// endpoint: localhost:22379 / Leader: false
-	// endpoint: localhost:32379 / Leader: true
+	})
+	// Output:
 }
 
+func mockMaintenance_defragment() {}
+
 func ExampleMaintenance_defragment() {
-	for _, ep := range endpoints {
+	forUnitTestsRunInMockedContext(mockMaintenance_defragment, func() {
+		for _, ep := range exampleEndpoints() {
 			cli, err := clientv3.New(clientv3.Config{
 				Endpoints:   []string{ep},
 				DialTimeout: dialTimeout,
@@ -59,4 +62,6 @@ func ExampleMaintenance_defragment() {
 				log.Fatal(err)
 			}
 		}
+	})
+	// Output:
 }

tests/integration/clientv3/examples/example_metrics_test.go

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-package clientv3test
+package clientv3_test
 
 import (
 	"context"
@@ -30,9 +30,14 @@ import (
 	"google.golang.org/grpc"
 )
 
+func mockClient_metrics() {
+	fmt.Println(`grpc_client_started_total{grpc_method="Range",grpc_service="etcdserverpb.KV",grpc_type="unary"} 1`)
+}
+
 func ExampleClient_metrics() {
+	forUnitTestsRunInMockedContext(mockClient_metrics, func() {
 		cli, err := clientv3.New(clientv3.Config{
-		Endpoints: endpoints,
+			Endpoints: exampleEndpoints(),
 			DialOptions: []grpc.DialOption{
 				grpc.WithUnaryInterceptor(grpcprom.UnaryClientInterceptor),
 				grpc.WithStreamInterceptor(grpcprom.StreamClientInterceptor),
@@ -80,6 +85,7 @@ func ExampleClient_metrics() {
 				break
 			}
 		}
+	})
 	// Output:
 	//	grpc_client_started_total{grpc_method="Range",grpc_service="etcdserverpb.KV",grpc_type="unary"} 1
 }

tests/integration/clientv3/examples/example_test.go

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-package clientv3test
+package clientv3_test
 
 import (
 	"context"
@@ -21,9 +21,12 @@ import (
 	"log"
 )
 
+func mockConfig_insecure() {}
+
 func ExampleConfig_insecure() {
+	forUnitTestsRunInMockedContext(mockConfig_insecure, func() {
 		cli, err := clientv3.New(clientv3.Config{
-		Endpoints:   endpoints,
+			Endpoints:   exampleEndpoints(),
 			DialTimeout: dialTimeout,
 		})
 		if err != nil {
@@ -35,13 +38,17 @@ func ExampleConfig_insecure() {
 		if err != nil {
 			log.Fatal(err)
 		}
+	})
 
 	// Without the line below the test is not being executed
 
 	// Output:
 }
 
+func mockConfig_withTLS() {}
+
 func ExampleConfig_withTLS() {
+	forUnitTestsRunInMockedContext(mockConfig_withTLS, func() {
 		tlsInfo := transport.TLSInfo{
 			CertFile:      "/tmp/test-certs/test-name-1.pem",
 			KeyFile:       "/tmp/test-certs/test-name-1-key.pem",
@@ -52,7 +59,7 @@ func ExampleConfig_withTLS() {
 			log.Fatal(err)
 		}
 		cli, err := clientv3.New(clientv3.Config{
-		Endpoints:   endpoints,
+			Endpoints:   exampleEndpoints(),
 			DialTimeout: dialTimeout,
 			TLS:         tlsConfig,
 		})
@@ -65,6 +72,7 @@ func ExampleConfig_withTLS() {
 		if err != nil {
 			log.Fatal(err)
 		}
+	})
 	// Without the line below the test is not being executed
 	// Output:
 }

tests/integration/clientv3/examples/example_watch_test.go

@@ -12,19 +12,25 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-package clientv3test
+package clientv3_test
 
 import (
 	"context"
 	"fmt"
 	"log"
+	"time"
 
 	"go.etcd.io/etcd/v3/clientv3"
 )
 
+func mockWatcher_watch() {
+	fmt.Println(`PUT "foo" : "bar"`)
+}
+
 func ExampleWatcher_watch() {
+	forUnitTestsRunInMockedContext(mockWatcher_watch, func() {
 		cli, err := clientv3.New(clientv3.Config{
-		Endpoints:   endpoints,
+			Endpoints:   exampleEndpoints(),
 			DialTimeout: dialTimeout,
 		})
 		if err != nil {
@@ -38,12 +44,18 @@ func ExampleWatcher_watch() {
 				fmt.Printf("%s %q : %q\n", ev.Type, ev.Kv.Key, ev.Kv.Value)
 			}
 		}
+	})
 	// PUT "foo" : "bar"
 }
 
+func mockWatcher_watchWithPrefix() {
+	fmt.Println(`PUT "foo1" : "bar"`)
+}
+
 func ExampleWatcher_watchWithPrefix() {
+	forUnitTestsRunInMockedContext(mockWatcher_watchWithPrefix, func() {
 		cli, err := clientv3.New(clientv3.Config{
-		Endpoints:   endpoints,
+			Endpoints:   exampleEndpoints(),
 			DialTimeout: dialTimeout,
 		})
 		if err != nil {
@@ -57,12 +69,20 @@ func ExampleWatcher_watchWithPrefix() {
 				fmt.Printf("%s %q : %q\n", ev.Type, ev.Kv.Key, ev.Kv.Value)
 			}
 		}
+	})
 	// PUT "foo1" : "bar"
 }
 
+func mockWatcher_watchWithRange() {
+	fmt.Println(`PUT "foo1" : "bar1"`)
+	fmt.Println(`PUT "foo2" : "bar2"`)
+	fmt.Println(`PUT "foo3" : "bar3"`)
+}
+
 func ExampleWatcher_watchWithRange() {
+	forUnitTestsRunInMockedContext(mockWatcher_watchWithRange, func() {
 		cli, err := clientv3.New(clientv3.Config{
-		Endpoints:   endpoints,
+			Endpoints:   exampleEndpoints(),
 			DialTimeout: dialTimeout,
 		})
 		if err != nil {
@@ -72,19 +92,43 @@ func ExampleWatcher_watchWithRange() {
 
 		// watches within ['foo1', 'foo4'), in lexicographical order
 		rch := cli.Watch(context.Background(), "foo1", clientv3.WithRange("foo4"))
+
+		go func() {
+			cli.Put(context.Background(), "foo1", "bar1")
+			cli.Put(context.Background(), "foo5", "bar5")
+			cli.Put(context.Background(), "foo2", "bar2")
+			cli.Put(context.Background(), "foo3", "bar3")
+		}()
+
+		i := 0
 		for wresp := range rch {
 			for _, ev := range wresp.Events {
 				fmt.Printf("%s %q : %q\n", ev.Type, ev.Kv.Key, ev.Kv.Value)
+				i++
+				if i == 3 {
+					// After 3 messages we are done.
+					cli.Delete(context.Background(), "foo", clientv3.WithPrefix())
+					cli.Close()
+					return
 				}
 			}
-	// PUT "foo1" : "bar"
-	// PUT "foo2" : "bar"
-	// PUT "foo3" : "bar"
+		}
+	})
+
+	// Output:
+	// PUT "foo1" : "bar1"
+	// PUT "foo2" : "bar2"
+	// PUT "foo3" : "bar3"
+}
+
+func mockWatcher_watchWithProgressNotify() {
+	fmt.Println(`wresp.IsProgressNotify: true`)
 }
 
 func ExampleWatcher_watchWithProgressNotify() {
+	forUnitTestsRunInMockedContext(mockWatcher_watchWithProgressNotify, func() {
 		cli, err := clientv3.New(clientv3.Config{
-		Endpoints:   endpoints,
+			Endpoints:   exampleEndpoints(),
 			DialTimeout: dialTimeout,
 		})
 		if err != nil {
@@ -92,9 +136,24 @@ func ExampleWatcher_watchWithProgressNotify() {
 		}
 
 		rch := cli.Watch(context.Background(), "foo", clientv3.WithProgressNotify())
+		closedch := make(chan bool)
+		go func() {
+			// This assumes that cluster is configured with frequent WatchProgressNotifyInterval
+			// e.g. WatchProgressNotifyInterval: 200 * time.Millisecond.
+			time.Sleep(time.Second)
+			err := cli.Close()
+			if err != nil {
+				log.Fatal(err)
+			}
+			close(closedch)
+		}()
 		wresp := <-rch
-	fmt.Printf("wresp.Header.Revision: %d\n", wresp.Header.Revision)
 		fmt.Println("wresp.IsProgressNotify:", wresp.IsProgressNotify())
-	// wresp.Header.Revision: 0
+		<-closedch
+	})
+
+	// TODO: Rather wresp.IsProgressNotify: true should be expected
+
+	// Output:
 	// wresp.IsProgressNotify: true
 }

tests/integration/clientv3/examples/main_test.go

@@ -1,4 +1,4 @@
-// Copyright 2016 The etcd Authors
+// 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.
@@ -12,67 +12,41 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-package clientv3test
+package clientv3_test
 
 import (
-	"fmt"
-	"go.etcd.io/etcd/tests/v3/integration"
-	"go.etcd.io/etcd/v3/clientv3"
-	"go.etcd.io/etcd/v3/pkg/testutil"
-	"google.golang.org/grpc/grpclog"
 	"os"
-	"strings"
 	"testing"
 	"time"
+
+	"go.etcd.io/etcd/tests/v3/integration"
+	"go.etcd.io/etcd/v3/pkg/testutil"
 )
 
-var (
+const (
 	dialTimeout    = 5 * time.Second
 	requestTimeout = 10 * time.Second
-	endpoints      = []string{"localhost:2379", "localhost:22379", "localhost:32379"}
 )
 
+var lazyCluster = integration.NewLazyClusterWithConfig(
+	integration.ClusterConfig{
+		Size:                        3,
+		WatchProgressNotifyInterval: 200 * time.Millisecond})
+
+func exampleEndpoints() []string { return lazyCluster.EndpointsV3() }
+
+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]
-			useCluster = 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")
-	}
+	v := m.Run()
+	lazyCluster.Terminate()
 
-	var v int
-	if useCluster {
-		// Redirecting outputs to Stderr, such that they not interleave with examples outputs.
-		// Setting it once and before running any of the test such that it not data-races
-		// between HTTP servers running in different tests.
-		clientv3.SetLogger(grpclog.NewLoggerV2(os.Stderr, os.Stderr, os.Stderr))
-
-		cfg := integration.ClusterConfig{Size: 3}
-		clus := integration.NewClusterV3(nil, &cfg)
-		endpoints = make([]string, 3)
-		for i := range endpoints {
-			endpoints[i] = clus.Client(i).Endpoints()[0]
-		}
-		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() {
-		os.Exit(1)
+	if v == 0 {
+		testutil.MustCheckLeakedGoroutine()
 	}
 	os.Exit(v)
 }

tests/integration/cluster.go

@@ -312,7 +312,8 @@ func (c *cluster) mustNewMember(t testing.TB) *member {
 	return m
 }
 
-func (c *cluster) addMember(t testing.TB) {
+// addMember return PeerURLs of the added member.
+func (c *cluster) addMember(t testing.TB) types.URLs {
 	m := c.mustNewMember(t)
 
 	scheme := schemeFromTLSInfo(c.cfg.PeerTLS)
@@ -327,7 +328,11 @@ func (c *cluster) addMember(t testing.TB) {
 		}
 	}
 	if err != nil {
+		if t != nil {
 			t.Fatalf("add member failed on all members error: %v", err)
+		} else {
+			log.Fatalf("add member failed on all members error: %v", err)
+		}
 	}
 
 	m.InitialPeerURLsMap = types.URLsMap{}
@@ -342,6 +347,7 @@ func (c *cluster) addMember(t testing.TB) {
 	c.Members = append(c.Members, m)
 	// wait cluster to be stable to receive future client requests
 	c.waitMembersMatch(t, c.HTTPMembers())
+	return m.PeerURLs
 }
 
 func (c *cluster) addMemberByURL(t testing.TB, clientURL, peerURL string) error {
@@ -360,8 +366,9 @@ func (c *cluster) addMemberByURL(t testing.TB, clientURL, peerURL string) error
 	return nil
 }
 
-func (c *cluster) AddMember(t testing.TB) {
-	c.addMember(t)
+// AddMember return PeerURLs of the added member.
+func (c *cluster) AddMember(t testing.TB) types.URLs {
+	return c.addMember(t)
 }
 
 func (c *cluster) RemoveMember(t testing.TB, id uint64) {

tests/integration/lazy_cluster.go

@@ -23,13 +23,26 @@ import (
 	"go.etcd.io/etcd/v3/pkg/transport"
 )
 
+// Infrastructure to provision a single shared cluster for tests - only
+// when its needed.
+//
+// See ./tests/integration/clientv3/examples/main_test.go for canonical usage.
+// Please notice that the shared (LazyCluster's) state is preserved between
+// testcases, so left-over state might has cross-testcase effects.
+// Prefer dedicated clusters for substancial test-cases.
+
 type LazyCluster interface {
-	// EndpointsV2 - call to this method might initialize the cluster.
+	// EndpointsV2 - exposes connection points for client v2.
+	// Calls to this method might initialize the cluster.
 	EndpointsV2() []string
 
-	// EndpointsV2 - call to this method might initialize the cluster.
+	// EndpointsV3 - exposes connection points for client v3.
+	// Calls to this method might initialize the cluster.
 	EndpointsV3() []string
 
+	// Cluster - calls to this method might initialize the cluster.
+	Cluster() *ClusterV3
+
 	// Transport - call to this method might initialize the cluster.
 	Transport() *http.Transport
 
@@ -46,7 +59,13 @@ type lazyCluster struct {
 // NewLazyCluster returns a new test cluster handler that gets created on the
 // first call to GetEndpoints() or GetTransport()
 func NewLazyCluster() LazyCluster {
-	return &lazyCluster{cfg: ClusterConfig{Size: 1}}
+	return NewLazyClusterWithConfig(ClusterConfig{Size: 1})
+}
+
+// NewLazyClusterWithConfig returns a new test cluster handler that gets created
+// on the first call to GetEndpoints() or GetTransport()
+func NewLazyClusterWithConfig(cfg ClusterConfig) LazyCluster {
+	return &lazyCluster{cfg: cfg}
 }
 
 func (lc *lazyCluster) mustLazyInit() {
@@ -61,19 +80,23 @@ func (lc *lazyCluster) mustLazyInit() {
 }
 
 func (lc *lazyCluster) Terminate() {
-	if lc != nil {
+	if lc != nil && lc.cluster != nil {
 		lc.cluster.Terminate(nil)
+		lc.cluster = nil
 	}
 }
 
 func (lc *lazyCluster) EndpointsV2() []string {
-	lc.mustLazyInit()
-	return []string{lc.cluster.Members[0].URL()}
+	return []string{lc.Cluster().Members[0].URL()}
 }
 
 func (lc *lazyCluster) EndpointsV3() []string {
+	return lc.Cluster().Client(0).Endpoints()
+}
+
+func (lc *lazyCluster) Cluster() *ClusterV3 {
 	lc.mustLazyInit()
-	return []string{lc.cluster.Client(0).Endpoints()[0]}
+	return lc.cluster
 }
 
 func (lc *lazyCluster) Transport() *http.Transport {