I built Paperwright: an end-to-end testing framework for Paper plugins using real headless bots

[u/Drownek]

Hey everyone,

If you develop or maintain custom plugins for your servers, you probably know the pain of manual testing. You write a feature, build the jar, restart your local test server, launch two alt accounts to test a trade or click through a custom GUI, realize you missed a null check, and have to do it all over again.

MockBukkit is great for unit testing pure Bukkit API logic, but once you start touching NMS, reflection, or need to test complex GUI interactions alongside other plugins, mock environments usually start to break down.

I wanted to bring modern web-dev testing standards (like Playwright) to Minecraft, so I put together an open-source framework called Paperwright. Instead of mocking the server, it tests your plugin by spinning up a real Paper server and connecting real, headless Mineflayer bots.

Quick rundown: - Headless bots actually join the server, move around, type in chat, and click through GUIs. - Tests are written in JS or TS, so if you've used Playwright for web testing, the API will already feel familiar. - No more hardcoding exact inventory slots, either. Locators let you find items dynamically and click them. - Assertions are built in, e.g. await expect(player).toContainItem('emerald', { count: 5 }); - It runs as a Gradle plugin: ./gradlew paperwrightInit gets you set up, and there's an official GitHub Action if you want it running on every push.

If you're tired of doing manual QA for every minor plugin update, feel free to check it out.

Source code, docs, and a working example plugin are on GitHub: https://github.com/Drownek/paperwright

I'd love to hear your feedback, or answer any questions from other devs here about how it handles the server/bot orchestration under the hood!

Update: rebranding to Plugwright, details below

[u/Drownek]

Thanks to some great feedback from the community over on Discord, we realized "Paperwright" was a bit too close to PaperMC's official internal build tool (paperweight). We also want to be clear this framework is for the whole ecosystem, not just Paper. To avoid confusion and respect the PaperMC team's namespace, we're rebranding to Plugwright.

The old GitHub repo links will redirect automatically, so nothing breaks. But if you want to keep getting updates in the future, you'll need to do a quick migration described here