ModsJava
Plugwright
Java mod listed for Minecraft 1.8–1.19. Download on the author's site.
⬇ Download on Spigot
Plugwright
End-to-end testing framework for Paper/Spigot Minecraft plugins. Supports JavaScript and TypeScript.
Features
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.
Quick Start
Prerequisites: Java 17+, Gradle 7+, Node.js 16+, and a Paper/Spigot plugin project.Click to expand...
Code (Kotlin):
plugins {
id ( "io.github.drownek.plugwright" ) version "1.3.3"
}
plugwright {
minecraftVersion. set ( "1.19.4" )
testsDir. set (file ( "src/test/e2e" ) )
acceptEula. set ( true )
}
Code (Bash):
. /gradlew plugwrightInit
Code (Bash):
. /gradlew plugwrightTest
Want to see a working example? Check out the example_plugin directory in the GitHub repository.Click to expand...
Why Plugwright vs MockBukkit?
Approach
- Plugwright: End-to-end – runs a real Paper server with real player bots
- MockBukkit: Unit testing – mocks the Bukkit API in-process
- Plugwright: Real Mineflayer bots that join, move, chat, and click GUIs
- MockBukkit: Mocked Player objects with simulated method calls
- Plugwright: ✅ Full support – real server means real NMS
- MockBukkit: ❌ Breaks on NMS / reflection / internals
- Plugwright: ✅ Tests the plugin exactly as players experience it (multi-plugin testing works naturally)
- MockBukkit: ❌ May miss bugs caused by mock/real behavior mismatch
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.Click to expand...
Examples
Basic command test
Code (Javascript):
import { expect , test } from '@drownek/plugwright' ;
test ( 'help displays message' , async ( { player } ) => {
player. chat ( '/help' ) ;
await expect (player ). toHaveReceivedMessage ( 'Help' ) ;
} ) ;
Code (Javascript):
test ( 'admin can interact with gui' , async ( { player } ) => {
await player. makeOp ( ) ;
player. chat ( '/example gui-settings' ) ;
const gui = await player. gui ( { title : 'guiSettings' } ) ;
await gui. locator (item => item. getDisplayName ( ). includes ( 'guiItemInfo' ) ). click ( ) ;
await expect (player ). toHaveReceivedMessage ( 'You clicked on item' ) ;
} ) ;
Code (Javascript):
test ( 'multi-bot teleportation' , async ( { player , createPlayer } ) => {
await player. makeOp ( ) ;
const friend = await createPlayer ( { username : 'FriendBot' } ) ;
await friend. teleport ( 100 , 100 , 100 ) ;
player. chat (` /tp $ {player. username } $ {friend. username }` ) ;
await expect (player ). toBeNear ( 100 , 100 , 100 , { tolerance : 2 } ) ;
} ) ;
Continuous Integration (CI)
Setting up CI takes less than 5 minutes. Use the official plugwright-action to run your entire test suite.
Just create a `.github/workflows/e2e.yml` file with the following content:
Code (Text):
name: E2E Tests
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: drownek/plugwright-action@v1
Documentation
See the GitHub Wiki:
- Getting Started - Installation and setup
- Writing Tests - Test examples and patterns
- Matchers Reference - All available assertions
- GUI Testing - Testing inventory GUIs
- Configuration - Gradle plugin options
- Test Filtering - Running specific tests
Quick facts
- Edition: Minecraft Java
- File type: .jar
- Minecraft versions listed: 1.8, 1.9, 1.10
- How to install: Install the matching mod loader (Forge, Fabric or NeoForge) for your Minecraft version. → Download the .jar. → Put it in the .minecraft/mods folder and launch that loader profile.
- Where to get it: Opens on Spigot — not every file is mirrored on our own servers.
Install steps are the general flow for this file type — How to install Minecraft Java mods & modpacks walks through it step by step.
Plugwright is a free Minecraft Java mod. Compatible with Minecraft 1.8, 1.9, 1.10, 1.11 and newer. Downloaded 12 times (via Spigot). Download it and open it directly in the game.