v2.0.2

Summary

This is the rename release: the project moves from Paperwright to Plugwright. Everything that was named after the old project — the npm package, Gradle plugin ID, tasks, Kotlin package, and settings — has been renamed in a coordinated bump. Alongside the rebranding, this major release includes a new task to run the test server interactively, fixes for newer Minecraft versions, and significant CI/CD improvements with NPM provenance support.

Important

Breaking change. Existing users must update their package.json, build.gradle.kts, GitHub Actions CI, and any imports/task invocations. See Migration below.

Changes

Rename (Breaking)

• NPM package renamed: @drownek/paperwright → @drownek/plugwright.
• Gradle plugin ID renamed: io.github.drownek.paperwright → io.github.drownek.plugwright.
• Gradle tasks renamed: paperwrightClean / paperwrightTest / paperwrightInit → plugwrightClean / plugwrightTest / plugwrightInit.
• Kotlin package and classes renamed: me.drownek.paperwright.PaperwrightPlugin → me.drownek.plugwright.PlugwrightPlugin (along with Extension, TestTask, etc.).
• Environment Variables: PAPERWRIGHT_DEBUG is now PLUGWRIGHT_DEBUG.

Features

• New Task: Added the plugwrightRunServer Gradle task. This allows you to easily spin up the test server (with plugins and environment prepared) without running the automated test suite, which is extremely useful for manual debugging and GUI testing.

Bug Fixes

• Mineflayer & Formatting: Fixed text component parsing for newer Minecraft versions by updating the underlying mineflayer dependency.
• Server Downloads: Updated the Paper API integration to correctly allow downloading newer server versions.
• Test Stability: Fixed an issue where some test cases would fail on very slow machines.

Tooling & CI

• NPM Provenance: Moved to NPM trusted publishing. The packages are now signed with provenance using stable NPM versions.
• Release Automation: Improved the bump-version.js script to target explicit tags, preventing push rejections, and optimized the release workflow.

Migration

In your plugin project:

build.gradle.kts

- id("io.github.drownek.paperwright") version "1.3.3"
+ id("io.github.drownek.plugwright") version "2.0.2"

- paperwright { ... }
+ plugwright { ... }

Gradle task invocations

- ./gradlew paperwrightTest
- ./gradlew paperwrightInit
- ./gradlew paperwrightClean
+ ./gradlew plugwrightTest
+ ./gradlew plugwrightInit
+ ./gradlew plugwrightClean

package.json

- "@drownek/paperwright": "^1.3.3"
+ "@drownek/plugwright": "^2.0.2"

Test Imports

- import { test, expect } from '@drownek/paperwright';
+ import { test, expect } from '@drownek/plugwright';

GitHub Actions CI

- uses: drownek/paperwright-action@v1
+ uses: drownek/plugwright-action@v1

Full changelog

v1.3.3...v2.0.2

v1.3.3

Summary

This release includes important fixes to support newer server versions, major CI/CD workflow updates, documentation improvements, and various runner cleanups.

Changes

Runner

• Fixed text component parsing for newer server versions and updated mineflayer.
• Gated verbose DEBUG logs behind the PAPERWRIGHT_DEBUG environment variable.
• Replaced unicode symbols with reliable ANSI fallbacks for better terminal compatibility.
• Cleaned up unused banner methods and dropped the unused paperwright bin entry.
• Fixed casing in package.json.

Gradle Plugin

• Updated the Paper API to allow downloading newer server versions.
• Included rimraf in the scaffold generated by the paperwrightInit task.

CI/CD

• Added a complete release workflow and migrated to npm trusted publishing.
• Updated workflows to use the official Paperwright action and added working directory support.
• Bumped the Node version and ensured gradlew is explicitly made executable.

Documentation

• Added a showcase section and CI usage guide to the README.
• Reformatted tables, added a CI badge, and fixed the broken npm version badge.

Example Plugin & Tests

• Simplified the example plugin to be more descriptive.
• Cleaned up test files by adding missing awaits and removing unused method parameters.

Full changelog

v1.3.2...v1.3.3

v1.3.2

Summary

This is the rename release: the project moves from paper-e2e-test to Paperwright. Everything that was named after the old project — npm package, Gradle plugin id, tasks, Kotlin package, CLI binary — has been renamed in a coordinated bump. Also includes documentation cleanup and improvements to the version-bump tooling.

Important

Breaking change. Existing users must update their package.json, build.gradle.kts, and any imports/task invocations. See Migration below.

Changes

Rename (Breaking)

