Go recorded test framework

sdk/internal/go.mod

@@ -2,4 +2,11 @@ module github.com/Azure/azure-sdk-for-go/sdk/internal
 
 go 1.14
 
-require golang.org/x/net v0.0.0-20201010224723-4f7140c49acb
+require (
+	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/dnaeon/go-vcr v1.2.0
+	github.com/stretchr/testify v1.7.0
+	golang.org/x/net v0.0.0-20210610132358-84b48f89b13b
+	gopkg.in/yaml.v2 v2.4.0
+	gopkg.in/yaml.v3 v3.0.0-20210107192922-496545a6307b // indirect
+)

sdk/internal/go.sum

@@ -1,12 +1,27 @@
-golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
-golang.org/x/crypto v0.0.0-20200622213623-75b288015ac9/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto=
-golang.org/x/net v0.0.0-20190404232315-eb5bcb51f2a3/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
-golang.org/x/net v0.0.0-20201010224723-4f7140c49acb h1:mUVeFHoDKis5nxCAzoAi7E8Ghb86EXh/RK6wtvJIqRY=
-golang.org/x/net v0.0.0-20201010224723-4f7140c49acb/go.mod h1:sp8m0HH+o8qH0wwXwYZr8TS3Oi6o0r6Gce1SSxlDquU=
-golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
-golang.org/x/sys v0.0.0-20190412213103-97732733099d/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
-golang.org/x/sys v0.0.0-20200930185726-fdedc70b468f/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
-golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
-golang.org/x/text v0.3.3 h1:cokOdA+Jmi5PJGXLlLllQSgYigAEfHXJAERHVMaCc2k=
-golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/dnaeon/go-vcr v1.2.0 h1:zHCHvJYTMh1N7xnV7zf1m1GPBF9Ad0Jk/whtQ1663qI=
+github.com/dnaeon/go-vcr v1.2.0/go.mod h1:R4UdLID7HZT3taECzJs4YgbbH6PIGXB6W/sc5OLb6RQ=
+github.com/modocache/gover v0.0.0-20171022184752-b58185e213c5/go.mod h1:caMODM3PzxT8aQXRPkAt8xlV/e7d7w8GM5g0fa5F0D8=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/testify v1.7.0 h1:nwc3DEeHmmLAfoZucVR881uASk0Mfjw8xYJ99tb5CcY=
+github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+golang.org/x/net v0.0.0-20210610132358-84b48f89b13b h1:k+E048sYJHyVnsr1GDrRZWQ32D2C7lWs9JRc0bel53A=
+golang.org/x/net v0.0.0-20210610132358-84b48f89b13b/go.mod h1:9nx3DQGgdP8bBQD5qxJ1jj9UTztislL4KSBs9R2vV5Y=
+golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20210423082822-04245dca01da/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
+golang.org/x/text v0.3.6 h1:aRYxNxv6iGQlyVaZmk6ZgYEDa+Jg18DxebPSrd6bg1M=
+golang.org/x/text v0.3.6/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
 golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v2 v2.2.8/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
+gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY=
+gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gopkg.in/yaml.v3 v3.0.0-20210107192922-496545a6307b h1:h8qDotaEPuJATrMmW04NCwg7v22aHH28wwpauUhK9Oo=
+gopkg.in/yaml.v3 v3.0.0-20210107192922-496545a6307b/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

sdk/internal/recording/README.md

