Uso del kit de herramientas para pruebas de plantillas de ARM

Artículo
10/05/2021
7 minutos para leer

El kit de herramientas para pruebas de la plantilla de Resource Manager comprueba si la plantilla usa los procedimientos recomendados. Cuando la plantilla no es compatible con los procedimientos recomendados, devuelve una lista de advertencias con los cambios sugeridos. Con el kit de herramientas para pruebas, puede obtener información sobre cómo evitar los problemas comunes en el desarrollo de plantillas. En este artículo se describe cómo ejecutar el kit de herramientas para pruebas y cómo agregar o eliminar pruebas. Para más información sobre cómo ejecutar pruebas o sobre la ejecución de una prueba específica, consulte Parámetros de prueba.

El kit de herramientas es un conjunto de scripts de PowerShell que se puede ejecutar desde un comando de PowerShell o la CLI. Estas pruebas son recomendaciones, pero no requisitos. Puede decidir qué pruebas son adecuadas para sus objetivos y personalizar qué pruebas se ejecutan.

El kit de herramientas contiene cuatro conjuntos de pruebas:

Microsoft Learn

Para obtener más información sobre el kit de herramientas de pruebas de plantillas de ARM y para obtener instrucciones prácticas, consulte Validación de recursos de Azure mediante el kit de herramientas para pruebas de plantillas de ARM en Microsoft Learn.

Instalar en Windows

Si aún no tiene PowerShell, instale PowerShell en Windows.
Descargue el archivo ZIP más reciente para el kit de herramientas de pruebas y extráigalo.
Inicie PowerShell.
Navegue hasta la carpeta en la que extrajo el kit de herramientas de pruebas. Dentro de esa carpeta, vaya a la carpeta arm-ttk.
Si la directiva de ejecución bloquea los scripts de Internet, debe desbloquear los archivos de script. Asegúrese de que se encuentra en la carpeta arm-ttk.
```
Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File
```
Importe el módulo.
```
Import-Module .\arm-ttk.psd1
```
Para ejecutar las pruebas, use el siguiente comando:
```
Test-AzTemplate -TemplatePath \path\to\template
```

Instalar en Linux

Si aún no tiene PowerShell, instale PowerShell en Linux.
Descargue el archivo ZIP más reciente para el kit de herramientas de pruebas y extráigalo.
Inicie PowerShell.
```
pwsh
```
Navegue hasta la carpeta en la que extrajo el kit de herramientas de pruebas. Dentro de esa carpeta, vaya a la carpeta arm-ttk.
Si la directiva de ejecución bloquea los scripts de Internet, debe desbloquear los archivos de script. Asegúrese de que se encuentra en la carpeta arm-ttk.
```
Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File
```
Importe el módulo.
```
Import-Module ./arm-ttk.psd1
```
Para ejecutar las pruebas, use el siguiente comando:
```
Test-AzTemplate -TemplatePath /path/to/template
```

Instalación en macOS

Si aún no tiene PowerShell, instale PowerShell en macOS.
Instale coreutils:
```
brew install coreutils
```
Descargue el archivo ZIP más reciente para el kit de herramientas de pruebas y extráigalo.
Inicie PowerShell.
```
pwsh
```
Navegue hasta la carpeta en la que extrajo el kit de herramientas de pruebas. Dentro de esa carpeta, vaya a la carpeta arm-ttk.
Si la directiva de ejecución bloquea los scripts de Internet, debe desbloquear los archivos de script. Asegúrese de que se encuentra en la carpeta arm-ttk.
```
Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File
```
Importe el módulo.
```
Import-Module ./arm-ttk.psd1
```
Para ejecutar las pruebas, use el siguiente comando:
```
Test-AzTemplate -TemplatePath /path/to/template
```

Formato de resultado

Las pruebas que se superan se muestran en color verde y precedidas de [+] .

Las pruebas con errores se muestran en color rojo y precedidas de [-] .

Las pruebas con una advertencia se muestran en color amarillo y precedidas de [?].

Vista de resultados de la prueba.

