From 0492dc711c69cacc0ec8aea69e7f2d33d0e66c0e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?McCoy=20Pati=C3=B1o?=
 <39780829+mccoyp@users.noreply.github.com>
Date: Thu, 14 Jul 2022 17:24:27 -0700
Subject: [PATCH] [Test Proxy] Improve variables API documentation (#25203)

---
 doc/dev/test_proxy_migration_guide.md | 19 ++++++++++++-------
 1 file changed, 12 insertions(+), 7 deletions(-)

diff --git a/doc/dev/test_proxy_migration_guide.md b/doc/dev/test_proxy_migration_guide.md
index bc36d453f85b..ffde70b542f9 100644
--- a/doc/dev/test_proxy_migration_guide.md
+++ b/doc/dev/test_proxy_migration_guide.md
@@ -316,20 +316,25 @@ class TestExample(AzureRecordedTestCase):
 
     @recorded_by_proxy
     def test_example(self, **kwargs):
-        # in live mode, variables is an empty dictionary
-        # in playback mode, the value of variables is {"table_name": "random-value"}
-        variables = kwargs.pop("variables")
-        if self.is_live:
-            table_name = "random-value"
-            variables = {"table_name": table_name}
+        # In live mode, variables is an empty dictionary
+        # In playback mode, the value of variables is {"table_name": "random-value"}
+        variables = kwargs.pop("variables", {})
+ 
+        # To fetch variable values, use the `setdefault` method to look for a key ("table_name")
+        # and set a real value for that key if it's not present ("random-value")
+        table_name = variables.setdefault("table_name", "random-value")
 
         # use variables["table_name"] when using the table name throughout the test
         ...
 
-        # return the variables at the end of the test
+        # return the variables at the end of the test to record them
         return variables
 ```
 
+> **Note:** `variables` will be passed as a named argument to any test that accepts `kwargs` by the test proxy. In
+> environments that don't use the test proxy, though -- like live test pipelines -- `variables` won't be provided.
+> To avoid a KeyError, providing an empty dictionary as the default value to `kwargs.pop` is recommended.
+
 ## Migrate management-plane tests
 
 For management-plane packages, test classes should inherit from [AzureMgmtRecordedTestCase][mgmt_recorded_test_case]