Document how to integrate test-proxy

documentation/api-scenario/how-to/IntegrateWithTestProxy.md

@@ -0,0 +1,87 @@
+# How to integrate test-proxy with API Scenario test
+
+In this section, we'll show you how to make test-proxy recording with API Scenario test, assuming you've already learnt how to use API Scenario test. If not, please go to [QuickStart](./QuickStart.md).
+
+Test-proxy is a tool that provides out-of-process record/playback capabilities compatible with any language. It also supports pushing/restoring the API test recordings from external git repository. See [how to install test-proxy](https://github.com/Azure/azure-sdk-tools/blob/main/tools/test-proxy/Azure.Sdk.Tools.TestProxy/README.md#installation)
+
+## Prepare assets.json file
+
+The assets.json file is a configuration file used by test-proxy to push/restore recording to/from external git repository. Create an assets.json file under `scenarios/` folder with following content:
+
+```json
+{
+  "AssetsRepo": "Azure/azure-sdk-assets",
+  "AssetsRepoPrefixPath": "",
+  "TagPrefix": "apitest/<ServiceName>/<package>"
+}
+```
+
+Take appConfiguration as an example,
+
+```
+specification/appconfiguration/data-plane
+├── Microsoft.AppConfiguration
+│   └── stable
+│       └── 1.0
+│           ├── appconfiguration.json
+│           ├── examples
+│           │   ├── CheckKeyValue.json
+│           │   ├── PutLock.json
+│           │   └── PutLock_IfMatch.json
+│           └── scenarios
+│               └── assets.json         <----- check-in assets.json here
+└── readme.md
+```
+
+## Make recording
+
+1. Start test-proxy under the repository root folder
+
+```bash
+test-proxy start
+```
+
+By default, it listens to 5000/5001 ports for http/https respectively.
+
+2. Run API Scenario test
+
+```bash
+oav run <your-scenario-file>.yaml -e <your-env>.json --testProxy http://localhost:5000 --testProxyAssets <your-assets-file>.json
+```
+
+3. Check the recording file
+
+The recording file can be found in the `<repository-root>/.assets` folder.
+
+## Push recording
+
+1. Delete secrets from recording files
+
+Please ensure no secrets in the recording file, before trying to push to external git repository.
+
+2. Push recording to the git repository
+
+```bash
+test-proxy push -a <your-assets-file>.json
+```
+
+3. Commit updated assets.json file
+
+After pushing the recording, test-proxy will write the latest git tag to assets.json file. Check the content of recording on github assets repository if as expected. If no problem, commit and push the updated assets.json file.
+
+## Restore recording
+
+Use following command to fetch recording:
+
+```bash
+test-proxy restore -a <your-assets-file>.json
+```
+
+or reset if any weird thing happens:
+
+```bash
+test-proxy reset -a <your-assets-file>.json
+```
+## Playback recording
+
+TBA

documentation/api-scenario/readme.md

@@ -17,6 +17,7 @@ API Scenario is a YAML file defining RESTful API usage scenarios of your service
 - [Example: Write and run your first API scenario file](./how-to/QuickStart.md)
 - [Example: Generate a basic API scenario file](./how-to/GenerateABasicApiScenario.md)
 - [Example: Resolve external dependencies](./how-to/ResolveDependencies.md)
+- [Example: Integrate with test-proxy](./how-to/IntegrateWithTestProxy.md)
 - [API scenario file sample](../samplefiles/Microsoft.YourServiceName/stable/YYYY-MM-DD/scenarios/quickStart.yaml)
 
 ## References