playwright-framework-detection

playwright-framework-detection

Detects the target application framework in the workspace to inform Playwright test generation, particularly selector strategy for locating UI elements and web server configuration for e2e tests.

Detection Sources

Apply this priority order to resolve the framework:

1. Frontend Agent Config — if .frontend-agent.json exists and integrationWithFrontendAgent is enabled, read framework and metaFramework (read-only; non-authoritative)
2. package.json Dependencies — check dependencies and devDependencies for framework markers
3. Config Files — check for framework-specific config files (next.config.ts, angular.json, etc.)
4. Directory Structure — infer from directory naming conventions (src/app/ for Angular, app/ for Next.js, etc.)
5. Default Fallback — Plain HTML/JavaScript (no framework)

Signal Table

Signal	Framework	Precedence	Notes
next.config.js or next.config.ts file exists	React (Next.js)	Config file	Most specific Next.js signal
angular.json file exists	Angular	Config file	Most specific Angular signal
nuxt.config.js, nuxt.config.ts, or nuxt.config.mjs file exists	Vue (Nuxt)	Config file	Most specific Nuxt signal
package.json has "next" in deps	React (Next.js)	package.json	Strong signal; verify with config file
package.json has "@angular/core" in deps	Angular	package.json	Strong signal; verify with config file
package.json has "nuxt" in deps	Vue (Nuxt)	package.json	Strong signal; verify with config file
package.json has "react" (and no Next.js signals)	React (plain)	package.json	Generic React without Next.js
package.json has "vue" (and no Nuxt signals)	Vue (plain)	package.json	Generic Vue without Nuxt
Directory src/app/ exists with .ts files	Angular	Directory	Angular CLI convention
Directory app/ exists with Next.js-style routing	React (Next.js)	Directory	Next.js 13+ app directory
No signals detected	Plain HTML/JavaScript	Fallback	Assume static or custom-built app

Signal precedence: Config file > package.json > directory structure > default fallback.

When multiple signals of the same precedence level match, prefer the more specific framework (Next.js > React, Nuxt > Vue).

Selector Strategy Mapping

Based on detected framework, resolve the optimal selector strategy for locating UI elements in tests:

Framework	Selector Strategy	Recommended Locators	Priority
React (any)	User-facing	getByRole, getByText, getByLabel, getByTestId	1. Role > 2. Text > 3. Label > 4. TestId
Angular	Hybrid	getByRole, getByText, data-testid, component selectors	1. Role > 2. TestId > 3. Text
Vue (any)	Hybrid	getByRole, getByText, data-test, component selectors	1. Role > 2. Data-test > 3. Text
Plain HTML	Semantic	semantic HTML selectors (a, button, input), aria-label, CSS (avoid class names)	1. Semantic > 2. ARIA > 3. CSS

When test type is api or visual, selector strategy is not applicable (no page locators needed).

WebServer Inference

For e2e tests, infer the dev server command and port to automate server startup:

Framework	Dev Command	Default Port	Config File	Notes
Next.js	next dev	3000	next.config.js/ts	Supports custom port via -p flag
Angular	ng serve	4200	angular.json	Supports custom port via --port flag
Vue/Nuxt	nuxt dev	3000	nuxt.config.js/ts/mjs	Supports custom port via -p flag
Plain HTML	None (assumed running)	3000	None	Assume user starts server manually

These can be overridden in .playwright-agent.json under webServer.command and webServer.port. When running tests, use the inferred or configured command to start the server before test execution.

Frontend Agent Integration

When integrationWithFrontendAgent: true in .playwright-agent.json:

• Attempt to read .frontend-agent.json from the workspace root
• Extract these fields if present: framework, metaFramework (e.g., next), and styling
• Use these as supporting signals in detection, not authoritative
• If frontend config reports React + Next.js, that reinforces the next dependency signal
• If frontend config conflicts with local signals (e.g., reports Vue but only React packages found), log a warning and prefer local signals
• If .frontend-agent.json does not exist or is malformed, proceed with local signal detection only

Output

Emit structured detection result:

{
  "framework": "<React|Angular|Vue|Plain>",
  "metaFramework": "<Next.js|Nuxt|null>",
  "selectorStrategy": "<user-facing|hybrid|semantic>",
  "webServer": {
    "command": "<dev-command>",
    "port": 3000,
    "reuseExistingServer": false
  },
  "detectedBy": "<config-file|package-json|directory|default>",
  "signals": [
    {
      "source": "<signal-source>",
      "type": "<signal-type>",
      "precedence": "<config-file|package-json|directory|default>",
      "matched": "<matched-value>"
    }
  ],
  "frontendAgentIntegration": {
    "enabled": false,
    "configRead": false,
    "conflicts": []
  }
}

Example output (Next.js + React):

{
  "framework": "React",
  "metaFramework": "Next.js",
  "selectorStrategy": "user-facing",
  "webServer": {
    "command": "next dev",
    "port": 3000,
    "reuseExistingServer": false
  },
  "detectedBy": "config-file",
  "signals": [
    {
      "source": "next.config.ts",
      "type": "config-file",
      "precedence": "config-file",
      "matched": "present"
    },
    {
      "source": "package.json",
      "type": "dependency",
      "precedence": "package-json",
      "matched": "\"next\": \"^14.0.0\""
    }
  ],
  "frontendAgentIntegration": {
    "enabled": true,
    "configRead": true,
    "conflicts": []
  }
}