Automatically record and play back test recordings

.editorconfig

@@ -7,6 +7,9 @@ indent_size = 4
 indent_style = space
 trim_trailing_whitespace = true
 
+[*.bicep]
+indent_size = 2
+
 [*.json]
 indent_size = 2
 

.vscode/cspell.json

@@ -41,12 +41,14 @@
     "hmac",
     "iothub",
     "keyvault",
+    "lldb",
     "maxresults",
     "maxsize",
     "msrc",
     "newtonsoft",
     "oidc",
     "pageable",
+    "pageables",
     "pkce",
     "pkcs",
     "posix",
@@ -60,7 +62,8 @@
     "upvote",
     "userdelegationkey",
     "versionid",
-    "virtualmachine"
+    "virtualmachine",
+    "worktree"
   ],
   "dictionaryDefinitions": [
     {
@@ -160,4 +163,4 @@
       ]
     }
   ]
-}
+}

CONTRIBUTING.md

@@ -6,7 +6,7 @@
 
   When you run `cargo build`, toolchain version [1.80](https://releases.rs/docs/1.80.0/) and necessary components will be installed automatically.
 
-- (Recommended) If you use [Visual Studio Code](https://code.visualstudio.com), install recommended extensions to improve your development experience.
+- (Recommended) If you use [Visual Studio Code], install recommended extensions to improve your development experience.
 
 ## Generated code
 
@@ -21,6 +21,77 @@ To build any library in the Azure SDK for Rust navigate to the library's project
 [TODO] Add instructions on how to run tests for a specific project.
 [TODO] Add instructions for write new tests.
 
+### Debugging with Visual Studio Code
+
+[Visual Studio Code] with recommended extensions installed can be used to run and debug tests for a module or individual tests.
+
+If you need to debug a test, you can use the LLDB extension and set environment variables as needed. For example, to debug recording a specific test,
+your `.vscode/launch.json` file might look something like:
+
+```json
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "lldb",
+      "request": "launch",
+      "name": "Record secret_roundtrip",
+      "cargo": {
+        "args": [
+          "test",
+          "--no-run",
+          "--test=secret_client",
+          "--package=azure_security_keyvault_secrets",
+          "secret_roundtrip"
+        ],
+        "filter": {
+          "name": "secret_client",
+          "kind": "test"
+        },
+        "env": {
+        }
+      },
+      "cwd": "${workspaceFolder}",
+      "env": {
+        "AZURE_KEYVAULT_URL": "https://my-vault.vault.azure.net/",
+        "PROXY_MANUAL_START": "true",
+        "RUST_LOG": "trace"
+      }
+    },
+    {
+      "type": "lldb",
+      "request": "launch",
+      "name": "Play back secret_roundtrip",
+      "cargo": {
+        "args": [
+          "test",
+          "--no-run",
+          "--test=secret_client",
+          "--package=azure_security_keyvault_secrets",
+          "secret_roundtrip"
+        ],
+        "filter": {
+          "name": "secret_client",
+          "kind": "test"
+        },
+        "env": {
+          "AZURE_TEST_MODE": "playback"
+        }
+      },
+      "cwd": "${workspaceFolder}",
+      "env": {
+        "RUST_LOG": "trace"
+      }
+    }
+  ]
+}
+```
+
+You can also start the [Test Proxy] manually, in which can you add to the outer `env` above to `"PROXY_MANUAL_START": "true"`.
+
+To enable tracing, you can add the `RUST_LOG` environment variable as shown above using the [same format supported by `env_logger`](https://docs.rs/env_logger/latest/env_logger/#enabling-logging).
+The targets are the crate names if you want to trace more or less for specific targets e.g., `RUST_LOG=info,azure_core=trace` to trace information messages by default but detailed traces for the `azure_core` crate.
+
 ## Code Review Process
 
 Before a pull request will be considered by the Azure SDK team, the following requirements must be met:
@@ -94,3 +165,6 @@ Samples may take the following categories of dependencies:
 - **Tiered licensed**: Offerings that enable readers to use the license tier that corresponds to their characteristics. For example, tiers may be available for students, hobbyists, or companies with defined revenue  thresholds. For offerings with tiered licenses, strive to limit our use in tutorials to the features available in the lowest tier. This policy enables the widest audience for the article. [Docker](https://www.docker.com/), [IdentityServer](https://duendesoftware.com/products/identityserver), [ImageSharp](https://sixlabors.com/products/imagesharp/), and [Visual Studio](https://visualstudio.com) are examples of this license type.
 
 In general, we prefer taking dependencies on licensed components in the order of the listed categories. In cases where the category may not be well known, we'll document the category so that readers understand the choice that they're making by using that dependency.
+
+[Test Proxy]: https://github.com/Azure/azure-sdk-tools/blob/main/tools/test-proxy/Azure.Sdk.Tools.TestProxy/README.md
+[Visual Studio Code]: https://code.visualstudio.com

sdk/core/azure_core/src/test.rs

@@ -36,8 +36,8 @@ impl fmt::Debug for TestMode {
     }
 }
 
-impl From<&TestMode> for &'static str {
-    fn from(mode: &TestMode) -> Self {
+impl From<TestMode> for &'static str {
+    fn from(mode: TestMode) -> Self {
         match mode {
             TestMode::Playback => "playback",
             TestMode::Record => "record",
@@ -46,6 +46,12 @@ impl From<&TestMode> for &'static str {
     }
 }
 
+impl From<&TestMode> for &'static str {
+    fn from(mode: &TestMode) -> Self {
+        TestMode::into(*mode)
+    }
+}
+
 impl FromStr for TestMode {
     type Err = Error;
 

sdk/core/azure_core_test/Cargo.toml

@@ -12,18 +12,36 @@ keywords = ["sdk", "azure", "rest", "iot", "cloud"]
 categories = ["development-tools::testing"]
 edition.workspace = true
 rust-version.workspace = true
+publish = false
+
+[features]
+default = []
+tracing = ["tracing-subscriber"]
 
 [dependencies]
 async-trait.workspace = true
 azure_core = { workspace = true, features = ["test"] }
 azure_core_test_macros.workspace = true
+azure_identity.workspace = true
+futures.workspace = true
 serde.workspace = true
 serde_json.workspace = true
 tracing.workspace = true
+tracing-subscriber = { workspace = true, features = [
+  "env-filter",
+  "fmt",
+], optional = true }
 typespec_client_core = { workspace = true, features = ["derive"] }
+url.workspace = true
 
 [target.'cfg(not(target_arch = "wasm32"))'.dependencies]
-tokio = { workspace = true, features = ["io-util", "process", "sync", "time"] }
+tokio = { workspace = true, features = [
+  "io-util",
+  "process",
+  "rt-multi-thread",
+  "sync",
+  "time",
+] }
 
 [dev-dependencies]
 clap.workspace = true

sdk/core/azure_core_test/README.md

@@ -4,22 +4,24 @@ The types and functions in this crate help test client libraries built on `azure
 
 ## Client methods
 
-To test client methods using our [Test Proxy], you can attribute both synchronous and asynchronous (recommend) tests
+To test client methods using our [Test Proxy] or run against live resources, you can attribute asynchronous tests
 using the `#[recorded::test]` attribute:
 
 ```rust
-use azure_core_test::{recorded, TestContext};
 use azure_core::Result;
+use azure_core_test::{recorded, TestContext};
 
 #[recorded::test]
 async fn get_secret(ctx: TestContext) -> Result<()> {
     todo!()
 }
 ```
 
-The `TestContext` parameter is required unless your test function is attribute as `#[recorded::test(live)]` (live-only),
-in which case it is optional. You can name the parameter whatever you want.
+The `TestContext` parameter is required unless your test function is attributed as `#[recorded::test(live)]` (live-only).
+You can name the parameter whatever you want.
 The `TestContext` parameter is used to initialize an HTTP client to play back or record tests
 and provides other information to test functions that may be useful.
 
+These tests must also return a `std::result::Result<T, E>`, which can be redefined e.g., `azure_core::Result<T>`.
+
 [Test Proxy]: https://github.com/Azure/azure-sdk-tools/blob/main/tools/test-proxy/Azure.Sdk.Tools.TestProxy/README.md