Los resultados de texto son:

deploymentTemplate
[+] adminUsername Should Not Be A Literal (6 ms)
[+] apiVersions Should Be Recent In Reference Functions (9 ms)
[-] apiVersions Should Be Recent (6 ms)
    Api versions must be the latest or under 2 years old (730 days) - API version 2019-06-01 of
    Microsoft.Storage/storageAccounts is 760 days old
    Valid Api Versions:
    2021-04-01
    2021-02-01
    2021-01-01
    2020-08-01-preview

[+] artifacts parameter (4 ms)
[+] CommandToExecute Must Use ProtectedSettings For Secrets (9 ms)
[+] DependsOn Best Practices (5 ms)
[+] Deployment Resources Must Not Be Debug (6 ms)
[+] DeploymentTemplate Must Not Contain Hardcoded Uri (4 ms)
[?] DeploymentTemplate Schema Is Correct (6 ms)
    Template is using schema version '2015-01-01' which has been deprecated and is no longer
    maintained.

Parámetros de prueba

Cuando se proporciona el parámetro -TemplatePath, el kit de herramientas busca en esa carpeta una plantilla con el nombre azuredeploy.json o maintemplate.json. Primero se prueba esta plantilla y, a continuación, se prueban todas las demás plantillas de la carpeta y sus subcarpetas. Las otras plantillas se prueban como plantillas vinculadas. Si la ruta de acceso incluye un archivo llamado createUiDefinition.json, se ejecutan las pruebas que corresponden a la definición de la interfaz de usuario. Las pruebas también se ejecutan para los archivos de parámetros y todos los archivos JSON de la carpeta.

Test-AzTemplate -TemplatePath $TemplateFolder

Para probar un archivo de esa carpeta, agregue el parámetro -File. Sin embargo, la carpeta debe tener una plantilla principal llamada azuredeploy.json o maintemplate.json.

Test-AzTemplate -TemplatePath $TemplateFolder -File cdn.json

De forma predeterminada, se ejecutan todas las pruebas. Para especificar pruebas individuales que se van a ejecutar, use el parámetro -Test y proporcione el nombre de la prueba. Para los nombres de prueba, consulte las plantillas de ARM, los archivos de parámetros, createUiDefinition.json y todos los archivos.

Test-AzTemplate -TemplatePath $TemplateFolder -Test "Resources Should Have Location"

Personalización de las pruebas

Puede personalizar las pruebas predeterminadas o crear sus propias pruebas. Si quiere eliminar permanentemente una prueba, elimine el archivo .test.ps1 de la carpeta.

El kit de herramientas tiene cuatro carpetas que contienen las pruebas predeterminadas que se ejecutan para tipos de archivo específicos:

Plantillas de ARM: \arm-ttk\testcases\deploymentTemplate
Archivos de parámetros: \arm-ttk\testcases\deploymentParameters
createUiDefinition.json: \arm-ttk\testcases\CreateUIDefinition
Todos los archivos: \arm-ttk\testcases\AllFiles

Adición de una prueba personalizada

Para agregar su propia prueba, cree un archivo con la convención de nomenclatura: Your-Custom-Test-Name.test.ps1.

La prueba puede obtener la plantilla como un parámetro de objeto o un parámetro de cadena. Normalmente se usa uno u otro, pero se pueden usar ambos.

Use el parámetro de objeto cuando necesite obtener una sección de la plantilla y recorrer en iteración sus propiedades. Una prueba que usa el parámetro de objeto tiene el siguiente formato:

param(
  [Parameter(Mandatory=$true,Position=0)]
  [PSObject]
  $TemplateObject
)

# Implement test logic that evaluates parts of the template.
# Output error with: Write-Error -Message

El objeto de la plantilla tiene las siguientes propiedades:

$schema
contentVersion
parameters
variables
resources
outputs

Por ejemplo, puede obtener la colección de parámetros con $TemplateObject.parameters.

Use el parámetro de cadena cuando necesite realizar una operación de cadena en toda la plantilla. Una prueba que usa el parámetro de cadena tiene el siguiente formato:

