How rcasia/neotest-java works
Main Components
• Plugin/Adapter Interface: This is the entry point for Neovim integration. The file plugin/neotest-java.lua serves as the connection between Neotest and the adapter’s functionalities.
• Core Functionality: Under lua/neotest-java/core, you have modules responsible for handling test discovery, file checking, parsing test positions, and building test results. For example, components like dir_filter.lua, file_checker.lua, positions_discoverer.lua, result_builder.lua, and root_finder.lua.
• Build Tool Integration: The lua/neotest-java/build_tool folder provides support for different build tools (Gradle and Maven). Each build tool (e.g., gradle.lua and maven.lua) encapsulates commands to compile and run tests.
• Command Modules: In lua/neotest-java/command, modules (like junit_command_builder.lua, jdtls.lua, and run.lua) map the core test data into executable commands and manage interactions with external tools like JDTLS and nvim-dap.
• Utility Layer: Under lua/neotest-java/util, helper modules (e.g., read_file.lua, resolve_qualified_name.lua, timer.lua, etc.) offer shared functionalities to support the core logic.
• Logging: The logger module (lua/neotest-java/logger.lua) handles logging and debugging messages.
• Testing and Spec Modules: The tests directory provides unit tests for verifying the behaviors of the core, utility, and build integrations.
• Configuration and Workflows: Top-level files like Makefile, .luacheckrc, .luarc.json, and files under .github show that the project uses continuous integration, static analysis, and release tooling. They provide context for automated testing and build integrity.
Relationships and Interactions
• The Plugin Layer receives user commands (like running a test or debugging one) from Neovim. This layer calls the Command Modules.
• The Command Modules orchestrate test execution by invoking the appropriate build tool integrations (depending on whether it is a Maven or Gradle project) to construct the test command.
• The Core modules are responsible for interpreting project structure and discovering test specifications (including multimodule project support).
• Utility modules are used across the adapter by both Core and Command modules to process files, paths, and configuration details.
• Logging is used throughout to trace operations and errors.
• Integration with external tools: The adapter interacts with nvim-dap for debugging and jdtls for language-server related actions.
Architectural Patterns and Design Principles
• Modular Architecture: Components are separated into distinct directories (plugin, core, command, build_tool, util) which makes the project highly modular and maintainable.
• Adapter Pattern: The neotest-java module acts as an adapter that bridges Neotest’s generic test-runner expectations with Java-specific operations (JUnit, Maven, Gradle).
• Separation of Concerns: Each module has a well-defined responsibility (e.g., constructing test commands, filtering files, or resolving dependencies).
• Extensibility: The integration with external plugins (nvim-dap, nvim-treesitter, etc.) is designed to allow easy configuration and potential addition of more capabilities.
Relevant Technologies and Frameworks
• Neovim and the Neotest toolset.
• JUnit and Java testing frameworks.
• Build tools: Maven and Gradle.
• Debugging via nvim-dap.
• Lua and its plugin ecosystem (nvim-treesitter, plenary.nvim, etc.).