From 8480b917b2466c6dbdde31d4f8fef5810c75fd95 Mon Sep 17 00:00:00 2001 From: Milamber Date: Tue, 7 Jul 2026 15:53:48 +0200 Subject: [PATCH 1/2] docs: add build & test guidance for coding agents to AGENTS.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Document the JMeter build/test essentials so any coding agent knows how to build, run, and test the project — independent of any agent framework: - core gradlew tasks (build, test, check, runGui, createDist, style) - JDK selection for build and tests via -PjdkBuildVersion / -PjdkTestVersion / -PjdkTestVendor (the test-JDK flag), with an example - dependency-checksum refresh, coverage, and RAT tasks - pointer to the CI matrix and the Error Prone job Addresses the dev@ suggestion to give agents JMeter-specific build context (e.g. how to trigger tests under a specific JDK version). Generated-by: Claude Opus 4.8 --- AGENTS.md | 45 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 8c32763d3da..254dec8057c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1 +1,46 @@ Security model: [SECURITY.md](./SECURITY.md) + +## Building and testing (for coding agents) + +JMeter builds with Gradle. Use the wrapper `./gradlew` (or `gw` from +[gdub](https://github.com/dougborg/gdub)). The full command list is in +[`gradle.md`](gradle.md), and toolchain details are in the +[Test builds](README.md#test-builds) section of `README.md`. The essentials: + +- **Build everything (incl. tests + static checks):** `./gradlew build` +- **Unit tests only:** `./gradlew test` — single module, e.g. `./gradlew :src:core:test` +- **All checks (tests, checkstyle, spotless, …):** `./gradlew check` +- **Run the GUI from source:** `./gradlew runGui` +- **Assemble a runnable dist:** `./gradlew createDist && ./bin/jmeter` +- **Format before committing:** `./gradlew style` (spotlessApply + checkstyleAll); check-only: `./gradlew spotlessCheck checkstyleAll` +- **Skip tests:** append `-x test` + +### Selecting the JDK for build and tests + +JMeter uses Gradle [toolchains](https://docs.gradle.org/current/userguide/toolchains.html), +so JDKs are found locally or auto-provisioned. The default build JDK is 17 +(artifacts target Java 8). To build or test under a specific JDK — the way CI +runs its matrix — pass build parameters: + +- `-PjdkBuildVersion=` — JDK to build with (e.g. `21`) +- `-PjdkTestVersion=` — JDK to run **tests** with; `0` means "use the current Java" +- `-PjdkTestVendor=` / `-PjdkTestImplementation=` — pin the vendor / VM implementation + +Example — run the test suite on JDK 21 (Corretto): + +```sh +./gradlew test -PjdkTestVersion=21 -PjdkTestVendor=corretto +``` + +List every available build parameter with `./gradlew parameters`. + +### Other useful tasks + +- After bumping a dependency version, refresh the expected checksums: + `./gradlew -PupdateExpectedJars check` +- Coverage report: `./gradlew jacocoTestReport -Pcoverage` +- Release Audit Tool (license-header check): `./gradlew rat` + +CI mirrors these across a JDK × vendor × OS × timezone × locale matrix (see +[`.github/workflows/main.yml`](.github/workflows/main.yml)); the Error Prone +static-analysis job runs on JDK 21. From 0b9667b5990801491f5d9443da4445ead5d79854 Mon Sep 17 00:00:00 2001 From: Milamber Date: Wed, 8 Jul 2026 16:14:24 +0200 Subject: [PATCH 2/2] docs: trim AGENTS.md build notes per review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Apply @vlsi's review on PR #2: keep only JMeter-specific, non-obvious guidance an agent doesn't already know — the --quiet flag, the "run ./gradlew --quiet classes style before handing back" instruction, and the JDK-test build parameters. Drop the generic gradlew build/test/check list, the heading suffix, and the checksums/coverage/RAT/CI section. Generated-by: Claude Opus 4.8 --- AGENTS.md | 45 ++++++++------------------------------------- 1 file changed, 8 insertions(+), 37 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 254dec8057c..565e4252f80 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,46 +1,17 @@ Security model: [SECURITY.md](./SECURITY.md) -## Building and testing (for coding agents) +## Building and testing -JMeter builds with Gradle. Use the wrapper `./gradlew` (or `gw` from -[gdub](https://github.com/dougborg/gdub)). The full command list is in -[`gradle.md`](gradle.md), and toolchain details are in the -[Test builds](README.md#test-builds) section of `README.md`. The essentials: +JMeter builds with Gradle. Use `./gradlew --quiet ...` to reduce output verbosity. -- **Build everything (incl. tests + static checks):** `./gradlew build` -- **Unit tests only:** `./gradlew test` — single module, e.g. `./gradlew :src:core:test` -- **All checks (tests, checkstyle, spotless, …):** `./gradlew check` -- **Run the GUI from source:** `./gradlew runGui` -- **Assemble a runnable dist:** `./gradlew createDist && ./bin/jmeter` -- **Format before committing:** `./gradlew style` (spotlessApply + checkstyleAll); check-only: `./gradlew spotlessCheck checkstyleAll` -- **Skip tests:** append `-x test` +After modifying Java code, before reporting the change as done (handing +control back to the user), run `./gradlew --quiet classes style` and fix any +reported issues. -### Selecting the JDK for build and tests +JMeter uses Gradle toolchains; JDKs are found locally or auto-provisioned. The +code targets JDK 17. To test under a specific JDK pass build parameters: -JMeter uses Gradle [toolchains](https://docs.gradle.org/current/userguide/toolchains.html), -so JDKs are found locally or auto-provisioned. The default build JDK is 17 -(artifacts target Java 8). To build or test under a specific JDK — the way CI -runs its matrix — pass build parameters: - -- `-PjdkBuildVersion=` — JDK to build with (e.g. `21`) - `-PjdkTestVersion=` — JDK to run **tests** with; `0` means "use the current Java" -- `-PjdkTestVendor=` / `-PjdkTestImplementation=` — pin the vendor / VM implementation - -Example — run the test suite on JDK 21 (Corretto): - -```sh -./gradlew test -PjdkTestVersion=21 -PjdkTestVendor=corretto -``` +- `-PjdkTestVendor=` / `-PjdkTestImplementation=` — pin the vendor / VM implementation (jdkTestVersion is enough for most cases) List every available build parameter with `./gradlew parameters`. - -### Other useful tasks - -- After bumping a dependency version, refresh the expected checksums: - `./gradlew -PupdateExpectedJars check` -- Coverage report: `./gradlew jacocoTestReport -Pcoverage` -- Release Audit Tool (license-header check): `./gradlew rat` - -CI mirrors these across a JDK × vendor × OS × timezone × locale matrix (see -[`.github/workflows/main.yml`](.github/workflows/main.yml)); the Error Prone -static-analysis job runs on JDK 21.