Skip to content
Martkos IT Docs

Quick Start

This guide takes you from zero to a linted script and a report you can gate a build on — the two most common entry points into the ecosystem.

Prerequisites

Section titled “Prerequisites”
  • Docker and Docker Compose installed
  • A JMeter (.jmx), k6 (.js), or Gatling (.scala) script to work with

Option A — Lint a script

Section titled “Option A — Lint a script”

  1. Install perf-lint

    Terminal window
    pip install perf-lint-tool

  2. Run the linter against your script

    Terminal window
    # JMeter
    perf-lint check my-test.jmx
    

    # k6
    perf-lint check my-script.js
    

    # Gatling
    perf-lint check MySimulation.scala

  3. Review the output

    my-test.jmx
      line 12  WARN  [JMX001] Thread group uses "Forever" loop — set a finite loop count
      line 34  ERROR [JMX010] HTTP sampler missing explicit timeout — default is infinite
      line 67  INFO  [JMX042] Consider using CSV Data Set Config for parameterisation
    

    3 problems (1 error, 1 warning, 1 info)

    Errors block CI pipelines. Warnings and info are advisory.

  4. Fix and re-run

    Terminal window
    perf-lint check my-test.jmx --fix

    The --fix flag auto-corrects rules that support it.

Option B — Report on a run, and catch a regression

Section titled “Option B — Report on a run, and catch a regression”

  1. Get perf-reporting

    Download it from martkos-it.co.uk/store/perf-reporting-dashboard. The desktop app is free with a licence key emailed on registration; the CLI ships inside that download and needs a Pro or Enterprise key.

  2. Run your test and export results

    Terminal window
    # k6 — export JSON results
    k6 run --out json=results.json my-script.js
    

    # JMeter — export CSV (default listener output)
    jmeter -n -t my-test.jmx -l results.jtl
    

    # Gatling — results are in simulation.log by default

  3. Generate a report

    Terminal window
    perf-report -i results.json --tool k6 -o report.json --summary

    Add -f html for something to send to a human, and --fail-on-error to make the command exit non-zero when the run contained errors.

  4. Compare against previous runs

    Terminal window
    perf-report compare --baseline 'baselines/*.json' --current report.json

    This compares runs rather than samples: each report contributes one value per metric, so the question is whether this build’s p95 is worse than recent builds’ p95. Around eight baseline runs are needed before the verdict means much, and the tool says so rather than pretending otherwise.

Option C — Full pipeline in CI

Section titled “Option C — Full pipeline in CI”

See the CI/CD Integration guide for a complete GitHub Actions pipeline that:

  1. Generates test data with dummydatagenpro
  2. Lints the script with perf-lint
  3. Runs the test with the perf-containers Docker image
  4. Generates a report with perf-reporting
  5. Fails the build on statistical regression (perf-report compare)

Next Steps

Section titled “Next Steps”