playwright-test-agent 1.0.2 → 1.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "playwright-test-agent",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Initialize Playwright Test agents with a Playwright CLI-first browser workflow.",
   "type": "module",
   "bin": {

package/playwright-test-agent/SKILL.md

@@ -23,7 +23,7 @@ Before Planner, the parent may read relevant local project information to unders
 
 If the available context is sufficient, start/enter Planner without further confirmation. During exploration, pause when required information is missing, incorrect, or contradictory, including credentials, URL, role, prerequisites, expected behavior that changes assertions, or authorization for a consequential action. Ask the user for the specific correction, then resume or restart Planner with the answer and blocking observation. Do not guess credentials, probe nearby environments, bypass access controls, or wander through unrelated pages.
 
-Keep credentials and tokens in environment variables or ignored secret files. Never copy them into plans, tests, screenshots, evidence, or chat. Browser snapshots and session artifacts produced by `playwright-cli` under `.playwright-cli` are reusable workflow state: preserve them across Planner, Generator, and Healer phases by default. Do not clean up snapshots, sessions, or other transient browser artifacts merely because they were created during validation. Remove or redact only a file that is confirmed to contain an exposed credential/token, or when the user explicitly requests cleanup.
+Keep all runtime configuration—including URLs, accounts, passwords, tokens, and feature flags—in the project-root `.env` file. Commit only `.env.example` with variable names and safe placeholders; `.env` must be ignored by Git. Load it through the project's Playwright/Node configuration (for example, `dotenv/config`) so settings persist for the project without relying on global or one-shot shell environment variables. Never copy secrets into plans, tests, screenshots, evidence, or chat. Browser snapshots and session artifacts produced by `playwright-cli` under `.playwright-cli` are reusable workflow state: preserve them across Planner, Generator, and Healer phases by default. Do not clean up snapshots, sessions, or other transient browser artifacts merely because they were created during validation. Remove or redact only a file that is confirmed to contain an exposed credential/token, or when the user explicitly requests cleanup.
 
 ## Planner
 
@@ -37,7 +37,7 @@ Planner, Generator, and Healer may reuse the existing `.playwright-cli` session
 
 ## Generator
 
-Generator starts only after confirmation and converts the confirmed plan into executable Playwright test code. Pass the resolved Playwright `testDir` to Generator. Generator—not the parent—uses `playwright-cli` to validate flows, locators, and assertions, writes every new test inside that configured `testDir`, and returns their paths. Generic `tests/` paths in generated role examples, plans, or seed references do not override the configured directory. Generate only confirmed scenarios; prefer independent tests, semantic locators, explicit assertions, and environment-based secrets.
+Generator starts only after confirmation and converts the confirmed plan into executable Playwright test code. Pass the resolved Playwright `testDir` to Generator. Generator—not the parent—uses `playwright-cli` to validate flows, locators, and assertions, writes every new test inside that configured `testDir`, and returns their paths. Generic `tests/` paths in generated role examples, plans, or seed references do not override the configured directory. Generate only confirmed scenarios; prefer independent tests, semantic locators, explicit assertions, and values loaded from the project's `.env` file.
 
 After Generator returns, the parent executes the generated test files with `npx playwright test`. This execution step is mandatory. If all tests pass, report the executed result. If any fail, pass the failed test names, failure output, confirmed plan, and generated file paths to Healer.
 

package/playwright-test-agent/scripts/init-playwright.mjs

@@ -13,7 +13,7 @@ const cliFirstInstructions = (role) => `${ROLE_BLOCK_START}
 
 ## Browser tool priority
 
-Use the installed \`playwright-cli\` command as the primary browser interface for this role. Read the globally installed \`playwright-cli\` skill when available. Start or attach a session with \`playwright-cli open\`/\`attach\`, navigate with \`goto\`, inspect compact state with \`snapshot\`, and interact through refs from the latest snapshot. Prefer \`snapshot\` and \`find\` over screenshots. Keep credentials in environment variables or ignored files and never print them. Preserve \`.playwright-cli\` snapshots, sessions, and other browser artifacts for reuse by later phases; do not delete validation artifacts by default. Only remove or redact a confirmed credential/token leak, or act on an explicit cleanup request.
+Use the installed \`playwright-cli\` command as the primary browser interface for this role. Read the globally installed \`playwright-cli\` skill when available. Start or attach a session with \`playwright-cli open\`/\`attach\`, navigate with \`goto\`, inspect compact state with \`snapshot\`, and interact through refs from the latest snapshot. Prefer \`snapshot\` and \`find\` over screenshots. Keep all runtime configuration in the project-root \`.env\` file (commit only \`.env.example\`); load it through Playwright/Node configuration and never rely on global or one-shot shell variables. Never print secrets. Preserve \`.playwright-cli\` snapshots, sessions, and other browser artifacts for reuse by later phases; do not delete validation artifacts by default. Only remove or redact a confirmed credential/token leak, or act on an explicit cleanup request.
 
 Keep the official Playwright Test MCP configuration and tools generated for this role; do not remove or disable them. Prefer CLI for live page interaction and use it when those MCP tools are unavailable, so missing \`planner_*\`, \`generator_*\`, \`test_*\`, or \`browser_*\` tools must not block the phase. Do not call Chrome DevTools or an unrelated browser integration, and do not spawn a nested or same-role agent.
 
@@ -113,6 +113,27 @@ async function updateInstructionFiles(projectDir) {
   }
 }
 
+async function ensureEnvFiles(projectDir) {
+  const examplePath = path.join(projectDir, '.env.example');
+  if (!await exists(examplePath)) {
+    await writeFile(examplePath,
+      '# Copy this file to .env and fill in project-specific runtime settings.\n' +
+      '# Keep .env local; never commit secrets.\n' +
+      '# BASE_URL=https://example.test\n' +
+      '# TEST_USERNAME=\n' +
+      '# TEST_PASSWORD=\n', 'utf8');
+  }
+
+  const gitignorePath = path.join(projectDir, '.gitignore');
+  const source = await exists(gitignorePath) ? await readFile(gitignorePath, 'utf8') : '';
+  const entries = ['.env', '.env.*', '!.env.example', '.playwright-evidence/', '.playwright-cli/'];
+  const missing = entries.filter((entry) => !source.split(/\r?\n/).includes(entry));
+  if (missing.length > 0) {
+    const prefix = source.length === 0 || source.endsWith('\n') ? source : `${source}\n`;
+    await writeFile(gitignorePath, `${prefix}\n# Playwright Test Agent local configuration\n${missing.join('\n')}\n`, 'utf8');
+  }
+}
+
 function withRoleBlock(source, role) {
   const start = source.indexOf(ROLE_BLOCK_START);
   const end = source.indexOf(ROLE_BLOCK_END);
@@ -253,9 +274,12 @@ async function installPlaywrightCli(projectDir, run) {
   await run(projectDir, 'playwright-cli', ['install-browser']);
 }
 
-async function patchPlaywrightConfig(projectDir) {
-  const configPath = path.join(projectDir, 'playwright.config.ts');
-  let source = await readFile(configPath, 'utf8');
+async function patchPlaywrightConfig(projectDir) {
+  const configPath = path.join(projectDir, 'playwright.config.ts');
+  let source = await readFile(configPath, 'utf8');
+  if (!/^import\s+['"]dotenv\/config['"];?/m.test(source)) {
+    source = `import 'dotenv/config';\n${source}`;
+  }
   source = source.replace(/testDir:\s*['"]\.\/tests['"]/, "testDir: './playwright-tests'");
   source = source.replace(
     /reporter:\s*['"]html['"],?/,
@@ -315,10 +339,15 @@ async function initializePlaywright(projectDir, run) {
       await mkdir(targetDir, { recursive: true });
       await rename(generatedExample, path.join(targetDir, 'example.spec.ts'));
     }
-    await patchPlaywrightConfig(projectDir);
-  }
+  }
+
+  await patchPlaywrightConfig(projectDir);
 
-  await disableTraceScreenshots(projectDir);
+  await disableTraceScreenshots(projectDir);
+
+  if (await exists(path.join(projectDir, 'package.json'))) {
+    await run(projectDir, 'npm', ['install', '--save-dev', 'dotenv']);
+  }
 
   await run(projectDir, 'npx', ['--no-install', 'playwright', 'init-agents', '--loop=codex']);
   await run(projectDir, 'npx', ['--no-install', 'playwright', 'init-agents', '--loop=claude']);
@@ -347,7 +376,8 @@ export async function initializeProject({
   await runStage('installing skill', () => installSkill(target, skillSourceDir));
   await runStage('installing Playwright CLI and browser', () => installPlaywrightCli(target, run));
   await runStage('initializing Playwright Test agents', () => initializePlaywright(target, run));
-  await runStage('updating project instructions', () => updateInstructionFiles(target));
+  await runStage('configuring project .env files', () => ensureEnvFiles(target));
+  await runStage('updating project instructions', () => updateInstructionFiles(target));
 
   process.stdout.write(
     'Playwright Test Agent ready: Playwright CLI and skills installed globally, ' +