playwright-config-resolver

playwright-config-resolver

Resolves the active configuration for the Playwright coding agent by layering multiple sources in a defined precedence order and enforcing governance constraints before any test action begins.

Guardrails Handoff Check

Before running any governance checks, inspect the workspace root for .guardrails-agent.json.

If .guardrails-agent.json exists:

• Set internal flag guardrailsActive: true
• Skip the entire Governance section below — those checks are now handled by the policy-enforcement skill via the agent's adapter skill.
• Continue with: test-type detection, framework detection, selector strategy resolution, and LSP startup only.

If .guardrails-agent.json does not exist:

• guardrailsActive: false
• Proceed with all sections below as normal (backwards-compatible mode).

Configuration File

Read .playwright-agent.json from the workspace root if it exists. This file is optional; all fields fall back to plugin defaults when absent. Parse it as JSON and surface a clear error if the file is present but malformed.

Resolution Order

Apply the following five-level priority chain. Higher levels fully override lower levels for the same key. Merge objects at the same key rather than replacing them, except where a level explicitly sets a scalar.

1. Per-invocation override — options passed directly in the current prompt (e.g., --framework react, inline @config blocks).
2. Directory mapping — directoryMappings entries in .playwright-agent.json matched against the path of the file being worked on.
3. Auto-detection — signals derived from files present in the workspace (see sections below).
4. Config defaults — top-level defaults declared in .playwright-agent.json.
5. Plugin defaults — hard-coded fallbacks bundled with the core plugin.

Auto-Detection Signals

When no higher-priority source specifies a value, scan the workspace for the following signals.

Test-Type Detection

Signal	Resolved Test Type
File path contains /e2e/ or /tests/	e2e
File path contains /api/	api
File path contains /visual/ or .spec.visual.ts	visual
Filename contains .e2e.ts	e2e
Filename contains .api.ts	api
Filename contains .visual.ts	visual
Default (no signal)	e2e

See test-type-detection skill for detailed detection algorithm.

Framework Detection

Signal	Resolved Framework
next.config.js or next.config.ts present	React (Next.js)
angular.json present	Angular
nuxt.config.js or nuxt.config.ts present	Vue (Nuxt)
package.json dependency next	React (Next.js)
package.json dependency @angular/core	Angular
package.json dependency nuxt	Vue (Nuxt)
package.json dependency react (no Next.js)	React (plain)
package.json dependency vue (no Nuxt)	Vue (plain)
No signals detected	Plain HTML/JavaScript

When multiple signals match, prefer the more specific signal (config file > package.json dep; framework-specific config > generic dep).

Playwright Detection

Signal	Resolved Version
playwright.config.ts or playwright.config.js present with version	Parsed version from file
package.json dependency @playwright/test	Version from package.json
Not present	Use plugin default (latest stable)

Frontend Agent Integration

When enabled (via integrationWithFrontendAgent: true in .playwright-agent.json):

• Attempt to read .frontend-agent.json from the workspace root
• If present, extract: framework, metaFramework, and styling values
• Use these as signals for selector strategy and web server inference
• Read-only mode — do not modify .frontend-agent.json
• If .frontend-agent.json does not exist or is malformed, continue with Playwright-only detection

Selector Strategy Resolution

Resolve the preferred selector strategy for locating UI elements in tests.

Framework	Strategy Options	Auto-Resolved
React	getByRole, getByText, getByTestId, data-testid	getByRole (user-first)
Angular	getByRole, getByText, data-testid, component selectors	getByRole + data-testid
Vue	getByRole, getByText, data-test, component selectors	getByRole + data-test
Plain HTML	semantic selectors, CSS, aria-label	semantic (a, button, input)

When selectorStrategy: auto is set in config, resolve from detected framework using the above table. Otherwise, use explicitly configured strategy.

WebServer Inference

When running e2e tests with webServer block in playwright.config.ts, infer the dev server command and port:

Framework	Dev Command	Default Port
Next.js	next dev	3000
Angular	ng serve	4200
Vue/Nuxt	nuxt dev	3000
Plain	None (assumes running)	3000

