|
| 1 | +--- |
| 2 | +title: Configure JMeter user properties |
| 3 | +titleSuffix: Azure Load Testing |
| 4 | +description: Learn how to use JMeter user properties with Azure Load Testing. |
| 5 | +services: load-testing |
| 6 | +ms.service: load-testing |
| 7 | +ms.author: nicktrog |
| 8 | +author: ntrogh |
| 9 | +ms.date: 04/27/2022 |
| 10 | +ms.topic: how-to |
| 11 | +zone_pivot_groups: load-testing-config |
| 12 | +--- |
| 13 | + |
| 14 | +# Use JMeter user properties with Azure Load Testing Preview |
| 15 | + |
| 16 | +In this article, learn how to configure and use Apache JMeter user properties with Azure Load Testing Preview. With user properties, you can make your test configurable by keeping test settings outside of the JMeter test script. Use cases for user properties include: |
| 17 | + |
| 18 | +- You want to use the JMX test script in multiple deployment environments with different application endpoints. |
| 19 | +- Your test script needs to accommodate multiple load patterns, such as smoke tests, peak load, or soak tests. |
| 20 | +- You want to override default JMeter behavior by configuring JMeter settings, such as the results file format. |
| 21 | + |
| 22 | +Azure Load Testing supports the standard [Apache JMeter properties](https://jmeter.apache.org/usermanual/test_plan.html#properties) and enables you to upload a user properties file. You can configure one user properties file per load test. |
| 23 | + |
| 24 | +Alternately, you can also [use environment variables and secrets in Azure Load Testing](./how-to-parameterize-load-tests.md) to make your tests configurable. |
| 25 | + |
| 26 | +> [!IMPORTANT] |
| 27 | +> Azure Load Testing is currently in preview. For legal terms that apply to Azure features that are in beta, in preview, or otherwise not yet released into general availability, see the [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/). |
| 28 | +
|
| 29 | +## Prerequisites |
| 30 | + |
| 31 | +- An Azure account with an active subscription. If you don't have an Azure subscription, create a [free account](https://azure.microsoft.com/free/?WT.mc_id=A261C142F) before you begin. |
| 32 | +- An Azure Load Testing resource. If you need to create an Azure Load Testing resource, see the quickstart [Create and run a load test](./quickstart-create-and-run-load-test.md). |
| 33 | + |
| 34 | +## Add a JMeter user properties file to your load test |
| 35 | + |
| 36 | +You can define user properties for your JMeter test script by uploading a *.properties* file to the load test. The following code snippet shows an example user properties file: |
| 37 | + |
| 38 | +```properties |
| 39 | +# peak-load.properties |
| 40 | +# User properties for testing peak load |
| 41 | +threadCount=250 |
| 42 | +rampUpSeconds=30 |
| 43 | +durationSeconds=600 |
| 44 | + |
| 45 | +# Override default JMeter properties |
| 46 | +jmeter.save.saveservice.thread_name=false |
| 47 | +``` |
| 48 | + |
| 49 | +Azure Load Testing supports using a single properties file per load test. Additional property files are ignored. |
| 50 | + |
| 51 | +You can also specify [JMeter configuration settings](https://jmeter.apache.org/usermanual/properties_reference.html) in user properties file to override default behavior. For example, you can modify any of the `jmeter.save.saveservice.*` settings to configure the JMeter results file. |
| 52 | + |
| 53 | +::: zone pivot="experience-azp" |
| 54 | + |
| 55 | +To add a user properties file to your load test by using the Azure portal, follow these steps: |
| 56 | + |
| 57 | +1. In the [Azure portal](https://portal.azure.com), go to your Azure Load Testing resource. |
| 58 | +1. On the left pane, select **Tests** to view the list of tests. |
| 59 | +1. Select your test from the list by selecting the checkbox, and then select **Edit**. Alternately, select **Create test** to create a new load test. |
| 60 | +1. Select the **Test plan** tab. |
| 61 | +1. Select the properties file from your computer, and then select **Upload** to upload the file to Azure. |
| 62 | + |
| 63 | + :::image type="content" source="media/how-to-configure-user-properties/edit-test-upload-properties.png" alt-text="Screenshot that shows the steps to upload a user properties file on the Test plan tab on the Edit test pane."::: |
| 64 | + |
| 65 | +1. Select **User properties** in the **File relevance** dropdown list. |
| 66 | + |
| 67 | + :::image type="content" source="media/how-to-configure-user-properties/edit-test-upload-properties-file-relevance.png" alt-text="Screenshot that highlights the file relevance dropdown for a user properties file on the Test plan pane."::: |
| 68 | + |
| 69 | + You can select only one file as a user properties file for a load test. |
| 70 | + |
| 71 | +1. Select **Apply** to modify the test, or **Review + create**, and then **Create** to create the new test. |
| 72 | +::: zone-end |
| 73 | + |
| 74 | +::: zone pivot="experience-pipelines,experience-ghactions" |
| 75 | + |
| 76 | +If you run a load test within your CI/CD workflow, you add the user properties file to the source control repository. You then specify this properties file in the [load test configuration YAML file](./reference-test-config-yaml.md). |
| 77 | + |
| 78 | +For more information about running a load test in a CI/CD workflow, see the [Automated regression testing tutorial](./tutorial-cicd-azure-pipelines.md). |
| 79 | + |
| 80 | +To add a user properties file to your load test, follow these steps: |
| 81 | + |
| 82 | +1. Add the *.properties* file to the source control repository. |
| 83 | +1. Open your YAML test configuration file in Visual Studio Code or your editor of choice. |
| 84 | +1. Specify the *.properties* file in the `properties.userPropertyFile` setting. |
| 85 | + ```yaml |
| 86 | + testName: MyTest |
| 87 | + testPlan: SampleApp.jmx |
| 88 | + description: Configure a load test with peak load properties. |
| 89 | + engineInstances: 1 |
| 90 | + properties: |
| 91 | + userPropertyFile: peak-load.properties |
| 92 | + configurationFiles: |
| 93 | + - input-data.csv |
| 94 | + ``` |
| 95 | +
|
| 96 | + > [!NOTE] |
| 97 | + > If you store the properties file in a separate folder, specify the file with a relative path name. For more information, see the [Test configuration YAML syntax](./reference-test-config-yaml.md). |
| 98 | +
|
| 99 | +1. Save the YAML configuration file and commit it to your source control repository. |
| 100 | +
|
| 101 | + The next time the CI/CD workflow runs, it will use the updated configuration. |
| 102 | +
|
| 103 | +::: zone-end |
| 104 | +
|
| 105 | +## Reference properties in JMeter |
| 106 | +
|
| 107 | +Azure Load Testing supports the built-in Apache JMeter functionality to reference user properties in your JMeter test script (JMX). You can use the [**__property**](https://jmeter.apache.org/usermanual/functions.html#__property) or [**__P**](https://jmeter.apache.org/usermanual/functions.html#__P) functions to retrieve the property values from the property file you uploaded previously. |
| 108 | +
|
| 109 | +The following code snippet shows an example of how to reference properties in a JMX file: |
| 110 | +
|
| 111 | + ```xml |
| 112 | + <ThreadGroup guiclass="ThreadGroupGui" testclass="ThreadGroup" testname="Test home page" enabled="true"> |
| 113 | + <stringProp name="ThreadGroup.on_sample_error">continue</stringProp> |
| 114 | + <elementProp name="ThreadGroup.main_controller" elementType="LoopController" guiclass="LoopControlPanel" testclass="LoopController" testname="Loop Controller" enabled="true"> |
| 115 | + <boolProp name="LoopController.continue_forever">false</boolProp> |
| 116 | + <intProp name="LoopController.loops">-1</intProp> |
| 117 | + </elementProp> |
| 118 | + <stringProp name="ThreadGroup.num_threads">${__P(threadCount,1)}</stringProp> |
| 119 | + <stringProp name="ThreadGroup.ramp_time">${__P(rampUpSeconds,1)}</stringProp> |
| 120 | + <boolProp name="ThreadGroup.scheduler">true</boolProp> |
| 121 | + <stringProp name="ThreadGroup.duration">${__P(durationSeconds,30)}</stringProp> |
| 122 | + <stringProp name="ThreadGroup.delay"></stringProp> |
| 123 | + <boolProp name="ThreadGroup.same_user_on_next_iteration">true</boolProp> |
| 124 | + </ThreadGroup> |
| 125 | + ``` |
| 126 | + |
| 127 | +Alternately, you also specify properties in the JMeter user interface. The following image shows how to use properties to configure a JMeter thread group: |
| 128 | + |
| 129 | + :::image type="content" source="media/how-to-configure-user-properties/jmeter-user-properties.png" alt-text="Screenshot that shows how to reference user properties in the JMeter user interface."::: |
| 130 | + |
| 131 | +You can [download the JMeter errors logs](./how-to-find-download-logs.md) to troubleshoot errors during the load test. |
| 132 | + |
| 133 | +## Next steps |
| 134 | + |
| 135 | +- Learn more about [parameterizing a load test by using environment variables and secrets](./how-to-parameterize-load-tests.md). |
| 136 | +- Learn more about [troubleshooting load test execution errors](./how-to-find-download-logs.md). |
0 commit comments