Read data from a CSV file in JMeter with Azure Load Testing Preview

In this article, you'll learn how to read data from a comma-separated value (CSV) file in JMeter with Azure Load Testing Preview. You can use the JMeter CSV Data Set Config element in your test script.

Use data from an external CSV file to make your JMeter test script configurable. For example, you might invoke an API for each entry in a customers CSV file.

In this article, you learn how to:

  • Configure your JMeter script to read the CSV file.
  • Add the CSV file to your load test.
  • Optionally, split the CSV file evenly across all test engine instances.

Important

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.

Prerequisites

  • An Azure account with an active subscription. If you don't have an Azure subscription, create a free account before you begin.
  • An Azure Load Testing resource. To create a Load Testing resource, see Create and run a load test.
  • An Apache JMeter test script (JMX).
  • (Optional) Apache JMeter GUI to author your test script. To install Apache JMeter, see Apache JMeter Getting Started.

Configure your JMeter script

In this section, you'll configure your Apache JMeter script to reference the external CSV file. You'll use a CSV Data Set Config element to read data from a CSV file.

Azure Load Testing uploads the JMX file and all related files in a single folder. When you reference an external file in your JMeter script, verify that your only use the file name and remove any file path references.

To edit your JMeter script by using the Apache JMeter GUI:

  1. Select the CSV Data Set Config element in your test plan.

  2. Update the Filename information and remove any file path reference.

  3. Optionally, enter the CSV field names in Variable Names, when you split the CSV file across test engines.

    Azure Load Testing doesn't preserve the header row when splitting your CSV file. Provide the variable names in the CSV Data Set Config element instead of using a header row.

    Screenshot that shows the JMeter UI to configure a C S V Data Set Config element.

  4. Repeat the previous steps for every CSV Data Set Config element in the script.

  5. Save the JMeter script and add it to your test plan.

To edit your JMeter script by using Visual Studio Code or your editor of preference:

  1. Open the JMX file in Visual Studio Code.

  2. For each CSVDataSet:

    1. Update the filename element and remove any file path reference.

    2. Add the CSV field names as a comma-separated list in variableNames.

    <CSVDataSet guiclass="TestBeanGUI" testclass="CSVDataSet" testname="Search parameters" enabled="true">
      <stringProp name="delimiter">,</stringProp>
      <stringProp name="fileEncoding">UTF-8</stringProp>
      <stringProp name="filename">search-params.csv</stringProp>
      <boolProp name="ignoreFirstLine">true</boolProp>
      <boolProp name="quotedData">false</boolProp>
      <boolProp name="recycle">true</boolProp>
      <stringProp name="shareMode">shareMode.all</stringProp>
      <boolProp name="stopThread">false</boolProp>
      <stringProp name="variableNames">username,query</stringProp>
    </CSVDataSet>
    
  3. Save the JMeter script and add it to your test plan.

Add a CSV file to your load test

When you reference an external file in your JMeter script, upload this file to your load test. When the load starts, Azure Load Testing copies all files to a single folder on each of the test engines instances.

Important

Azure Load Testing doesn't preserve the header row when splitting your CSV file. Before you add the CSV file to the load test, remove the header row from the file.

To add a CSV file to your load test by using the Azure portal:

  1. In the Azure portal, go to your Azure Load Testing resource.

  2. On the left pane, select Tests to view a list of tests.

    Tip

    To limit the number of tests to display in the list, you can use the search box and the Time range filter.

  3. Select your test from the list by selecting the checkbox, and then select Edit.

    Screenshot that shows the list of load tests and the 'Edit' button.

  4. On the Edit test page, select the Test plan tab.

  5. Select the CSV file from your computer, and then select Upload to upload the file to Azure.

    Screenshot of the Test plan tab on the Edit test pane.

  6. Select Apply to modify the test and to use the new configuration when you rerun it.

If you run a load test within your CI/CD workflow, you can add a CSV file to the test configuration YAML file. For more information about running a load test in a CI/CD workflow, see the Automated regression testing tutorial.

To add a CSV file to your load test:

  1. Commit the CSV file to the source control repository that contains the JMX file and YAML test configuration file.

  2. Open your YAML test configuration file in Visual Studio Code or your editor of choice.

  3. Add the CSV file to the configurationFiles setting. You can use wildcards or specify multiple individual files.

    testName: MyTest
    testPlan: SampleApp.jmx
    description: Run a load test for my sample web app
    engineInstances: 1
    configurationFiles:
    - search-params.csv
    

    Note

    If you store the CSV file in a separate folder, specify the file with a relative path name. For more information, see the Test configuration YAML syntax.

  4. Save the YAML configuration file and commit it to your source control repository.

    The next time the CI/CD workflow runs, it will use the updated configuration.

Split CSV input data across test engines

By default, Azure Load Testing copies and processes your input files unmodified across all test engine instances. Azure Load Testing enables you to split the CSV input data evenly across all engine instances. If you have multiple CSV files, each file will be split evenly.

For example, if you have a large customer CSV input file, and the load test runs on 10 parallel test engines, then each instance will process 1/10th of the customers.

Important

Azure Load Testing doesn't preserve the header row when splitting your CSV file.

  1. Configure your JMeter script to use variable names when reading the CSV file.
  2. Remove the header row from the CSV file before you add it to the load test.

To configure your load test to split input CSV files:

  1. Go to the Test plan page for your load test.

  2. Select Split CSV evenly between Test engines.

    Screenshot that shows the checkbox to enable splitting input C S V files when configuring a test in the Azure portal.

  3. Select Apply to confirm the configuration changes.

    The next time you run the test, Azure Load Testing splits and processes the CSV file evenly across the test engines.

  1. Open your YAML test configuration file in Visual Studio Code or your editor of choice.

  2. Add the splitAllCSVs setting and set its value to True.

    testName: MyTest
    testPlan: SampleApp.jmx
    description: Run a load test for my sample web app
    engineInstances: 1
    configurationFiles:
      - customers.csv
    splitAllCSVs: True
    
  3. Save the YAML configuration file and commit it to your source control repository.

    The next time you run the test, Azure Load Testing splits and processes the CSV file evenly across the test engines.

Next steps