From 679ab5371c6c8e53c913ba39430f243c1a5e9f8b Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 5 Sep 2026 10:27:07 +0000
Subject: [PATCH 1/5] Improve Playwright browser provisioning guidance

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
 .../improve-playwright-browser-guidance.md    |   5 +
 .github/aw/playwright.md                      |  22 +++-
 pkg/workflow/compiler_validators.go           |   1 +
 pkg/workflow/playwright_validation.go         |  44 ++++++++
 pkg/workflow/playwright_validation_test.go    | 106 ++++++++++++++++++
 5 files changed, 172 insertions(+), 6 deletions(-)
 create mode 100644 .changeset/improve-playwright-browser-guidance.md

diff --git a/.changeset/improve-playwright-browser-guidance.md b/.changeset/improve-playwright-browser-guidance.md
new file mode 100644
index 00000000000..45be8ed8048
--- /dev/null
+++ b/.changeset/improve-playwright-browser-guidance.md
@@ -0,0 +1,5 @@
+---
+gh-aw: patch
+---
+
+Warn when workflow steps install Playwright browser engines and direct authors to `tools.playwright.browsers`.
diff --git a/.github/aw/playwright.md b/.github/aw/playwright.md
index f9891a0f712..7a06fdd075a 100644
--- a/.github/aw/playwright.md
+++ b/.github/aw/playwright.md
@@ -17,12 +17,22 @@ tools:
   playwright:
 ```
 
-The compiler installs the pinned default `@playwright/cli` package and its agent
-skills. It also provisions Chromium, Firefox, and WebKit before the agent starts;
-the default `open` session uses Chromium. Do not add installation steps to the
-workflow: runtime installation of packages or browsers is prohibited. Pin
-`version` only when reproducible browser output is required, such as for visual
-baselines:
+The compiler installs the pinned default `@playwright/cli` package, its agent
+skills, and Chromium before the agent starts. The default `open` session uses
+Chromium. To use other browser engines, list them in `browsers`; `chrome` is an
+alias for `chromium`:
+
+```yaml
+tools:
+  playwright:
+    browsers: [chromium, firefox, webkit]
+```
+
+Supported values are `chrome`, `chromium`, `firefox`, and `webkit`. Do not add
+steps such as `npx playwright install` or `npm exec playwright install`; the
+compiler provisions the selected engines, and browser installation during agent
+execution is prohibited. Pin `version` only when reproducible browser output is
+required, such as for visual baselines:
 
 ```yaml
 tools:
diff --git a/pkg/workflow/compiler_validators.go b/pkg/workflow/compiler_validators.go
index 70a117b4d2d..9cd2c239347 100644
--- a/pkg/workflow/compiler_validators.go
+++ b/pkg/workflow/compiler_validators.go
@@ -434,6 +434,7 @@ func (c *Compiler) emitGeneralToolWarnings(workflowData *WorkflowData, markdownP
 	}
 	c.emitSandboxRuntimeWarnings(workflowData, markdownPath)
 	c.emitPiThreatDetectionAuthWarning(workflowData, markdownPath)
+	c.emitPlaywrightBrowserInstallWarning(workflowData, markdownPath)
 	if workflowData.SafeOutputs != nil && workflowData.SafeOutputs.AssignToAgent != nil &&
 		workflowData.SafeOutputs.GitHubApp != nil && workflowData.SafeOutputs.AssignToAgent.GitHubToken == "" {
 		fmt.Fprintln(os.Stderr, console.FormatWarningMessageStderr(
diff --git a/pkg/workflow/playwright_validation.go b/pkg/workflow/playwright_validation.go
index 5ed3391f576..5e9699ecc5d 100644
--- a/pkg/workflow/playwright_validation.go
+++ b/pkg/workflow/playwright_validation.go
@@ -26,9 +26,15 @@ package workflow
 
 import (
 	"fmt"
+	"os"
+	"regexp"
 	"strings"
+
+	"github.com/goccy/go-yaml"
 )
 
+var playwrightBrowserInstallPattern = regexp.MustCompile(`(?im)(?:^|&&|\|\||;)[ \t]*(?:(?:npx|npm[ \t]+(?:exec|x)|pnpm[ \t]+(?:exec|dlx)|yarn(?:[ \t]+dlx)?|bunx)[ \t]+(?:(?:--yes|--no-install|--)[ \t]+)*)?playwright(?:@[^\s;&|]+)?[ \t]+install(?:[ \t]|$)`)
+
 func normalizePlaywrightBrowser(browser string) string {
 	switch strings.ToLower(strings.TrimSpace(browser)) {
 	case "chrome", "chromium":
@@ -94,3 +100,41 @@ func (c *Compiler) validatePlaywrightMode(workflowData *WorkflowData) error {
 	}
 	return nil
 }
+
+func (c *Compiler) emitPlaywrightBrowserInstallWarning(workflowData *WorkflowData, markdownPath string) {
+	if workflowData == nil || !isPlaywrightCLIMode(workflowData.Tools) || !hasPlaywrightBrowserInstallStep(workflowData) {
+		return
+	}
+
+	fmt.Fprintln(os.Stderr, formatCompilerMessage(markdownPath, "warning",
+		"custom steps install Playwright browser engines. Remove those installation commands and use `tools.playwright.browsers` instead; the compiler provisions the selected browsers before the agent starts."))
+	c.IncrementWarningCount()
+}
+
+func hasPlaywrightBrowserInstallStep(workflowData *WorkflowData) bool {
+	sections := []struct {
+		name    string
+		content string
+	}{
+		{name: "pre-steps", content: workflowData.PreSteps},
+		{name: "steps", content: workflowData.CustomSteps},
+		{name: "pre-agent-steps", content: workflowData.PreAgentSteps},
+		{name: "post-steps", content: workflowData.PostSteps},
+	}
+
+	for _, section := range sections {
+		if section.content == "" {
+			continue
+		}
+		var wrapper map[string][]WorkflowStep
+		if err := yaml.Unmarshal([]byte(section.content), &wrapper); err != nil {
+			continue
+		}
+		for _, step := range wrapper[section.name] {
+			if playwrightBrowserInstallPattern.MatchString(step.Run) {
+				return true
+			}
+		}
+	}
+	return false
+}
diff --git a/pkg/workflow/playwright_validation_test.go b/pkg/workflow/playwright_validation_test.go
index 6141a0da9e1..0e0f72669c7 100644
--- a/pkg/workflow/playwright_validation_test.go
+++ b/pkg/workflow/playwright_validation_test.go
@@ -7,6 +7,7 @@ import (
 	"path/filepath"
 	"testing"
 
+	"github.com/github/gh-aw/pkg/testutil"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
@@ -221,3 +222,108 @@ func TestValidatePlaywrightBrowsers(t *testing.T) {
 	}})
 	require.Error(t, err)
 }
+
+func TestEmitPlaywrightBrowserInstallWarning(t *testing.T) {
+	tests := []struct {
+		name        string
+		tools       map[string]any
+		customSteps string
+		wantWarning bool
+	}{
+		{
+			name:  "npm exec browser install",
+			tools: map[string]any{"playwright": nil},
+			customSteps: `steps:
+- name: Install Playwright Chromium
+  run: npm exec playwright install --with-deps chromium
+`,
+			wantWarning: true,
+		},
+		{
+			name:  "npx browser install",
+			tools: map[string]any{"playwright": nil},
+			customSteps: `steps:
+- run: npx --yes playwright@latest install firefox
+`,
+			wantWarning: true,
+		},
+		{
+			name:  "browser install after another command",
+			tools: map[string]any{"playwright": nil},
+			customSteps: `steps:
+- run: npm ci && pnpm exec playwright install webkit
+`,
+			wantWarning: true,
+		},
+		{
+			name:  "skills install is not a browser install",
+			tools: map[string]any{"playwright": nil},
+			customSteps: `steps:
+- run: playwright-cli install --skills
+`,
+		},
+		{
+			name:  "package install is not a browser install",
+			tools: map[string]any{"playwright": nil},
+			customSteps: `steps:
+- run: npm install playwright
+`,
+		},
+		{
+			name:  "disabled Playwright tool",
+			tools: map[string]any{"playwright": false},
+			customSteps: `steps:
+- run: npx playwright install chromium
+`,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			compiler := NewCompiler()
+			output := testutil.CaptureStderr(t, func() {
+				compiler.emitPlaywrightBrowserInstallWarning(&WorkflowData{
+					Tools:       tt.tools,
+					CustomSteps: tt.customSteps,
+				}, "test.md")
+			})
+
+			if tt.wantWarning {
+				assert.Contains(t, output, "use `tools.playwright.browsers` instead")
+				assert.Equal(t, 1, compiler.GetWarningCount())
+			} else {
+				assert.Empty(t, output)
+				assert.Zero(t, compiler.GetWarningCount())
+			}
+		})
+	}
+}
+
+func TestCompileWorkflowWarnsAboutPlaywrightBrowserInstallStep(t *testing.T) {
+	tmpDir := t.TempDir()
+	mdPath := filepath.Join(tmpDir, "test-workflow.md")
+	content := `---
+on: push
+permissions:
+  contents: read
+engine: copilot
+tools:
+  playwright:
+    browsers: [chromium]
+steps:
+  - name: Install Playwright Chromium
+    run: npm exec playwright install --with-deps chromium
+---
+
+# Test Workflow
+`
+	require.NoError(t, os.WriteFile(mdPath, []byte(content), 0o644))
+
+	compiler := NewCompiler()
+	output := testutil.CaptureStderr(t, func() {
+		require.NoError(t, compiler.CompileWorkflow(mdPath))
+	})
+
+	assert.Contains(t, output, "use `tools.playwright.browsers` instead")
+	assert.Equal(t, 1, compiler.GetWarningCount())
+}

From ed0dd6cbf26736ab34ecd42acc82ed090b0d628a Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 5 Sep 2026 10:30:48 +0000
Subject: [PATCH 2/5] Harden Playwright install step detection

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
 pkg/workflow/playwright_validation.go      | 25 +++++++++++-----------
 pkg/workflow/playwright_validation_test.go | 22 +++++++++++++------
 2 files changed, 28 insertions(+), 19 deletions(-)

diff --git a/pkg/workflow/playwright_validation.go b/pkg/workflow/playwright_validation.go
index 5e9699ecc5d..861455c65c8 100644
--- a/pkg/workflow/playwright_validation.go
+++ b/pkg/workflow/playwright_validation.go
@@ -112,27 +112,26 @@ func (c *Compiler) emitPlaywrightBrowserInstallWarning(workflowData *WorkflowDat
 }
 
 func hasPlaywrightBrowserInstallStep(workflowData *WorkflowData) bool {
-	sections := []struct {
-		name    string
-		content string
-	}{
-		{name: "pre-steps", content: workflowData.PreSteps},
-		{name: "steps", content: workflowData.CustomSteps},
-		{name: "pre-agent-steps", content: workflowData.PreAgentSteps},
-		{name: "post-steps", content: workflowData.PostSteps},
+	sections := []string{
+		workflowData.PreSteps,
+		workflowData.CustomSteps,
+		workflowData.PreAgentSteps,
+		workflowData.PostSteps,
 	}
 
 	for _, section := range sections {
-		if section.content == "" {
+		if section == "" {
 			continue
 		}
 		var wrapper map[string][]WorkflowStep
-		if err := yaml.Unmarshal([]byte(section.content), &wrapper); err != nil {
+		if err := yaml.Unmarshal([]byte(section), &wrapper); err != nil {
 			continue
 		}
-		for _, step := range wrapper[section.name] {
-			if playwrightBrowserInstallPattern.MatchString(step.Run) {
-				return true
+		for _, steps := range wrapper {
+			for _, step := range steps {
+				if playwrightBrowserInstallPattern.MatchString(step.Run) {
+					return true
+				}
 			}
 		}
 	}
diff --git a/pkg/workflow/playwright_validation_test.go b/pkg/workflow/playwright_validation_test.go
index 0e0f72669c7..2c7b32b9788 100644
--- a/pkg/workflow/playwright_validation_test.go
+++ b/pkg/workflow/playwright_validation_test.go
@@ -225,10 +225,11 @@ func TestValidatePlaywrightBrowsers(t *testing.T) {
 
 func TestEmitPlaywrightBrowserInstallWarning(t *testing.T) {
 	tests := []struct {
-		name        string
-		tools       map[string]any
-		customSteps string
-		wantWarning bool
+		name          string
+		tools         map[string]any
+		customSteps   string
+		preAgentSteps string
+		wantWarning   bool
 	}{
 		{
 			name:  "npm exec browser install",
@@ -252,6 +253,14 @@ func TestEmitPlaywrightBrowserInstallWarning(t *testing.T) {
 			tools: map[string]any{"playwright": nil},
 			customSteps: `steps:
 - run: npm ci && pnpm exec playwright install webkit
+`,
+			wantWarning: true,
+		},
+		{
+			name:  "browser install in pre-agent steps",
+			tools: map[string]any{"playwright": nil},
+			preAgentSteps: `pre-agent-steps:
+- run: bunx playwright install chromium
 `,
 			wantWarning: true,
 		},
@@ -283,8 +292,9 @@ func TestEmitPlaywrightBrowserInstallWarning(t *testing.T) {
 			compiler := NewCompiler()
 			output := testutil.CaptureStderr(t, func() {
 				compiler.emitPlaywrightBrowserInstallWarning(&WorkflowData{
-					Tools:       tt.tools,
-					CustomSteps: tt.customSteps,
+					Tools:         tt.tools,
+					CustomSteps:   tt.customSteps,
+					PreAgentSteps: tt.preAgentSteps,
 				}, "test.md")
 			})
 

From 427c47dfb915c1344e97147d03860a0ff344c0db Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 5 Sep 2026 10:34:06 +0000
Subject: [PATCH 3/5] Expand Playwright install warning coverage

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
 pkg/workflow/playwright_validation_test.go | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/pkg/workflow/playwright_validation_test.go b/pkg/workflow/playwright_validation_test.go
index 2c7b32b9788..e36ee4669f1 100644
--- a/pkg/workflow/playwright_validation_test.go
+++ b/pkg/workflow/playwright_validation_test.go
@@ -227,8 +227,10 @@ func TestEmitPlaywrightBrowserInstallWarning(t *testing.T) {
 	tests := []struct {
 		name          string
 		tools         map[string]any
+		preSteps      string
 		customSteps   string
 		preAgentSteps string
+		postSteps     string
 		wantWarning   bool
 	}{
 		{
@@ -253,6 +255,14 @@ func TestEmitPlaywrightBrowserInstallWarning(t *testing.T) {
 			tools: map[string]any{"playwright": nil},
 			customSteps: `steps:
 - run: npm ci && pnpm exec playwright install webkit
+`,
+			wantWarning: true,
+		},
+		{
+			name:  "bare browser install in pre-steps",
+			tools: map[string]any{"playwright": nil},
+			preSteps: `pre-steps:
+- run: playwright install chromium
 `,
 			wantWarning: true,
 		},
@@ -261,6 +271,14 @@ func TestEmitPlaywrightBrowserInstallWarning(t *testing.T) {
 			tools: map[string]any{"playwright": nil},
 			preAgentSteps: `pre-agent-steps:
 - run: bunx playwright install chromium
+`,
+			wantWarning: true,
+		},
+		{
+			name:  "browser install in post-steps",
+			tools: map[string]any{"playwright": nil},
+			postSteps: `post-steps:
+- run: yarn dlx playwright install webkit
 `,
 			wantWarning: true,
 		},
@@ -293,8 +311,10 @@ func TestEmitPlaywrightBrowserInstallWarning(t *testing.T) {
 			output := testutil.CaptureStderr(t, func() {
 				compiler.emitPlaywrightBrowserInstallWarning(&WorkflowData{
 					Tools:         tt.tools,
+					PreSteps:      tt.preSteps,
 					CustomSteps:   tt.customSteps,
 					PreAgentSteps: tt.preAgentSteps,
+					PostSteps:     tt.postSteps,
 				}, "test.md")
 			})
 

From 0f4ae739b1181f6792e21fc0b83b17f4ee54c2e2 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 5 Sep 2026 10:37:37 +0000
Subject: [PATCH 4/5] Detect Yarn Playwright browser installs

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
 pkg/workflow/playwright_validation.go      | 2 +-
 pkg/workflow/playwright_validation_test.go | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/pkg/workflow/playwright_validation.go b/pkg/workflow/playwright_validation.go
index 861455c65c8..a37c23f0e6b 100644
--- a/pkg/workflow/playwright_validation.go
+++ b/pkg/workflow/playwright_validation.go
@@ -33,7 +33,7 @@ import (
 	"github.com/goccy/go-yaml"
 )
 
-var playwrightBrowserInstallPattern = regexp.MustCompile(`(?im)(?:^|&&|\|\||;)[ \t]*(?:(?:npx|npm[ \t]+(?:exec|x)|pnpm[ \t]+(?:exec|dlx)|yarn(?:[ \t]+dlx)?|bunx)[ \t]+(?:(?:--yes|--no-install|--)[ \t]+)*)?playwright(?:@[^\s;&|]+)?[ \t]+install(?:[ \t]|$)`)
+var playwrightBrowserInstallPattern = regexp.MustCompile(`(?im)(?:^|&&|\|\||;)[ \t]*(?:(?:npx|npm[ \t]+(?:exec|x)|pnpm[ \t]+(?:exec|dlx)|yarn(?:[ \t]+(?:exec|dlx))?|bunx)[ \t]+(?:(?:--yes|--no-install|--)[ \t]+)*)?playwright(?:@[^\s;&|]+)?[ \t]+install(?:[ \t]|$)`)
 
 func normalizePlaywrightBrowser(browser string) string {
 	switch strings.ToLower(strings.TrimSpace(browser)) {
diff --git a/pkg/workflow/playwright_validation_test.go b/pkg/workflow/playwright_validation_test.go
index e36ee4669f1..ca8bab410aa 100644
--- a/pkg/workflow/playwright_validation_test.go
+++ b/pkg/workflow/playwright_validation_test.go
@@ -278,7 +278,7 @@ func TestEmitPlaywrightBrowserInstallWarning(t *testing.T) {
 			name:  "browser install in post-steps",
 			tools: map[string]any{"playwright": nil},
 			postSteps: `post-steps:
-- run: yarn dlx playwright install webkit
+- run: yarn exec playwright install webkit
 `,
 			wantWarning: true,
 		},

From fbc34c0ac3273eb9b852d0a0fa267c2817b806aa Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 5 Sep 2026 11:10:16 +0000
Subject: [PATCH 5/5] Support Chrome for Testing browser alias

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
 .github/aw/playwright.md                        | 17 ++++++++++-------
 .../content/docs/reference/frontmatter-full.md  |  4 ++--
 docs/src/content/docs/reference/playwright.md   |  8 +++++---
 pkg/parser/schemas/main_workflow_schema.json    |  4 ++--
 pkg/workflow/playwright_cli_test.go             |  2 +-
 pkg/workflow/playwright_validation.go           |  4 ++--
 pkg/workflow/playwright_validation_test.go      |  7 +++++--
 7 files changed, 27 insertions(+), 19 deletions(-)

diff --git a/.github/aw/playwright.md b/.github/aw/playwright.md
index 7a06fdd075a..191c9a3eb28 100644
--- a/.github/aw/playwright.md
+++ b/.github/aw/playwright.md
@@ -19,8 +19,9 @@ tools:
 
 The compiler installs the pinned default `@playwright/cli` package, its agent
 skills, and Chromium before the agent starts. The default `open` session uses
-Chromium. To use other browser engines, list them in `browsers`; `chrome` is an
-alias for `chromium`:
+Chromium. To use other browser engines, list them in `browsers`. Playwright's
+`chromium` download is the Chrome for Testing distribution; `chrome` and
+`chrome-for-testing` are accepted aliases:
 
 ```yaml
 tools:
@@ -28,11 +29,13 @@ tools:
     browsers: [chromium, firefox, webkit]
 ```
 
-Supported values are `chrome`, `chromium`, `firefox`, and `webkit`. Do not add
-steps such as `npx playwright install` or `npm exec playwright install`; the
-compiler provisions the selected engines, and browser installation during agent
-execution is prohibited. Pin `version` only when reproducible browser output is
-required, such as for visual baselines:
+Supported values are `chrome`, `chrome-for-testing`, `chromium`, `firefox`, and
+`webkit`. The broader Playwright install-target list also contains system browser
+channels and platform-specific tools, but those are not portable browser engines
+for this field. Do not add steps such as `npx playwright install` or
+`npm exec playwright install`; the compiler provisions the selected engines, and
+browser installation during agent execution is prohibited. Pin `version` only
+when reproducible browser output is required, such as for visual baselines:
 
 ```yaml
 tools:
diff --git a/docs/src/content/docs/reference/frontmatter-full.md b/docs/src/content/docs/reference/frontmatter-full.md
index 6efa9459b97..9b6a5418c6b 100644
--- a/docs/src/content/docs/reference/frontmatter-full.md
+++ b/docs/src/content/docs/reference/frontmatter-full.md
@@ -4208,8 +4208,8 @@ tools:
     # GitHub Actions expression.
     mode: "example-value"
 
-    # Browsers to provision before the agent starts. Defaults to Chromium. Chrome is
-    # accepted as an alias for Chromium.
+    # Browsers to provision before the agent starts. Defaults to Chromium. Chrome and
+    # Chrome for Testing are accepted as aliases for Chromium.
     # (optional)
     browsers: []
       # Array of strings
diff --git a/docs/src/content/docs/reference/playwright.md b/docs/src/content/docs/reference/playwright.md
index 85d919f46ec..82c8a5b8569 100644
--- a/docs/src/content/docs/reference/playwright.md
+++ b/docs/src/content/docs/reference/playwright.md
@@ -18,8 +18,9 @@ tools:
 
 The compiler installs `@playwright/cli` as a global npm package, its skills, and
 Chromium before the agent runs. The default `open` browser is Chromium. Select
-additional browsers with `browsers`; `chrome` is accepted as an alias for
-`chromium`:
+additional browsers with `browsers`. Playwright's `chromium` download is the
+Chrome for Testing distribution; `chrome` and `chrome-for-testing` are accepted
+aliases:
 
 ```yaml wrap
 tools:
@@ -27,7 +28,8 @@ tools:
     browsers: [chrome, firefox]
 ```
 
-The supported values are `chrome`, `chromium`, `firefox`, and `webkit`.
+The supported values are `chrome`, `chrome-for-testing`, `chromium`, `firefox`,
+and `webkit`.
 Requested browsers are downloaded with retries before the agent starts; package
 and browser installation during agent execution is prohibited. The agent
 invokes `playwright-cli <command>` from bash:
diff --git a/pkg/parser/schemas/main_workflow_schema.json b/pkg/parser/schemas/main_workflow_schema.json
index c190184610e..9b85cda0276 100644
--- a/pkg/parser/schemas/main_workflow_schema.json
+++ b/pkg/parser/schemas/main_workflow_schema.json
@@ -4966,10 +4966,10 @@
                 },
                 "browsers": {
                   "type": "array",
-                  "description": "Browsers to provision before the agent starts. Defaults to Chromium. Chrome is accepted as an alias for Chromium.",
+                  "description": "Browsers to provision before the agent starts. Defaults to Chromium. Chrome and Chrome for Testing are accepted as aliases for Chromium.",
                   "items": {
                     "type": "string",
-                    "enum": ["chrome", "chromium", "firefox", "webkit"]
+                    "enum": ["chrome", "chrome-for-testing", "chromium", "firefox", "webkit"]
                   },
                   "minItems": 1,
                   "uniqueItems": true
diff --git a/pkg/workflow/playwright_cli_test.go b/pkg/workflow/playwright_cli_test.go
index cdb78b0ae4d..83d4df9c563 100644
--- a/pkg/workflow/playwright_cli_test.go
+++ b/pkg/workflow/playwright_cli_test.go
@@ -50,7 +50,7 @@ func TestGeneratePlaywrightCLIInstallSteps_ModeOmitted(t *testing.T) {
 func TestGeneratePlaywrightCLIInstallSteps_SelectedBrowsers(t *testing.T) {
 	steps := generatePlaywrightCLIInstallSteps(&WorkflowData{
 		Tools: map[string]any{"playwright": map[string]any{
-			"browsers": []any{"chrome", "Firefox", "webkit", "chrome"},
+			"browsers": []any{"chrome", "Firefox", "webkit", "chrome-for-testing", "chrome"},
 		}},
 	})
 
diff --git a/pkg/workflow/playwright_validation.go b/pkg/workflow/playwright_validation.go
index a37c23f0e6b..78d695ae015 100644
--- a/pkg/workflow/playwright_validation.go
+++ b/pkg/workflow/playwright_validation.go
@@ -37,7 +37,7 @@ var playwrightBrowserInstallPattern = regexp.MustCompile(`(?im)(?:^|&&|\|\||;)[
 
 func normalizePlaywrightBrowser(browser string) string {
 	switch strings.ToLower(strings.TrimSpace(browser)) {
-	case "chrome", "chromium":
+	case "chrome", "chrome-for-testing", "chromium":
 		return "chromium"
 	case "firefox":
 		return "firefox"
@@ -91,7 +91,7 @@ func (c *Compiler) validatePlaywrightMode(workflowData *WorkflowData) error {
 					return NewValidationError(
 						"tools.playwright.browsers",
 						fmt.Sprint(browser),
-						"unsupported browser; choose chrome, chromium, firefox, or webkit",
+						"unsupported browser; choose chrome, chrome-for-testing, chromium, firefox, or webkit",
 						"Set browsers to a list containing supported Playwright browser names",
 					)
 				}
diff --git a/pkg/workflow/playwright_validation_test.go b/pkg/workflow/playwright_validation_test.go
index ca8bab410aa..bcbd6f4a1dd 100644
--- a/pkg/workflow/playwright_validation_test.go
+++ b/pkg/workflow/playwright_validation_test.go
@@ -213,7 +213,7 @@ func TestValidatePlaywrightModeNilWorkflow(t *testing.T) {
 func TestValidatePlaywrightBrowsers(t *testing.T) {
 	compiler := NewCompiler()
 	err := compiler.validatePlaywrightMode(&WorkflowData{Tools: map[string]any{
-		"playwright": map[string]any{"browsers": []any{"chrome", "firefox"}},
+		"playwright": map[string]any{"browsers": []any{"chrome", "chrome-for-testing", "firefox"}},
 	}})
 	require.NoError(t, err)
 
@@ -339,7 +339,7 @@ permissions:
 engine: copilot
 tools:
   playwright:
-    browsers: [chromium]
+    browsers: [chrome-for-testing]
 steps:
   - name: Install Playwright Chromium
     run: npm exec playwright install --with-deps chromium
@@ -356,4 +356,7 @@ steps:
 
 	assert.Contains(t, output, "use `tools.playwright.browsers` instead")
 	assert.Equal(t, 1, compiler.GetWarningCount())
+	lockContent, err := os.ReadFile(filepath.Join(tmpDir, "test-workflow.lock.yml"))
+	require.NoError(t, err)
+	assert.Contains(t, string(lockContent), `install_playwright_browsers.sh" chromium`)
 }