1# Live Test Resource Management 2 3Running and recording live tests often requires first creating some resources 4in Azure. Service directories that include a test-resources.json file require 5running [New-TestResources.ps1][] to create these resources and output 6environment variables you must set. 7 8The following scripts can be used both in on your desktop for developer 9scenarios as well as on hosted agents for continuous integration testing. 10 11* [New-TestResources.ps1][] - Creates new test resources for a given service. 12* [Remove-TestResources.ps1][] - Deletes previously created resources. 13 14## Prerequisites 15 161. Install [PowerShell][] version 7.0 or newer. 172. Install the [Azure PowerShell][PowerShellAz]. 18 19## On the Desktop 20 21To set up your Azure account to run live tests, you'll need to log into Azure, 22and set up your resources defined in test-resources.json as shown in the following 23example using Azure Key Vault. The script will create a service principal automatically, 24or you may create a service principal you can save and reuse subsequently. 25 26Note that `-Subscription` is an optional parameter but recommended if your account 27is a member of multiple subscriptions. If you didn't specify it when logging in, 28you should select your desired subscription using `Select-AzSubscription`. The 29default can be saved using `Set-AzDefault` for future sessions. 30 31```powershell 32Connect-AzAccount -Subscription 'YOUR SUBSCRIPTION ID' 33eng\common\TestResources\New-TestResources.ps1 keyvault 34``` 35 36The `OutFile` switch will be set by default if you are running this for a .NET project on Windows. This will save test environment settings 37into a test-resources.json.env file next to test-resources.json. The file is protected via DPAPI. 38The environment file would be scoped to the current repository directory and avoids the need to 39set environment variables or restart your IDE to recognize them. 40 41Along with some log messages, this will output environment variables based on 42your current shell like in the following example: 43 44```powershell 45${env:KEYVAULT_TENANT_ID} = '<<secret>>' 46${env:KEYVAULT_CLIENT_ID} = '<<secret>>' 47${env:KEYVAULT_CLIENT_SECRET} = '<<secret>>' 48${env:KEYVAULT_SUBSCRIPTION_ID} = 'YOUR SUBSCRIPTION ID' 49${env:KEYVAULT_RESOURCE_GROUP} = 'rg-myusername' 50${env:KEYVAULT_LOCATION} = 'westus2' 51${env:KEYVAULT_SKU} = 'premium' 52${env:AZURE_KEYVAULT_URL} = '<<url>>' 53``` 54 55For security reasons we do not set these environment variables automatically 56for either the current process or persistently for future sessions. You must 57do that yourself based on your current platform and shell. 58 59If your current shell was detected properly, you should be able to copy and 60paste the output directly in your terminal and add to your profile script. 61For example, in PowerShell on Windows you can copy the output above and paste 62it back into the terminal to set those environment variables for the current 63process. To persist these variables for future terminal sessions or for 64applications started outside the terminal, you could copy and paste the 65following commands: 66 67```powershell 68setx KEYVAULT_TENANT_ID ${env:KEYVAULT_TENANT_ID} 69setx KEYVAULT_CLIENT_ID ${env:KEYVAULT_CLIENT_ID} 70setx KEYVAULT_CLIENT_SECRET ${env:KEYVAULT_CLIENT_SECRET} 71setx KEYVAULT_SUBSCRIPTION_ID ${env:KEYVAULT_SUBSCRIPTION_ID} 72setx KEYVAULT_RESOURCE_GROUP ${env:KEYVAULT_RESOURCE_GROUP} 73setx KEYVAULT_LOCATION ${env:KEYVAULT_LOCATION} 74setx KEYVAULT_SKU ${env:KEYVAULT_SKU} 75setx AZURE_KEYVAULT_URL ${env:AZURE_KEYVAULT_URL} 76``` 77 78### Cleaning up Resources 79 80By default, resource groups are tagged with a `DeleteAfter` value and date according to the default or specified 81value for the `-DeleteAfterHours` switch. You can use this tag in scheduled jobs to remove older resources based 82on that date. 83 84If you are not ready for the resources to be deleted, you can update the resource group by running [Update-TestResources.ps1][]: 85 86```powershell 87Update-TestResources.ps1 keyvault 88``` 89 90This will extend the expiration time by the default value (e.g. 48 hours) from now. 91 92Alternatively, after running or recording live tests, if you do not plan on further testing 93you can immediately remove the test resources you created above by running [Remove-TestResources.ps1][]: 94 95```powershell 96Remove-TestResources.ps1 keyvault -Force 97``` 98 99If you persisted environment variables, you should also remove those as well. 100 101### Passing Additional Arguments 102 103Some test-resources.json templates utilize the `AdditionalParameters` parameter to control additional resource configuration options. For example: 104 105```powershell 106New-TestResources.ps1 keyvault -AdditionalParameters @{enableHsm = $true} 107``` 108 109## In CI 110 111Test pipelines should include deploy-test-resources.yml and 112remove-test-resources.yml like in the following examples: 113 114```yml 115- template: /eng/common/TestResources/deploy-test-resources.yml 116 parameters: 117 ServiceDirectory: '${{ parameters.ServiceDirectory }}' 118 119# Run tests 120 121- template: /eng/common/TestResources/remove-test-resources.yml 122``` 123 124Be sure to link the **Secrets for Resource Provisioner** variable group 125into the test pipeline for these scripts to work. 126 127## Documentation 128 129To regenerate documentation for scripts within this directory, you can install 130[platyPS][] and run it like in the following example: 131 132```powershell 133Install-Module platyPS -Scope CurrentUser -Force 134New-MarkdownHelp -Command .\New-TestResources.ps1 -OutputFolder . -Force 135``` 136 137After the markdown files are generated, please make sure all "http" URIs use "https". 138 139PowerShell markdown documentation created with [platyPS][]. 140 141 [New-TestResources.ps1]: https://aka.ms/azsdk/tools/New-TestResources 142 [Update-TestResources.ps1]: https://aka.ms/azsdk/tools/Update-TestResources 143 [Remove-TestResources.ps1]: https://aka.ms/azsdk/tools/Remove-TestResources 144 [PowerShell]: https://github.com/PowerShell/PowerShell 145 [PowerShellAz]: https://docs.microsoft.com/powershell/azure/install-az-ps 146 [platyPS]: https://github.com/PowerShell/platyPS 147