|
| 1 | +# Guide for migrating test recordings out of the `azure-sdk-for-java` repository |
| 2 | + |
| 3 | +The Azure SDK test proxy enables tests to run recorded tests, even when these test recordings are outside the |
| 4 | +`azure-sdk-for-java` repository. Migrating to this out-of-repo recording setup requires an initial recording move, |
| 5 | +and after this the flow to update recordings will be slightly different. This guide describes the first stage of this |
| 6 | +process and links to updated recording instructions. |
| 7 | + |
| 8 | +More technical documentation of the test proxy's out-of-repo recording support can be found [here][detailed_docs] in |
| 9 | +the `azure-sdk-tools` repository. |
| 10 | + |
| 11 | +## Table of contents |
| 12 | + |
| 13 | +- [Guide for migrating test recordings out of the `azure-sdk-for-java` repository](#guide-for-migrating-test-recordings-out-of-the-azure-sdk-for-java-repository) |
| 14 | + - [Table of contents](#table-of-contents) |
| 15 | + - [Current recording setup](#current-recording-setup) |
| 16 | + - [New recording setup](#new-recording-setup) |
| 17 | + - [Initial recording migration](#initial-recording-migration) |
| 18 | + - [Migration script prerequisites](#migration-script-prerequisites) |
| 19 | + - [Execute the migration script](#execute-the-migration-script) |
| 20 | + - [Run tests with out-of-repo recordings](#run-tests-with-out-of-repo-recordings) |
| 21 | + |
| 22 | +## Current recording setup |
| 23 | + |
| 24 | +Currently, test recordings live in the `azure-sdk-for-java` repository (or "language repo"), under a given package's |
| 25 | +`src/test/resources/session-records/` directory. The test proxy loads recordings from this local directory and can be |
| 26 | +done entirely offline. |
| 27 | + |
| 28 | +Storing recordings in the language repository significantly contributes to the repository's large size, which is its |
| 29 | +main drawback. Recording file updates are also included in pull requests, which can make them more tedious to review |
| 30 | +and difficult to load. |
| 31 | + |
| 32 | +## New recording setup |
| 33 | + |
| 34 | +With the test proxy, we can instead store recordings in a completely different git repository (called |
| 35 | +[`azure-sdk-assets`][azure_sdk_assets], or the "assets repo"). The test proxy creates a sparse clone of only the |
| 36 | +recordings for the package being tested, stores them locally in a git-excluded language repo directory, and runs |
| 37 | +playback tests in the same way as before. |
| 38 | + |
| 39 | +The out-of-repo recording system requires a connection to fetch recordings but frees up considerable space in the |
| 40 | +language repo. Additionally, pull requests that update recordings now update a single pointer to new recordings instead |
| 41 | +of full recording files. |
| 42 | + |
| 43 | +The pointer to test recordings is stored in a new `assets.json` file that will be created for each package during the |
| 44 | +initial migration. |
| 45 | + |
| 46 | +## Initial recording migration |
| 47 | + |
| 48 | +A [PowerShell script][transition_script] in the `azure-sdk-tools` repository will assist in pushing recordings to the |
| 49 | +assets repo, removing recordings from the language repo, and creating an `assets.json` file for the package you're |
| 50 | +migrating. |
| 51 | + |
| 52 | +This script -- [`generate-assets-json.ps1`][generate_assets_json] -- should be run once per package, and can be used |
| 53 | +either directly from an `azure-sdk-tools` repo clone or with a local download of the script. To download the script to |
| 54 | +your current working directory, use the following PowerShell command: |
| 55 | + |
| 56 | +```PowerShell |
| 57 | +Invoke-WebRequest -OutFile "generate-assets-json.ps1" https://raw.githubusercontent.com/Azure/azure-sdk-for-java/main/eng/common/testproxy/onboarding/generate-assets-json.ps1 |
| 58 | +``` |
| 59 | + |
| 60 | +### Migration script prerequisites |
| 61 | + |
| 62 | +- The targeted library is already migrated to use the test proxy. |
| 63 | +- Git version > 2.25.0 is to on the machine and in the path. Git is used by the script and test proxy. |
| 64 | +- [PowerShell Core][powershell] >= 7.0 is installed. |
| 65 | +- Global [git config settings][git_setup] are configured for `user.name` and `user.email`. |
| 66 | + - These settings can be overridden with environment variables `GIT_COMMIT_OWNER` and `GIT_COMMIT_EMAIL`, respectively. |
| 67 | +- Membership in the `azure-sdk-write` GitHub group. |
| 68 | + |
| 69 | +### Execute the migration script |
| 70 | + |
| 71 | +In a PowerShell window: |
| 72 | + |
| 73 | +1. Set your working directory to the root of the package you're migrating (`sdk/{service}/{package}`) -- for example: |
| 74 | + |
| 75 | +```PowerShell |
| 76 | +cd C:\azure-sdk-for-java\sdk\textanalytics\azure-ai-textanalytics |
| 77 | +``` |
| 78 | + |
| 79 | +2. Run the following command: |
| 80 | + |
| 81 | +```PowerShell |
| 82 | +<path-to-script>/generate-assets-json.ps1 -InitialPush |
| 83 | +``` |
| 84 | + |
| 85 | +If you run `git status` from within the language repo, you should see: |
| 86 | + |
| 87 | +- Deleted files for each test recording in the package |
| 88 | +- A new `assets.json` file under the root of your package |
| 89 | + |
| 90 | +The `assets.json` file will have the form: |
| 91 | + |
| 92 | +```json |
| 93 | +{ |
| 94 | + "AssetsRepo": "Azure/azure-sdk-assets", |
| 95 | + "AssetsRepoPrefixPath": "java", |
| 96 | + "TagPrefix": "java/{service}/{package}", |
| 97 | + "Tag": "java/{service}/{package}_<10-character-commit-SHA>" |
| 98 | +} |
| 99 | +``` |
| 100 | + |
| 101 | +The `Tag` field matches the name of a tag that's been created in the assets repo and contains the uploaded recordings. |
| 102 | +Before creating a PR to cement the recording move, it's a good idea to check out that tag in the assets repo and make |
| 103 | +sure the recordings that you expect to see are there. |
| 104 | + |
| 105 | +## Run tests with out-of-repo recordings |
| 106 | + |
| 107 | +After moving recordings to the asset repo, live and playback testing will be the same as it was in the past. The test |
| 108 | +proxy automatically pulls down the correct set of recordings based on the `Tag` in your package's `assets.json` file. |
| 109 | + |
| 110 | +The process for updating test recordings is slightly different from it was with in-repo recordings, and differs in two |
| 111 | +primary ways: |
| 112 | + |
| 113 | +1. When tests are run in recording mode, recording changes won't be visible in the language repo and will instead be |
| 114 | + tracked in a separate git ignored `.assets` directory. |
| 115 | +2. When updated recordings are pushed to the assets repo, the `Tag` field in your package's `assets.json` file will be |
| 116 | + updated to point to these new recordings. This `assets.json` change is what you'll include in a pull request to update |
| 117 | + recordings in the language repo. |
| 118 | + |
| 119 | +[azure_sdk_assets]: https://github.com/Azure/azure-sdk-assets |
| 120 | +[detailed_docs]: https://github.com/Azure/azure-sdk-tools/blob/main/tools/test-proxy/documentation/asset-sync/README.md |
| 121 | +[generate_assets_json]: https://github.com/Azure/azure-sdk-tools/blob/main/eng/common/testproxy/onboarding/generate-assets-json.ps1 |
| 122 | +[git_setup]: https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup |
| 123 | +[git_token]: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token |
| 124 | +[powershell]: https://learn.microsoft.com/powershell/scripting/install/installing-powershell?view=powershell-latest |
| 125 | +[transition_script]: https://github.com/Azure/azure-sdk-for-java/blob/main/eng/common/testproxy/onboarding/README.md |
0 commit comments