• npm package renamed: @drownek/paper-e2e-runner → @drownek/paperwright.
• Gradle plugin id renamed: io.github.drownek.paper-e2e-test → io.github.drownek.paperwright.
• Gradle tasks renamed: paperE2EClean / paperE2ETest / paperE2EInit → paperwrightClean / paperwrightTest / paperwrightInit.
• Kotlin package and classes renamed: me.drownek.papere2e.PaperE2EPlugin → me.drownek.paperwright.PaperwrightPlugin (and the matching Extension / TestTask / Banner).
• Runner env vars / banner / settings file paths updated to the new name.

Documentation

• Fixed broken anchors, ordering, and stale links in the README.
• Removed the hardcoded version number from Configuration.md so it no longer drifts on each release.
• Simplified examples by dropping unnecessary awaits.

Tooling

• scripts/bump-version.js now also rewrites version references inside the docs/ tree, so a single bump propagates everywhere.
• bump-version is now interactive: prompts for the target version (pre-filled from version.txt), asks whether to create an annotated tag (defaults Y for stable / N for prerelease), and prompts whether to push after committing/tagging.
• Version files are now committed directly via git commit -- rather than git add of the whole tree.

Migration

In your plugin project:

build.gradle.kts

- id("io.github.drownek.paper-e2e-test") version "1.3.1"
+ id("io.github.drownek.paperwright") version "1.3.2"

- paperE2ETest { ... }
+ paperwright { ... }

Gradle task invocations

- ./gradlew paperE2ETest
- ./gradlew paperE2EInit
- ./gradlew paperE2EClean
+ ./gradlew paperwrightTest
+ ./gradlew paperwrightInit
+ ./gradlew paperwrightClean

src/test/e2e/package.json

- "@drownek/paper-e2e-runner": "^1.3.1"
+ "@drownek/paperwright": "^1.3.2"

Run ./gradlew paperwrightInit against a fresh project to see the new defaults, or just diff your package.json against the template emitted there.

Full changelog

v1.3.1...v1.3.2

v1.3.1

Summary

This release includes documentation improvements, CI updates, and important bug fixes for the runner and API.

Changes

Gradle Plugin

• Introduced paperE2EInit task to automate the setup of the end-to-end testing environment.

Documentation

• Migrated the entire documentation set into the repository under the docs/ directory
• Added dedicated _Sidebar and _Footer for the documentation system.
• Updated README with a streamlined Quick Start guide and prerequisites.

CI/CD

• Added a new GitHub Action (wiki-sync.yml) to automatically keep the GitHub Wiki in sync with the repository's docs/ folder.
• Updated ci.yml to ensure builds run correctly on the master branch and added necessary write permissions for automation.

Runner

• Updated internal runner versions and dependencies to match the v1.3.1 release.

Paper E2E v1.3.0

Features

• Bot Lifecycle & Reconnection: Enhanced bot connection management and lifecycle handling. PlayerWrapper now dynamically uses getters for inventory and username to ensure accurate values even after reconnects.
• New Assertions: Added rejects.toThrow for asserting promise rejections in tests, and added a since option to the toHaveReceivedMessage matcher to tightly scope chat buffer assertions.
• Stability Utilities: Added a new waitForStable utility for asserting that a condition remains continuously true over a given duration.
• Movement Threshold Adjustments: The Gradle plugin now automatically configures spigot.yml to increase movement thresholds (moved-wrongly-threshold and moved-too-quickly-multiplier), preventing the server from kicking teleporting test bots.
• Server Log Validation: Added server log validation capabilities and refactored command execution buffering.
• Runner Banner: Added a styled execution banner displaying the current framework version during test runs.

Bug Fixes

• Test Leakage (Zombie Tests): Introduced an AbortController and passed AbortSignal through the TestContext down to all polling utilities. This instantly terminates background execution when a test times out, permanently fixing cross-test contamination.
• Server Process Cleanup: Fixed zombie Java processes. The entire Paper server process tree is now forcefully and reliably killed when a Gradle task is abruptly terminated or cancelled from an IDE.
• Disconnect Hangs & Event Wiping: Eliminated 2-second teardown hangs by checking if bots are already disconnected, and removed destructive bot.removeAllListeners() calls that broke Mineflayer's internal packet handlers during teardown.
• Bot Naming: Fixed a race condition where undefined could occasionally appear as a bot's username before the server handshake completed.
• CI Pipeline: Fixed the CI workflow by ensuring the runner-package is properly built before E2E tests are executed.

Refactoring & Chore

• API Simplification: Simplified the internal test runner API and removed unused legacy code.
• Build & Typing: Added rimraf for clean builds and introduced a typecheck script for strict static type validation without emitting files.
• GitHub Actions: Added comprehensive E2E testing workflows using GitHub Actions and updated CI environments to use Node.js 22.
• Documentation: Simplified README setup instructions to directly link to the Wiki.
• Wiki: Updated the Wiki (Configuration.md, Getting-Started.md, GUI-Testing.md, TypeScript-Support.md) with the 1.3.0 version bumps and modern API usage.

