Usar o kit de ferramentas de teste de modelo do ARM

O kit de ferramentas de teste do modelo do ARM (modelo do Azure Resource Manager) verifica se o modelo usa as práticas recomendadas. Quando seu modelo não está em conformidade com as práticas recomendadas, ele retorna uma lista de avisos com as alterações sugeridas. Usando o kit de ferramentas de teste, você pode aprender como evitar problemas comuns no desenvolvimento de modelos. Este artigo descreve como executar o kit de ferramentas de teste e como adicionar ou remover testes. Para obter mais informações sobre como executar testes ou como executar um teste específico, confira Parâmetros de teste.

O kit de ferramentas é um conjunto de scripts do PowerShell que podem ser executados a partir de um comando no PowerShell ou na CLI. Esses testes são recomendações, mas não requisitos. Você pode decidir quais testes são relevantes para seus objetivos e personalizar quais testes são executados.

O kit de ferramentas contém quatro conjuntos de testes:

Observação

O kit de ferramentas de teste só está disponível para modelos do ARM. Para validar arquivos Bicep, use o linter Bicep.

Recursos de treinamento

Para saber mais sobre o kit de ferramentas de teste de modelo do ARM e obter diretrizes práticas, consulte Validar recursos do Azure usando o Kit de Ferramentas de Teste de Modelo do ARM.

Instalar no Windows

Se você ainda não tiver o PowerShell, instale o PowerShell no Windows.
Faça download do arquivo .zip mais recente para o kit de ferramentas de teste e extraia-o.
Inicie o PowerShell.
Navegue até a pasta onde você extraiu o kit de ferramentas de teste. Dentro dessa pasta, navegue até a pasta arm-ttk .
Se sua política de execução bloquear scripts da Internet, você precisará desbloquear os arquivos de script. Verifique se você está na pasta arm-ttk .
```
Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File
```
Importe o módulo.
```
Import-Module .\arm-ttk.psd1
```

Para executar os testes, use o seguinte comando:

Test-AzTemplate -TemplatePath \path\to\template

Instalar no Linux

Se você ainda não tiver o PowerShell, instale o PowerShell no Linux.
Faça download do arquivo .zip mais recente para o kit de ferramentas de teste e extraia-o.
Inicie o PowerShell.
```
pwsh
```
Navegue até a pasta onde você extraiu o kit de ferramentas de teste. Dentro dessa pasta, navegue até a pasta arm-ttk .
Se sua política de execução bloquear scripts da Internet, você precisará desbloquear os arquivos de script. Verifique se você está na pasta arm-ttk .
```
Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File
```
Importe o módulo.
```
Import-Module ./arm-ttk.psd1
```

Para executar os testes, use o seguinte comando:

Test-AzTemplate -TemplatePath /path/to/template

Instalar no macOS

Se você ainda não tiver o PowerShell, instale o PowerShell no macOS.
Instale coreutils:
```
brew install coreutils
```
Faça download do arquivo .zip mais recente para o kit de ferramentas de teste e extraia-o.
Inicie o PowerShell.
```
pwsh
```
Navegue até a pasta onde você extraiu o kit de ferramentas de teste. Dentro dessa pasta, navegue até a pasta arm-ttk .
Se sua política de execução bloquear scripts da Internet, você precisará desbloquear os arquivos de script. Verifique se você está na pasta arm-ttk .
```
Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File
```
Importe o módulo.
```
Import-Module ./arm-ttk.psd1
```

Para executar os testes, use o seguinte comando:

Test-AzTemplate -TemplatePath /path/to/template

Formato de resultado

Os testes aprovados são exibidos em verde e precedidos por [+].

Os testes que falham são exibidos em vermelho e precedidos por [-].

Os testes com um aviso são exibidos em amarelo e precedidos por [?].

Captura de tela dos resultados do teste em cores diferentes para aprovação, reprovação e aviso.

Os resultados do texto são:

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 teste

Quando você fornece o -TemplatePath parâmetro, o kit de ferramentas procura nessa pasta um modelo chamado azuredeploy.json ou maintemplate.json. Ele testa esse modelo primeiro e, em seguida, testa todos os outros modelos na pasta e suas subpastas. Os outros modelos são testados como modelos vinculados. Se o caminho incluir um arquivo chamado createUiDefinition.json, ele executará testes relevantes para a definição da interface do usuário. Os testes também são executados para arquivos de parâmetro e todos os arquivos JSON na pasta.

