[Recorder] [Test Proxy] [Asset Sync] Updates to the docs

CONTRIBUTING.md

@@ -150,13 +150,11 @@ By default, these npm scripts run previously recorded tests. The recordings have
 
 Most of the tests in our projects run in playback mode by default, i.e they make no network requests to the real services. For HTTP requests made in each test case, there is a recorded response that reproduces the service behavior. The readme file in the `test` folder of each package will indicate whether the package uses recorded tests or not.
 
-At the moment, tests in our repo depend on one of the two different versions of the recorder tool (`@azure-tools/test-recorder`) - `1.a.b` and `2.x.y`.
-Currently, version `2.x.y` is maintained in the repository which is built as part of a cross-language unification effort in terms of the tests and recordings.
-Eventually, all the tests will be migrated to depend on the `2.x.y` version of the recorder that depends on the language-agnostic [test proxy server].
+At the moment, tests in our repo depend on one of the two different versions of the recorder tool (`@azure-tools/test-recorder`) - `1.a.b` and `3.m.n`.
+Currently, version `3.m.n` is maintained in the repository which is built as part of a cross-language unification effort in terms of the tests and recordings.
+Eventually, all the tests will be migrated to depend on the `3.m.n` version of the recorder that depends on the language-agnostic [test proxy server].
 
-To record and playback the tests that depend on version `2.x.y` of `@azure-tools/test-recorder`, [docker] is required, as the [test proxy server] is run in a container during testing. When running the tests, ensure the Docker daemon is running and you have permission to use it. For WSL 2, running `sudo service docker start` and `sudo usermod -aG docker $USER` should be sufficient.
-
-Refer to the [Migration Guide](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/test-utils/recorder/MIGRATION.md) for more information on migrating the tests from recorder v1 to v2.
+Refer to the [Migration Guide](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/test-utils/recorder/MIGRATION.md) for more information on migrating the tests from recorder v1 to v3.
 
 #### Live tests
 
