specwright.json / specwright.plugin.json
Specwright uses two different config files with similar names. One lives in your project; one lives in a plugin package. Neither stores credentials or test instructions — those belong in .env.testing and instructions.js.
Two different files
| File | Lives in | Written by |
|---|---|---|
.specwright.json | Project root (the app being tested) | Specwright Desktop |
specwright.plugin.json | Root of an overlay plugin package | Plugin author |
.specwright.json — Project configuration
Location: project root (the app being tested)
Written and maintained by: Specwright Desktop. You generally do not edit this file by hand.
{
"plugin": "@specwright/plugin",
"version": "0.4.0",
"authStrategy": "oauth"
}
With an overlay plugin installed:
{
"plugin": "@specwright/plugin",
"version": "0.4.0",
"authStrategy": "email-password",
"overlay": "your-org/your-e2e-plugin",
"overlayPath": "../plugins/your-e2e-plugin"
}
Fields
| Field | Description |
|---|---|
plugin | Base plugin name (always @specwright/plugin) |
version | Installed base plugin version — display only in Desktop UI |
authStrategy | Auth strategy in use — display only, does not control behavior |
overlay | Overlay plugin name (optional) |
overlayPath | Relative path to the overlay plugin directory (optional) |
Detection order
The Desktop App reads .specwright.json first. If the file is absent, it falls through to specwright.plugin.json at the project root.
What does NOT go here
BASE_URL, credentials, or environment variables → use.env.testing- Test scope, page instructions, or scenario hints → use
instructions.js
This file is safe to commit — it contains no secrets.
specwright.plugin.json — Plugin overlay manifest
Location: root of an overlay plugin package (not the project being tested)
Written by: the plugin author, published alongside the plugin.
{
"name": "@specwright/plugin-mui",
"version": "0.1.0",
"extends": "@specwright/plugin",
"requiredBaseVersion": ">=0.3.8",
"description": "Material UI overlay",
"authStrategy": "email-password",
"overrides": [
"e2e-tests/utils/stepHelpers.js",
".claude/agents/playwright/code-generator.md"
]
}
Fields
| Field | Description |
|---|---|
name | npm package name of the overlay |
version | Overlay plugin version |
extends | Always @specwright/plugin |
requiredBaseVersion | Semver range for compatible base plugin versions |
description | Human-readable description shown in Desktop UI |
authStrategy | Default auth strategy for projects using this overlay |
overrides | Files this overlay replaces when installed |
For a full guide on authoring overlay plugins, see the Plugin Creation section.
Note on the todo-app example
The todo-app example project ships with only a specwright.plugin.json at its root — it has no .specwright.json. The Desktop App detects it correctly via the fallback lookup, so this is a valid configuration for simpler projects.