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:
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 yourbuild.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 executablecache- Minecraft/Paper cache folderlibraries- Server dependencies
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:
.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 areSecretRef 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:
.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 onplugwright { } 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).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.