Plugwright

End-to-end testing framework for Paper/Spigot Minecraft plugins. Supports JavaScript and TypeScript.

⚠️ Upgrading from Plugwright 2.x? The npm package moved.

The runner is published as @plugwright/runner from 3.0 onwards; @drownek/plugwright stops receiving releases at 2.x. Change the dependency in your package.json, run npm install, and update the import in your test files. Nothing else moves: the Gradle plugin id stays io.github.drownek.plugwright. See the full v2 to v3 Migration Guide for layout changes, configuration updates, and new features.

Features

🚀 Setup – Automated server lifecycle management with Paper server downloads.

• Supported Minecraft versions: 1.8 to 26.1 (1.8, 1.9, 1.10, 1.11, 1.12, 1.13, 1.14, 1.15, 1.16, 1.17, 1.18, 1.19, 1.20, 1.21, 1.21.9, 1.21.11, 26.1)

🎮 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.

🌍 Multi-Server Ready – Run tests against staging or external servers (see External Servers).

Quick Start

0. Prerequisites: Before you begin, you need:

• Java 17 or higher
• Gradle 7 or higher
• Node.js (for running the test runner, can be downloaded automatically by using downloadNode setting)
• A Paper/Spigot plugin project

1. Add the plugin to your build.gradle.kts:

import me.drownek.plugwright.local.LocalMode

plugins {
    id("io.github.drownek.plugwright") version "3.0.0"
}

plugwright {
    environments {
        // Paper downloaded, patched, started and killed by plugwright itself.
        create("local", LocalMode) {
            minecraftVersion.set("1.19.4")
            acceptEula.set(true)
            
            // Download some dependencies your plugin might need
            downloadPlugins {
                url("https://url.to/plugin1.jar")
                url("https://url.to/plugin2.jar")
                // ... etc
            }
        }
    }

    testsDir.set(file("src/test/e2e"))

    // If true, always downloads and uses an isolated Node.js version, ignoring the system Node.
    downloadNode.set(true)
}

💡 Tip: If you already have Node.js installed on your system, you can comment out downloadNode.set(true) to speed up initialization. Otherwise, leave it uncommented.

2. Initialize the test folder:

Run the init command to set up your test folder. It asks where to put it, then writes an npm project with a package.json, a TypeScript config, a .gitignore, an example spec and an example runner plugin:

./gradlew plugwrightInit

src/test/e2e/
  tests/example.spec.ts          your specs go here
  plugins/example-plugin.ts      hooks, fixtures and matchers
  package.json, tsconfig.json
  .gitignore                     node_modules, dist, generated

Compiled specs land in dist, and everything an environment writes — the Paper server the local one starts, for instance — in generated. Neither belongs in version control. See Project Layout.

3. Run your tests:

./gradlew plugwrightTest

💡 Tip: Plugwright hooks into your build process and tests against your compiled plugin jar. Ensure your plugin compiles successfully (e.g. jar or shadowJar task) before running tests!

💡 Want to see a working example? Check out the example_plugin directory in this repository.

Why Plugwright vs MockBukkit?

MockBukkit is built for fast unit testing with simulated API mocks. Plugwright spins up a real Paper server with real Mineflayer bots for true end-to-end integration, GUIs, packets, and NMS.

Feature Comparison Table

	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.

Continuous Integration (CI)

Plugwright provides an official GitHub Action to run your end-to-end suite on every PR in minutes.

👉 Setup plugwright-action

Used in Production

HolyWorld
~10,000 peak online players. Plugwright powers their CI/CD pipeline for end-to-end plugin testing.
Integrated by @monikon22

Documentation & Examples

For full examples on how to test GUIs, multi-bot interactions, NMS, and the complete API Reference, visit our official documentation site:

👉 Read the full documentation at plugwright.dev

Support & Community

Got a question, found a bug, or want to suggest a feature? 👉 Open an issue - don't hesitate, even if it's just a beginner question!

License

MIT