@@ -0,0 +1,166 @@
+# Azure SDK for Go Recorded Test Framework
+
+[![Build Status](https://dev.azure.com/azure-sdk/public/_apis/build/status/go/Azure.azure-sdk-for-go?branchName=master)](https://dev.azure.com/azure-sdk/public/_build/latest?definitionId=1842&branchName=master)
+
+The `testframework` package makes it easy to add recorded tests to your track-2 client package.
+Below are some examples that walk through setting up a recorded test end to end.
+
+## Examples
+
+### Initializing a Recording instance for a test
+
+The first step in instrumenting a client to interact with recorded tests is to create a `TestContext`.
+This acts as the interface between the recorded test framework and your chosen test package.
+In these examples we'll use testify's [assert](https://pkg.go.dev/github.com/stretchr/testify/assert),
+but you can use the framework of your choice.
+
+In the snippet below, demonstrates an example test setup func in which we are initializing the `TestContext`
+with the methods that will be invoked when your recorded test needs to Log, Fail, get the Name of the test,
+or indicate that the test IsFailed.
+
+***Note**: an instance of TestContext should be initialized for each test.*
+
+```go
+type testState struct {
+    recording *testframework.Recording
+    client    *TableServiceClient
+    context   *testframework.TestContext
+}
+// a map to store our created test contexts
+var clientsMap map[string]*testState = make(map[string]*testState)
+
+// recordedTestSetup is called before each test execution by the test suite's BeforeTest method
+func recordedTestSetup(t *testing.T, testName string, mode testframework.RecordMode) {
+    var accountName string
+    var suffix string
+    var cred *SharedKeyCredential
+    var secret string
+    var uri string
+    assert := assert.New(t)
+
+    // init the test framework
+    context := testframework.NewTestContext(func(msg string) { assert.FailNow(msg) }, func(msg string) { t.Log(msg) }, func() string { return testName })
+    //mode should be testframework.Playback. This will automatically record if no test recording is available and playback if it is.
+    recording, err := testframework.NewRecording(context, mode) 
+    assert.Nil(err)
+```
+
+After creating the TestContext, it must be passed to a new instance of `Recording` along with the current test mode.
+`Recording` is the main component of the testframework package.
+
+```go
+//func recordedTestSetup(t *testing.T, testName string, mode testframework.RecordMode) {
+//  <...>
+    recording, err := testframework.NewRecording(context, mode)
+    assert.Nil(err)
+```
+
+### Initializing recorded variables
+
+A key component to recorded tests is recorded variables.
+They allow creation of values that stay with the test recording so that playback of service operations is consistent.
+
+In the snippet below we are calling `GetRecordedVariable` to acquire details such as the service account name and
+client secret to configure the client.
+
+```go
+//func recordedTestSetup(t *testing.T, testName string, mode testframework.RecordMode) {
+//  <...>
+    accountName, err := recording.GetRecordedVariable(storageAccountNameEnvVar, testframework.Default)
+    suffix := recording.GetOptionalRecordedVariable(storageEndpointSuffixEnvVar, DefaultStorageSuffix, testframework.Default)
+    secret, err := recording.GetRecordedVariable(storageAccountKeyEnvVar, testframework.Secret_Base64String)
+    cred, _ := NewSharedKeyCredential(accountName, secret)
+    uri := storageURI(accountName, suffix)
+```
+
+The last step is to instrument your client by replacing its transport with your `Recording` instance.
+`Recording` satisfies the `azcore.Transport` interface.
+
+```go
+//func recordedTestSetup(t *testing.T, testName string, mode testframework.RecordMode) {
+//  <...>
+    // Set our client's HTTPClient to our recording instance.
+    // Optionally, we can also configure MaxRetries to -1 to avoid the default retry behavior.
+    client, err := NewTableServiceClient(uri, cred, &TableClientOptions{HTTPClient: recording, Retry: azcore.RetryOptions{MaxRetries: -1}})
+    assert.Nil(err)
+
+    // either return your client instance, or store it somewhere that your test can use it for test execution.
+    clientsMap[testName] = &testState{client: client, recording: recording, context: &context}
+}
+
+
+func getTestState(key string) *testState {
+    return clientsMap[key]
+}
+```
+
+### Completing the recorded test session
+
+After the test run completes we need to signal the `Recording` instance to save the recording.
+
+```go
+// recordedTestTeardown fetches the context from our map based on test name and calls Stop on the Recording instance.
+func recordedTestTeardown(key string) {
+    context, ok := clientsMap[key]
+    if ok && !(*context.context).IsFailed() {
+        context.recording.Stop()
+    }
+}
+```
+
+### Setting up a test to use our Recording instance
+
+Test frameworks like testify suite allow for configuration of a `BeforeTest` method to be executed before each test.
+We can use this to call our `recordedTestSetup` method
+
+Below is an example test setup which executes a single test.
+
+```go
+package aztable
+
+import (
+    "errors"
+    "fmt"
+    "net/http"
+    "testing"
+
+    "github.com/Azure/azure-sdk-for-go/sdk/internal/runtime"
+    "github.com/Azure/azure-sdk-for-go/sdk/internal/testframework"
+    "github.com/stretchr/testify/assert"
+    "github.com/stretchr/testify/suite"
+)
+
+type tableServiceClientLiveTests struct {
+    suite.Suite
+    mode         testframework.RecordMode
+}
+
+// Hookup to the testing framework
+func TestServiceClient_Storage(t *testing.T) {
+    storage := tableServiceClientLiveTests{mode: testframework.Playback /* change to Record to re-record tests */}
+    suite.Run(t, &storage)
+}
+
+func (s *tableServiceClientLiveTests) TestCreateTable() {
+    assert := assert.New(s.T())
+    context := getTestContext(s.T().Name())
+    // generate a random recorded value for our table name.
+    tableName, err := context.recording.GenerateAlphaNumericID(tableNamePrefix, 20, true)
+
+    resp, err := context.client.Create(ctx, tableName)
+    defer context.client.Delete(ctx, tableName)
+
+    assert.Nil(err)
+    assert.Equal(*resp.TableResponse.TableName, tableName)
+}
+
+func (s *tableServiceClientLiveTests) BeforeTest(suite string, test string) {
+    // setup the test environment
+    recordedTestSetup(s.T(), s.T().Name(), s.mode)
+}
+
+func (s *tableServiceClientLiveTests) AfterTest(suite string, test string) {
+    // teardown the test context
+    recordedTestTeardown(s.T().Name())
+}
+```