> ## Documentation Index
> Fetch the complete documentation index at: https://plugwright.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Complete reference for Gradle plugin configuration options.

## Example Configuration

In your `build.gradle.kts`:

```kotlin theme={null}
plugwright {
    // ---- Server Configuration ----
    // Version of Paper server to download and run
    minecraftVersion.set("1.19.4")
    
    // Directory where the test server will be located
    runDir.set(file("run"))
    
    // Automatically accept the Minecraft EULA
    acceptEula.set(true)
    
    // Pass custom JVM arguments to the test server
    jvmArgs.set(listOf("-Xmx4G", "-XX:+UseG1GC"))
    
    // ---- Test Configuration ----
    // Directory containing your .spec.js test files
    testsDir.set(file("src/test/e2e"))
    
    // ---- Dependency / External Plugins ----
    // Download external plugins before starting the server
    downloadPlugins {
        url("https://url.to/plugin.jar")
    }
    
    // ---- Cleanup Configuration ----
    // Files to preserve when 'plugwrightClean' is executed
    cleanExcludePatterns.set(listOf(
        "server.jar",
        "cache",
        "libraries"
    ))
}
```

## Configuration Options

<ParamField path="minecraftVersion" type="Property<String>" required>
  The Minecraft version to use for testing. Default is `"1.19.4"`.
</ParamField>

```kotlin theme={null}
minecraftVersion.set("1.19.4")
minecraftVersion.set("1.20.1")
```

<ParamField path="runDir" type="DirectoryProperty">
  Directory where the test server will be located. Default is `project.layout.projectDirectory.dir("run")`.
</ParamField>

```kotlin theme={null}
runDir.set(file("run"))
runDir.set(file("test-server"))
```

<ParamField path="testsDir" type="DirectoryProperty">
  Directory containing test files. Default is `file("src/test/e2e")`.
</ParamField>

```kotlin theme={null}
testsDir.set(file("src/test/e2e"))
testsDir.set(file("tests/integration"))
```

<ParamField path="acceptEula" type="Property<Boolean>">
  Automatically accept Minecraft EULA, if you agree to the [Minecraft EULA](https://www.minecraft.net/en-us/eula). Default is `true`.
</ParamField>

```kotlin theme={null}
acceptEula.set(true)
```

<ParamField path="cleanExcludePatterns" type="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.
</ParamField>

```kotlin theme={null}
// Custom exclusions - add additional files to preserve
cleanExcludePatterns.set(listOf(
    "server.jar",
    "cache",
    "libraries"
))
```

<ParamField path="useExternalPluginsOnly" type="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`.
</ParamField>

```kotlin theme={null}
useExternalPluginsOnly.set(true)
```

<ParamField path="downloadPlugins" type="Action<PluginDownloadSpec>">
  Download external plugins (like dependencies) before starting the server.
</ParamField>

```kotlin theme={null}
plugwright {
    downloadPlugins {
        url("https://url.to/plugin.jar")
    }
}
```

<ParamField path="jvmArgs" type="ListProperty<String>">
  Arguments to pass to the Java virtual machine when starting the test server. Default is `listOf("-Xmx2G")`.
</ParamField>

```kotlin theme={null}
plugwright {
    jvmArgs.set(listOf("-Xmx4G", "-XX:+UseG1GC"))
}
```

<ParamField path="writeFiles" type="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.
</ParamField>

```kotlin theme={null}
plugwright {
    writeFiles {
        // inline text content
        file("plugins/SomePlugin/config.yml", """
            key: "value"
        """.trimIndent())

        // copy from a local source file
        file("plugins/MyPlugin/data.json", projectDir.resolve("test-fixtures/data.json"))
    }
}
```

## Environment Variables

<ParamField path="PLUGWRIGHT_DEBUG" type="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.
</ParamField>