From f4ab76818ccfdf6ccac53b86a002c5d5ff95a2a4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?McCoy=20Pati=C3=B1o?=
 <39780829+mccoyp@users.noreply.github.com>
Date: Wed, 26 Oct 2022 14:19:35 -0700
Subject: [PATCH] Add test proxy setup instructions to `dev_setup.md` (#27081)

---
 doc/dev/dev_setup.md | 20 ++++++++++++++------
 doc/dev/tests.md     |  2 +-
 2 files changed, 15 insertions(+), 7 deletions(-)

diff --git a/doc/dev/dev_setup.md b/doc/dev/dev_setup.md
index f2dca9198181..4f2171f49123 100644
--- a/doc/dev/dev_setup.md
+++ b/doc/dev/dev_setup.md
@@ -1,9 +1,9 @@
-# Getting the tests to run
+# Run SDK tests
 
-This section describes how to create a dev environment, in order to run the SDK tests,
+This document describes how to create a dev environment in order to run SDK tests
 or execute the various commands available in the toolbox.
 
-## Setting up a virtual environment
+## Set up a virtual environment
 
 1.  If you don't already have it, install Python:
 
@@ -33,7 +33,7 @@ or execute the various commands available in the toolbox.
 
 4. Setup your development environment
 
-    Install the development requirements for a specific library (located in the `dev_requirements.txt` file at the root of the library), [Tox][tox], [Tox monorepo][tox_monorepo] and an editable install of your library:
+    Install the development requirements for a specific library (located in the `dev_requirements.txt` file at the root of the library), [Tox][tox], [Tox monorepo][tox_monorepo] and an editable install of your library. For example, to install requirements for `azure-ai-formrecognizer`:
     ```
     azure-sdk-for-python> cd sdk/formrecognizer/azure-ai-formrecognizer
     azure-sdk-for-python/sdk/formrecognizer/azure-ai-formrecognizer> pip install -r dev_requirements.txt
@@ -46,10 +46,18 @@ or execute the various commands available in the toolbox.
     The recommended place to store your .env file is one directory higher than the `azure-sdk-for-python` location.
     This ensures the secrets will be loaded by the interpreter and most importantly not be committed to Git history.
 
+## Set up the SDK's test-running tool
+
+SDK tests use an in-house tool called the test proxy, which runs in a container and enables recording and playing back HTTP interactions.
+
+Follow the instructions in the [Perform one-time test proxy setup][proxy_setup] section of [tests.md][tests] to set up the test proxy on your machine.
+
 
 <!-- LINKS -->
 [python_website]: https://www.python.org/downloads/
 [python_39]: https://www.microsoft.com/p/python-39/9p7qfqmjrfp7
-[virtual_environment]: https://docs.python.org/3/tutorial/venv.html
+[proxy_setup]: https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/tests.md#perform-one-time-test-proxy-setup
+[tests]: https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/tests.md
 [tox]: https://tox.readthedocs.io/en/latest/
-[tox_monorepo]: https://pypi.org/project/tox-monorepo/
\ No newline at end of file
+[tox_monorepo]: https://pypi.org/project/tox-monorepo/
+[virtual_environment]: https://docs.python.org/3/tutorial/venv.html
diff --git a/doc/dev/tests.md b/doc/dev/tests.md
index 4be3fbb65562..0ff021852414 100644
--- a/doc/dev/tests.md
+++ b/doc/dev/tests.md
@@ -652,7 +652,7 @@ Tests that use the Shared Access Signature (SAS) to authenticate a client should
 
 [packaging]: https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/packaging.md
 [podman]: https://podman.io/
-[proxy_cert_docs]: https://github.com/Azure/azure-sdk-tools/blob/main/tools/test-proxy/documentation/trusting-cert-per-language.md
+[proxy_cert_docs]: https://github.com/Azure/azure-sdk-tools/blob/main/tools/test-proxy/documentation/test-proxy/trusting-cert-per-language.md
 [proxy_general_docs]: https://github.com/Azure/azure-sdk-tools/blob/main/tools/test-proxy/README.md
 [proxy_migration_guide]: https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/test_proxy_migration_guide.md
 [py_sanitizers]: https://github.com/Azure/azure-sdk-for-python/blob/main/tools/azure-sdk-tools/devtools_testutils/sanitizers.py