diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c82e4f9acddb..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. @@ -150,13 +153,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 +181,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](https://github.com/Azure/azure-sdk-for-js/wiki/Golden-Testing-Commands) 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. @@ -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. 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..1ea0f03a677a 100644 --- a/sdk/test-utils/recorder/ASSET_SYNC_MIGRATION.md +++ b/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// +``` + +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. + ## 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,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
TEST_MODE=record rushx test
] --> -playback[Inspect recordings and test in playback
TEST_MODE=playback rushx test
] - -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
npx dev-tool test-proxy push
] --> -assets[Commit assets.json 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 assets.json 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/wiki/Golden-Testing-Commands) 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 diff --git a/sdk/test-utils/recorder/MIGRATION.md b/sdk/test-utils/recorder/MIGRATION.md index a910a327edf9..46c9e68ee4aa 100644 --- a/sdk/test-utils/recorder/MIGRATION.md +++ b/sdk/test-utils/recorder/MIGRATION.md @@ -1,24 +1,20 @@ # 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 +## Advantages of migration to v3 -- [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. - -## Advantages of migration to v2 - -- 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 +22,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 +294,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..6749350dc311 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](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/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. @@ -26,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) @@ -39,7 +44,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 +148,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. @@ -165,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](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/test-utils/recorder/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. @@ -288,6 +303,8 @@ module.exports = function (config) { }; ``` +## Onboard to asset-sync workflow + ## Examples ### How to record @@ -364,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](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`. - 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. @@ -482,63 +505,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. -#### 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 -``` - -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] +#### Switching ports +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`) - Reference: [Azure SDK Tools Test Proxy](https://github.com/Azure/azure-sdk-tools/tree/main/tools/test-proxy/Azure.Sdk.Tools.TestProxy) +### Inspecting recordings +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 -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