Skip to content

docs: clarify Gradle test task structure in AGENTS.md #19004

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jsvd merged 2 commits into from
Apr 15, 2026
Merged

docs: clarify Gradle test task structure in AGENTS.md #19004

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2dba128
docs: clarify Gradle test task structure in AGENTS.md
andrewvc Apr 14, 2026
8a82949
More clarity
andrewvc Apr 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 15 additions & 2 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,11 +44,18 @@ Use Gradle tasks as the normal entry points from the repo root. Rake and bundle

**Test layout:** Unit specs live under **`spec/`** (root) and **`logstash-core/spec/`**. Integration and acceptance tests live under **`qa/`** (e.g. **`qa/integration`** for integration tests). Use the commands below from the repo root; the single-integration-test example uses a path under `qa/integration`.

**Test task structure:** There are two separate Gradle test tasks: `javaTests` (pure Java unit tests) and `rubyTests` (Ruby specs **and** Java tests that depend on Ruby infrastructure). The top-level `test` task excludes all classes itself and simply delegates to both, so `./gradlew test --tests ...` will silently match nothing. Always apply `--tests` to `javaTests` or `rubyTests` directly.

**`javaTests` vs `rubyTests` split:** Several Java test classes are excluded from `javaTests` and included in `rubyTests` because they load Ruby code at runtime. The exclude/include lists are in `logstash-core/build.gradle`. If `--tests` returns "No tests found for given includes", the class is likely in the other task. Examples of Java tests that live in `rubyTests`:
- `OutputDelegatorTest`, `JavaCodecDelegatorTest` — test delegators that wrap Ruby plugin instances
- `ConfigCompilerTest`, `CompiledPipelineTest`, `EventConditionTest` — test config compilation which invokes the Ruby parser
- `PluginFactoryExtTest` — tests Ruby plugin instantiation

```bash
# All unit tests (Java + Ruby)
./gradlew test

# All Java tests
# All Java tests (pure Java, no Ruby dependency)
./gradlew :logstash-core:javaTests

# Single Java test class
Expand All @@ -60,7 +67,13 @@ Use Gradle tasks as the normal entry points from the repo root. Rake and bundle
# Java tests by pattern
./gradlew :logstash-core:javaTests --tests "org.logstash.settings.*"

# All Ruby tests (core)
# WRONG — will silently run nothing because `test` excludes all classes:
# ./gradlew :logstash-core:test --tests org.logstash.TimestampTest

# Java test that depends on Ruby — must use rubyTests, not javaTests:
./gradlew :logstash-core:rubyTests --tests org.logstash.config.ir.compiler.OutputDelegatorTest

# All Ruby tests (core) — also runs the Ruby-dependent Java tests listed above
./gradlew :logstash-core:rubyTests

# Single Ruby spec file
Expand Down
Loading