End-to-end testing framework for Paper/Spigot Minecraft plugins. Supports JavaScript and TypeScript.
Warning
Migration from Paperwright (v1.x to v2.0) This framework has been renamed from Paperwright to Plugwright. If you are upgrading from an older version, you must update the following things in your project:
- Change
id("io.github.drownek.paperwright")toid("io.github.drownek.plugwright"). - Rename your
paperwright { ... }configuration block toplugwright { ... }and Gradle tasks (e.g../gradlew paperwrightTestto./gradlew plugwrightTest). - In your
package.json, change@drownek/paperwrightto@drownek/plugwrightand runnpm install. - Update your test files:
import { test } from '@drownek/paperwright'toimport { test } from '@drownek/plugwright'. - Change your CI to use
drownek/plugwright-action@v1.
🚀 Setup – Automated server lifecycle management with Paper server downloads.
🎮 Bot Testing – Powered by Mineflayer. Bots join, move, chat, and click GUIs like real players.
🎭 Playwright-inspired API – Live handles and locators for scripting player interactions.
🧪 Type-Safe – Native JavaScript and TypeScript with full type safety.
🔄 Automatic Retries – Built-in retry logic to handle flaky tests.
📊 Rich Assertions – Custom matchers built for Minecraft mechanics.
🔧 Gradle Integration – Run your entire suite with a single command.
Prerequisites: Java 17+, Gradle 7+, Node.js 16+, and a Paper/Spigot plugin project.
1. Add the plugin to your build.gradle.kts:
plugins {
id("io.github.drownek.plugwright") version "2.0.2"
}
plugwright {
minecraftVersion.set("1.19.4")
testsDir.set(file("src/test/e2e"))
acceptEula.set(true)
// Download some dependencies your plugin might need
downloadPlugins {
url("https://url.to/plugin1.jar")
url("https://url.to/plugin2.jar")
// ... etc
}
}2. Initialize the test folder:
./gradlew plugwrightInit3. Run your tests:
./gradlew plugwrightTest💡 Want to see a working example? Check out the example_plugin directory in this repository.
| Plugwright | MockBukkit | |
|---|---|---|
| Approach | End-to-end – runs a real Paper server with real player bots | Unit testing – mocks the Bukkit API in-process |
| Server | Real Paper server with actual game logic | No server – simulated API stubs |
| Player interaction | Real Mineflayer bots that join, move, chat, and click GUIs | Mocked Player objects with simulated method calls |
| NMS / internals | ✅ Full support – real server means real NMS | ❌ Breaks on NMS / reflection / internals |
| Plugin compatibility | Tests the plugin exactly as players experience it | May miss bugs caused by mock/real behavior mismatch |
| Multi-plugin testing | ✅ All plugins load together naturally | Limited – each mock is isolated |
| GUI testing | ✅ First-class support with locators and click simulation | Partial – inventory content mocks supported; click/drag simulation limited |
| Speed | Slower (server startup ~10-20s, then fast) | Very fast (milliseconds per test) |
| Best for | Integration & E2E tests, NMS-heavy plugins, GUI testing | Fast unit tests for pure Bukkit API logic |
💡 Tip: Plugwright and MockBukkit work well together. MockBukkit for fast unit tests; Plugwright for end-to-end tests that verify behavior on a real server.
Setting up CI takes less than 5 minutes. Use the official plugwright-action to run your entire test suite on every pull request.
name: E2E Tests
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: drownek/plugwright-action@v1For full examples on how to test GUIs, multi-bot interactions, NMS, and the complete API Reference, visit our official documentation site:
MIT