1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
|
# Live Test Resource Management
Running and recording live tests often requires first creating some resources
in Azure. Service directories that include a test-resources.json file require
running [New-TestResources.ps1][] to create these resources and output
environment variables you must set.
The following scripts can be used both in on your desktop for developer
scenarios as well as on hosted agents for continuous integration testing.
* [New-TestResources.ps1][] - Creates new test resources for a given service.
* [Remove-TestResources.ps1][] - Deletes previously created resources.
## Prerequisites
1. Install [PowerShell][] version 7.0 or newer.
2. Install the [Azure PowerShell][PowerShellAz].
## On the Desktop
To set up your Azure account to run live tests, you'll need to log into Azure,
create a service principal, and set up your resources defined in
test-resources.json as shown in the following example using Azure Search.
Note that `-Subscription` is an optional parameter but recommended if your account
is a member of multiple subscriptions.
```powershell
Connect-AzAccount -Subscription 'YOUR SUBSCRIPTION ID'
eng\common\TestResources\New-TestResources.ps1 -ServiceDirectory 'search'
```
The `OutFile` switch would be set if you are running this for a .NET project on Windows. This will save test environment settings
into a test-resources.json.env file next to test-resources.json. The file is protected via DPAPI.
The environment file would be scoped to the current repository directory and avoids the need to
set environment variables or restart your IDE to recognize them.
Along with some log messages, this will output environment variables based on
your current shell like in the following example:
```powershell
${env:AZURE_TENANT_ID} = '<<secret>>'
${env:AZURE_CLIENT_ID} = '<<secret>>'
${env:AZURE_CLIENT_SECRET} = '<<secret>>'
${env:AZURE_SUBSCRIPTION_ID} = 'YOUR SUBSCRIPTION ID'
${env:AZURE_RESOURCE_GROUP} = 'rg-myusername'
${env:AZURE_LOCATION} = 'westus2'
${env:AZURE_SEARCH_STORAGE_NAME} = 'myusernamestg'
${env:AZURE_SEARCH_STORAGE_KEY} = '<<secret>>'
```
For security reasons we do not set these environment variables automatically
for either the current process or persistently for future sessions. You must
do that yourself based on your current platform and shell.
If your current shell was detected properly, you should be able to copy and
paste the output directly in your terminal and add to your profile script.
For example, in PowerShell on Windows you can copy the output above and paste
it back into the terminal to set those environment variables for the current
process. To persist these variables for future terminal sessions or for
applications started outside the terminal, you could copy and paste the
following commands:
```powershell
setx AZURE_TENANT_ID ${env:AZURE_TENANT_ID}
setx AZURE_CLIENT_ID ${env:AZURE_CLIENT_ID}
setx AZURE_CLIENT_SECRET ${env:AZURE_CLIENT_SECRET}
setx AZURE_SUBSCRIPTION_ID ${env:AZURE_SUBSCRIPTION_ID}
setx AZURE_RESOURCE_GROUP ${env:AZURE_RESOURCE_GROUP}
setx AZURE_LOCATION ${env:AZURE_LOCATION}
setx AZURE_SEARCH_STORAGE_NAME ${env:AZURE_SEARCH_STORAGE_NAME}
setx AZURE_SEARCH_STORAGE_KEY ${env:AZURE_SEARCH_STORAGE_KEY}
```
After running or recording live tests, if you do not plan on further testing
you can remove the test resources you created above by running:
[Remove-TestResources.ps1][]:
```powershell
Remove-TestResources.ps1 -BaseName 'myusername' -Force
```
If you created a new service principal as shown above, you might also remove it:
```powershell
Remove-AzADServicePrincipal -ApplicationId $sp.ApplicationId -Force
```
If you persisted environment variables, you should also remove those as well.
## In CI
Test pipelines should include deploy-test-resources.yml and
remove-test-resources.yml like in the following examples:
```yml
- template: /eng/common/TestResources/deploy-test-resources.yml
parameters:
ServiceDirectory: '${{ parameters.ServiceDirectory }}'
# Run tests
- template: /eng/common/TestResources/remove-test-resources.yml
```
Be sure to link the **Secrets for Resource Provisioner** variable group
into the test pipeline for these scripts to work.
## Documentation
To regenerate documentation for scripts within this directory, you can install
[platyPS][] and run it like in the following example:
```powershell
Install-Module platyPS -Scope CurrentUser -Force
New-MarkdownHelp -Command .\New-TestResources.ps1 -OutputFolder . -Force
```
PowerShell markdown documentation created with [platyPS][].
[New-TestResources.ps1]: https://github.com/Azure/azure-sdk-tools/blob/master/eng/common/TestResources/New-TestResources.ps1.md
[Remove-TestResources.ps1]: https://github.com/Azure/azure-sdk-tools/blob/master/eng/common/TestResources/Remove-TestResources.ps1.md
[PowerShell]: https://github.com/PowerShell/PowerShell
[PowerShellAz]: https://docs.microsoft.com/powershell/azure/install-az-ps
[platyPS]: https://github.com/PowerShell/platyPS
|
