Skip to main content
There are two ways to write this block, and they describe the same thing. The short one is everything below: flat properties on plugwright { }, describing a single local Paper server. Nothing about it has changed, and builds that use it keep working. The long one names its servers explicitly, which is what you want as soon as there is more than one:
Inside create("local", LocalMode) { } you get the same properties documented on this page, plus includeInMatrix, allowFailure, excludeTests and plugins { }. Adding a second environment — a staging server, a proxy, anything — is a second create call. See Environments and External Servers.
Without an environments { } block, the flat properties below describe one implicit environment named local. They are deprecated and will be removed in 4.0.

Example Configuration

In your build.gradle.kts:

Configuration Options

Property<String>
required
The Minecraft version to use for testing. Default is "1.19.4".
DirectoryProperty
Directory where the test server will be located. Unset by default, which puts it in <testsDir>/generated/<environment>/run — set it only to keep the server somewhere else. See Project Layout.
DirectoryProperty
Root of the test workspace: the npm project, the tests and plugins sources, and the dist and generated directories the build writes. Default is file("src/test/e2e").
Property<Boolean>
Automatically accept Minecraft EULA, if you agree to the Minecraft EULA. Default is true.
ListProperty<String>
Configures which files or folders in the runDir should not be deleted when the plugwrightClean task runs. This is useful for preserving the server JAR, dependency caches, or other persistent data between test runs. Default is listOf("server.jar", "cache", "libraries").By default, the cleanup preserves:
  • server.jar - The Paper server executable
  • cache - Minecraft/Paper cache folder
  • libraries - Server dependencies
Everything else in the run directory will be deleted to ensure a clean test environment.
Property<Boolean>
Whether to use only externally downloaded plugins instead of building the project plugin. When true, the plugwrightTest task will not depend on jar/shadowJar/reobfJar tasks. Useful when running E2E tests with plugins downloaded from external sources only. Default is false.
Action<PluginDownloadSpec>
Download external plugins (like dependencies) before starting the server.
ListProperty<String>
Arguments to pass to the Java virtual machine when starting the test server. Default is listOf("-Xmx2G").
Action<RunDirFileSpec>
Stage files into the run directory before the server starts. You can provide inline text content or copy from an existing local file. Paths are relative to the run directory.
Property<Boolean>
Whether to automatically download Node.js for running tests. Default is false: the system-installed node/npm on your PATH are used, and the build fails with instructions if Node.js is not installed. When true, the plugin downloads a Node.js distribution into a shared per-user cache in the Gradle user home (~/.gradle/caches/plugwright/node), verifies it against the official SHASUMS256.txt checksums from nodejs.org, and uses it for all node/npm invocations. The cache is keyed by version, OS and architecture, shared across all projects, and survives gradle clean.
Property<String>
The Node.js version to download and use when downloadNode is true. Default is "22.14.0".

npm registries

The workspace is an npm project, and by default it installs from whatever registry the machine is already pointed at. If your packages come from a private registry (a Nexus or an Artifactory, usually), declare it in the build script instead of leaving a .npmrc for everyone to set up by hand:
Plugwright writes this to a .npmrc next to package.json immediately before it runs npm install, which covers both the workspace’s own dependencies and the runner packages your environments pull in. Without an npm { } block no file is written and nothing changes.
Action<NpmSpec>
Registries the workspace installs from. registry(url) sets the default one, scope("@org", url) routes a single scope, and option(key, value) writes any other npmrc setting verbatim. All three are optional and can appear in any order.

Credentials

Credentials are SecretRef values — secret.env("NPM_TOKEN"), secret.file("/run/secrets/npm"), secret.systemProperty("npm.token"). There is deliberately no way to write a literal token: a build script is a file in your repository, and a literal would also end up in the configuration cache. authToken(...) becomes an _authToken line. username(...) plus password(...) become username and a base64-encoded _password, which is what npm 7 and later expect. A username without a password (or the other way round) is a configuration error and fails the build. So is a secret that resolves to nothing. An unset NPM_TOKEN stops the build before npm install runs, with the name of the variable that was empty — rather than several minutes later, with a 404 from the public registry.

The generated file

The .npmrc carries a marker on its first line:
Only a file carrying that marker is ever overwritten. If the workspace already has an .npmrc you wrote yourself, plugwright leaves it alone and warns that the npm { } block is being ignored — delete the file to hand the job over. Remove the block from the build script and the generated file is deleted with it, so a registry you stopped declaring stops applying. The file holds resolved credentials, so it is gitignored: plugwrightInit scaffolds a .gitignore that lists it, and a workspace created before this existed gets the entry the first time the file is generated. It is written with owner-only permissions where the filesystem supports them.

Multi-environment options

These live on plugwright { } itself, next to testsDir.
Property<String>
Environment the unsuffixed task aliases point at. plugwrightRunServer means plugwrightRunServerLocal when this is "local". Default is "local". It does not mean “the only environment that runs” — the matrix runs all of them.
Action<MatrixSpec>
Settings for the plugwrightTest matrix run. parallel runs environments concurrently (off by default), maxParallel caps how many at once (default 2).
Per-environment, inside create(...) { }:
Property<Boolean>
Whether plugwrightTest includes this environment. true for LocalMode, false for ExternalMode. Ignored when the per-environment task is called directly.
Property<Boolean>
Whether failures here fail the matrix build. Failures are still reported as failures. Default false, and ignored when the per-environment task is called directly.
ListProperty<String>
Test name substrings to skip in this environment. Skipped tests appear in the report with the reason.
Property<Int>
Port the local server binds and bots connect on. Default 25565.
Action<PluginsSpec>
Runner plugins this environment loads: npm("@scope/name") { options["key"] = "value" } for a published package, local("name") for one of your own in the workspace’s plugins directory. See Runner Plugins.

Environment Variables

String
Set PLUGWRIGHT_DEBUG=1 in your environment to enable verbose debug logging during test execution. This is particularly useful for troubleshooting GUI flows and inspecting window open/close events from the bot.