JMeter Configuration

Introduction

This guide will walk you through the steps for integration of your JMeter test plans/scripts into the performance application.

Step 1 - Copy Files

Copy all your files (test plans, data files like CSV) to the jmeter directory in the project. You can maintain any kind of sub-directory tree within the jmeter directory, just make sure they reference each other with relative file paths.

All test plans must have a .jmx extension.

You must have the Simple Data Writer listener enabled in your test plan. If this is not present or disabled, the application will show an error and refuse to run the test. You can have other listeners in your test plan, but it is recommended to disable these listeners for performance reasons.

Step 2 - Setup JMeter properties

While you can add any number of JMeter properties to your test plan, it is recommended that, at minimum, you configure the threads count in your thread group(s) as JMeter properties (instead of a fixed value).

⭐ Using a fixed value for the threads count will lead to incorrect tests when the threads count exceeds the maximum allowed threads per agent. In this case, the application will fire twice as many requests than desired, since it will issue a fixed number of requests from each load agent. If you use a property, the application auto-distributes the load.

JMeter configuration is specified using the jmeter property. You define a JMeter configuration block and in this configuration block you have access to specific properties within the jmeter property.

config.jmeter do |jmeter|
  # The jmeter property is used further...
end

The JMeter properties are accessed via the jmeter#properties property. This exposes a block element which can be used as a set of key-value pairs (a map); each key represents a JMeter property name (as defined in the test plan) and the value is the value of the property (which will be passed to JMeter at runtime).

config.jmeter do |jmeter|
  jmeter.properties do |map|
    map['ThreadGroup.num_threads'] = 10
    # ThreadGroup.num_threads is supposed to be present in the plan as ${__P(ThreadGroup.num_threads)}.
  end
end

For the configuration above, at runtime, -J"ThreadGroup.num_threads=10" will be passed to JMeter. As an aside, ThreadGroup.num_threads is just an example name, you can potentially use any name like "virtualUsers". You must ensure however to use the same name in your test plan.

The config/environment.rb is a Ruby file, so it can have Ruby code in it as well.

Hailstorm.application.config do |config|
  # This is the JMeter configuration
  config.jmeter do |jmeter|
    # default properties for all jmeter/**/*.jmx files
    jmeter.properties do |map|
      map['ThreadGroup.loops_count'] = 1
      map['ThreadGroup.num_threads'] = 10
      map['ThreadGroup.ramp_time'] = map['ThreadGroup.num_threads']
    end
  end
end

Optional Configuration

There are a number of optional configuration properties that can be useful for different needs.

JMeter Labels and Comments

If you add comments to your test plan, thread-groups and samplers, these are parsed during report generation to generate a list of scenarios.

Choose Test Plans

If you have multiple test plans, the application default behavior is to execute all plans in parallel. If you want to execute one plan at a time, or a subset of plans, you can use the jmeter#test_plans property. The plan is specified relative to the jmeter directory; specifying the .jmx file extension is not necessary.

config.jmeter do |jmeter|
  jmeter.test_plans = ["admin/inventory", "portal/shopping_cart"] # leave empty [] to load all jmeter/**/*.jmx files.
end

Specify Properties per Plan

If you have a number of test plans in your jemeter directory, you can specify properties on a per plan basis. This also allows you to override any general properties you may have setup. For example:

config.jmeter do |jmeter|
  # file specific properties - overrides default properties
  jmeter.properties(:test_plan => 'admin/inventory') do |map|
    map['ThreadGroup.num_threads'] = 20
  end
end

Specify JMeter Version

The application will use JMeter version 3.2 by default. The application supports the following JMeter versions:

• 2.4
• 2.6
• 2.7
• 3.2 (default)

If you have developed your scripts in a different (and supported!) JMeter version, you can specify the version:

config.jmeter do |jmeter|
  # add this line
  jmeter.version = "2.6"
end