https://github.com/rcasia/neotest-java
Neotest adapter for Java.
https://github.com/rcasia/neotest-java
java junit lua neotest neovim
Last synced: 12 days ago
JSON representation
Neotest adapter for Java.
- Host: GitHub
- URL: https://github.com/rcasia/neotest-java
- Owner: rcasia
- License: mit
- Created: 2022-11-22T00:20:21.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2026-03-29T15:43:13.000Z (about 1 month ago)
- Last Synced: 2026-03-29T18:17:00.347Z (about 1 month ago)
- Topics: java, junit, lua, neotest, neovim
- Language: Lua
- Homepage:
- Size: 1.02 MB
- Stars: 67
- Watchers: 3
- Forks: 40
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Roadmap: ROADMAP.md
Awesome Lists containing this project
README
neotest-java
Neotest adapter for Java, using JUnit.
## ⭐ Features
- ✅ **Maven & Gradle** - Full support for both build systems (Groovy & Kotlin DSL)
- ✅ **Multi-module projects** - Automatic detection and per-module test execution
- ✅ **JUnit 5 (Jupiter)** - Support for `@Test`, `@ParameterizedTest`, `@TestFactory`, nested tests
- ✅ **JUnit Platform 1.10.x & 6.x** - Compatible with both legacy and latest versions
- ✅ **Spring Framework** - Auto-loads `application.yml`, `application-test.yml`, and `.properties` files
- ✅ **Debugging with nvim-dap** - Full integration with breakpoints, JDWP, and DAP REPL output
- ✅ **Incremental compilation** - Smart compilation of only changed files via nvim-jdtls
- ✅ **Automatic classpath management** - Retrieves runtime and test classpaths from LSP
- ✅ **JUnit JAR management** - Automatic installation, version detection, and upgrade prompts
- ✅ **Health check** - Comprehensive diagnostics with `:checkhealth neotest-java`
> Check [ROADMAP.md](./ROADMAP.md) to see what's coming!
## 📦 Installation
### Prerequisites
- **Neovim 0.10.4+**
- **nvim-treesitter** with Java parser: `:TSInstall java`
- **A JDTLS-based Java LSP** — either [nvim-jdtls](https://github.com/mfussenegger/nvim-jdtls) or [nvim-java](https://github.com/nvim-java/nvim-java) (both are compatible)
- **nvim-dap** - For debugging support (optional)
### Setup with [lazy.nvim](https://github.com/folke/lazy.nvim)
#### Using nvim-jdtls
```lua
return {
{
"rcasia/neotest-java",
ft = "java",
dependencies = {
"mfussenegger/nvim-jdtls",
"mfussenegger/nvim-dap", -- for debugging (optional)
"rcarriga/nvim-dap-ui", -- recommended
"theHamsta/nvim-dap-virtual-text", -- recommended
},
},
{
"nvim-neotest/neotest",
dependencies = {
"nvim-neotest/nvim-nio",
"nvim-lua/plenary.nvim",
"nvim-treesitter/nvim-treesitter",
},
config = function()
require("neotest").setup({
adapters = {
require("neotest-java")({
-- Optional configuration here
}),
},
})
end,
},
}
```
#### Using nvim-java
[nvim-java](https://github.com/nvim-java/nvim-java) is fully compatible — neotest-java communicates with the LSP through the standard `vim.lsp.Client` API and does not depend directly on nvim-jdtls.
```lua
return {
{
"rcasia/neotest-java",
ft = "java",
dependencies = {
"mfussenegger/nvim-dap", -- for debugging (optional)
},
},
-- nvim-java handles JDTLS setup separately
{ "nvim-java/nvim-java" },
{
"nvim-neotest/neotest",
dependencies = {
"nvim-neotest/nvim-nio",
"nvim-lua/plenary.nvim",
"nvim-treesitter/nvim-treesitter",
},
config = function()
require("neotest").setup({
adapters = {
require("neotest-java")({
-- Optional configuration here
}),
},
})
end,
},
}
```
### JUnit JAR Installation
After setting up the plugin, run:
```vim
:NeotestJava setup
```
This will automatically download and verify the JUnit Platform Console Standalone JAR from [Maven Central](https://mvnrepository.com/artifact/org.junit.platform/junit-platform-console-standalone) with SHA-256 checksum verification.
> [!TIP]
> The plugin will detect if you have an older JUnit version installed and prompt you to upgrade to the latest version.
## ⚙️ Configuration
All configuration options are optional. Pass them to `require("neotest-java")({})`:
```lua
require("neotest").setup({
adapters = {
require("neotest-java")({
junit_jar = nil, -- default: auto-detected
jvm_args = { "-Xmx512m" }, -- custom JVM arguments
incremental_build = true, -- recompile only changed files
disable_update_notifications = false, -- show JUnit update prompts
test_classname_patterns = { "^.*Tests?$", "^.*IT$", "^.*Spec$" },
}),
},
})
```
### Options
| Option | Type | Default | Description |
|-------------------------------|------------|------------------------------------------------------------|-----------------------------------------------------------------------------|
| `junit_jar` | `string?` | `stdpath("data")/neotest-java/junit-*.jar` | Path to JUnit Platform Console Standalone JAR |
| `jvm_args` | `string[]` | `{}` | Additional JVM arguments for test execution |
| `incremental_build` | `boolean` | `true` | Enable incremental compilation (recompile only changed files) |
| `disable_update_notifications`| `boolean` | `false` | Disable notifications about available JUnit updates |
| `test_classname_patterns` | `string[]` | `{"^.*Tests?$", "^.*IT$", "^.*Spec$"}` | Regex patterns for test class names (classes must match at least one pattern)|
## ⚠️ Troubleshooting
### Spring Tests Failing with "parameter name information not available"
If you're running Spring tests that use reflection (e.g., `@MockBean`, `@WebMvcTest`) and encounter errors like:
```
java.lang.IllegalArgumentException: Name for argument of type [int] not specified,
and parameter name information not available via reflection.
Ensure that the compiler uses the '-parameters' flag.
```
**Solution:** Configure the JDTLS compiler to preserve parameter names in bytecode by adding the following to your project's `.settings/org.eclipse.jdt.core.prefs` file:
```properties
org.eclipse.jdt.core.compiler.codegen.methodParameters=generate
```
If the `.settings` directory doesn't exist, create it in your project root:
```bash
mkdir -p .settings
echo "org.eclipse.jdt.core.compiler.codegen.methodParameters=generate" > .settings/org.eclipse.jdt.core.prefs
```
After adding this setting, restart your LSP server (`:LspRestart`) and run your tests again.
## 🤝 Contributing
Contributions are welcome! Please feel free to:
- 🐛 Report bugs and issues
- 💡 Suggest new features or improvements
- 🔧 Submit pull requests
See [CONTRIBUTING.md](https://github.com/rcasia/neotest-java/blob/main/CONTRIBUTING.md) for guidelines.
### Running Tests
The project includes both unit tests and end-to-end (E2E) tests:
```bash
# Run unit tests
make test
# Run E2E tests (requires Java and JAVA_HOME)
make test-e2e
# Run all tests
make test && make test-e2e
```
**E2E Test Requirements:**
- Java JDK (11 or higher)
- `JAVA_HOME` environment variable set
- Maven wrapper is included in the test fixture
See [tests/e2e/README.md](tests/e2e/README.md) for detailed E2E test documentation.
## ✨ Acknowledgements
Thanks to all contributors who have helped improve this project!
[](https://github.com/rcasia/neotest-java/graphs/contributors)