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.

tests/integration/client/examples/example_keys_test.go

@@ -23,71 +23,89 @@ 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() {
-	c, err := client.New(client.Config{
-		Endpoints: exampleEndpoints,
-		Transport: exampleTransport,
-	})
-	if err != nil {
-		log.Fatal(err)
-	}
-	kapi := client.NewKeysAPI(c)
+	forUnitTestsRunInMockedContext(
+		mockKeysAPI_directory,
+		func() {
+			c, err := client.New(client.Config{
+				Endpoints: exampleEndpoints,
+				Transport: exampleTransport,
+			})
+			if err != nil {
+				log.Fatal(err)
+			}
+			kapi := client.NewKeysAPI(c)
 
-	// Setting '/myNodes' to create a directory that will hold some keys.
-	o := client.SetOptions{Dir: true}
-	resp, err := kapi.Set(context.Background(), "/myNodes", "", &o)
-	if err != nil {
-		log.Fatal(err)
-	}
+			// Setting '/myNodes' to create a directory that will hold some keys.
+			o := client.SetOptions{Dir: true}
+			resp, err := kapi.Set(context.Background(), "/myNodes", "", &o)
+			if err != nil {
+				log.Fatal(err)
+			}
 
-	// Add keys to /myNodes directory.
-	resp, err = kapi.Set(context.Background(), "/myNodes/key1", "value1", nil)
-	if err != nil {
-		log.Fatal(err)
-	}
-	resp, err = kapi.Set(context.Background(), "/myNodes/key2", "value2", nil)
-	if err != nil {
-		log.Fatal(err)
-	}
+			// Add keys to /myNodes directory.
+			resp, err = kapi.Set(context.Background(), "/myNodes/key1", "value1", nil)
+			if err != nil {
+				log.Fatal(err)
+			}
+			resp, err = kapi.Set(context.Background(), "/myNodes/key2", "value2", nil)
+			if err != nil {
+				log.Fatal(err)
+			}
 
-	// fetch directory
-	resp, err = kapi.Get(context.Background(), "/myNodes", nil)
-	if err != nil {
-		log.Fatal(err)
-	}
-	// print directory keys
-	sort.Sort(resp.Node.Nodes)
-	for _, n := range resp.Node.Nodes {
-		fmt.Printf("Key: %q, Value: %q\n", n.Key, n.Value)
-	}
+			// fetch directory
+			resp, err = kapi.Get(context.Background(), "/myNodes", nil)
+			if err != nil {
+				log.Fatal(err)
+			}
+			// print directory keys
+			sort.Sort(resp.Node.Nodes)
+			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() {
-	c, err := client.New(client.Config{
-		Endpoints: exampleEndpoints,
-		Transport: exampleTransport,
-	})
-	if err != nil {
-		log.Fatal(err)
-	}
-	kapi := client.NewKeysAPI(c)
+	forUnitTestsRunInMockedContext(
+		mockKeysAPI_setget,
+		func() {
+			c, err := client.New(client.Config{
+				Endpoints: exampleEndpoints,
+				Transport: exampleTransport,
+			})
+			if err != nil {
+				log.Fatal(err)
+			}
+			kapi := client.NewKeysAPI(c)
 
-	// Set key "/foo" to value "bar".
-	resp, err := kapi.Set(context.Background(), "/foo", "bar", nil)
-	if err != nil {
-		log.Fatal(err)
-	}
-	// Get key "/foo"
-	resp, err = kapi.Get(context.Background(), "/foo", nil)
-	if err != nil {
-		log.Fatal(err)
-	}
+			// Set key "/foo" to value "bar".
+			resp, err := kapi.Set(context.Background(), "/foo", "bar", nil)
+			if err != nil {
+				log.Fatal(err)
+			}
+			// Get key "/foo"
+			resp, err = kapi.Get(context.Background(), "/foo", nil)
+			if err != nil {
+				log.Fatal(err)
+			}
 
-	fmt.Printf("%q key has %q value\n", resp.Node.Key, resp.Node.Value)
+			fmt.Printf("%q key has %q value\n", resp.Node.Key, resp.Node.Value)
+		})
 
 	// Output: "/foo" key has "bar" value
 }