ARM UI and ARM Template Testing

Within this article, the scope of “Azure Marketplace” is limited to China.

1. ARM UI Testing

In this section, we will use sample files to demonstrate how to test user interfaces.

1.1 Prerequisites

  • An Azure subscription. If you don’t have an Azure subscription, you can create a free account before you start.

  • A createUiDefinition.json file. If you don't have this file, copy the sample file (you can also refer to the Global Azure sample files) and save it locallyMarketplace-uisample.

1.2 Open the Create UI Definition Sandbox

1.3 Replace the empty definition with the contents of your createUiDefinition.json file. Select Preview.

  • If the handler value in your createUiDefinition.json file is 'Microsoft.Compute.MultiVm', please change it to 'Microsoft.Azure.CreateUIDef' and test.

1.4 The form you created is displayed. You can step through the user experience and fill in the values.

1.5 View the Test Interface

Provide values for the fields in the portal. When finished, you will see the values that have been passed to the template. After clicking "View Outputs payload", you will see the filled parameters on the right. as shown below. Save these parameters as a parameter file such as exampletemplate.parameters.json. In Section 4, you will use this parameter file to test the template deployment.

1.6 Troubleshooting Interface Issues

Some common errors you might see are:

  • The portal doesn't load your interface. Instead, it shows an icon of a cloud with tear drop. Usually, you see this icon when there's a syntax error in your file. Open the file in VS Code (or other JSON editor that has schema validation) and look for syntax errors.
  • The portal hangs at the summary screen. Usually, this interruption happens when there's a bug in the output section. For example, you may have referenced a control that does not exist.
  • A parameter in the output is empty. The parameter might be referencing a property that doesn't exist. For example, the reference to the control is valid, but the property reference isn't valid.

2. Integration Testing for ARM Templates and the createUiDefinition UI file

Method 1: Copy the template parameters in Section 1.5 into a parameter file for testing

This method is simpler. This method uses the ARM template file and createUiDefinition to test the generated parameter file. It uses these parameters to deploy the template, and validates the correctness of createUiDefinition by testing whether the parameters are correct. If your template file is called exampletemplate.json and the parameters file is called exampletemplate.parameters.json, in PowerShell, you would do the following:

New-AzureRmResourceGroup -Name ExampleResourceGroup -Location "China North"

New-AzureRmResourceGroupDeployment `
-Name ExampleDeployment `
-ResourceGroupName ExampleResourceGroup `
-TemplateFile c:\MyTemplates\exampletemplate.json `
-TemplateParameterFile c:\MyTemplates\exampletemplate.parameters.json


Test-AzureRmResourceGroupDeployment `
-ResourceGroupName ExampleResourceGroup `
-TemplateFile c:\MyTemplates\exampletemplate.parameters.json `
-storageAccountType Standard_GRS

For details, see the “Parameter Files” or “Test Template Deployment” sections in Using PowerShell to Deploy an ARM Template.

Method 2: Integrate the createUiDefinition file with the ARM Template file

After verifying your portal interface is working as expected, you can validate that your createUiDefinition file is properly integrated with your mainTemplate.json file. You can run a validation script test to test the content of your solution files, including the createUiDefinition file. The script validates the JSON syntax, checks for regex expressions on text fields, and makes sure the output values of the portal interface match the parameters of your template. For information on running this script, see Run static validation checks for templates.

Next steps


  • If you have any questions about this documentation, please submit user feedback in the Azure Marketplace.
  • You can also look for solutions in the FAQs.