@@ -180,6 +178,8 @@ Regenerating the recordings has the same requirements as running the live tests.
 
 For more information the recorder, please visit the [test-recorder's readme](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/test-utils/recorder/README.md).
 
+Here are a few [Useful Commands](./sdk/test-utils/recorder/GoldenCommands.md) that can be handy while testing your SDKs.
+
 ### Other NPM scripts
 
 Most package scripts are exposed as Rush commands. Use `rushx <scriptname>` in place of `npm run <scriptname>` to run the package script in all projects. Navigate to a project's directory and substitute `rushx` for `rush` to run the script for just the current project. Run `rush <scriptname> --help` for more information about each script.

common/tools/dev-tool/README.md

@@ -23,6 +23,7 @@ It provides a place to centralize scripts, resources, and processes for developm
   - `run` (execute a sample or all samples within a directory)
   - `check-node-versions` (execute samples with different node versions, typically in preparation for release)
 - `test-proxy`
+  - `init` (initializes `assets.json` in your package folder)
   - `push` (pushes 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's pending changes)
   - `restore` (restore the assets, referenced by assets.json, from git)

common/tools/dev-tool/src/commands/test-proxy/init.ts

@@ -0,0 +1,16 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import { leafCommand, makeCommandInfo } from "../../framework/command";
+import { createAssetsJson } from "../../util/testProxyUtils";
+
+export const commandInfo = makeCommandInfo(
+  "test-proxy",
+  "initialize the assets.json file required for the assets-sync mechanism to store recordings",
+  {}
+);
+
+export default leafCommand(commandInfo, async () => {
+  await createAssetsJson();
+  return true;
+});

common/tools/dev-tool/src/util/testProxyUtils.ts

@@ -166,6 +166,10 @@ export async function runTestProxyCommand(argv: string[]): Promise<void> {
   return runCommand(await getTestProxyExecutable(), argv, { stdio: "inherit" }).result;
 }
 
+export function createAssetsJson(): Promise<void> {
+  return runMigrationScript(false);
+}
+
 export async function runMigrationScript(initialPush: boolean): Promise<void> {
   const migrationScriptLocation = path.join(
     await resolveRoot(),
@@ -210,8 +214,7 @@ export async function isProxyToolActive(): Promise<boolean> {
     await axios.get(`http://localhost:${process.env.TEST_PROXY_HTTP_PORT ?? 5000}/info/available`);
 
     log.info(
-      `Proxy tool seems to be active at http://localhost:${
-        process.env.TEST_PROXY_HTTP_PORT ?? 5000
+      `Proxy tool seems to be active at http://localhost:${process.env.TEST_PROXY_HTTP_PORT ?? 5000
       }\n`
     );
     return true;

sdk/test-utils/recorder/ASSET_SYNC_MIGRATION.md

@@ -6,25 +6,77 @@ Recordings take up a large amount of space in our repository and generate a lot
 
 ## Performing the migration
 
-The package you are migrating needs to be using the new version of the recorder that uses the test proxy (`@azure-tools/test-recorder@^2.0.0`). Most packages are using the new recorder already; if yours is not you should migrate as soon as possible. More detail on migrating to the new recorder can be found in the [recorder 2.0 migration guide]. To run the migration script, you will need both [Powershell] and [`dev-tool`] installed. If you haven't installed `dev-tool` yet, you can install it as follows:
+### Prerequisites
 
-```bash
-$ cd common/tools/dev-tool # (from your azure-sdk-for-js repo root)
-$ npm install -g
-```
+To be able to leverage the asset-sync workflow, you will need
+
+- [Powershell] installed
+- `dev-tool` among your `devDependencies` in the `package.json`.
+
+_If you are working on a new package and don't have any recorded tests, skip to [New Package - No Recorded Tests](#new-package---no-recorded-tests)._
+
+The package you are migrating needs to be using the new version of the recorder that uses the test proxy (`@azure-tools/test-recorder@^3.0.0`). If you're on an older version, follow [recorder 3.0 migration guide] first.
+
+### Migration
+
+Run the following command to migrate the recordings.
 
 ```bash
 $ npx dev-tool test-proxy migrate --initial-push
 ```
 
+_Note: If you [install `dev-tool` globally], you don't need `npx` prefix in the above command_
+
 Once this is done, validate that your recorded tests still pass, and create a PR with the changes. That's it!
 
+The above `migrate` command produces an `assets.json`, with a tag pointing to your recordings in the `Azure/azure-sdk-assets` repository.
+
+Example `assets.json` from "keyvault-certificates" SDK.
+
+```json
+{
+  "AssetsRepo": "Azure/azure-sdk-assets",
+  "AssetsRepoPrefixPath": "js",
+  "TagPrefix": "js/keyvault/keyvault-certificates",
+  "Tag": "js/keyvault/keyvault-certificates_43821e21b3"
+}
+```
+
+And the recordings are located at https://github.com/Azure/azure-sdk-assets/tree/js/keyvault/keyvault-certificates_43821e21b3
+
+### New Package - No Recorded Tests
+
+_If you already have an `assets.json` file, skip to [Workflow with asset sync enabled](#workflow-with-asset-sync-enabled)._
+
+This section assumes that your package is new to the JS repo and that you're trying to onboard your tests with recorder, and the asset-sync workflow.
+
+From the root of the repo, navigate to your package
+
+```
+cd sdk/<service-folder>/<package-name>
+```
+
+Generate an `sdk/<service-folder>/<package-name>/assets.json` file by running the following command.
+
+```
+npx dev-tool test-proxy init
+```
+
+This command would generate an `assets.json` file with an empty tag.
+
 ## Workflow with asset sync enabled
 
+At this point, you should have an `assets.json` file under your SDK.
+`sdk/<service-folder>/<package-name>/assets.json`.
+
+Run your tests using the usual [package.json scripts].
+
+`rushx integration-test:node`, for example.
+
 With asset sync enabled, there is one extra step that must be taken before you create a PR with changes to recorded tests: you must push the new recordings to the assets repo. This is done with the following command:
 
 ```bash
-$ npx dev-tool test-proxy push
+npx dev-tool test-proxy push
 ```
 
 This command will:
@@ -34,27 +86,43 @@ This command will:
 
 You should stage and commit the `assets.json` update as part of your PR. If you don't run the `push` command before creating a PR, the CI (and anyone else who tries to run your recorded tests) will use the old recordings, which will cause failures.
 
-This diagram describes the new workflow (new steps highlighted):
+After onboarding your new package or after migrating your package to the asset-sync workflow, the following diagram describes the new workflow (new steps highlighted):
 
 ```mermaid
 graph TD
-record[Record tests<pre>TEST_MODE=record rushx test</pre>] -->
-playback[Inspect recordings and test in playback<pre>TEST_MODE=playback rushx test</pre>]
-
-playback -- Tests don't work, re-record --> record
-playback -- Tests pass in playback\nand are properly sanitized --> push
-
-subgraph New steps
-push[Push recordings to asset sync repo<pre>npx dev-tool test-proxy push</pre>] -->
-assets[Commit <code>assets.json</code> change]
-end
-
-assets --> pr[Push branch and\ncreate PR]
+    subgraph p3 [New steps]
+        subgraph p4 [Push recordings to asset sync repo]
+            push[npx dev-tool test-proxy push]
+        end
+        p4-->assets[Commit <code>assets.json</code> change]
+    end
+
+    assets --> pr[Push branch and\ncreate PR]
+
+    subgraph p2 [Inspect recordings and test in playback]
+        playback[TEST_MODE=playback rushx test]
+    end
+
+    subgraph p1 [Record tests]
+        record[TEST_MODE=record rushx test]
+    end
+
+    p1 --> p2
+    p2 -- Tests don't work re-record --> p1
+    p2 -- Tests pass in playback\nand are properly sanitized --> p4
+
+
+    classDef green fill:#548235,stroke:#333,stroke-width:2px
+    classDef orange fill:#C65911,stroke:#333,stroke-width:2px
+    classDef blue fill:#305496,stroke:#333,stroke-width:2px
+    class p1 orange
+    class p2 green
+    class p3 blue
 ```
 
 ### Inspecting recordings with asset sync enabled
 
-Often, when re-recording tests, you will want to inspect the recordings that have been made, either to debug something or to make sure secrets have been sanitized properly. With asset sync enabled, the recordings are no longer stored in the same place as your SDK. You'll need to follow the following process to find them:
+Often, when re-recording tests, you will want to inspect the recordings that have been made, either to debug something or to make sure secrets have been sanitized properly. With asset sync workflow enabled, the recordings are no longer stored in the same place as your SDK. You'll need to follow the following process to find them:
 
 1. Navigate to the root of the `azure-sdk-for-js` repo.
 1. Go into the `.assets` directory. This will contain a file called `.breadcrumb`; open it and find the entry that matches your SDK. This will give you the name of the directory within `.assets` that your recordings are located in.
@@ -73,16 +141,16 @@ A few commands have been added to `dev-tool` to facilitate pushing and fetching
 - `dev-tool test-proxy reset`: if you've made any changes to the recordings locally, you can use this to revert those local changes and reset to what is currently checked in to the assets repo. This is a destructive operation and if you have local changes it will prompt you before removing your work.
 - `dev-tool test-proxy migrate`: used for migrating existing recordings to the assets repo as described above.
 
+**Refer to [testing-commands](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/test-utils/recorder/GoldenCommands.md) guide if you need help on the commands to run during testing.**
+
 ### Working offline
 
 Offline work is supported out-of-the-box. Of course, however, you won't be able to push or pull from the assets repo while offline. You can fetch recordings from the assets repo by running `npx dev-tool test-proxy restore`. This will download the recordings (and the test proxy executable, if you haven't got that already), making them ready for you to run tests with.
 
 ## Further reading
 
-- [Asset Sync reference in azure-sdk-tools][asset-sync-reference]
-- [Recorder 2.0 migration guide]
-
-[recorder 2.0 migration guide]: https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/test-utils/recorder/MIGRATION.md
+[recorder 3.0 migration guide]: https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/test-utils/recorder/MIGRATION.md
 [asset-sync-reference]: https://github.com/Azure/azure-sdk-tools/tree/main/tools/test-proxy/documentation/asset-sync
 [powershell]: https://github.com/PowerShell/PowerShell
-[`dev-tool`]: https://github.com/Azure/azure-sdk-for-js/tree/main/common/tools/dev-tool#installation
+[install `dev-tool` globally]: https://github.com/Azure/azure-sdk-for-js/tree/main/common/tools/dev-tool#installation
+[package.json scripts]: https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/test-utils/recorder/README.md#packagejson-scripts

sdk/test-utils/recorder/GoldenCommands.md

@@ -0,0 +1,39 @@
+## Useful Commands while Testing your packages
+
+If you're not familiar with the recorder refer to [recorder-readme](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/test-utils/recorder/README.md).
+If you're looking to migrate your existing package from recorder v1 to v3, refer to [migrate-v1-to-v3](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/test-utils/recorder/MIGRATION.md).
+If you're looking to be onboarded to the asset-sync workflow to push out the test recordings to `Azure/azure-sdk-assets` repository, refer to [asset-sync-migration](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/test-utils/recorder/ASSET_SYNC_MIGRATION.md).
+
+### `rush` Commands
+
+| script name       | What does it do?                                                                                                |
+| :---------------- | :-------------------------------------------------------------------------------------------------------------- |
+| `rush update`     | Updates dependencies                                                                                            |
+| `rush build -t .` | Expected to be run from inside your package(`sdk/service-name/package-name`). Builds the whole dependency tree. |
+|                   |                                                                                                                 |
+
+### `rushx` Commands - to run the tests
+
+| script name                      | command(usually)                                                                                                 |
+| :------------------------------- | :--------------------------------------------------------------------------------------------------------------- |
+| `rushx unit-test:browser`        | `dev-tool run test:browser`                                                                                      |
+| `rushx unit-test:node`           | `dev-tool run test:node-ts-input -- --timeout 1200000 --exclude 'test/**/browser/*.spec.ts' 'test/**/*.spec.ts'` |
+| `rushx integration-test:browser` | `dev-tool run test:browser`                                                                                      |
+| `rushx integration-test:node`    | `dev-tool run test:node-js-input -- --timeout 5000000 'dist-esm/test/**/*.spec.js'`                              |
+|                                  |                                                                                                                  |
+
+### After migrating to asset-sync
+
+Expects that you have `dev-tool` among your devDependencies.
+Expects that you have [powershell] installed.
+
+| script name                                      | What does it do?                                                                                                                                                                                                                                                                                                                     |
+| :----------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `npx dev-tool test-proxy init`                   | [Only once per package] Generates the `assets.json` with an empty tag.                                                                                                                                                                                                                                                               |
+| `npx dev-tool test-proxy migrate --initial-push` | [Only once per package] To migrate the test recordings to the assets repo for the first time. Also generates `assets.json`                                                                                                                                                                                                           |
+| `npx dev-tool test-proxy push`                   | To migrate the test recordings to the assets repo for the first time.                                                                                                                                                                                                                                                                |
+| `npx dev-tool test-proxy reset`                  | Reverts the local changes to recordings and resets to what is currently checked in to the assets repo. This is a destructive operation.                                                                                                                                                                                              |
+| `npx dev-tool test-proxy restore`                | Pulls the recordings from the assets repo that are referenced in your `assets.json`. Typically this will be done automatically when you first run tests in playback if the recordings haven't been downloaded already. But you can run this command in advance if you'd like to download them earlier, for example for offline work. |
+|                                                  |                                                                                                                                                                                                                                                                                                                                      |
+
+[powershell]: https://github.com/PowerShell/PowerShell