Quick Start

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

Installation

Add Plugwright to your build.gradle.kts file:

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)
}

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.

If npm at your company goes through a private registry, add an npm { } block now — the next step installs packages, and it will need it:

plugwright {
    npm {
        registry("https://nexus.corp/repository/npm-group/") {
            authToken(secret.env("NPM_TOKEN"))
        }
    }
}

Plugwright writes that to a gitignored .npmrc in the workspace before each install. See Configuration.

Initialization

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, .npmrc

Everything a run generates — the compiled specs, the server the local environment starts — stays inside that directory, under dist and generated. See Project Layout.

Your First Test

Run your tests:

./gradlew plugwrightTest

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!

Get Started

Documentation

Environments

Maintaining