The 30-Minute Folder That Saves Your Playwright MCP Project

Before using Playwright MCP with Claude Code, create an empty folder structure for pages and utils. This simple planning step prevents unmaintainable chaos.

GAla Smith & AI Research Desk·9h ago·3 min read·2 views·AI-Generated

Source: dev.tovia devto_mcpCorroborated

The Trap of Unplanned MCP Speed

When you use the Playwright MCP server with Claude Code, you get a superpower: describe a test, get working code. The source author learned this creates a dangerous trap. Moving fast without a plan leads to selectors hardcoded across 15 files, the same login logic copy-pasted 8 times, and a single UI change breaking 40 tests overnight. The problem isn't the tool—it's the workflow.

The Fix: Plan Your Architecture First

The solution is a 30-minute planning session before you write your first prompt. This mindset shift treats MCP as a code generator that fits inside your architecture, not a replacement for architectural thinking.

Step 1: Map Your Pages

List every page in your application (Login, Dashboard, Checkout, Profile). Each page gets its own Page Object file. This is your foundation. Write this list in a CLAUDE.md file or a simple text document.

Step 2: Define Reusable Utilities

Identify actions that happen on multiple pages: login, navigation, form fills, API calls. These become shared utility modules.

Step 3: Create the Empty Folder Structure

Run these commands in your terminal to create the skeleton:

mkdir -p tests/e2e/pages tests/e2e/utils tests/e2e/fixtures tests/smoke
touch tests/e2e/pages/LoginPage.ts tests/e2e/pages/DashboardPage.ts
touch tests/e2e/utils/auth.ts tests/e2e/utils/api.ts

You now have this structure:

tests/
├── e2e/
│   ├── pages/
│   │   ├── LoginPage.ts
│   │   └── DashboardPage.ts
│   └── utils/
│       ├── auth.ts
│       └── api.ts
├── smoke/
└── fixtures/

Do not write any code yet. The empty files and folders are the plan.

How To Use MCP With Your Structure

Now, when you prompt Claude Code with the Playwright MCP server enabled, you give it specific architectural instructions. Instead of "Write a test for checkout," you prompt:

"Generate a test for the checkout flow. Use the Page Object pattern. The CheckoutPage should be created in tests/e2e/pages/CheckoutPage.ts. The test file itself should be tests/e2e/checkout.spec.ts. Use the shared login utility from tests/e2e/utils/auth.ts."

Claude Code, with access to the Playwright MCP tools, will now generate code that fits into your predefined slots. It fills your structure instead of creating its own.

The Result: Maintainable Speed

You keep the 10x generation speed but lose the mess. A UI change requires a fix in one Page Object file, not a hunt through dozens of tests. A new team member can understand the project in minutes. The structure enforces reusability by design.

The One Rule

Never open Claude Code with the Playwright MCP server until your folder structure and page object plan are on disk. This rule forces the planning that makes MCP sustainable.

AI Analysis

Claude Code users should immediately adopt this "empty folder first" workflow for any MCP-driven project, especially for test generation. The key change is to treat the initial prompt not as the start of work, but as the middle. Your first action should be using the CLI to `mkdir` and `touch` the planned architecture. When configuring MCP servers for other domains (like the Terraform or Ansible MCP servers mentioned in recent history), apply the same principle. Before asking Claude Code to generate Terraform modules, create the `modules/`, `environments/`, and `variables.tf` skeleton. This planning overhead is minimal but prevents the "quick fix chaos" that undermines MCP's long-term value. Integrate this planning into your `CLAUDE.md` file. Add a section titled "Test Architecture" that outlines the page object map and folder convention. This gives Claude Code the context it needs to generate code that aligns with your plan from the very first prompt.

#best-practices #mcp #playwright #testing

Enjoyed this article?

Get the weekly AI intelligence briefing