Paper E2E v1.2.0

This release focuses on runner reliability, environment validation improvements, and Gradle plugin enhancements.

Bug Fixes

• Runner stability: Added a server process check before sending the stop command, preventing errors when the process is already gone
• Environment validation: JAVA_PATH is now validated alongside SERVER_JAR and SERVER_DIR during startup checks, catching misconfigurations early
• Error output capture: Added a stderr handler to the server process so error output is now captured and logged instead of silently dropped
• Safe shutdown: Removed a redundant process.exit(1) call and corrected the exit code used in the safety-net shutdown path
• Bot version: The Mineflayer bot now reads the Minecraft version from MC_VERSION environment variable instead of the hardcoded '1.19.4'
• GuiItemLocator: Fixed internal calls to deprecated GuiWrapper methods

Features

• Plugin download support: Gradle plugin E2E tasks (TestE2ETask) can now download plugins as part of the task setup
• MC_VERSION env var: MC_VERSION is now passed through as an environment variable in TestE2ETask, enabling version-aware test runs

Refactoring

• Replaced waitAbit with pollForAbsence for error validation in the runner, making error-state detection more reliable and deterministic
• Renamed test file extensions for consistency across the project

Chore

• Added a version bump script and aligned project versioning

Paper E2E v1.1.0

This release introduces a new reactive architecture for GUI testing, significantly improving stability when testing asynchronous inventory updates. It also adds a suite of player management utilities and improved assertion logic.

Highlights

Reactive GUI API

The framework has transitioned from a snapshot-based model to a live handle model. Previous versions relied on GuiWrapper, which captured the inventory state at a single moment in time. Version 1.1.0 introduces LiveGuiHandle and GuiItemLocator.

• Live Handles: The new player.gui({ title }) method returns a handle that maintains a reference to the currently open container. It remains valid even as items within the inventory change.
• Locators: Items are now defined by query logic rather than direct reference. Locators allow tests to define an item (e.g., by name or lore) and interact with it regardless of when it appears in the inventory.
• Automatic Retries: Interactions such as .click() and assertions now automatically wait and retry until the condition is met or a timeout is reached. This eliminates flaky tests caused by server-tick delays.

Player Lifecycle Utilities

Common administrative tasks have been standardized into the PlayerWrapper class to reduce boilerplate code in test setups:

• player.makeOp() / player.deOp()
• player.setGameMode(mode)
• player.teleport(x, y, z)
• player.giveItem(item, count)

Changes

New API Usage

The following example demonstrates the new locator pattern compared to the legacy approach.

// New Pattern
test('admin can toggle settings', async ({ player }) => {
  await player.chat('/admin menu');
  
  // 1. Get a live handle (does not resolve items immediately)
  const menu = await player.gui({ title: /Settings/ });
  
  // 2. Define a locator
  const toggleBtn = menu.locator(item => item.name === 'lever');
  
  // 3. Assertions automatically wait for the item to appear and match the state
  await expect(toggleBtn).toHaveLore('Status: OFF');
  
  // 4. Click automatically waits for the item to be clickable
  await toggleBtn.click();
  
  // 5. Re-use the same locator to verify the state change
  await expect(toggleBtn).toHaveLore('Status: ON');
});

Deprecations

The snapshot-based API is now deprecated. These methods will continue to function in v1.1.0 but will emit console warnings and will be removed in a future major release.

• player.waitForGui(predicate): Replaced by player.gui({ title }).
• player.waitForGuiItem(predicate): Replaced by gui.locator(predicate).
• player.clickGuiItem(predicate): Replaced by gui.locator(predicate).click().
• GuiWrapper.findItem / findAllItems: Replaced by GuiItemLocator.

Paper E2E v1.0.4

What's New

Automatic Test Environment Cleanup

• New cleanE2E task automatically wipes server data before tests for a clean slate
• Configurable exclusion patterns to preserve essential files (server.jar, cache, libraries)
• Runs automatically before testE2E to ensure consistent test environments

Configuration Improvements

• bukkit.yml configuration now handled by the Gradle plugin
• connection-throttle automatically set to 0, eliminating need to wait few seconds between each test

Enhanced Error Reporting

• Stack traces now point directly to your test files with accurate line and column numbers
• Failed tests display clickable file URLs for instant navigation in IDEs
• Source map support for TypeScript tests shows original .spec.ts locations
• Test summary at the end of each run

Better Bot Management

• Unique bot usernames using UUID fragments prevent naming conflicts
• Improved bot cleanup between tests

Technical Changes

• Refactored stack trace utilities into dedicated module
• Improved test result tracking and reporting
• Better separation of concerns in runner logic
• Enhanced logging throughout the test lifecycle