Testing Minecraft Plugins Gets Easy With run-task

If you've built a Minecraft plugin and tested it locally, you know the dance: download the server jar, set up directories, place your plugin in plugins/, hit start, wait for initialization. Every single time. run-task eliminates that repetitive setup with a single Gradle command that handles everything automatically.

What run-task Does

run-task is a suite of Gradle plugins that automate one of the most tedious parts of Minecraft plugin development: integration testing. Instead of manually downloading server software, configuring it, and placing your compiled plugin in the right folder, you define what version you want and run a command. The plugin handles the download, setup, and launch automatically.

There are three main variants. run-paper handles Paper servers (the go-to choice for most devs), run-velocity covers Velocity proxy software, and run-waterfall covers Waterfall proxies. Each operates on the same principle: configure once in your build.gradle.kts, then use a simple task to spin up your testing environment.

This might sound like a small convenience. When you're iterating on a plugin and testing dozens of times a day, the time savings compound fast.

Why Plugin Developers Need This

Testing a Minecraft plugin is fundamentally different from testing a regular Java library. You can't just run unit tests and move on. Your code runs inside the Minecraft server, interacts with game state, manages player events, and relies on APIs that change between versions. That's integration testing territory, and there's no way around it.

Without run-task? The workflow is painful. Download Paper 1.21.8, extract it, create plugins folder, build your jar, copy it over, run the server script, wait for startup, connect with a client, test your feature, shut down, change code, repeat. Do this fifty times while developing a feature and you've lost hours to pure boilerplate.

Speed matters here.

run-task removes that friction completely. Modify your code, run gradle runServer, and your plugin is already loaded within seconds. This is especially valuable when testing multiple Minecraft versions - switch versions in your config and re-run without manual setup.

Getting Started with run-task

Installation is straightforward. Add the plugin to your build.gradle.kts and specify the version you want to run:

plugins {
 id("xyz.jpenilla.run-paper") version "3.0.2"
}

tasks {
 runServer {
 minecraftVersion("1.21.8")
 }
}

That's all you need. run-task automatically detects your plugin's compiled jar and includes it. If you're using shadowJar to bundle dependencies, it'll use that instead - no manual configuration.

To launch:

gradle runServer

Your Paper server starts with your plugin already loaded and ready for testing. The first run takes longer while downloading everything, but subsequent runs are much faster with cached server files.

For Velocity proxy testing, setup is almost identical:

plugins {
 id("xyz.jpenilla.run-velocity") version "3.0.2"
}

tasks {
 runVelocity {
 velocityVersion("3.4.0")
 }
}

The plugin handles version compatibility automatically, so you can test against snapshot releases or stable versions without worrying about compatibility layers.

What Makes run-task Worth Using

The best feature is brutal simplicity. run-task doesn't try to be clever - it downloads the specified server software, detects your plugin jar, and runs it. Fewer moving parts means fewer things break.

Automatic shadowJar detection is genuinely useful if you're bundling dependencies. Many plugins need to shade libraries for custom data formats or newer APIs. run-task respects that without extra configuration.

Version switching is dead simple.

Want to test on 1.20.4, 1.21.1, and the latest snapshot? Change one line and re-run. Regression testing becomes way less painful. And if you're building tools for server admins (like testing Votifier voting systems or experimenting with custom server MOTDs), having quick access to a running server is invaluable.

One detail worth noting: run-task respects Gradle subproject structure. If you're organizing plugin code across multiple modules, it figures out the correct jar automatically. That's less trivial than it sounds.

Common Gotchas and Things to Know

First gotcha: run-task downloads server software to your.gradle cache - usually ~/.gradle on Linux/Mac, %USERPROFILE%\.gradle on Windows. If you're short on disk space or dealing with a slow connection, the first run takes a minute or two. It's worth it, but expect that initial wait.

Java version matters.

Paper and Waterfall generally need Java 21 or higher, while older Velocity versions might work with Java 17. If you're using a version manager like sdkman, make sure the correct version is active before running.

There's also a learning curve with Gradle syntax if you're new to it. run-task uses Kotlin DSL (build.gradle.kts), which is more type-safe than Groovy but steeper for beginners. If you're still on build.gradle syntax, converting is usually straightforward.

Actually, here's something that trips people up: run-task assumes you're testing a single plugin in isolation. If you're building something that requires multiple servers running simultaneously (like a proxy setup with multiple backends), you'll need to orchestrate that separately. It's not a limitation of the tool, just its design philosophy.

When run-task Isn't the Right Choice

run-task is excellent for plugin development. It's not a one-size-fits-all solution.

If you're building a full server distribution with custom configs, startup scripts, and multiple plugins, you probably want Docker or a manual setup instead. run-task assumes you're testing a single plugin in isolation.

For integration testing across multiple server software types simultaneously, you'd want more sophisticated orchestration - maybe Docker Compose or a custom test harness built into your CI/CD pipeline.

Heavy testing of server administration workflows (monitoring, backups, cluster management) might be better served by a full server environment with proper persistence rather than run-task's temporary setups.

Most plugin developers will find run-task covers 90% of their testing needs.