These can be overridden in .playwright-agent.json under webServer.

Governance Enforcement

After resolving the configuration, enforce the following constraints. All checks are evaluated before any test action proceeds.

Approved Browsers

If governance.approvedBrowsers is set, verify that each browser used in tests is included in the list. If not, halt with:

Browser '<browser>' is not in approvedBrowsers. Update .playwright-agent.json or contact your admin.

Approved Reporters

If governance.approvedReporters is set, verify that all configured reporters are included in the list. If not, halt with:

Reporter '<reporter>' is not in approvedReporters. Update .playwright-agent.json or contact your admin.

Mandatory Guidelines

If governance.mandatoryGuidelines is true and no guidelines file is resolvable for the active test type, halt with a blocking error:

mandatoryGuidelines is true but no guidelines file is configured for test type '<type>'. Set testTypes.<type>.guidelines in .playwright-agent.json.

Enforced LSP

If governance.enforceLsp is true and the LSP server for TypeScript is not available (not installed, not running, or unreachable), halt with a blocking error:

enforceLsp is true but the TypeScript LSP server is not available. Ensure the language server is installed and running.

Org Policy Endpoint

If governance.orgPolicyEndpoint is configured in .playwright-agent.json, fetch the org policy before resolving governance rules.

Request:

GET <orgPolicyEndpoint>
X-Plugin-Name: playwright-coding-agent
X-Plugin-Version: <current-version>
Authorization: Bearer <token>    (if configured)

Response handling:

Condition	Behavior
Timeout or 5xx	Fail-closed. Halt with: "Cannot reach org policy endpoint. Contact your admin."
401 or 403	Halt with: "Org policy endpoint returned auth error. Check your API token configuration."
Not configured (no endpoint set)	Use .playwright-agent.json governance fields only; skip this step.
200 OK	Merge returned policy over .playwright-agent.json governance fields (policy wins on conflict). Cache the result for 1 hour per session.

The cache is per-session and in-memory. Re-fetch at session start or when the cache is stale.

Output

Emit the resolved configuration as structured data before proceeding. The output includes:

{
  "testType": "<e2e|api|visual>",
  "framework": "<resolved-framework>",
  "selectorStrategy": "<strategy>",
  "webServer": {
    "command": "<dev-command>",
    "port": 3000,
    "reuseExistingServer": false
  },
  "browsers": ["chromium", "firefox", "webkit"],
  "reporters": ["html", "junit", "list"],
  "guidelinesFile": "<path-or-null>",
  "lspAvailable": true,
  "frontendAgentIntegration": false,
  "governance": {
    "approvedBrowsers": [],
    "approvedReporters": [],
    "mandatoryGuidelines": false,
    "enforceLsp": false,
    "orgPolicyEndpoint": "<url-or-null>"
  },
  "resolutionSource": {
    "testType": "<level>",
    "framework": "<level>",
    "selectorStrategy": "<level>",
    "browsers": "<level>"
  }
}

resolutionSource records which level (per-invocation, directory-mapping, auto-detection, config-defaults, plugin-defaults) provided each resolved value, for transparency and debugging.

Categorization Resolution

When categorization is present in the config file, resolve it using the standard 5-level resolution order.

Default behavior:

• New projects (created by /playwright-init): categorization.enabled: true with all four categories active
• Existing projects without a categorization block: categorization.enabled: false — backward compatible, no tags generated
• When securityEnabled: false: coverageBreadth.security is forced to 0 regardless of its configured value

Resolved output includes:

Field	Type	Description
categorization.enabled	boolean	Whether test case categorization is active
categorization.categories	string[]	Active category list (["positive", "negative", "edge", "security"])
categorization.minimumCategoriesPerFeature	integer	Minimum distinct categories required per test.describe block
categorization.securityEnabled	boolean	Whether @security scenarios are generated
categorization.coverageBreadth	object	Minimum scenario counts: { positive: 2, negative: 2, edge: 1, security: 1 }

The resolutionSource object gains a categorization key tracking whether the value came from per-invocation override, config file, or plugin defaults.