Test-AzTemplate -TemplatePath $TemplateFolder

Para testar um arquivo nessa pasta, adicione o -File parâmetro. No entanto, a pasta ainda deve ter um modelo principal chamado azuredeploy.json ou maintemplate.json.

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

Por padrão, todos os testes são executados. Para especificar testes individuais a serem executados, use o -Test parâmetro e forneça o nome do teste. Para obter os nomes de teste, consulte Modelos do ARM, arquivos de parâmetro, createUiDefinition.jsone todos os arquivos.

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

Personalizar testes

Você pode personalizar os testes padrão ou criar seus próprios testes. Se você quiser remover permanentemente um teste, exclua o arquivo .test.ps1 da pasta.

O kit de ferramentas tem quatro pastas que contêm os testes padrão que são executados para tipos de arquivo específicos:

Modelos do ARM: \arm-ttk\testcases\deploymentTemplate
Arquivos de parâmetro: \arm-ttk\testcases\deploymentParameters
createUiDefinition.json: \arm-ttk\testcases\CreateUIDefinition
Todos os arquivos: \arm-ttk\testcases\AllFiles

Adicionar um teste personalizado

Para adicionar seu próprio teste, crie um arquivo com a convenção de nomenclatura: Your-Custom-Test-Name.test.ps1.

O teste pode obter o modelo como um parâmetro de objeto ou um parâmetro de cadeia de caracteres. Normalmente, você usa um ou outro, mas pode usar os dois.

Use o parâmetro object quando precisar obter uma seção do modelo e iterar por meio de suas propriedades. Um teste que usa o parâmetro object tem o seguinte formato:

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

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

O objeto de modelo tem as seguintes propriedades:

$schema
contentVersion
parameters
variables
resources
outputs

Por exemplo, você pode obter a coleção de parâmetros com $TemplateObject.parameters.

Use o parâmetro string quando precisar fazer uma operação de string em todo o modelo. Um teste que usa o parâmetro string tem o seguinte formato:

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

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

Por exemplo, você pode executar uma expressão regular do parâmetro string para ver se uma sintaxe específica é usada.

Para saber mais sobre como implementar o teste, examine os outros testes nessa pasta.

Validar modelos para o Azure Marketplace

Para publicar uma oferta no Azure Marketplace, use o kit de ferramentas de teste para validar os modelos. Quando seus modelos passarem nos testes de validação, o Azure Marketplace aprovará sua oferta mais rapidamente. Se eles falharem nos testes, a oferta falhará na certificação.

Importante

Os testes do Marketplace foram adicionados em julho de 2022. Atualize seu módulo se você tiver uma versão anterior.

Executar os testes em seu ambiente

Depois de instalar o kit de ferramentas e importar o módulo, execute o seguinte cmdlet para testar seu pacote:

Test-AzMarketplacePackage -TemplatePath "Path to the unzipped package folder"

Interpretar os resultados

Os testes retornam resultados em duas seções. A primeira seção inclui os testes que são obrigatórios. Os resultados desses testes são exibidos na seção de resumo.

Importante

Você deve corrigir todos os resultados em vermelho antes que a oferta do Marketplace seja aceita. Recomendamos corrigir todos os resultados que retornam em amarelo.

Os resultados do texto são:

Validating nestedtemplates\AzDashboard.json
    [+] adminUsername Should Not Be A Literal (210 ms)
    [+] artifacts parameter (3 ms)
    [+] CommandToExecute Must Use ProtectedSettings For Secrets (201 ms)
    [+] Deployment Resources Must Not Be Debug (160 ms)
    [+] DeploymentTemplate Must Not Contain Hardcoded Url (13 ms)
    [+] Location Should Not Be Hardcoded (31 ms)
    [+] Min and Max Value Are Numbers (4 ms)
    [+] Outputs Must Not Contain Secrets (9 ms)
    [+] Password params must be secure (3 ms)
    [+] Resources Should Have Location (2 ms)
    [+] Resources Should Not Be Ambiguous (2 ms)
    [+] Secure Params In Nested Deployments (205 ms)
    [+] Secure String Parameters Cannot Have Default (3 ms)
    [+] URIs Should Be Properly Constructed (190 ms)
    [+] Variables Must Be Referenced (9 ms)
    [+] Virtual Machines Should Not Be Preview (173 ms)
    [+] VM Size Should Be A Parameter (165 ms)
