Skip to content
MaxoPerf MaxoPerf docs

JMeter JMX on MaxoPerf

Apache JMeter is a long-established Java load-testing engine with decades of community tooling. MaxoPerf runs JMeter scenarios natively. Upload your .jmx file and mark it as the entrypoint. MaxoPerf detects the JMeter engine, validates the plan, and sends it to the runner fleet. You do not need Java installed locally.

Upload and run your own scripts.

Before you start

Section titled “Before you start”
  • You need an existing .jmx test plan, or you create one in JMeter Desktop and export it.
  • Read Upload test files. The Files tab workflow is the same for JMX as for any other engine.
  • Read By engine: decision guide if you are not sure JMeter is the right choice.

How MaxoPerf handles JMX files

Section titled “How MaxoPerf handles JMX files”

When you upload a .jmx file and mark it as the entrypoint, MaxoPerf:

  1. Parses the JMX as XML and validates it is well-formed with at least one Thread Group.
  2. Sets the test’s engine kind to JMeter and shows the JMeter badge.
  3. At run time, synthesizes a Taurus execution.yaml that points at your JMX. Your plan runs exactly as authored, with MaxoPerf’s reporting overlay added.

You can also wrap a JMX in a Taurus YAML. Then you set concurrency, ramp-up, and hold-for in the YAML instead of the Thread Group settings:

execution:
  - executor: jmeter
    concurrency: 100
    ramp-up: 1m
    hold-for: 10m
    scenario: checkout


scenarios:
  checkout:
    script: checkout.jmx    # uploaded as a Test asset

In this layout, the .yml is the entrypoint, and checkout.jmx is a test asset. The Taurus YAML’s concurrency / ramp-up / hold-for override the Thread Group settings in the JMX. You can change the load profile without editing the JMX.

Upload and run a JMX file

Section titled “Upload and run a JMX file”
  1. In JMeter Desktop, author your test plan and save it as my-plan.jmx.
  2. Open the test in MaxoPerf console → Files tab.
  3. Upload my-plan.jmx. MaxoPerf auto-marks it as Entrypoint and sets the engine kind to JMeter.
  4. Upload any CSV data files, response scripts, or BeanShell/JSR223 script files the JMX references. Mark them as Test asset and keep the filenames the JMX uses (relative paths only).
  5. Save. The console shows a green validation badge when the JMX is valid and all referenced assets are present.
  6. Click Run.

JMX best practices for MaxoPerf

Section titled “JMX best practices for MaxoPerf”

Remove listener elements

Section titled “Remove listener elements”

JMX plans built in JMeter Desktop often contain listeners (View Results Tree, Aggregate Report, etc.). Listeners slow down runs and produce output MaxoPerf does not use. MaxoPerf collects metrics from the Taurus reporting overlay instead. Remove listeners before you upload.

<!-- Remove elements like these before upload -->
<!-- <ResultCollector guiclass="ViewResultsFullVisualizer" ... -->
<!-- <ResultCollector guiclass="SummaryReport" ... -->

Use CSV Config Elements for data

Section titled “Use CSV Config Elements for data”

If your test plan uses a CSV Data Set Config element, upload the CSV file as a Test asset with the same filename the JMX references:

<CSVDataSet guiclass="TestBeanGUI" ...>
  <stringProp name="filename">users.csv</stringProp>   <!-- must match uploaded test asset name -->
  ...
</CSVDataSet>

Avoid absolute paths

Section titled “Avoid absolute paths”

JMX files that reference local absolute paths (e.g. /Users/name/tests/data.csv) fail in MaxoPerf, because the runner does not have that path. Use relative filenames that match your uploaded test assets.

Thread Group concurrency vs. Taurus concurrency

Section titled “Thread Group concurrency vs. Taurus concurrency”

If you upload a bare JMX (not wrapped in a Taurus YAML), MaxoPerf synthesizes an execution.yaml that preserves your Thread Group’s thread count and duration. To override them for a specific run, wrap the JMX in a Taurus YAML and set concurrency / hold-for there.

Validating a JMX

Section titled “Validating a JMX”

MaxoPerf validates every JMX upload for:

  • Well-formed XML (no truncation, no DTD injection).
  • At least one Thread Group element.
  • No absolute paths in CSV Data Set Config elements.

If validation fails, the console shows an error badge with the reason. Fix the issue in JMeter Desktop, re-export the JMX, and re-upload.

Reading JMeter results in MaxoPerf

Section titled “Reading JMeter results in MaxoPerf”

After a JMeter run finishes, MaxoPerf shows the same result view as any other engine:

  • Overview tab: throughput (RPS), p50/p95/p99 latency, error rate.
  • Errors tab: errors grouped by type, with captured request and response samples.
  • Runners tab: runner status and per-runner VU distribution.

JMeter’s per-sampler breakdown (if you used named HTTP Request samplers) appears in the per-endpoint latency panel on the Overview tab.

Do / don’t

Section titled “Do / don’t”

Do:

  • Remove JMeter listeners before you upload. They add overhead and MaxoPerf ignores their output.
  • Use relative filenames for all CSV, JAR, and script references inside the JMX.
  • Run your JMX locally in JMeter Desktop before you upload it. This catches YAML/XML issues early.

Don’t:

  • Upload JMX files with absolute paths. They fail with a missing_reference validation error.
  • Use JMeter GUI scripts (.side Selenium recorder exports) as JMX replacements. They are different formats.
  • Rely on JMeter plugins that are not in the MaxoPerf JMeter image. Ask support which plugins it includes.

Where to go next

Section titled “Where to go next”