JMeter JMX on MaxoPerf

Apache JMeter is the long-established Java load-testing engine with decades of community tooling. MaxoPerf runs JMeter scenarios natively — upload your .jmx file, mark it as the entrypoint, and MaxoPerf auto-detects the JMeter engine, validates the plan, and dispatches it to the runner fleet. No local Java installation required.

Before you start

• You need an existing .jmx test plan or be ready to create one in JMeter Desktop and export it.
• Understand 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

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 pointing 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 if you want explicit control over concurrency, ramp-up, and hold-for from the YAML rather than 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 — useful for parameterizing load profiles without editing the JMX itself.

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 use the same filenames the JMX references (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

Remove listener elements

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

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

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

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

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. If you want to override these for a specific run, wrap the JMX in a Taurus YAML and set concurrency / hold-for there.

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

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.
• Log tab — sample errors with HTTP status codes and response bodies.
• 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

Do:

• Remove JMeter listeners before uploading — they add overhead without benefit.
• Use relative filenames for all CSV, JAR, and script references inside the JMX.
• Test your JMX locally with JMeter Desktop before uploading to catch YAML/XML issues early.

Don’t:

• Upload JMX files with absolute paths — they will fail with a missing_reference validation error.
• Use JMeter GUI scripts (.side Selenium recorder exports) as JMX replacements — these are different formats.
• Rely on JMeter plugins that are not in the MaxoPerf JMeter image — contact support to check plugin availability.

Where to go next

• Taurus fundamentals — wrap your JMX in a Taurus YAML for full parameter control.
• Taurus executor catalog — the jmeter executor entry with full details.
• Upload test files — Files tab how-to.
• Cookbook: CSV data-driven test — parameterize your JMX with user data from a CSV.