Skip to content

Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.

feat(agents): add Codex --loop=codex generator (#40817)

Hark Singh [SSW]b07c76ffc3a2
diff --git a/docs/src/test-agents-js.md b/docs/src/test-agents-js.md
index 6ef76dd03d..e1a7bc1f04 100644
--- a/docs/src/test-agents-js.md
+++ b/docs/src/test-agents-js.md
@@ -39,6 +39,10 @@ npx playwright init-agents --loop=vscode
npx playwright init-agents --loop=claude
```
+```bash tab=bash-codex
+npx playwright init-agents --loop=codex
+```
+
```bash tab=bash-opencode
npx playwright init-agents --loop=opencode
```
diff --git a/packages/isomorphic/stringUtils.ts b/packages/isomorphic/stringUtils.ts
index 65dc22051f..c4a3476818 100644
--- a/packages/isomorphic/stringUtils.ts
+++ b/packages/isomorphic/stringUtils.ts
@@ -189,6 +189,21 @@ export function parseRegex(regex: string): RegExp {
return new RegExp(source, flags);
}
+export function tomlBasicString(value: string): string {
+ // JSON.stringify produces a valid TOML basic string: escapes \", \\, \n, \r, \t and uses \uXXXX for control chars.
+ return JSON.stringify(value);
+}
+
+export function tomlArray(values: string[]): string {
+ return `[${values.map(value => tomlBasicString(value)).join(', ')}]`;
+}
+
+export function tomlMultilineBasicString(value: string): string {
+ // Triple-quoted basic string: escape backslashes first, then any literal """ sequences.
+ const escaped = value.replace(/\\/g, '\\\\').replace(/"""/g, '\\"\\"\\"');
+ return `"""\n${escaped}\n"""`;
+}
+
// Semicolons removed from [[\]()#;?] to avoid polynomial backtracking
// when both that group and (?:;...)* can match runs of semicolons.
// \d{1,4} relaxed to \d{0,4} so empty params (e.g. ESC[;H) still match.
diff --git a/packages/playwright/src/agents/DEPS.list b/packages/playwright/src/agents/DEPS.list
index f064674bf4..b28b6edfba 100644
--- a/packages/playwright/src/agents/DEPS.list
+++ b/packages/playwright/src/agents/DEPS.list
@@ -1,4 +1,5 @@
[*]
+@isomorphic/**
@utils/**
../mcp/test/
node_modules/colors/safe
diff --git a/packages/playwright/src/agents/generateAgents.ts b/packages/playwright/src/agents/generateAgents.ts
index ffa5ccf33c..6370ec830c 100644
--- a/packages/playwright/src/agents/generateAgents.ts
+++ b/packages/playwright/src/agents/generateAgents.ts
@@ -19,6 +19,7 @@ import path from 'path';
import colors from 'colors/safe';
import yaml from 'yaml';
+import { tomlArray, tomlBasicString, tomlMultilineBasicString } from '@isomorphic/stringUtils';
import { mkdirIfNeeded } from '@utils/fileUtils';
import { defaultSeedFile, findSeedFile, seedFileContent, seedProject } from '../mcp/test/seed';
@@ -90,6 +91,64 @@ export class ClaudeGenerator {
}
}
+export class CodexGenerator {
+ static async init(fullConfig: FullConfigInternal, projectName: string, prompts: boolean) {
+ await initRepo(fullConfig, projectName, {
+ promptsFolder: prompts ? '.codex/prompts' : undefined,
+ });
+
+ const agents = await loadAgentSpecs();
+
+ await fs.promises.mkdir('.codex/agents', { recursive: true });
+ for (const agent of agents)
+ await writeFile(`.codex/agents/${CodexGenerator.codexName(agent)}.toml`, CodexGenerator.agentSpec(agent), '🤖', 'agent definition');
+
+ initRepoDone();
+ }
+
+ // Codex's subagent registry rejects hyphenated identifiers at spawn time with
+ // `error=unknown agent_type '<name>'`. Codex's own documentation only shows
+ // snake_case names (`pr_explorer`, `reviewer`, `docs_researcher`, ...), see
+ // https://developers.openai.com/codex/subagents. Translate the shared agent
+ // name into snake_case so the filename and the `name` field stay in sync.
+ static codexName(agent: AgentSpec): string {
+ return agent.name.replace(/-/g, '_');
+ }
+
+ static agentSpec(agent: AgentSpec): string {
+ const mcpName = 'playwright-test';
+ const enabledTools: string[] = [];
+ for (const tool of agent.tools) {
+ const [first, second] = tool.split('/');
+ if (second && first === mcpName)
+ enabledTools.push(second);
+ }
+
+ const sandboxMode = agent.tools.includes('edit') ? 'workspace-write' : 'read-only';
+ const mcpServer = process.platform === 'win32'
+ ? { command: 'cmd', args: ['/c', 'npx', 'playwright', 'run-test-mcp-server'] }
+ : { command: 'npx', args: ['playwright', 'run-test-mcp-server'] };
+
+ const examples = agent.examples.length
+ ? ` Examples: ${agent.examples.map(example => `<example>${example}</example>`).join('')}`
+ : '';
+
+ const lines: string[] = [];
+ lines.push(`name = ${tomlBasicString(CodexGenerator.codexName(agent))}`);
+ lines.push(`description = ${tomlBasicString(agent.description + examples)}`);
+ lines.push(`sandbox_mode = ${tomlBasicString(sandboxMode)}`);
+ lines.push(`developer_instructions = ${tomlMultilineBasicString(agent.instructions)}`);
+ lines.push('');
+ lines.push(`[mcp_servers.${mcpName}]`);
+ lines.push(`command = ${tomlBasicString(mcpServer.command)}`);
+ lines.push(`args = ${tomlArray(mcpServer.args)}`);
+ if (enabledTools.length)
+ lines.push(`enabled_tools = ${tomlArray(enabledTools)}`);
+ lines.push('');
+ return lines.join('\n');
+ }
+}
+
export class OpencodeGenerator {
static async init(fullConfig: FullConfigInternal, projectName: string, prompts: boolean) {
await initRepo(fullConfig, projectName, {
@@ -155,6 +214,7 @@ export class OpencodeGenerator {
return JSON.stringify(result, null, 2);
}
}
+
export class CopilotGenerator {
static async init(fullConfig: FullConfigInternal, projectName: string, prompts: boolean) {
diff --git a/packages/playwright/src/program.ts b/packages/playwright/src/program.ts
index ea447ad948..0fd53b4856 100644
--- a/packages/playwright/src/program.ts
+++ b/packages/playwright/src/program.ts
@@ -25,7 +25,7 @@ import { builtInReporters, config, configLoader } from './common';
import { runTests, clearCache, runTestServerAction } from './cli/testActions';
import { showReport, mergeReports } from './cli/reportActions';
import { TestServerBackend, testServerBackendTools } from './mcp/test/testBackend';
-import { ClaudeGenerator, OpencodeGenerator, VSCodeGenerator, CopilotGenerator } from './agents/generateAgents';
+import { ClaudeGenerator, CodexGenerator, OpencodeGenerator, VSCodeGenerator, CopilotGenerator } from './agents/generateAgents';
import { packageJSON } from './package';
export { program };
@@ -155,7 +155,7 @@ function addInitAgentsCommand(program: Command) {
const command = program.command('init-agents');
command.description('Initialize repository agents');
const option = command.createOption('--loop <loop>', 'Agentic loop provider');
- option.choices(['claude', 'copilot', 'opencode', 'vscode', 'vscode-legacy']);
+ option.choices(['claude', 'codex', 'copilot', 'opencode', 'vscode', 'vscode-legacy']);
command.addOption(option);
command.option('-c, --config <file>', `Configuration file to find a project to use for seed test`);
command.option('--project <project>', 'Project to use for seed test');
@@ -168,6 +168,8 @@ function addInitAgentsCommand(program: Command) {
await VSCodeGenerator.init(loadedConfig, opts.project);
} else if (opts.loop === 'claude') {
await ClaudeGenerator.init(loadedConfig, opts.project, opts.prompts);
+ } else if (opts.loop === 'codex') {
+ await CodexGenerator.init(loadedConfig, opts.project, opts.prompts);
} else {
await CopilotGenerator.init(loadedConfig, opts.project, opts.prompts);
return;
diff --git a/tests/mcp/init-agents.spec.ts b/tests/mcp/init-agents.spec.ts
index 65a9641688..dca2fe3945 100644
--- a/tests/mcp/init-agents.spec.ts
+++ b/tests/mcp/init-agents.spec.ts
@@ -90,3 +90,34 @@ test('claude generates correct mcp config', async ({ }) => {
expect(mcpJson.mcpServers['playwright-test'].args).toEqual(['playwright', 'run-test-mcp-server']);
}
});
+
+test('codex generates agent toml files', async ({ }) => {
+ const baseDir = await writeFiles({
+ 'playwright.config.ts': `module.exports = {};`,
+ });
+
+ await runInitAgents({ cwd: baseDir, args: ['--loop', 'codex'] });
+
+ const agentsDir = path.join(baseDir, '.codex', 'agents');
+ expect(fs.existsSync(agentsDir)).toBe(true);
+
+ const plannerToml = fs.readFileSync(path.join(agentsDir, 'playwright_test_planner.toml'), 'utf-8');
+ expect(plannerToml).toContain(`name = "playwright_test_planner"`);
+ expect(plannerToml).toContain(`[mcp_servers.playwright-test]`);
+ expect(plannerToml).toContain(`developer_instructions = """`);
+ if (process.platform === 'win32') {
+ expect(plannerToml).toContain(`command = "cmd"`);
+ expect(plannerToml).toContain(`args = ["/c", "npx", "playwright", "run-test-mcp-server"]`);
+ } else {
+ expect(plannerToml).toContain(`command = "npx"`);
+ expect(plannerToml).toContain(`args = ["playwright", "run-test-mcp-server"]`);
+ }
+
+ expect(plannerToml).toContain(`sandbox_mode = "read-only"`);
+ expect(plannerToml).toMatch(/enabled_tools = \[[^\]]*"planner_save_plan"[^\]]*\]/);
+ expect(plannerToml).toMatch(/enabled_tools = \[[^\]]*"browser_navigate"[^\]]*\]/);
+
+ const healerToml = fs.readFileSync(path.join(agentsDir, 'playwright_test_healer.toml'), 'utf-8');
+ expect(healerToml).toContain(`sandbox_mode = "workspace-write"`);
+ expect(healerToml).toMatch(/enabled_tools = \[[^\]]*"test_debug"[^\]]*\]/);
+});