From fcfad5d03c2e19d8c87f95a8a8c96ecb77efea50 Mon Sep 17 00:00:00 2001
From: Scott Beddall <45376673+scbedd@users.noreply.github.com>
Date: Tue, 23 May 2023 13:59:54 -0700
Subject: [PATCH] Add documentation covering usage of the test-proxy config
 feature (#6213)

* add documentation covering usage of the test-proxy config feature
* add additional documentation for where proxy commands should be invoked from
* small correction to rid ourselves of trailing []
---
 .../CommandOptions/OptionsGenerator.cs        | 11 ++-
 .../Azure.Sdk.Tools.TestProxy/README.md       | 70 ++++++++++++++-----
 .../documentation/asset-sync/README.md        | 46 ++++++++----
 3 files changed, 97 insertions(+), 30 deletions(-)

diff --git a/tools/test-proxy/Azure.Sdk.Tools.TestProxy/CommandOptions/OptionsGenerator.cs b/tools/test-proxy/Azure.Sdk.Tools.TestProxy/CommandOptions/OptionsGenerator.cs
index e5a119c4618..efede8671e0 100644
--- a/tools/test-proxy/Azure.Sdk.Tools.TestProxy/CommandOptions/OptionsGenerator.cs
+++ b/tools/test-proxy/Azure.Sdk.Tools.TestProxy/CommandOptions/OptionsGenerator.cs
@@ -56,7 +56,16 @@ public static RootCommand GenerateCommandLineOptions(Func<DefaultOptions, Task>
             };
             #endregion
 
-            var root = new RootCommand();
+
+            var Description = @"This tool is used by the Azure SDK team in two primary ways:
+
+  - Run as a http record/playback server. (""start"" / default verb)
+  - Invoke a CLI Tool to interact with recordings in an external store. (""push"", ""restore"", ""reset"", ""config"")";
+
+            var root = new RootCommand()
+            {
+                Description = Description
+            };
             root.AddGlobalOption(storageLocationOption);
             root.AddGlobalOption(storagePluginOption);
 
diff --git a/tools/test-proxy/Azure.Sdk.Tools.TestProxy/README.md b/tools/test-proxy/Azure.Sdk.Tools.TestProxy/README.md
index eccece25e3a..5be66555b83 100644
--- a/tools/test-proxy/Azure.Sdk.Tools.TestProxy/README.md
+++ b/tools/test-proxy/Azure.Sdk.Tools.TestProxy/README.md
@@ -149,32 +149,70 @@ For safety, the "official target" version that the azure-sdk team uses is presen
 
 ## Command line arguments
 
-This is the help information for test-proxy. It uses the nuget package [`CommandLineParser`](https://www.nuget.org/packages/CommandLineParser) to parse arguments.
+This is the help information for test-proxy. It uses the nuget package [`System.CommandLine`](https://www.nuget.org/packages/System.CommandLine) to parse arguments.
 
 The test-proxy executable fulfills one of two primary purposes:
 
 1. The test-proxy server (the only option up to this point)
-2. [`asset-sync`](#asset-sync-retrieve-external-test-recordings) push/restore/reset.
+2. [`asset-sync`](#asset-sync-retrieve-external-test-recordings) verbs
+   - `push`
+   - `restore`
+   - `reset`
+   - `config`
 
 This is surfaced by only showing options for the default commands. Each individual command has its own argument set that can be detailed by invoking `test-proxy <command> --help`.
 
 ```text
-/>test-proxy --help
-Azure.Sdk.Tools.TestProxy 1.0.0-dev.20220926.1
-c Microsoft Corporation. All rights reserved.
-
-  start      (Default Verb) Start the TestProxy.
-
-  push       Push the assets, referenced by assets.json, into git.
-
-  reset      Reset the assets, referenced by assets.json, from git to their original files referenced by the tag. Will prompt
-             if there are pending changes.
-
-  restore    Restore the assets, referenced by assets.json, from git.
+/>Azure.Sdk.Tools.TestProxy --help
+Description:
+  This tool is used by the Azure SDK team in two primary ways:
+
+    - Run as a http record/playback server. ("start" / default verb)
+    - Invoke a CLI Tool to interact with recordings in an external store. ("push", "restore", "reset", "config")
+
+Usage:
+  Azure.Sdk.Tools.TestProxy [command] [options]
+
+Options:
+  -l, --storage-location <storage-location>  The path to the target local git repo. If not provided as an argument, Environment
+                                             variable TEST_PROXY_FOLDER will be consumed. Lacking both, the current working
+                                             directory will be utilized.
+  -p, --storage-plugin <storage-plugin>      The plugin for the selected storage, default is Git storage is GitStore. (Currently
+                                             the only option) [default: GitStore]
+  --version                                  Show version information
+  -?, -h, --help                             Show help and usage information
+
+Commands:
+  start <args>  Start the TestProxy.
+  push          Push the assets, referenced by assets.json, into git.
+  restore       Restore the assets, referenced by assets.json, from git.
+  reset         Reset the assets, referenced by assets.json, from git to their original files referenced by the tag. Will prompt if
+                there are pending changes unless indicated by -y/--yes.
+  config        Interact with an assets.json.
+```
 
-  help       Display more information on a specific command.
+For the `config` verb, there are subverbs!
 
-  version    Display version information.
+```text
+/>Azure.Sdk.Tools.TestProxy config --help
+Description:
+  Interact with an assets.json.
+
+Usage:
+  Azure.Sdk.Tools.TestProxy config [command] [options]
+
+Options:
+  -l, --storage-location <storage-location>  The path to the target local git repo. If not provided as an argument, Environment
+                                             variable TEST_PROXY_FOLDER will be consumed. Lacking both, the current working
+                                             directory will be utilized.
+  -p, --storage-plugin <storage-plugin>      The plugin for the selected storage, default is Git storage is GitStore. (Currently
+                                             the only option) [default: GitStore]
+  -?, -h, --help                             Show help and usage information
+
+Commands:
+  create  Enter a prompt and create an assets.json.
+  show    Show the content of a given assets.json.
+  locate  Get the assets repo root for a given assets.json path.
 ```
 
 ### Storage Location
diff --git a/tools/test-proxy/documentation/asset-sync/README.md b/tools/test-proxy/documentation/asset-sync/README.md
index 13b12ade834..31aae84e7a8 100644
--- a/tools/test-proxy/documentation/asset-sync/README.md
+++ b/tools/test-proxy/documentation/asset-sync/README.md
@@ -69,10 +69,12 @@ Each of these CLI Commands takes an `assets.json` argument that provides the _co
 
 When using a Windows machine, it is technically possible to invoke tests from WSL against a windows clone. That path would appear under `/mnt/c/path/to/your/repo`. This is _not_ a supported scenario, as the `test-proxy` shells out to git for the push/restore actions. Running a `git push/pull` from _linux_ against a repo that was cloned down using a _windows_ git client can have unexpected results. Better to avoid the situation entirely and use an entirely separate clone for work on WSL.
 
-## test-proxy CLI commands
+## test-proxy CLI (asset) commands
 
 The test-proxy also offers interactions with the external assets repository as a CLI. Invoking `test-proxy --help` will show the available list of commands. `test-proxy <command> --help` will show the help and options for an individual command. The options for a given command are all `--<option>`, for example, `--assets-json-path`, but each option has an abbreviation shown in the help, those are a single dash. For example the abbreviation for `--assets-json-path` is `-a`.
 
+Please note that all test-proxy asset commands should be invoked **in the context of the language repository itself**.
+
 ### The following CLI commands are available for manipulation of assets
 
 #### Restore
@@ -103,6 +105,30 @@ After assets have been restored and then modified (re-recorded etc.) a push will
 test-proxy push --assets-json-path <assetsJsonPath>
 ```
 
+#### Config Commands
+
+When a client provides the additional body key `x-recording-assets-file` to `/Record/Start` or `/Playback/Start`, the test-proxy will invoke that test using **external assets**.
+
+It's great that recordings are externalized, but this adds some complexity as these recordings don't live directly next to their test code anymore. The test-proxy provides the `config` verb to offer easy insight into interactions with the `assets.json` to assist with these complexities.
+
+Currently there are two sub-verbs for `test-proxy config`:
+
+- `locate`
+- `show`
+
+`locate`: Dumps which folder under the `.assets` folder contains your recordings. [See `config` usage in layout section below.](#layout-within-a-language-repo)
+`show`: Dumps the contents of the targeted assets.json.
+
+```bash
+# from C:/repo/azure-sdk-for-python, the root of the python language repository
+test-proxy config locate --assets-json-file sdk/keyvault/azure-keyvault-keys/assets.json
+```
+
+```bash
+# from C:/repo/azure-sdk-for-js, the root of the js language repository
+test-proxy config show -a sdk/tables/data-tables/assets.json
+```
+
 ## Using `asset-sync` for azure sdk development
 
 ### Where are my files?
@@ -181,21 +207,15 @@ The below diagram illustrates how an individual assets.json, language repo, and
 
 > Side note: the `.breadcrumb` file is created/updated as an artifact of the test-proxy restore/push/reset operations. Don't look for one if you haven't restored at least one assets.json first!
 
-One can use visual inspection of the `.breadcrumb` file to _find_ which folder contains the files for your assets.json. Or, they can simply use one of the one-liners above to change directory into their assets.
-
-Powershell one-liner:
+One can use visual inspection of the `.breadcrumb` file to _find_ which folder contains the files for your assets.json. Or, more conveniently, a user can use the `config` verb to access this data! Using assets diagram directly above. we can work an example:
 
 ```powershell
-# From root of repo. Substitute your target assets.json path in the StartsWith clause.
-cd ".assets/$((Get-Content ".assets/.breadcrumb" | Where-Object { $_.StartsWith("sdk/tables/assets.json") }).Split(";")[1])"
+# from the root of the azure-sdk-for-net repo, run:
+test-proxy config locate -a "sdk/confidentialledger/Azure.Security.ConfidentialLedger/assets.json"
+# returns -> path/to/azure-sdk-for-net/.assets/2Km0Z8755m/net/"
 ```
 
-Bash one-liner:
-
-```bash
-# From root of repo. Substitute your target assets.json path in the initial grep
-A=$(grep "sdk/tables/assets.json" .assets/.breadcrumb | awk '{split($0,a,";"); print a[2];}'); cd .assets/$A
-```
+The `config` verb offers various interactions with an input assets.json path, with `locate` just being one of them! In all cases, all interactions with the `config` verb should be made in the context of the **language repository**, where the source for a given package resides.
 
 #### A few details about context directory
 
@@ -281,7 +301,7 @@ This will _force_ the locally cloned assets to align with the assets.json that h
 
 #### Attempt to manually resolve
 
-A **new tag** is pushed with each `test-proxy push` invocation. There should be _no such thing_ as `merge conflicts` when automatically pushing up a new tag. However, if you wish to manually resolve instead of discarding current state, `cd` into the assets repo using one of the one-liners above.
+A **new tag** is pushed with each `test-proxy push` invocation. There should be _no such thing_ as `merge conflicts` when automatically pushing up a new tag. However, if you wish to manually resolve instead of discarding current state, `cd` into the assets repo using the `config locate` command discussed above.
 
 Once there, use standard `git` operations to resolve your issue.