Basic Configuration

Basic Configuration

Add the plugin to the build section of your pom.xml (Best practice is to define the version of the Maven JMeter plugin that you want to use in either your pom.xml or a parent pom.xml):

<project>
    [...]
        <build>
            <plugins>
                <plugin>
                <groupId>com.lazerycode.jmeter</groupId>
                <artifactId>jmeter-maven-plugin</artifactId>
                <version>3.6.0</version>
                <executions>
                    <!-- Generate JMeter configuration -->
                    <execution>
                        <id>configuration</id>
                        <goals>
                            <goal>configure</goal>
                        </goals>
                    </execution>
                    <!-- Run JMeter tests -->
                    <execution>
                        <id>jmeter-tests</id>
                        <goals>
                            <goal>jmeter</goal>
                        </goals>
                    </execution>
                    <!-- Fail build on errors in test -->
                    <execution>
                        <id>jmeter-check-results</id>
                        <goals>
                            <goal>results</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
            </plugins>
        </build>
    [...]
</project>

By default, the plugin uses the default properties files supplied with JMeter. If you want to override any of these files you simply need to create a replacement in ${project.base.directory}/src/test/jmeter.

The following properties files will be used if they are found in ${project.base.directory}/src/test/jmeter:

• jmeter.properties
• saveservice.properties
• upgrade.properties
• system.properties
• user.properties
• global.properties

The plugin will copy all of the JMX test files held in the ${project.base.directory}/src/test/jmeter/ directory, as well as any sub-directories, to ${project.build.directory}/jmeter/testFiles.

Any sub-directories will be flattened and the directory path will be used to create the test filename. Tests will then be run using all of the files in ${project.build.directory}/jmeter/testFiles.

For other configuration files like log4j2.xml, use the folder ${project.base.directory}/src/test/conf.

There are many more configuration options available, see the advanced configuration section for more information.

Running on the command line

Once you have configured your POM, you will be able to run your tests. Open a terminal/command prompt and then type:

mvn clean verify

The jmeter-maven-plugin breaks the process of running JMeter tests up into multiple phases:

Maven Phase	Jmeter Maven Plugin Goal	Description
compile	configure	This will download all required dependencies and configure a local instance of JMeter in a unique directory in your target directory to run your tests.
integration-test	jmeter	This will run your tests using the locally configured instance of JMeter that was created in the Compile phase.
verify	results	This will scan the results of your test run and work out if the build should fail.

When JMeter is configured, the configuration is associated with the Execution ID. This execution ID is then supplied by the other phases to ensure we run the correctly configured instance of JMeter. Since we suggest an Execution ID of configuration in the above documentation, we default the expected Execution ID of the later phases to configuration as well.

You can change the default Execution ID, for example:

<!-- Generate JMeter configuration -->
<execution>
  <id>bananas</id>
  <goals>
    <goal>configure</goal>
  </goals>
</execution>

However, if you do this you will need to modify the configuration for your other phases so that it knows which Execution ID to use, for example:

<!-- Run JMeter tests -->
<execution>
  <id>jmeter-tests</id>
  <goals>
    <goal>jmeter</goal>
  </goals>
  <configuration>
    <selectedConfiguration>bananas</selectedConfiguration>
  </configuration>
</execution>

It is important to understand the above when trying to run a specific goal on the command line.

If you have run your tests once, but you want to run them again you do not need to run the compile phase again, you can just run the jmeter goal.

mvn jmeter:jmeter

The jmeter goal will always use the <selectedConfiguration> specified in your POM to find a specific Jmeter configuration. If you want to run the tests against a different configuration that you have already run the configuration goal for you can specify the configuration you want to use with the command:

mvn jmeter:jmeter -DselectConfiguration=configuration

Running the JMeter GUI

It is possible to run the JMeter GUI by using the following command:

mvn jmeter:configure jmeter:gui

The jmeter:gui goal uses the current Execution ID to set its selected configuration instead of the selectConfiguration property. This is because it is designed to run in isolation without any configuration in your POM.xml. Since no Execution IDs have been specified in the above example both commands will use the default Maven Execution ID of default-cli

If you want to start the GUI up using a specific configuration you can specify the associated Execution ID. If we assume that we have already run the configure goal using an Execution ID of configuration specified in our POM.xml, to load the GUI we would run the following:

mvn jmeter:gui@configuration

If you want to preload a test, you can specify it on the command line:

mvn jmeter:configure jmeter:gui -DguiTestFile=src/test/jmeter/test.jmx

If you haven't added the plugin to your project you can still invoke it (provided you have a valid pom.xml in your project) by using the following:

mvn com.lazerycode.jmeter:jmeter-maven-plugin:configure com.lazerycode.jmeter:jmeter-maven-plugin:gui