param(
  [Parameter(Mandatory)]
  [string]
  $TemplateText
)

# Implement test logic that performs string operations.
# Output error with: Write-Error -Message

Por ejemplo, puede ejecutar una expresión regular del parámetro de cadena para ver si se utiliza una sintaxis específica.

Para más información sobre la implementación de la prueba, examine las otras pruebas de esa carpeta.

Integración con Azure Pipelines

Puede agregar el kit de herramientas para pruebas a su canalización de Azure. Con una canalización, puede ejecutar la prueba cada vez que se actualiza la plantilla o ejecutarla como parte del proceso de implementación.

La forma más fácil de agregar el kit de herramientas para pruebas a la canalización es con extensiones de terceros. Están disponibles las dos extensiones siguientes:

O bien, puede implementar sus propias tareas. En el ejemplo siguiente se muestra cómo descargar el kit de herramientas para pruebas.

{
  "environment": {},
  "enabled": true,
  "continueOnError": false,
  "alwaysRun": false,
  "displayName": "Download TTK",
  "timeoutInMinutes": 0,
  "condition": "succeeded()",
  "task": {
    "id": "e213ff0f-5d5c-4791-802d-52ea3e7be1f1",
    "versionSpec": "2.*",
    "definitionType": "task"
  },
  "inputs": {
    "targetType": "inline",
    "filePath": "",
    "arguments": "",
    "script": "New-Item '$(ttk.folder)' -ItemType Directory\nInvoke-WebRequest -uri '$(ttk.uri)' -OutFile \"$(ttk.folder)/$(ttk.asset.filename)\" -Verbose\nGet-ChildItem '$(ttk.folder)' -Recurse\n\nWrite-Host \"Expanding files...\"\nExpand-Archive -Path '$(ttk.folder)/*.zip' -DestinationPath '$(ttk.folder)' -Verbose\n\nWrite-Host \"Expanded files found:\"\nGet-ChildItem '$(ttk.folder)' -Recurse",
    "errorActionPreference": "stop",
    "failOnStderr": "false",
    "ignoreLASTEXITCODE": "false",
    "pwsh": "true",
    "workingDirectory": ""
  }
}

En el ejemplo siguiente se muestra cómo ejecutar las pruebas.

{
  "environment": {},
  "enabled": true,
  "continueOnError": true,
  "alwaysRun": false,
  "displayName": "Run Best Practices Tests",
  "timeoutInMinutes": 0,
  "condition": "succeeded()",
  "task": {
    "id": "e213ff0f-5d5c-4791-802d-52ea3e7be1f1",
    "versionSpec": "2.*",
    "definitionType": "task"
  },
  "inputs": {
    "targetType": "inline",
    "filePath": "",
    "arguments": "",
    "script": "Import-Module $(ttk.folder)/arm-ttk/arm-ttk.psd1 -Verbose\n$testOutput = @(Test-AzTemplate -TemplatePath \"$(sample.folder)\")\n$testOutput\n\nif ($testOutput | ? {$_.Errors }) {\n   exit 1 \n} else {\n    Write-Host \"##vso[task.setvariable variable=result.best.practice]$true\"\n    exit 0\n} \n",
    "errorActionPreference": "continue",
    "failOnStderr": "true",
    "ignoreLASTEXITCODE": "false",
    "pwsh": "true",
    "workingDirectory": ""
  }
}

Pasos siguientes

Para más información sobre las pruebas de plantillas, consulte Casos de prueba para plantillas de ARM.
Para probar los archivos de parámetros, consulte Casos de prueba para archivos de parámetros.
Para las pruebas de createUiDefinition, consulte Casos de prueba para createUiDefinition.json.
Para información sobre las pruebas de todos los archivos, vea Casos de prueba para todos los archivos.
Para un módulo de Microsoft Learn que abarque el uso del kit de herramientas de pruebas, consulte Validación de recursos de Azure mediante el kit de herramientas para pruebas de plantillas de ARM.