Pass : 99
Fail : 3
Total: 102
Validating StartStopV2mkpl_1.0.09302021\anothertemplate.json
    [?] Parameters Must Be Referenced (86 ms)
        Unreferenced parameter: resourceGroupName
        Unreferenced parameter: ___location
        Unreferenced parameter: azureFunctionAppName
        Unreferenced parameter: applicationInsightsName
        Unreferenced parameter: applicationInsightsRegion

A seção abaixo da seção de resumo inclui falhas de teste que podem ser interpretadas como avisos. Corrigir as falhas é opcional, mas altamente recomendado. As falhas geralmente apontam para problemas comuns que causam falhas quando um cliente instala sua oferta.

Para corrigir seus testes, siga o caso de teste aplicável a você:

Submeter a oferta

Depois de fazer as correções necessárias, execute novamente o kit de ferramentas de teste. Antes de enviar sua oferta para o Azure Marketplace, verifique se você não tem falhas.

Integrar com o Azure Pipelines

Você pode adicionar o kit de ferramentas de teste ao Azure Pipeline. Com um pipeline, você pode executar o teste sempre que o modelo for atualizado ou executá-lo como parte do processo de implantação.

A maneira mais fácil de adicionar o kit de ferramentas de teste ao pipeline é com extensões de terceiros. As duas extensões a seguir estão disponíveis:

Ou você pode implementar suas próprias tarefas. O exemplo a seguir mostra como baixar o kit de ferramentas de teste.

Para o pipeline de lançamento:

{
  "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": ""
  }
}

Para definição de YAML de pipeline:

- pwsh: |
   New-Item '$(ttk.folder)' -ItemType Directory
   Invoke-WebRequest -uri '$(ttk.uri)' -OutFile "$(ttk.folder)/$(ttk.asset.filename)" -Verbose
   Get-ChildItem '$(ttk.folder)' -Recurse
   
   Write-Host "Expanding files..."
   Expand-Archive -Path '$(ttk.folder)/*.zip' -DestinationPath '$(ttk.folder)' -Verbose
   
   Write-Host "Expanded files found:"
   Get-ChildItem '$(ttk.folder)' -Recurse
  displayName: 'Download TTK'

O próximo exemplo mostra como executar os testes.

Para o pipeline de lançamento:

{
  "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": ""
  }
}

Para definição de YAML de pipeline:

- pwsh: |
   Import-Module $(ttk.folder)/arm-ttk/arm-ttk.psd1 -Verbose
   $testOutput = @(Test-AzTemplate -TemplatePath "$(sample.folder)")
   $testOutput
   
   if ($testOutput | ? {$_.Errors }) {
      exit 1 
   } else {
       Write-Host "##vso[task.setvariable variable=result.best.practice]$true"
       exit 0
   } 
  errorActionPreference: continue
  failOnStderr: true
  displayName: 'Run Best Practices Tests'
  continueOnError: true

Próximas etapas

Para saber mais sobre os testes de modelo, consulte Casos de teste para modelos do ARM.
Para testar arquivos de parâmetros, confira Casos de teste para arquivos de parâmetros.
Para testes createUiDefinition, confira Casos de teste para createUiDefinition.json.
Para saber mais sobre testes para todos os arquivos, consulte Casos de teste para todos os arquivos.
Para obter um módulo do Learn que aborda o uso do kit de ferramentas de teste, consulte Validar recursos do Azure usando o Kit de Ferramentas de Teste de Modelo do ARM.

Comentários

Esta página foi útil?

Last updated on 2025-07-23

Compartilhar via

Usar o kit de ferramentas de teste de modelo do ARM

Recursos de treinamento

Instalar no Windows

Instalar no Linux

Instalar no macOS

Formato de resultado

Parâmetros de teste

Personalizar testes

Adicionar um teste personalizado

Validar modelos para o Azure Marketplace

Executar os testes em seu ambiente

Interpretar os resultados

Submeter a oferta

Integrar com o Azure Pipelines

Próximas etapas

Comentários

Recursos adicionais