{"id":20763939,"url":"https://github.com/qualersoft/jmeter-gradle-plugin","last_synced_at":"2026-03-07T02:33:45.501Z","repository":{"id":37032521,"uuid":"399952915","full_name":"qualersoft/jmeter-gradle-plugin","owner":"qualersoft","description":"Gradle plugin for using JMeter","archived":false,"fork":false,"pushed_at":"2026-03-04T13:05:52.000Z","size":2540,"stargazers_count":13,"open_issues_count":14,"forks_count":2,"subscribers_count":1,"default_branch":"develop","last_synced_at":"2026-03-04T20:42:35.542Z","etag":null,"topics":["gradle-plugin","jmeter"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/qualersoft.png","metadata":{"files":{"readme":"README.adoc","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.adoc","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.adoc","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.adoc","support":null,"governance":"GOVERNANCE.adoc","roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-08-25T20:46:05.000Z","updated_at":"2025-08-11T18:37:14.000Z","dependencies_parsed_at":"2023-10-05T06:28:17.468Z","dependency_job_id":"18016d9c-013a-4b8b-9c04-4ad8a72d187b","html_url":"https://github.com/qualersoft/jmeter-gradle-plugin","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/qualersoft/jmeter-gradle-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qualersoft%2Fjmeter-gradle-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qualersoft%2Fjmeter-gradle-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qualersoft%2Fjmeter-gradle-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qualersoft%2Fjmeter-gradle-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/qualersoft","download_url":"https://codeload.github.com/qualersoft/jmeter-gradle-plugin/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qualersoft%2Fjmeter-gradle-plugin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30206070,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-06T19:07:06.838Z","status":"online","status_checked_at":"2026-03-07T02:00:06.765Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gradle-plugin","jmeter"],"created_at":"2024-11-17T10:48:03.701Z","updated_at":"2026-03-07T02:33:45.479Z","avatar_url":"https://github.com/qualersoft.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"= jmeter-gradle-plugin\nifdef::env-github[]\n:tip-caption: :bulb:\n:note-caption: :information_source:\n:important-caption: :heavy_exclamation_mark:\n:caution-caption: :fire:\n:warning-caption: :warning:\nendif::[]\nifndef::env-github[]\n:icons: font\nendif::[]\n:jm_base:       https://jmeter.apache.org\n:jm_tm:         {jm_base}/[JMeter(TM),window=_blank]\n:jm_doc_base:   {jm_base}/usermanual\n:jm_remoteing:  {jm_doc_base}/remote-test.html\n:jm_cli:        {jm_doc_base}/get-started.html#override\n:gh_rp:         https://github.com/qualersoft/jmeter-gradle-plugin\n:toc: preamble\n\n[cols=\"1,~\", frame=none, grid=none]\n|===\n|General\n|image:https://img.shields.io/github/license/qualersoft/jmeter-gradle-plugin[link={gh_rp}/blob/main/LICENSE]\nimage:https://app.fossa.com/api/projects/custom%2B17788%2Fgithub.com%2Fqualersoft%2Fjmeter-gradle-plugin.svg?type=shield[link=https://app.fossa.com/projects/custom%2B17788%2Fjmeter-gradle-plugin/refs/branch/main/]\n\n|Main\n|image:{gh_rp}/actions/workflows/build.yml/badge.svg?branch=main[title=\"Build status\", link={gh_rp}/blob/main/.github/workflows/build.yml]\nimage:https://www.codefactor.io/repository/github/qualersoft/jmeter-gradle-plugin/badge/main[title=\"Code quality\", link=https://www.codefactor.io/repository/github/qualersoft/jmeter-gradle-plugin/overview/main]\nimage:https://codecov.io/gh/qualersoft/jmeter-gradle-plugin/branch/main/graph/badge.svg?token=Z5CT2C7LN1[title=\"Coverage\", link=https://app.codecov.io/gh/qualersoft/jmeter-gradle-plugin/branch/main]\n\n|Develop\n|image:{gh_rp}/actions/workflows/build.yml/badge.svg?branch=develop[title=\"Build status\", link={gh_rp}/blob/develop/.github/workflows/build.yml]\nimage:https://www.codefactor.io/repository/github/qualersoft/jmeter-gradle-plugin/badge/develop[title=\"Code quality\", link=https://www.codefactor.io/repository/github/qualersoft/jmeter-gradle-plugin/overview/develop]\nimage:https://codecov.io/gh/qualersoft/jmeter-gradle-plugin/branch/develop/graph/badge.svg?token=XT7QzRFkaj[title=\"Coverage\", link=https://app.codecov.io/gh/qualersoft/jmeter-gradle-plugin/branch/develop]\n|===\n\nGradle plugin to integrate {jm_tm} tests into the gradle ecosystem. +\nThis plugin arose from the need of a simple to start, but easy to customize plugin. The current available plugins are either hardwired to older {jm_tm} version or configuration is not so well documented.\n\n== Usage\n=== Applying the plugin\n.Kotlin DSL\n[%collapsible%open]\n====\n[source,kotlin]\n----\nplugins {\n  id(\"de.qualersoft.jmeter\") version \"\u003clatest\u003e\"\n}\n----\n====\n\n.Groovy DSL\n[%collapsible]\n====\n[source,groovy]\n----\nplugins {\n  id 'de.qualersoft.jmeter' version '\u003clatest\u003e'\n}\n----\n====\n\n=== Customization\nThe easiest way to customize the plugin is via its `jmeter` extension. +\nThe extension offers the following properties\n[source,kotlin]\n----\njmeter {\n  systemPropertyFiles // \u003c.\u003e\n  systemProperties // \u003c.\u003e\n  mainPropertyFile // \u003c.\u003e\n  additionalPropertyFiles // \u003c.\u003e\n  jmeterProperties // \u003c.\u003e\n  customReportTemplate // \u003c.\u003e\n  globalPropertiesFile // \u003c.\u003e\n  globalProperties // \u003c.\u003e\n\n  proxxScheme // \u003c.\u003e\n  proxyHost // \u003c.\u003e\n  proxyPort // \u003c.\u003e\n  nonProxyHosts // \u003c.\u003e\n\n  logConfig // \u003c.\u003e\n  logOutputFile // \u003c.\u003e\n\n  jmxRootDir // \u003c.\u003e\n  resultDir // \u003c.\u003e\n  reportDir // \u003c.\u003e\n  maxHeap // \u003c.\u003e\n  jvmArgs //\u003c.\u003e\n\n  enableRemoteExecution // \u003c.\u003e\n  exitRemoteServers // \u003c.\u003e\n}\n----\n[%collapsible]\n====\n\u003c.\u003e Additional system property file(s).\n\u003c.\u003e Define additional system properties.\n\u003c.\u003e The jmeter property file to use.\n\u003c.\u003e Additional JMeter property file(s).\n\u003c.\u003e Define additional JMeter properties.\n\u003c.\u003e Path to a custom report-template folder used by report generator.\n\u003c.\u003e Path to a JMeter property file which will be sent to all servers.\n\u003c.\u003e Properties which will be sent to remote servers.\n\u003c.\u003e Scheme of the proxy (e.g. for non-http).\n\u003c.\u003e Proxy server hostname or ip address.\n\u003c.\u003e Proxy server port.\n\u003c.\u003e Non-proxy hosts (e.g *.apache.org).\n\u003c.\u003e Custom log configuration file (currently log4j2) +\nDefaults to bundled configuration.\n\u003c.\u003e File where jmeter log will be written to. +\nDefaults to \u003cbuildDir\u003e/logs/jmeter.log\n\u003c.\u003e Used to search for jmx files. +\nDefaults to src/test/jmeter\n\u003c.\u003e Directory to which the jtl-files will be written. +\nDefaults to \u003cbuildDir\u003e/test-results/jmeter\n\u003c.\u003e Root directory where to put the reports +\nDefaults to \u003cbuildDir\u003e/reports/jmeter\n\u003c.\u003e [Optional] Specifies the maximum heap size the JVM process will start with.\n\u003c.\u003e [Optional] additional JVM arguments that will be passed to the jvm directly.\n\u003c.\u003e [Optional] tells {jm_tm} to run the tests on the configured remote-servers (see {jm_remoteing}[remoting]) +\nDefaults to `false`.\n\u003c.\u003e [Optional] Flag to exit remote servers at the end of the test. Only effective iff `enableRemoteExecution` is `true`. +\nDefaults to `false`.\n====\nThese configurations will be applied to all tasks (where appropriate) and can be overridden or extended on a per task base.\n\n== Quickstarter\n[IMPORTANT,title=Important]\nTo use the quickstarter you must have gradle installed and available on your path\n\n=== Running a jmeter-test\n1. In a folder of your choice (referred to as `root`), execute:\n+\n[source,shell script]\n----\nroot\u003e gradle init --dsl kotlin --type basic\n----\nThis brings up the setup. We are going to create a `basic` project and using `Kotlin` as build script DSL.\n2. Create the following folder structure (gradle stuff from 1. left out)\n+\n[source]\n----\nroot\n├── src\n│   └── test\n│       └── jmeter\n│           └── Test.jmx \u003c.\u003e\n└── build.gradle.kts \u003c.\u003e\n----\n\u003c1\u003e default folder for jmx-files is `src/test/jmeter` +\nYou can copy the `Test.jmx` from link:./src/functionalTest/resources[functional test resources]\n\u003c2\u003e build.gradle.kts is generated by gradle; we need it in next step.\n3. Put the following into `build.gradle.kts`\n+\n[source,kotlin]\n----\nimport de.qualersoft.jmeter.gradleplugin.task.* // \u003c.\u003e\n\nplugins {\n  id(\"de.qualersoft.jmeter\") version \"\u003clatest\u003e\" // \u003c.\u003e\n}\n\nrepositories {\n  mavenCentral() // \u003c.\u003e\n}\n\ntasks {\n  register\u003cJMeterRunTask\u003e(\"runJMeter\") { // \u003c.\u003e\n    jmxFile.set(\"Test.jmx\") // \u003c.\u003e\n  }\n}\n----\n\u003c1\u003e Import `task` package. (to save some typing later on 😋)\n\u003c2\u003e Apply the plugin. (Don't forget to correct the version 😉)\n\u003c3\u003e We need a repository to retrieve jmeter-library. `mavenCentral` should work in almost any case.\n\u003c4\u003e Register a run-task and give it a name (if we wouldn't had imported the `task` package in (1), we would have to use the full qualified path)\n\u003c5\u003e Configure the task to use our test.jmx file under `src/test/jmeter`\n4. Run it by opening a cli of your choice in `root`\n+\n[source, shell script]\n----\nroot\u003e ./gradlew runJMeter\n----\n+\n[source, shell script,title=Output]\n----\n...\nStarting standalone test @ Sat Sep 04 18:53:51 CEST 2021 (1630774431340)\nWaiting for possible Shutdown/StopTestNow/HeapDump/ThreadDump message on port 4445\nWarning: Nashorn engine is planned to be removed from a future JDK release\nsummary =     30 in 00:00:03 =   10,0/s Avg:   206 Min:   108 Max:   345 Err:     2 (6,67%)\nTidying up ...    @ Sat Sep 04 18:53:55 CEST 2021 (1630774435185)\n... end of run\n\nBUILD SUCCESSFUL in 15s\n1 actionable task: 1 executed\n----\n\n👏 Congratulations, you've run your first jmeter script with this plugin. +\n🎉 4 steps, that's it. Simple, wasn't it?\n\n=== Generating a report\nAfter you've run your first jmeter script successfully, you might want to have a report showing some nice charts and stats.\n\nNo problem, just:\n\n1. add the following to your `build.gradel.kts` s `task` section\n+\n[source,kotlin]\n----\ntasks {\n  register\u003cJMeterRunTask\u003e(\"runJMeter\") {\n    jmxFile.set(\"Test.jmx\")\n  }\n\n  register\u003cJMeterReportTask\u003e(\"jmeterReport\") { // \u003c.\u003e\n    jmxFile.set(\"Test.jmx\") // \u003c.\u003e\n  }\n}\n----\n\u003c1\u003e registering a `JMeterReportTask` task (remember the include? Now it pays off 😊)\n\u003c2\u003e by pointing it to our `jmx` file the plugin knows where to find everything\n\n2. back in CLI run\n+\n[source, shell script]\n----\nroot\u003e ./gradlew jmeterReport\n----\nThis generates the report under `build/reports/jmeter/Test`\n[NOTE,title=Note]\nThe directory 'Test' is retrieved from the jmx-file's name.\n\n🎉 Voila, just 2 steps to get a report.\n\nRemark that to generate a report, you have to execute the `runJMeter` task before. There are two ways you can get it in one rush.\n\n1. Declare a `dependsOn` in report task\n+\n[source,kotlin]\n----\nregister\u003cJMeterReportTask\u003e(\"jmeterReport\") {\n  jmxFile.set(\"Test.jmx\")\n  dependsOn(\"runJMeter\")\n}\n----\nif you now execute `jmeterReport`, `runJMeter` get executed first if required\n2. Or let the 'run' task always generate a report with `generateReport` flag\n+\n[source,kotlin]\n----\nregister\u003cJMeterRunTask\u003e(\"runTest\") {\n  jmxFile.set(\"Test.jmx\")\n  generateReport = true\n}\n----\n[TIP,title=Tip]\nIf you are going to rerun the task without cleaning outputs you will get an error because the report already exists. In such cases just enable the `deleteResults` property\n\n=== Want to modify the jmx-Script with jmeter UI?\nNo problem, just add the following task to your build-script\n[source,kotlin]\n----\ntasks {\n  register\u003cJMeterGuiTask\u003e(\"edit\") {\n    jmxFile.set(\"Test.jmx\")\n  }\n}\n----\nAnd back to CLI\n[source,shell script]\n----\nroot\u003e ./gradlew edit\n----\nAs an alternative, if you don't want to clutter your tasks-section, you can use the `jmeter`-extension\n[source,kotlin]\n----\njmeter {\n  withGuiTask(\"edit\") {\n    jmxFile.set(\"Test.jmx\")\n  }\n}\n----\n\n== Cli arguments\nAll tasks also provide some of their properties through cli-arguments. +\nTo see what arguments are supported by a task simply run\n[source,shell script]\n----\nroot\u003e ./gradlew help --task \u003ctaskName\u003e \u003c.\u003e\n----\n\u003c1\u003e with \u003ctaskName\u003e being a JMeter*Task defined in your build script. E.g. our 'runTest' task from above.\n\n== Configure jmeter\nAs mentioned in the preamble, this plugin is designed to be as flexible as possible. +\nBy that, the used jmeter runner artifact as well as plugins or libraries aren't hardwired but can be configured.\n\n=== Configure the runner\nYou can easily configure not only the version but also its coordinates. All this can be done through the `jmeter.tool` property.\n[source,kotlin]\n----\njmeter {\n  tool {\n    group // \u003c.\u003e\n    name // \u003c.\u003e\n    version // \u003c.\u003e\n    mainConfigureClosure // \u003c.\u003e\n    mainClass // \u003c.\u003e\n  }\n}\n----\n[%collapsible]\n====\n\u003c1\u003e The group-id of the jmeter-runner. +\nDefaults to 'org.apache.jmeter'.\n\u003c2\u003e The name (artifact-id) of the jmeter-runner. +\nDefaults to 'ApacheJMeter'.\n\u003c3\u003e the version of the jmeter-runner. +\nDefaults to '5.5'.\n\u003c4\u003e A closure/lambda to configure the dependency any further. +\nWill only applied if not `null` (which is the default).\n\u003c5\u003e The main class used to execute the jmeter runner. +\nDefaults to 'org.apache.jmeter.NewDriver'.\n====\n\n=== Adding plugins\nBecause the runner itself is quite useless without any plugins you can add them with the `jmeterPlugin` dependency handler\n[source,kotlin]\n----\ndependencies {\n  jmeterPlugin(\"org.jmeter:a-plugin:1.2.3\") // \u003c.\u003e\n}\n----\n\u003c1\u003e Resolves the 'a-plugin' and puts its artifact into `/lib/ext`, transitive dependencies will be put to `lib` directory.\n\n[NOTE]\n====\nPlease note the \u003c\u003cPitfalls when using jmeter-dependencies/-plugins\u003e\u003e section.\n====\n\nBy default, this plugin includes the following plugins (as they are also default plugins in a normal JMeter installation):\n====\n\"bolt\", \"components\", \"core\", \"ftp\", \"functions\", \"http\", \"java\", \"jdbc\", \"jms\", \"junit\", \"ldap\", \"mail\", \"mongodb\", \"native\", \"tcp\"\n====\n[%collapsible, title=Info]\n====\nAt the current time, these plugins are hardwired and cannot be modified. +\n(Yeah, I know, so much about flexibility... Mea culpa! 😉)\n====\n\n=== Adding support libraries\nSometimes you have quite special and reusable code that you wouldn't maintain within JMeter. Or you just want to use an existing libraries functions within JMeter. +\nTo make them available to JMeter you can use the `jmeterLibrary` dependency handler\n[source,kotlin]\n----\ndependencies {\n  jmeterLibrary(\"org.apache.commons:commons-csv:1.9.0\") // \u003c.\u003e\n}\n----\n\u003c1\u003e Resolves the 'commons-csv' artifact and puts its artifact, and all its transitive dependencies, under `/lib` directory.\n\n[NOTE]\n====\nPlease note the \u003c\u003cPitfalls when using jmeter-dependencies/-plugins\u003e\u003e section.\n====\n\n[CAUTION,title=Internal only]\n====\nWithin an IDE with autocomplete, you may also notice the `jmeterRunner` dependency handler. This is for internal use only! Please use the respective `jmeter.tool` properties to configure the runner.\n====\n\n=== Pitfalls when using jmeter-dependencies/-plugins\nSome of the jmeter dependencies or plugins, which you want to apply through `jmeterLibrary` or `jmeterPlugin` might\ndepend on 'org.apache.jmeter:bom'.\nThis dependency seems not available on any maven-repository (for further information refer to https://bz.apache.org/bugzilla/show_bug.cgi?id=64465[Issue 64465]).\nIf you are affected by this issue, you will see an error message similar to\n----\n...\n\u003e Could not resolve all dependencies for configuration ':jmeterPlugin'.\n\u003e Could not find org.apache.jmeter:bom:5.5.\nRequired by:\n    project \u003e ...\n----\nwhen executing one of the jmeter-tasks.\nAs a convenient workaround, the `jmeter-gradle-plugin` provides the `jmeter.tool.applyBomWorkaround` function.\nYou can apply it to the affected dependencies like this:\n[source,kotlin]\n----\ndependencies {\n  // in case a library is affected\n  jmeterLibrary(\"org.apache.jmeter:a-library:1.2.3\") {\n    jmeter.tool.applyBomWorkaround(this)\n  }\n\n  // or in case a plugin is affected\n  jmeterPlugin(\"org.jmeter:a-plugin:1.2.3\") {\n    jmeter.tool.applyBomWorkaround(this)\n  }\n}\n----\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqualersoft%2Fjmeter-gradle-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqualersoft%2Fjmeter-gradle-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqualersoft%2Fjmeter-gradle-plugin/lists"}