JMeter tests

This topic provides an overview of running Apache JMeter tests from the Controller.

JMeter tests overview

Apache JMeter is an open source load testing tool for analyzing and measuring the performance of a variety of services, with a focus on web applications. If you work with Apache JMeter tests, LoadRunner Professional provides the ability to also run the tests through Controller.

By including JMeter (.jmx) scripts in your scenarios, you can run one or more JMeter tests side-by-side with any other protocol scripts, giving you a single entry point for executing your performance tests.

JMeter scripts can be run on both Windows and Linux load generators. The Docker installations of Windows and Linux also support JMeter scripts.

You can manipulate the number of running Vusers, and the ramp-up configuration for your JMeter scripts, from within Controller. Thread properties defined for JMeter Thread Group (such as "Number of Threads", "Ramp-up period", and "Loop Count") in the .jmx file are ignored. You configure JMeter Vusers the same way as you would configure Vusers of other protocol types.

Measurements can be viewed online and offline (in Controller and Analysis), using the data points from the JMeter tests.

Back to top

Transactions in JMeter scripts

JMeter tests work with threads, JMeter's equivalent of Vusers, and thread groups. LoadRunner Professional differs in the way it handles JMeter tests:

  • If your JMeter script contains multiple thread groups, you are prompted to split them into multiple scripts, where each script contains only one thread group. The ThreadGroup name is not included in the transaction name. Therefore, we recommend that you do not define transactions with the same name in different thread groups.
  • Only transaction names under the TransactionController section in the .jmx file are shown in the results.
  • Transaction names should not include a dot.

Back to top

Prerequisites for JMeter tests

Note the following guidelines before creating a scenario with a JMeter script.

JMeter installation package

  • To install JMeter automatically on a load generator machine, select the Install JMeter after installation option during OneLG setup.

  • To install JMeter manually on a load generator, LoadRunner Professional machine, or any other component, unzip the JMeter package:

    • Default package location: <LR_installdir>\integrations\jmeter.zip

    • Unzip package to the same folder: <LR_installdir>\integrations\jmeter

General

  • Make sure you have JRE installed on the load generator machine. For supported versions, see the JRE support matrix in the Virtual User Generator Help Center (select the relevant version).

  • If your JMeter script was developed with plugins, make sure to add them to the JMeter installation (in the <LR_InstallDir>\integrations\jmeter\lib\ext folder), to allow the script to run properly.

  • For Linux load generators, it is recommended that you set the JAVA_HOME environment variable to point to the Java JRE folder.
  • You can customize your JMeter configuration with some additional properties Java attributes. For details, see the Apache JMeter documentation. To customize the configuration, add the attributes to the Additional parameters box in the runtime settings, as described below.

  • Before running LoadRunner Professional scenarios, check that your JMeter test can run with the JMeter installation on the load generator machine.

Tip: We recommend that you use dedicated load generator machines for running JMeter test scripts. Running tests from the Controller, using the localhost load generator, may cause instability.

Data files

The JMeter script can reference parameter files in .csv format. To reference .csv files, make sure that:

  • They are in the same folder (and not a subfolder) as the .jmx file.
  • The reference path in the JMeter script correctly points to the .csv files.

Controller finds these files, and sends them to the load generator for execution.

JAR files

If your JMeter test includes .jar file dependencies, make sure to save them in the following locations:

  • .jar files containing classes added by the user must be saved in a folder named lib located in the same folder as the .jmx file: <.jmx file location> > lib
  • .jar files containing JMeter plugins must be saved in a subfolder of the lib folder, named ext: <.jmx file location> > lib > ext.

You must save the files in this folder structure so that when the scenario is run, Controller finds the files and copies them to the load generator for execution.

Back to top

Add a JMeter test to a scenario

This task describes how to create a scenario containing a JMeter script, and define its runtime settings.

To create a JMeter scenario:

  1. Make sure the load generator machines are set up to run JMeter tests, as described in Prerequisites for JMeter tests.
  2. On the main Controller toolbar, click the Create a new scenario button .
  3. In the New Scenario dialog box, click Add Scripts.
  4. From the Script Type dropdown, select JMeter Scripts. Click Browse and select a JMeter script (.jmx file).
  5. Click OK in the New Scenario dialog box. A scenario containing the JMeter script opens in the Design tab.

  6. Configure runtime settings if you need to:

    • Specify a custom JRE path

    • Customize the behavior of the JVM

    • Set the iteration pacing

    To open the runtime settings, right-click the script name, and select Runtime Settings or click the Runtime Settings toolbar button .

    1. In the JMeter settings section, specify the details such as the custom JRE path or a string in the Additional parameters section. For example, -Xms512m.

    2. In the Pacing section, specify the pacing details. For details, see Iterations and run logic in the Virtual User Generator Help Center (select the relevant version).

  7. Specify the schedule as you would for any other LoadRunner protocol. For details, see Define a schedule for the scenario.

  8. In the Run tab, click the Start Scenario button to begin running the scenario.
  9. To add Vusers during the scenario run, click Run/Stop Vusers and modify the number.

View JMeter test results

You can monitor JMeter test execution through the following standard Controller graphs:

  • Running Vusers
  • Transaction Response Time
  • Total Transaction per Second (Passed)
  • Transactions per Second (Passed)
  • HTTP Responses per Second
  • Hits per Second
  • Throughput - Whole Load Test

For details about viewing these graphs, see View and customize online monitor graphs.

Back to top

Known issues and troubleshooting

The following are known issues for JMeter tests running in LoadRunner Professional:

  • Only Web HTTP samplers are supported for JMeter tests.
  • The Setup ThreadGroup runs once only.
  • The TearDown ThreadGroup is not supported.
  • Loops defined in the .jmx file are ignored—they only run once.

  • Iteration numbers may not be correct in the Controller.

  • Network Virtualization is not supported for JMeter tests.

Troubleshooting JMeter tests

The following table provides several reasons and suggested solutions for run failures:

Error message Resolution
Cannot find the JMX file 'C:\jmeter_tests\test.jmx'.

Possible causes:

  • The file is not present in this location.
  • Not enough disk space to clone the file.
JMeter requires JRE 8+. Check the Java settings in the runtime settings or the JAVA_HOME environment variable. Check that Java is properly installed on the machine and that the JAVA_HOME variable is set correctly.

Failed to create pipes for JMeter.

Possible cause: Not enough available system resources.

JMeter internal error: "…"

Check the contents of the JMeter internal error as included in the message.
In jmeter.log file: CannotResolveClassException: ... Possible cause: The .jar file dependency containing the class is missing or is not saved in the correct location. For details, see JAR files.

Back to top

See also: