Document Playwright MCP usage to prevent module loading errors

[Copilot]

AI agents in the daily-multi-device-docs-tester workflow attempted require('playwright'), which fails because Playwright is provided via MCP server (Docker container), not as an npm package.

Changes:

• Workflow prompt (.github/workflows/daily-multi-device-docs-tester.md):

  • Added explicit MCP usage instructions with code examples
  • Documented incorrect patterns to avoid
  • Fixed docs URL: localhost:4321 → localhost:4321/gh-aw/

• Troubleshooting docs (docs/src/content/docs/troubleshooting/common-issues.md):

  • New "Cannot Find Module 'playwright'" section
  • Shows MCP tool alternatives with examples

Incorrect (fails):

const playwright = require('playwright');
const browser = await playwright.chromium.launch();

Correct (MCP tools):

await mcp__playwright__browser_run_code({
  code: `async (page) => {
    await page.setViewportSize({ width: 390, height: 844 });
    await page.goto('http://localhost:4321/gh-aw/');
    return { url: page.url(), title: await page.title() };
  }`
});

Available MCP tools: browser_navigate, browser_run_code, browser_snapshot, browser_click, browser_type, browser_close.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• https://api.github.com/user
  • Triggering command: /usr/bin/gh gh api user --jq .login (http block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

Reference: https://github.com/github/gh-aw/actions/runs/22028279959/job/63648613335#step:33:1

Investigate playwright failed to load. Look at the playwright logs

Custom agent used: agentic-workflows
GitHub Agentic Workflows (gh-aw) - Create, debug, and upgrade AI-powered workflows with intelligent prompt routing

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

---

✨ PR Review Safe Output Test - Run 22028525088

💥 [THE END] — Illustrated by Smoke Claude

[Copilot]

Pull request overview

This PR updates gh-aw workflow guidance and troubleshooting docs to prevent agents from trying to load Playwright as an npm module, clarifying that Playwright is accessed via MCP tools in these workflows.

Changes:

• Adds a new troubleshooting section for “Cannot find module 'playwright'” with MCP-based alternatives.
• Updates the daily-multi-device-docs-tester workflow prompt with explicit “MCP tools only” instructions and an example.
• Aligns the local docs preview URL to include the /gh-aw/ base path.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
docs/src/content/docs/troubleshooting/common-issues.md	Adds a new troubleshooting entry explaining the Playwright MCP usage pattern vs require('playwright').
.github/workflows/daily-multi-device-docs-tester.md	Updates the workflow prompt with explicit Playwright MCP instructions and an example snippet.

Comments suppressed due to low confidence (2)

docs/src/content/docs/troubleshooting/common-issues.md:190

• mcp__playwright__browser_snapshot() is described here as taking a screenshot, but elsewhere in the repo browser_snapshot is used for an accessibility tree/text snapshot (and there is a separate browser_take_screenshot tool for images). This could mislead users into using the wrong tool; either update the wording to “accessibility snapshot” or switch the example to the screenshot tool.

// ✅ CORRECT - Use MCP Playwright tools
// Example: Navigate and take screenshot
await mcp__playwright__browser_navigate({
  url: "https://example.com"
});

await mcp__playwright__browser_snapshot();

docs/src/content/docs/troubleshooting/common-issues.md:208

• The heading “Available MCP Playwright Tools” implies this is the full tool list, but the Playwright MCP integration exposes many more tools (e.g., browser_take_screenshot, browser_wait_for, etc.). Consider renaming this to indicate it’s a partial/common subset, or provide a link/instruction to use gh aw mcp inspect <workflow> --server playwright to see the complete set.

**Available MCP Playwright Tools:**
- `mcp__playwright__browser_navigate` - Navigate to URL
- `mcp__playwright__browser_snapshot` - Take screenshot
- `mcp__playwright__browser_run_code` - Execute custom Playwright code
- `mcp__playwright__browser_click` - Click elements
- `mcp__playwright__browser_type` - Type text
- `mcp__playwright__browser_close` - Close browser

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The link text says “complete details”, but the referenced Tools page documents Playwright configuration (tools: playwright:) and doesn’t describe the MCP tool operations (mcp__playwright__browser_*). Suggest rewording to “configuration details” and/or adding a pointer to gh aw mcp inspect for the runtime tool list and signatures.

This issue also appears in the following locations of the same file:

• line 184
• line 202

Suggested change

	See the [Playwright Tool documentation](/gh-aw/reference/tools/#playwright-tool-playwright) for complete details.
	See the [Playwright tool configuration documentation](/gh-aw/reference/tools/#playwright-tool-playwright) for configuration details. For the runtime MCP tool list and signatures, run `gh aw mcp inspect`.

[Copilot]

The Playwright MCP call in this example isn’t awaited. Since these MCP tool calls are async, leaving off await can cause agents to proceed before navigation/testing completes. Update the snippet to explicitly await the mcp__playwright__browser_run_code(...) call (and close it consistently).

Suggested change

	mcp__playwright__browser_run_code({
	code: `async (page) => {
	await page.setViewportSize({ width: 390, height: 844 });
	await page.goto('http://localhost:4321/gh-aw/');
	return { url: page.url(), title: await page.title() };
	}`
	})
	await mcp__playwright__browser_run_code({
	code: `async (page) => {
	await page.setViewportSize({ width: 390, height: 844 });
	await page.goto('http://localhost:4321/gh-aw/');
	return { url: page.url(), title: await page.title() };
	}`,
	});