From 3a4e528638c825191ab9a2a7220eeea1037cbbda Mon Sep 17 00:00:00 2001 From: Harsha Nalluru Date: Thu, 23 Mar 2023 04:54:17 +0000 Subject: [PATCH 01/12] updates to docs --- CONTRIBUTING.md | 12 +- common/tools/dev-tool/README.md | 1 + .../dev-tool/src/commands/test-proxy/init.ts | 16 +++ .../tools/dev-tool/src/util/testProxyUtils.ts | 7 +- .../recorder/ASSET_SYNC_MIGRATION.md | 106 ++++++++++++++---- sdk/test-utils/recorder/GoldenCommands.md | 39 +++++++ sdk/test-utils/recorder/MIGRATION.md | 53 +++++---- sdk/test-utils/recorder/README.md | 70 +----------- 8 files changed, 189 insertions(+), 115 deletions(-) create mode 100644 common/tools/dev-tool/src/commands/test-proxy/init.ts create mode 100644 sdk/test-utils/recorder/GoldenCommands.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c82e4f9acddb..b2ee1995642d 100644 --- a/CONTRIBUTING.md +++ b/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 ` in place of `npm run ` 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 --help` for more information about each script. diff --git a/common/tools/dev-tool/README.md b/common/tools/dev-tool/README.md index c51ccb92d8b1..18dcb7c88de0 100644 --- a/common/tools/dev-tool/README.md +++ b/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) diff --git a/common/tools/dev-tool/src/commands/test-proxy/init.ts b/common/tools/dev-tool/src/commands/test-proxy/init.ts new file mode 100644 index 000000000000..1cd4fac35c46 --- /dev/null +++ b/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; +}); diff --git a/common/tools/dev-tool/src/util/testProxyUtils.ts b/common/tools/dev-tool/src/util/testProxyUtils.ts index d6ce911fb6ae..4d464ed73549 100644 --- a/common/tools/dev-tool/src/util/testProxyUtils.ts +++ b/common/tools/dev-tool/src/util/testProxyUtils.ts @@ -166,6 +166,10 @@ export async function runTestProxyCommand(argv: string[]): Promise { return runCommand(await getTestProxyExecutable(), argv, { stdio: "inherit" }).result; } +export function createAssetsJson(): Promise { + return runMigrationScript(false); +} + export async function runMigrationScript(initialPush: boolean): Promise { const migrationScriptLocation = path.join( await resolveRoot(), @@ -210,8 +214,7 @@ export async function isProxyToolActive(): Promise { 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; diff --git a/sdk/test-utils/recorder/ASSET_SYNC_MIGRATION.md b/sdk/test-utils/recorder/ASSET_SYNC_MIGRATION.md index 92e988bd95c0..5353003e01d7 100644 --- a/sdk/test-utils/recorder/ASSET_SYNC_MIGRATION.md +++ b/sdk/test-utils/recorder/ASSET_SYNC_MIGRATION.md @@ -6,25 +6,72 @@ 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 work, 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`). More detail on migrating to the new recorder can be found in the [recorder 3.0 migration guide]. ```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)._ + +From the root of the repo, navigate to your package + +``` +cd sdk// +``` + +Generate an `sdk///assets.json` file. + +``` +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///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,22 +81,40 @@ 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 the onboarding your new package or after migrating your package to asset-sync, the following diagram describes the new workflow (new steps highlighted): ```mermaid + graph TD -record[Record tests
TEST_MODE=record rushx test
] --> -playback[Inspect recordings and test in playback
TEST_MODE=playback rushx test
] + subgraph p3 [New steps] + subgraph p4 [Push recordings to asset sync repo] + push[[npx dev-tool test-proxy push]] + end + p4-->assets[Commit assets.json change] + + end + + assets --> pr[Push branch and\ncreate PR] -playback -- Tests don't work, re-record --> record -playback -- Tests pass in playback\nand are properly sanitized --> push + subgraph p2 [Inspect recordings and test in playback] + playback[[TEST_MODE=playback rushx test]] + end -subgraph New steps -push[Push recordings to asset sync repo
npx dev-tool test-proxy push
] --> -assets[Commit assets.json change] -end + subgraph p1 [Record tests] + record[[TEST_MODE=record rushx test]] + end -assets --> pr[Push branch and\ncreate PR] + 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 @@ -73,16 +138,15 @@ 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. +Useful commands while 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 diff --git a/sdk/test-utils/recorder/GoldenCommands.md b/sdk/test-utils/recorder/GoldenCommands.md new file mode 100644 index 000000000000..aec6feadae51 --- /dev/null +++ b/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](./README.md). +If you're looking to migrate your existing package from recorder v1 to v3, refer to [migrate-v1-to-v3](./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](./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 diff --git a/sdk/test-utils/recorder/MIGRATION.md b/sdk/test-utils/recorder/MIGRATION.md index a910a327edf9..ed585a0bca10 100644 --- a/sdk/test-utils/recorder/MIGRATION.md +++ b/sdk/test-utils/recorder/MIGRATION.md @@ -1,24 +1,25 @@ # Migration Guide -This document outlines key differences between the legacy recorder and the new Unified Recorder client. The Unified Recorder replaces the existing `nock/nise`-based recorder with a solution that uses the language-agnostic [test proxy server]. +This document outlines key differences between the legacy recorder and the new Unified Recorder client. The Unified Recorder replaces the older `nock/nise`-based recorder(v1) with a solution that uses the language-agnostic [test proxy server]. -## Prerequisites +## No Prerequisites Like Before? How?? -- [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. +- With recorder v2, Docker was required for to leverage the [test proxy server]. This is not needed anymore with recorder v3. +- Using the [`dev-tool run ...` commands](changes-to-npm-scripts) would automatically download the [latest test proxy artifacts] from the [Azure/azure-sdk-tools] repo according to your operating system/architecture. -## Advantages of migration to v2 +## Advantages of migration to v3 -- Recorder v2 handles secrets in the recordings better than v1 leveraging the new sanitizers/transformations approach. -- There are maintenance benefits to recorder v2, partly owing to the new test-proxy tool that is built to support recorders in various languages. +- Recorder v3 handles secrets in the recordings better than v1 leveraging the new sanitizers/transformations approach. +- There are maintenance benefits to recorder v3, partly owing to the new test-proxy tool that is built to support recorders in various languages. - Will allow us to run the tests in parallel in the future. - All the recordings will be saved as JSON files instead of being JS files. -- Recordings will soon be migrated to an assets repository to lessen the load of the JS repo, which needs the packages to be migrated to recorder v2 first to grasp the benefits. - The new recorder allows tests to imitate the live service more accurately during playback, since real HTTP requests are being made. - The new recorder's API is more transparent and is easier to use compared to the old recorder. +- Leverages the asset-sync workflow to enable you push recordings out of the JS repo. ## Upgrading to the Unified Recorder -The new recorder is version 2.x.y of the `@azure-tools/test-recorder` package. Update the test-recorder dependency in your package.json file as follows: +The new recorder is version 3.x.y of the `@azure-tools/test-recorder` package. Update the test-recorder dependency in your package.json file as follows: ```json { @@ -26,7 +27,7 @@ The new recorder is version 2.x.y of the `@azure-tools/test-recorder` package. U "devDependencies": { // ... "@azure-tools/test-credential": "^1.0.0", // If you're using `@azure/identity` in your tests - "@azure-tools/test-recorder": "^2.0.0" + "@azure-tools/test-recorder": "^3.0.0" } } ``` @@ -298,28 +299,36 @@ Remove the following "devDependencies" from `package.json` ## Migrating your recordings -Once you have made the necessary code changes, it is time to re-record your tests using the Unified Recorder to complete the migration. To do this, first **delete** the directory containing the old recordings (the `recordings` folder). Then, run your tests with the `TEST_MODE` environment variable to `record`. +Once you have made the necessary code changes, it is time to re-record your tests using the Unified Recorder to complete the migration. -If everything succeeds, the new recordings will be made available in the `recordings` directory. Inspect them to make sure everything looks OK (no secrets present, etc.), and then run the tests in playback mode to ensure everything is passing. If you're running into issues, check out the [Troubleshooting section](#troubleshooting). +To do this, first **delete** the directory containing the old recordings (the `recordings` folder). -## Troubleshooting +### Asset Sync - Push recordings to the Azure/azure-sdk-assets repo -If you run into issues while migrating your package, some of the following troubleshooting steps may help: +Make sure you do have the [Powershell] installed. -### Viewing test proxy log output +`npx dev-tool test-proxy init` - to initialize an `assets.json` file -`dev-tool` by default outputs logs from the test proxy to `test-proxy-output.log` in your package's root directory. These logs can be inspected to see what requests were made to the proxy tool. +Then, run your tests with the `TEST_MODE` environment variable to `record`. -### Viewing more detailed logs by running the proxy tool manually +`npx dev-tool test-proxy push` - to push the recordings. -If you desire, you can run the proxy tool docker image manually before running your tests. This allows you to specify a different log level (debug in the below example), allowing for more detailed logs to be viewed. Do this by running: +If everything succeeds, the new recordings will be made available in the `Azure/azure-sdk-assets` repo based on the tag present in the `assets.json`. -```bash -docker run -v :/srv/testproxy -p 5001:5001 -p 5000:5000 -e Logging__LogLevel__Microsoft=Debug azsdkengsys.azurecr.io/engsys/testproxy-lin:latest -``` +Inspect them to make sure everything looks OK (no secrets present, etc.), and then run the tests in playback mode to ensure everything is passing. + +If you're running into issues, check out the [Troubleshooting section](#troubleshooting). -Once you've done this, you can run your tests in a separate terminal. `dev-tool` will detect that a test proxy container is already running and will point requests to the Docker container you started. +## Troubleshooting + +If you run into issues while migrating your package, some of the following troubleshooting steps may help: + +### Viewing test proxy log output + +`dev-tool` by default outputs logs from the test proxy to `test-proxy-output.log` in your package's root directory. These logs can be inspected to see what requests were made to the proxy tool. -[docker]: https://docker.com/ [`core-rest-pipeline`]: https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/core/core-rest-pipeline [test proxy server]: https://github.com/Azure/azure-sdk-tools/tree/main/tools/test-proxy +[latest test proxy artifacts]: https://github.com/Azure/azure-sdk-tools/releases/tag/Azure.Sdk.Tools.TestProxy_1.0.0-dev.20230322.1 +[Azure/azure-sdk-tools]: https://github.com/Azure/azure-sdk-tools +[powershell]: https://github.com/PowerShell/PowerShell diff --git a/sdk/test-utils/recorder/README.md b/sdk/test-utils/recorder/README.md index 2b6956d45994..c769cbeae836 100644 --- a/sdk/test-utils/recorder/README.md +++ b/sdk/test-utils/recorder/README.md @@ -11,7 +11,11 @@ The Azure SDK for JavaScript is composed of a multitude of libraries that attemp Our recorder tool package `@azure-tools/test-recorder` attempts to provide an answer for those questions. -**Note: In case you're depending on `@azure-tools/test-recorder@1.x.y` and want to migrate your tests to version 2, follow the [migration guide to recorder v2 from v1](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/test-utils/recorder/MIGRATION.md)** +**Note 1: In case you're depending on `@azure-tools/test-recorder@1.x.y` and want to migrate your tests to version 3, follow the [migration guide to recorder v3 from v1](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/test-utils/recorder/MIGRATION.md)** + +**Note 2: If you're looking to onboard to the asset-sync workflow to push out the test recordings to `Azure/azure-sdk-assets` repository, refer to [asset-sync-migration](./ASSET_SYNC_MIGRATION.md).** + +**Note 3: Refer [testing-commands](./GoldenCommands.md) if you need help on which command to run during testing.** This library provides interfaces and helper methods to equip the SDKs in the `azure-sdk-for-js` repo with the recording and playback capabilities for the tests, it targets HTTP requests in both Node.js and the Browsers. @@ -39,7 +43,6 @@ This tool helps to record and playback the tests in the JS repo by leveraging th - [Securing sensitive data](#securing-sensitive-data) - [Supporting parallelism](#supporting-parallelism) - [Isomorphic tests](#isomorphic-tests) - - [Many ways to run the test-proxy tool](#many-ways-to-run-the-test-proxy-tool) - [Troubleshooting](#troubleshooting) - [Next steps](#next-steps) - [Contributing](#contributing) @@ -144,16 +147,6 @@ Test scripts } ``` -#### Prerequisites - -- [Docker](https://docker.com/) is required, as the [test proxy server](https://github.com/Azure/azure-sdk-tools/tree/main/tools/test-proxy) is run in a container during testing. When running the tests, ensure the Docker daemon is running and you have permission to use it. - -Check [docker.com/get-started](https://www.docker.com/get-started/) to download and install docker desktop on your machine. - -For WSL 2, running `sudo service docker start` and `sudo usermod -aG docker $USER` should be sufficient. - -If for some reason, you have trouble running the test-proxy tool in your environment using the `dev-tool` commands as suggested above, please read [many ways to run the test-proxy tool](#many-ways-to-run-the-test-proxy-tool) to unblock yourself sooner. - ### TEST_MODE By using recorder with your clients, the requests are redirected to the test-proxy tool to either save them or replay them. @@ -482,60 +475,9 @@ If you run into issues while running the tests in record/playback modes, some of `dev-tool` by default outputs logs from the test proxy to `test-proxy-output.log` in your package's root directory. These logs can be inspected to see what requests were made to the proxy tool. -#### Viewing more detailed logs by running the proxy tool manually - -If you desire, you can run the proxy tool docker image manually before running your tests, refer to the [many ways to run the test-proxy tool](#many-ways-to-run-the-test-proxy-tool). This allows you to specify a different log level (debug in the below example), allowing for more detailed logs to be viewed. Do this by running: - -```bash -docker run -v :/srv/testproxy -p 5001:5001 -p 5000:5000 -e Logging__LogLevel__Microsoft=Debug azsdkengsys.azurecr.io/engsys/testproxy-lin:latest -``` - +#### Switching ports If port 5000 is already being used in your machine, you can specify any other port such as 2345:5000 in the args, and make sure to have the environment variable `TEST_PROXY_HTTP_PORT` set as the specified port(2345 in this case). -Once you've done this, you can run your tests in a separate terminal. `dev-tool` will detect that a test proxy container is already running and will point requests to the Docker container you started. - -### Many ways to run the test-proxy tool - -#### With the `dev-tool` commands - -- The following commands run the tests with the default configs, and concurrently runs the proxy tool in record/playback modes if it is not already active. Additionally, more options can be passeed to override the default configs. - - `dev-tool run test:node-js-input -- --timeout 5000000 'dist-esm/test/**/*.spec.js'` - - `dev-tool run test:node-ts-input -- --timeout 1200000 --exclude 'test/**/browser/*.spec.ts' 'test/**/*.spec.ts'` - - `dev-tool run test:browser` - Read more at [dev-tool commands #usage](https://github.com/Azure/azure-sdk-for-js/blob/main/common/tools/dev-tool/README.md#usage) - -Follow the below two methods if you wish to run the proxy tool yourself without relying on the `dev-tool` commands. - -#### With the `docker run` command - -- Run this command - - > `docker run -v /workspaces/azure-sdk-for-js/:/srv/testproxy -p 5001:5001 -p 5000:5000 azsdkengsys.azurecr.io/engsys/testproxy-lin:latest` - - Map the root directory of the azure-sdk-for-js repo to `/srv/testproxy` inside the container for an accurate location while generating recordings. - - Add `--add-host host.docker.internal:host-gateway` for linux to access host's network(to access `localhost`) through `host.docker.internal`. - Docker for Windows and Mac support `host.docker.internal` as a functioning alias for localhost. - - If the above command doesn't work directly, try [Troubleshooting Access to Public Container Registry](https://github.com/Azure/azure-sdk-tools/tree/main/tools/test-proxy/docker#troubleshooting-access-to-public-container-registry). - - Reference: [Using Test Proxy with docker container](https://github.com/Azure/azure-sdk-tools/tree/main/tools/test-proxy/docker#build-and-run) - - If port 5000 is already being used in your machine, you can specify any other port such as 2345:5000 in the args, and make sure to have the environment variable `TEST_PROXY_HTTP_PORT` set as the specified port(2345 in this case) so that the recorder knows which port to hit. - -#### (OR) With the `dotnet tool` - -- Install [.Net 5.0](https://dotnet.microsoft.com/download) -- Install test-proxy - > `dotnet tool install azure.sdk.tools.testproxy --global --add-source https://pkgs.dev.azure.com/azure-sdk/public/_packaging/azure-sdk-for-net/nuget/v3/index.json --version 1.0.0-dev*` -- After successful installation, run the tool: - - > `test-proxy --storage-location ` - - [ `root-of-the-repo example` - `/workspaces/azure-sdk-for-js` if you're on codespaces, `C:/Users/username/projects/azure-sdk-for-js/` on windows, etc] - - Reference: [Azure SDK Tools Test Proxy](https://github.com/Azure/azure-sdk-tools/tree/main/tools/test-proxy/Azure.Sdk.Tools.TestProxy) - ### Next steps The test-recorder(v3.0) might not be used yet in each one of the libraries in the `azure-sdk-for-js` repository (we're working on it). In the mean time, an easy way to find where we're using this package is by going through the following search link: From bbded0d83169c4dcea4903c1c52a187f88efd03a Mon Sep 17 00:00:00 2001 From: Harsha Nalluru Date: Thu, 23 Mar 2023 04:57:10 +0000 Subject: [PATCH 02/12] nits --- sdk/test-utils/recorder/ASSET_SYNC_MIGRATION.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sdk/test-utils/recorder/ASSET_SYNC_MIGRATION.md b/sdk/test-utils/recorder/ASSET_SYNC_MIGRATION.md index 5353003e01d7..459adc68d60e 100644 --- a/sdk/test-utils/recorder/ASSET_SYNC_MIGRATION.md +++ b/sdk/test-utils/recorder/ASSET_SYNC_MIGRATION.md @@ -8,14 +8,14 @@ Recordings take up a large amount of space in our repository and generate a lot ### Prerequisites -To be able to leverage the asset-sync work, you will need +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`). More detail on migrating to the new recorder can be found in the [recorder 3.0 migration guide]. +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. ```bash $ npx dev-tool test-proxy migrate --initial-push From 9c61fb75411c5b2b210f3050d1a2ed9eddd776a4 Mon Sep 17 00:00:00 2001 From: Harsha Nalluru Date: Thu, 23 Mar 2023 05:58:44 +0000 Subject: [PATCH 03/12] nits --- .../recorder/ASSET_SYNC_MIGRATION.md | 18 +++++++++++++----- sdk/test-utils/recorder/README.md | 2 +- 2 files changed, 14 insertions(+), 6 deletions(-) diff --git a/sdk/test-utils/recorder/ASSET_SYNC_MIGRATION.md b/sdk/test-utils/recorder/ASSET_SYNC_MIGRATION.md index 459adc68d60e..c9a4708834a1 100644 --- a/sdk/test-utils/recorder/ASSET_SYNC_MIGRATION.md +++ b/sdk/test-utils/recorder/ASSET_SYNC_MIGRATION.md @@ -17,6 +17,10 @@ _If you are working on a new package and don't have any recorded tests, skip to 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 ``` @@ -25,8 +29,7 @@ _Note: If you [install `dev-tool` globally], you don't need `npx` prefix in the 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. +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. @@ -45,13 +48,15 @@ And the recordings are located at https://github.com/Azure/azure-sdk-assets/tree _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// ``` -Generate an `sdk///assets.json` file. +Generate an `sdk///assets.json` file by running the following command. ``` npx dev-tool test-proxy init @@ -112,14 +117,16 @@ graph TD 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 + classDef purple fill:#6600cc,stroke:#333,stroke-width:2px class p1 orange class p2 green class p3 blue + class p4 purple ``` ### 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. @@ -138,7 +145,8 @@ 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. -Useful commands while testing. +**Refer to [testing-commands](./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. diff --git a/sdk/test-utils/recorder/README.md b/sdk/test-utils/recorder/README.md index c769cbeae836..271d2bd58efc 100644 --- a/sdk/test-utils/recorder/README.md +++ b/sdk/test-utils/recorder/README.md @@ -15,7 +15,7 @@ Our recorder tool package `@azure-tools/test-recorder` attempts to provide an an **Note 2: If you're looking to onboard to the asset-sync workflow to push out the test recordings to `Azure/azure-sdk-assets` repository, refer to [asset-sync-migration](./ASSET_SYNC_MIGRATION.md).** -**Note 3: Refer [testing-commands](./GoldenCommands.md) if you need help on which command to run during testing.** +**Note 3: Refer to [testing-commands](./GoldenCommands.md) if you need help on commands to run during testing.** This library provides interfaces and helper methods to equip the SDKs in the `azure-sdk-for-js` repo with the recording and playback capabilities for the tests, it targets HTTP requests in both Node.js and the Browsers. From fa4e3f4dc718cf63ad768aaedf14e1ac5b6b433f Mon Sep 17 00:00:00 2001 From: Harsha Nalluru Date: Wed, 22 Mar 2023 23:00:57 -0700 Subject: [PATCH 04/12] Update sdk/test-utils/recorder/ASSET_SYNC_MIGRATION.md --- sdk/test-utils/recorder/ASSET_SYNC_MIGRATION.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/test-utils/recorder/ASSET_SYNC_MIGRATION.md b/sdk/test-utils/recorder/ASSET_SYNC_MIGRATION.md index c9a4708834a1..f4a2704a6cd1 100644 --- a/sdk/test-utils/recorder/ASSET_SYNC_MIGRATION.md +++ b/sdk/test-utils/recorder/ASSET_SYNC_MIGRATION.md @@ -86,7 +86,7 @@ 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. -After the onboarding your new package or after migrating your package to asset-sync, the following 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 From 5ca5ce86c832770645c8bdae95fbd2afe492a597 Mon Sep 17 00:00:00 2001 From: Harsha Nalluru Date: Thu, 23 Mar 2023 06:02:56 +0000 Subject: [PATCH 05/12] unneeded color --- sdk/test-utils/recorder/ASSET_SYNC_MIGRATION.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/sdk/test-utils/recorder/ASSET_SYNC_MIGRATION.md b/sdk/test-utils/recorder/ASSET_SYNC_MIGRATION.md index c9a4708834a1..62c40df5f29e 100644 --- a/sdk/test-utils/recorder/ASSET_SYNC_MIGRATION.md +++ b/sdk/test-utils/recorder/ASSET_SYNC_MIGRATION.md @@ -89,14 +89,12 @@ You should stage and commit the `assets.json` update as part of your PR. If you After the onboarding your new package or after migrating your package to asset-sync, the following diagram describes the new workflow (new steps highlighted): ```mermaid - graph TD subgraph p3 [New steps] subgraph p4 [Push recordings to asset sync repo] push[[npx dev-tool test-proxy push]] end p4-->assets[Commit assets.json change] - end assets --> pr[Push branch and\ncreate PR] @@ -117,11 +115,9 @@ graph TD 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 - classDef purple fill:#6600cc,stroke:#333,stroke-width:2px class p1 orange class p2 green class p3 blue - class p4 purple ``` ### Inspecting recordings with asset sync enabled From 50a3c3dc94a2f80ddf755a766723e25e37c49687 Mon Sep 17 00:00:00 2001 From: Harsha Nalluru Date: Thu, 23 Mar 2023 06:07:41 +0000 Subject: [PATCH 06/12] reduce boxing --- sdk/test-utils/recorder/ASSET_SYNC_MIGRATION.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/sdk/test-utils/recorder/ASSET_SYNC_MIGRATION.md b/sdk/test-utils/recorder/ASSET_SYNC_MIGRATION.md index afa29766f5dc..7e4c4bdce117 100644 --- a/sdk/test-utils/recorder/ASSET_SYNC_MIGRATION.md +++ b/sdk/test-utils/recorder/ASSET_SYNC_MIGRATION.md @@ -92,7 +92,7 @@ After onboarding your new package or after migrating your package to the asset-s graph TD subgraph p3 [New steps] subgraph p4 [Push recordings to asset sync repo] - push[[npx dev-tool test-proxy push]] + push[npx dev-tool test-proxy push] end p4-->assets[Commit assets.json change] end @@ -100,11 +100,11 @@ graph TD assets --> pr[Push branch and\ncreate PR] subgraph p2 [Inspect recordings and test in playback] - playback[[TEST_MODE=playback rushx test]] + playback[TEST_MODE=playback rushx test] end subgraph p1 [Record tests] - record[[TEST_MODE=record rushx test]] + record[TEST_MODE=record rushx test] end p1 --> p2 From 35990cbd2133e6a3f2544c9a8d31eb6e131ccd7e Mon Sep 17 00:00:00 2001 From: Harsha Nalluru Date: Wed, 22 Mar 2023 23:10:41 -0700 Subject: [PATCH 07/12] Update sdk/test-utils/recorder/README.md --- sdk/test-utils/recorder/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/test-utils/recorder/README.md b/sdk/test-utils/recorder/README.md index 271d2bd58efc..744690faa566 100644 --- a/sdk/test-utils/recorder/README.md +++ b/sdk/test-utils/recorder/README.md @@ -476,7 +476,7 @@ If you run into issues while running the tests in record/playback modes, some of `dev-tool` by default outputs logs from the test proxy to `test-proxy-output.log` in your package's root directory. These logs can be inspected to see what requests were made to the proxy tool. #### Switching ports -If port 5000 is already being used in your machine, you can specify any other port such as 2345:5000 in the args, and make sure to have the environment variable `TEST_PROXY_HTTP_PORT` set as the specified port(2345 in this case). +If port 5000 is already being used in your machine, you can specify the environment variable `TEST_PROXY_HTTP_PORT` and point to the port number that you wish. (Example, `export TEST_PROXY_HTTP_PORT=2345`) ### Next steps From 11cdd821e7b23bcc5217830f0fa6ad7fc27c57d9 Mon Sep 17 00:00:00 2001 From: Harsha Nalluru Date: Thu, 23 Mar 2023 06:34:39 +0000 Subject: [PATCH 08/12] asset sync in readme --- sdk/test-utils/recorder/README.md | 39 +++++++++++++++++++++++++++++-- 1 file changed, 37 insertions(+), 2 deletions(-) diff --git a/sdk/test-utils/recorder/README.md b/sdk/test-utils/recorder/README.md index 271d2bd58efc..a5df9d927592 100644 --- a/sdk/test-utils/recorder/README.md +++ b/sdk/test-utils/recorder/README.md @@ -30,6 +30,7 @@ This tool helps to record and playback the tests in the JS repo by leveraging th - [Installing the package](#installing-the-package) - [Configuring your project](#configuring-your-project) - [TEST_MODE](#test_mode) +- [Onboard to asset-sync workflow](#onboard-to-asset---sync-workflow) - [Using the `Recorder`](#using-the-recorder) - [Recorder#variable()](#recordervariable) - [Environment Variables](#environment-variables) @@ -158,6 +159,27 @@ Interactions with the test-proxy tool vary based on what the `TEST_MODE` environ | `playback` | Stored requests/responses are utilized by the test-proxy tool when the requests are redirected to it instead of reaching the service | | `live` | Recorder and its methods are no-ops here, requests directly reach the service instead of being redirected at the test-proxy tool layer | +## Onboard to asset-sync workflow + +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// +``` + +Generate an `sdk///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. +Once you generate the recordings for your tests and push them to the assets repo, the tag gets populated here. + +For further understanding, please read the [asset sync migration and workflow](./ASSET_SYNC_MIGRATION.md). + ## Using the `Recorder` Inside a mocha test (either in the `beforeEach` or in the test body itself), you will need to instantiate the `Recorder` as below to leverage its functionalities. @@ -281,6 +303,8 @@ module.exports = function (config) { }; ``` +## Onboard to asset-sync workflow + ## Examples ### How to record @@ -357,7 +381,13 @@ describe(`TableServiceClient tests`, () => { ``` - After running this test with the `TEST_MODE` environment variable set to - `record`, the recorder assisted by the test-proxy tool will create a recording file located in `recordings/node/tableserviceclient_tests/recording_should_create_new_table_then_delete.json` with the contents of the HTTP requests as well as the responses. + `record`, the recorder assisted by the test-proxy tool will create a recording file with the contents of the HTTP requests as well as the responses. + + If the package has been onboarded to asset-sync workflow, the recording will be loacted under the `.assets/` at the root of the repository. + - To view the recording, refer to `.assets/.breadcrumb` to find the entry that matches your SDK. This will give you the name of the directory within `.assets` that your recordings are located in. + - Refer to [asset sync workflow](./ASSET_SYNC_MIGRATION.md#workflow-with-asset-sync-enabled) for more understanding and further steps. + + Otherwise, the recording will be located at `recordings/node/tableserviceclient_tests/recording_should_create_new_table_then_delete.json`. - You'll see in the code above that we're invoking `recorder.stop`. This is so that, after each test, we can stop recording and the test file can be generated. @@ -476,11 +506,16 @@ If you run into issues while running the tests in record/playback modes, some of `dev-tool` by default outputs logs from the test proxy to `test-proxy-output.log` in your package's root directory. These logs can be inspected to see what requests were made to the proxy tool. #### Switching ports + If port 5000 is already being used in your machine, you can specify any other port such as 2345:5000 in the args, and make sure to have the environment variable `TEST_PROXY_HTTP_PORT` set as the specified port(2345 in this case). +### Inspecting recordings +Refer to [asset sync workflow - inspect recordings](./ASSET_SYNC_MIGRATION.md#inspecting-recordings-with-asset-sync-enabled). + ### Next steps -The test-recorder(v3.0) might not be used yet in each one of the libraries in the `azure-sdk-for-js` repository (we're working on it). In the mean time, an easy way to find where we're using this package is by going through the following search link: +Almost all the libraries in the `azure-sdk-for-js` repository leverage test-recorder(v3.0). +If you want to refer to the tests that leverage this package, go through the following search link: ### Contributing From b081caf993b8efcf10bc2f9c4f6a7bea83182c44 Mon Sep 17 00:00:00 2001 From: Harsha Nalluru Date: Fri, 24 Mar 2023 12:02:20 +0000 Subject: [PATCH 09/12] fix rel links --- sdk/test-utils/recorder/ASSET_SYNC_MIGRATION.md | 2 +- sdk/test-utils/recorder/GoldenCommands.md | 6 +++--- sdk/test-utils/recorder/README.md | 10 +++++----- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/sdk/test-utils/recorder/ASSET_SYNC_MIGRATION.md b/sdk/test-utils/recorder/ASSET_SYNC_MIGRATION.md index 7e4c4bdce117..6ef2f6fd4d99 100644 --- a/sdk/test-utils/recorder/ASSET_SYNC_MIGRATION.md +++ b/sdk/test-utils/recorder/ASSET_SYNC_MIGRATION.md @@ -141,7 +141,7 @@ 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](./GoldenCommands.md) guide if you need help on the commands to run during testing.** +**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 diff --git a/sdk/test-utils/recorder/GoldenCommands.md b/sdk/test-utils/recorder/GoldenCommands.md index aec6feadae51..1b851ab97028 100644 --- a/sdk/test-utils/recorder/GoldenCommands.md +++ b/sdk/test-utils/recorder/GoldenCommands.md @@ -1,8 +1,8 @@ ## Useful Commands while Testing your packages -If you're not familiar with the recorder refer to [recorder-readme](./README.md). -If you're looking to migrate your existing package from recorder v1 to v3, refer to [migrate-v1-to-v3](./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](./ASSET_SYNC_MIGRATION.md). +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 diff --git a/sdk/test-utils/recorder/README.md b/sdk/test-utils/recorder/README.md index 80d6cc5d78ce..2d60657598d6 100644 --- a/sdk/test-utils/recorder/README.md +++ b/sdk/test-utils/recorder/README.md @@ -13,9 +13,9 @@ Our recorder tool package `@azure-tools/test-recorder` attempts to provide an an **Note 1: In case you're depending on `@azure-tools/test-recorder@1.x.y` and want to migrate your tests to version 3, follow the [migration guide to recorder v3 from v1](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/test-utils/recorder/MIGRATION.md)** -**Note 2: If you're looking to onboard to the asset-sync workflow to push out the test recordings to `Azure/azure-sdk-assets` repository, refer to [asset-sync-migration](./ASSET_SYNC_MIGRATION.md).** +**Note 2: If you're looking to onboard 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).** -**Note 3: Refer to [testing-commands](./GoldenCommands.md) if you need help on commands to run during testing.** +**Note 3: Refer to [testing-commands](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/test-utils/recorder/GoldenCommands.md) if you need help on commands to run during testing.** This library provides interfaces and helper methods to equip the SDKs in the `azure-sdk-for-js` repo with the recording and playback capabilities for the tests, it targets HTTP requests in both Node.js and the Browsers. @@ -178,7 +178,7 @@ npx dev-tool test-proxy init This command would generate an `assets.json` file with an empty tag. Once you generate the recordings for your tests and push them to the assets repo, the tag gets populated here. -For further understanding, please read the [asset sync migration and workflow](./ASSET_SYNC_MIGRATION.md). +For further understanding, please read the [asset sync migration and workflow](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/test-utils/recorder/ASSET_SYNC_MIGRATION.md). ## Using the `Recorder` @@ -385,7 +385,7 @@ describe(`TableServiceClient tests`, () => { If the package has been onboarded to asset-sync workflow, the recording will be loacted under the `.assets/` at the root of the repository. - To view the recording, refer to `.assets/.breadcrumb` to find the entry that matches your SDK. This will give you the name of the directory within `.assets` that your recordings are located in. - - Refer to [asset sync workflow](./ASSET_SYNC_MIGRATION.md#workflow-with-asset-sync-enabled) for more understanding and further steps. + - Refer to [asset sync workflow](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/test-utils/recorder/ASSET_SYNC_MIGRATION.md#workflow-with-asset-sync-enabled) for more understanding and further steps. Otherwise, the recording will be located at `recordings/node/tableserviceclient_tests/recording_should_create_new_table_then_delete.json`. @@ -509,7 +509,7 @@ If you run into issues while running the tests in record/playback modes, some of If port 5000 is already being used in your machine, you can specify the environment variable `TEST_PROXY_HTTP_PORT` and point to the port number that you wish. (Example, `export TEST_PROXY_HTTP_PORT=2345`) ### Inspecting recordings -Refer to [asset sync workflow - inspect recordings](./ASSET_SYNC_MIGRATION.md#inspecting-recordings-with-asset-sync-enabled). +Refer to [asset sync workflow - inspect recordings](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/test-utils/recorder/ASSET_SYNC_MIGRATION.md#inspecting-recordings-with-asset-sync-enabled). ### Next steps From 895219ceacd9cac6b3c299103c286aa4a485e0f3 Mon Sep 17 00:00:00 2001 From: Harsha Nalluru Date: Mon, 27 Mar 2023 14:03:49 +0000 Subject: [PATCH 10/12] move golden testing commands to wiki --- .../recorder/ASSET_SYNC_MIGRATION.md | 2 +- sdk/test-utils/recorder/GoldenCommands.md | 39 ------------------- sdk/test-utils/recorder/README.md | 2 +- 3 files changed, 2 insertions(+), 41 deletions(-) delete mode 100644 sdk/test-utils/recorder/GoldenCommands.md diff --git a/sdk/test-utils/recorder/ASSET_SYNC_MIGRATION.md b/sdk/test-utils/recorder/ASSET_SYNC_MIGRATION.md index 6ef2f6fd4d99..1ea0f03a677a 100644 --- a/sdk/test-utils/recorder/ASSET_SYNC_MIGRATION.md +++ b/sdk/test-utils/recorder/ASSET_SYNC_MIGRATION.md @@ -141,7 +141,7 @@ 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.** +**Refer to [testing-commands](https://github.com/Azure/azure-sdk-for-js/wiki/Golden-Testing-Commands) guide if you need help on the commands to run during testing.** ### Working offline diff --git a/sdk/test-utils/recorder/GoldenCommands.md b/sdk/test-utils/recorder/GoldenCommands.md deleted file mode 100644 index 1b851ab97028..000000000000 --- a/sdk/test-utils/recorder/GoldenCommands.md +++ /dev/null @@ -1,39 +0,0 @@ -## 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 diff --git a/sdk/test-utils/recorder/README.md b/sdk/test-utils/recorder/README.md index 2d60657598d6..6749350dc311 100644 --- a/sdk/test-utils/recorder/README.md +++ b/sdk/test-utils/recorder/README.md @@ -15,7 +15,7 @@ Our recorder tool package `@azure-tools/test-recorder` attempts to provide an an **Note 2: If you're looking to onboard 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).** -**Note 3: Refer to [testing-commands](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/test-utils/recorder/GoldenCommands.md) if you need help on commands to run during testing.** +**Note 3: Refer to [testing-commands](https://github.com/Azure/azure-sdk-for-js/wiki/Golden-Testing-Commands) if you need help on commands to run during testing.** This library provides interfaces and helper methods to equip the SDKs in the `azure-sdk-for-js` repo with the recording and playback capabilities for the tests, it targets HTTP requests in both Node.js and the Browsers. From 4c6611d13cffcd8608019e46c3e1b7af7d988bf1 Mon Sep 17 00:00:00 2001 From: Harsha Nalluru Date: Mon, 27 Mar 2023 14:07:22 +0000 Subject: [PATCH 11/12] no prereq section --- sdk/test-utils/recorder/MIGRATION.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/sdk/test-utils/recorder/MIGRATION.md b/sdk/test-utils/recorder/MIGRATION.md index ed585a0bca10..46c9e68ee4aa 100644 --- a/sdk/test-utils/recorder/MIGRATION.md +++ b/sdk/test-utils/recorder/MIGRATION.md @@ -2,11 +2,6 @@ This document outlines key differences between the legacy recorder and the new Unified Recorder client. The Unified Recorder replaces the older `nock/nise`-based recorder(v1) with a solution that uses the language-agnostic [test proxy server]. -## No Prerequisites Like Before? How?? - -- With recorder v2, Docker was required for to leverage the [test proxy server]. This is not needed anymore with recorder v3. -- Using the [`dev-tool run ...` commands](changes-to-npm-scripts) would automatically download the [latest test proxy artifacts] from the [Azure/azure-sdk-tools] repo according to your operating system/architecture. - ## Advantages of migration to v3 - Recorder v3 handles secrets in the recordings better than v1 leveraging the new sanitizers/transformations approach. From 9f3af41a348a294892eac97dfcecab0d11ae1ead Mon Sep 17 00:00:00 2001 From: Harsha Nalluru Date: Mon, 27 Mar 2023 15:20:37 +0000 Subject: [PATCH 12/12] golden commands link --- CONTRIBUTING.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b2ee1995642d..d9db94cec608 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -54,6 +54,7 @@ Rush provides many benefits: Not every library in the repository is managed by Rush yet, only those listed in the `projects` property in [rush.json](https://github.com/Azure/azure-sdk-for-js/blob/main/rush.json). Packages not managed by Rush can still be managed using `npm`. Check out our [wiki page on using rush](https://github.com/Azure/azure-sdk-for-js/wiki/Rush) for more information on + - running `rush update` command - How to update to a newer version of Rush or PNPM. @@ -78,11 +79,13 @@ If you prefer to setup your own environment instead, make sure you have these pr - Git - Any of the [LTS versions of Node.js](https://github.com/nodejs/release#release-schedule) - A C++ compiler toolchain and Python (for compiling machine-code modules): + - Windows: Install the [Visual Studio Build Tools][buildtools] from Microsoft and [Python 3.9][python39windows] from the Microsoft Store. - macOS: Install Xcode or the "Command Line Tools for XCode" (much smaller) from [Apple's developer downloads page](https://developer.apple.com/download/all/). - Linux: Install Python and GCC/G++ (part of the `build-essential` package on Ubuntu-based distributions) using your distribution's package manager. **On Linux, development headers for `libsecret` are also required.** Typically, these are available in a package called `libsecret-1-dev` (Debian/Ubuntu) or `libsecret-devel` (Fedora/Red Hat). + - Rush 5.x - Install / update Rush globally via `npm install -g @microsoft/rush`. - Rush will automatically manage the specific version needed by this repo as long as you have any v5 version installed. @@ -178,7 +181,7 @@ 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. +Here are a few [Useful Commands](https://github.com/Azure/azure-sdk-for-js/wiki/Golden-Testing-Commands) that can be handy while testing your SDKs. ### Other NPM scripts @@ -340,8 +343,8 @@ Samples may take the following categories of dependencies: - **Commercial**: Commercial offerings that enable readers to learn from our content without unnecessary extra costs. Typically, the offering has some form of a community edition, or a free trial sufficient for its use in content. A commercial license may be a form of dual-license, or tiered license. Links to commercial components should be to the commercial site for the software, even if the source software is hosted publicly on GitHub (or similar). -- **Dual licensed**: Commercial offerings that enable readers to choose either license based on their needs. For example, if the offering has an OSS and commercial license, readers can choose between them. [MySql](https://github.com/mysql/mysql-server) is an example of this license type. +- **Dual licensed**: Commercial offerings that enable readers to choose either license based on their needs. For example, if the offering has an OSS and commercial license, readers can choose between them. [MySql](https://github.com/mysql/mysql-server) is an example of this license type. -- **Tiered licensed**: Offerings that enable readers to use the license tier that corresponds to their characteristics. For example, tiers may be available for students, hobbyists, or companies with defined revenue thresholds. For offerings with tiered licenses, strive to limit our use in tutorials to the features available in the lowest tier. This policy enables the widest audience for the article. [Docker](https://www.docker.com/), [IdentityServer](https://duendesoftware.com/products/identityserver), [ImageSharp](https://sixlabors.com/products/imagesharp/), and [Visual Studio](https://visualstudio.com) are examples of this license type. +- **Tiered licensed**: Offerings that enable readers to use the license tier that corresponds to their characteristics. For example, tiers may be available for students, hobbyists, or companies with defined revenue thresholds. For offerings with tiered licenses, strive to limit our use in tutorials to the features available in the lowest tier. This policy enables the widest audience for the article. [Docker](https://www.docker.com/), [IdentityServer](https://duendesoftware.com/products/identityserver), [ImageSharp](https://sixlabors.com/products/imagesharp/), and [Visual Studio](https://visualstudio.com) are examples of this license type. In general, we prefer taking dependencies on licensed components in the order of the listed categories. In cases where the category may not be well known, we'll document the category so that readers understand the choice that they're making by using that dependency.