{"id":30717811,"url":"https://github.com/smartlabsat/claude-playwright","last_synced_at":"2026-02-06T14:30:10.331Z","repository":{"id":311893780,"uuid":"1045469767","full_name":"smartlabsAT/claude-playwright","owner":"smartlabsAT","description":"Claude-Playwright Toolkit provides seamless integration between Claude Code and Playwright MCP for efficient browser automation and testing. Features include browser session persistence, role-based  profile management, and intelligent code generation for Page Objects, Tests, and Fixtures.","archived":false,"fork":false,"pushed_at":"2025-08-27T16:37:42.000Z","size":166,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-27T17:51:36.156Z","etag":null,"topics":["browser-automation","browser-profiles","claude","claude-code","cli-tool","code-generation","developer-tools","e2e-testing","mcp","model-context-protocol","page-object-model","playwright","playwright-mcp","scaffold","session-management","test-automation","testing","typescript","web-automation"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/claude-playwright","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/smartlabsAT.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-27T08:14:25.000Z","updated_at":"2025-08-27T16:37:45.000Z","dependencies_parsed_at":"2025-08-27T17:51:40.009Z","dependency_job_id":"1edeea19-abd0-4f69-987e-d712c86a03b4","html_url":"https://github.com/smartlabsAT/claude-playwright","commit_stats":null,"previous_names":["smartlabsat/claude-playwright"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/smartlabsAT/claude-playwright","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smartlabsAT%2Fclaude-playwright","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smartlabsAT%2Fclaude-playwright/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smartlabsAT%2Fclaude-playwright/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smartlabsAT%2Fclaude-playwright/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/smartlabsAT","download_url":"https://codeload.github.com/smartlabsAT/claude-playwright/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smartlabsAT%2Fclaude-playwright/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273417342,"owners_count":25101817,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-03T02:00:09.631Z","response_time":76,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["browser-automation","browser-profiles","claude","claude-code","cli-tool","code-generation","developer-tools","e2e-testing","mcp","model-context-protocol","page-object-model","playwright","playwright-mcp","scaffold","session-management","test-automation","testing","typescript","web-automation"],"created_at":"2025-09-03T09:02:07.389Z","updated_at":"2026-02-06T14:30:10.291Z","avatar_url":"https://github.com/smartlabsAT.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Claude Playwright\n\nBrowser automation integration for Claude Code via MCP (Model Context Protocol).\n\n[![npm version](https://img.shields.io/npm/v/claude-playwright.svg)](https://www.npmjs.com/package/claude-playwright)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## 🎉 v0.1.3: Major Stability Update\n\n**80% fewer failures** with automatic retry logic, intelligent error recovery, and helpful error messages. Your automations are now much more reliable!\n\n## What it does\n\nClaude Playwright adds browser automation capabilities to Claude Code. It provides 26+ tools for controlling browsers, managing sessions, and automating web interactions with enterprise-grade reliability.\n\n## Installation\n\n```bash\n# Install globally\nnpm install -g claude-playwright\n\n# Or add to project\nnpm install --save-dev claude-playwright\n```\n\n## Quick Setup\n\n1. Initialize MCP configuration:\n```bash\nnpx claude-playwright mcp init --base-url http://localhost:3000\n```\n\n2. Restart Claude Code\n\n3. Use browser automation in Claude:\n```\n\"Navigate to login page and sign in\"\n\"Take a screenshot of the dashboard\"\n\"Click the submit button\"\n```\n\n## Core Features\n\n### Browser Automation Tools\n- Navigation and interaction (click, type, hover)\n- Form handling (fill forms, select options, file upload)\n- Screenshots (full page, element-specific)\n- Data extraction (JavaScript execution, DOM snapshots)\n- Monitoring (console messages, network requests)\n- Advanced features (tab management, dialog handling)\n\n### Session Management\nSave and restore authenticated browser sessions:\n\n```bash\n# Save session after manual login\nnpx claude-playwright session save my-app\n\n# List saved sessions\nnpx claude-playwright session list\n\n# Use in Claude: \"Load the my-app session\"\n```\n\nSessions include cookies, localStorage, and authentication state. Valid for 8 hours with auto-extension.\n\n### Profile Management\nTest on different devices and viewports:\n\n```bash\n# Setup default profiles\nnpx claude-playwright profile setup\n\n# Create custom profile\nnpx claude-playwright profile create mobile --device mobile --viewport 390x844\n\n# List profiles\nnpx claude-playwright profile list\n```\n\n### Intelligent Caching\n- AI-aware selector caching with fallback strategies\n- Bidirectional input-to-selector mapping\n- Supports multiple languages (English/German)\n- Automatic syntax correction for Playwright selectors\n- Project-local cache storage\n\n### Test Management\nSave and reuse browser interaction sequences:\n\n```bash\n# Save current workflow as test\nnpx claude-playwright test save --name \"Login Flow\"\n\n# Find tests by description\nnpx claude-playwright test find --query \"login\"\n\n# Run test on different environment\nnpx claude-playwright test run --name \"Login Flow\" --url \"staging.app.com\"\n```\n\n## Step-by-Step Tutorial\n\n### Getting Started in 5 Minutes\n\n**Step 1: Install and Initialize**\n```bash\n# Install the package\nnpm install -g claude-playwright\n\n# Navigate to your project directory\ncd my-web-app\n\n# Initialize MCP configuration\nnpx claude-playwright mcp init --base-url http://localhost:3000\n```\n\n**Step 2: Start Your Application**\n```bash\n# Start your web application (example)\nnpm run dev\n# Your app should be running at http://localhost:3000\n```\n\n**Step 3: Restart Claude Code**\n- Close Claude Code completely\n- Reopen Claude Code\n- Navigate to your project directory\n\n**Step 4: Test the Connection**\nIn Claude Code, type:\n```\n/mcp\n```\nYou should see `playwright` listed as an active MCP server.\n\n**Step 5: Your First Automation**\nIn Claude Code, try:\n```\n\"Navigate to the home page and take a screenshot\"\n```\n\nClaude will automatically:\n1. Open a browser\n2. Navigate to http://localhost:3000\n3. Take a screenshot\n4. Show you the result\n\n**Step 6: Save a Session (Optional)**\nIf your app requires authentication:\n```bash\n# Save an authenticated session\nnpx claude-playwright session save my-app --url http://localhost:3000/login\n```\nFollow the browser prompts to log in, then close the browser. The session is saved.\n\n**Step 7: Use Advanced Features**\nNow you can ask Claude to:\n```\n\"Load the my-app session and navigate to the dashboard\"\n\"Fill out the contact form with test data\"\n\"Test the shopping cart workflow\"\n\"Extract all product names from the catalog page\"\n```\n\n### Working with Tests\n\n**Save Your Workflow as a Test:**\n```bash\n# After using Claude to perform some actions\nnpx claude-playwright test save --name \"User Login\" --tags \"auth\"\n```\n\n**Reuse Your Test:**\n```bash\n# Run the same test on staging\nnpx claude-playwright test run --name \"User Login\" --url \"https://staging.myapp.com\"\n```\n\n**Find Tests by Purpose:**\n```bash\n# Search for authentication-related tests\nnpx claude-playwright test find --query \"login\"\n```\n\n### Device Testing\n\n**Setup Mobile Testing:**\n```bash\n# Create mobile profile\nnpx claude-playwright profile create iphone --device mobile --viewport 390x844\n\n# Use in Claude: \"Use the iphone profile and test the mobile navigation\"\n```\n\n### Troubleshooting Your Setup\n\n**If MCP connection fails:**\n```bash\n# Check status\nnpx claude-playwright mcp status\n\n# Verify .mcp.json was created\ncat .mcp.json\n```\n\n**If browser actions fail:**\n```bash\n# Clear cache and try again\nnpx claude-playwright cache clear\n```\n\n**If sessions don't work:**\n```bash\n# Check session health\nnpx claude-playwright session health\n\n# List all sessions\nnpx claude-playwright session list\n```\n\n## Available MCP Tools\n\nClaude Code has access to these browser automation tools:\n\n**Core Browser Actions:**\n- `mcp_browser_navigate` - Navigate to URLs\n- `mcp_browser_click` - Click elements\n- `mcp_browser_type` - Type text\n- `mcp_browser_snapshot` - Get accessibility tree\n- `mcp_browser_screenshot` - Take screenshots\n\n**Form Interactions:**\n- `mcp_browser_fill_form` - Fill multiple form fields\n- `mcp_browser_select_option` - Select dropdown options\n- `mcp_browser_hover` - Hover over elements\n- `mcp_browser_press_key` - Keyboard input\n\n**Session Management:**\n- `mcp_session_restore` - Load saved session\n- `mcp_session_save` - Save current session\n- `mcp_session_list` - List available sessions\n\n**Test Management:**\n- `mcp_test_save` - Save interaction sequence\n- `mcp_test_run` - Execute saved test\n- `mcp_test_search` - Find tests by intent\n- `mcp_test_library` - Browse test collection\n\n**Debug Tools:**\n- `mcp_debug_console` - Monitor console messages\n- `mcp_debug_network` - Track network requests\n- `mcp_debug_evaluate` - Execute JavaScript\n\n## CLI Commands\n\n### MCP Setup\n```bash\nnpx claude-playwright mcp init          # Initialize MCP config\nnpx claude-playwright mcp status        # Check status\n```\n\n### Session Management\n```bash\nnpx claude-playwright session list      # List sessions\nnpx claude-playwright session save \u003cname\u003e   # Save session\nnpx claude-playwright session load \u003cname\u003e   # Load session\nnpx claude-playwright session delete \u003cname\u003e # Delete session\n```\n\n### Profile Management\n```bash\nnpx claude-playwright profile setup     # Create default profiles\nnpx claude-playwright profile list      # List profiles\nnpx claude-playwright profile create \u003cname\u003e # Create profile\n```\n\n### Cache Management\n```bash\nnpx claude-playwright cache info        # Cache statistics\nnpx claude-playwright cache clear       # Clear cache\nnpx claude-playwright cache health      # Health check\n```\n\n### Test Management\n```bash\nnpx claude-playwright test save         # Save test scenario\nnpx claude-playwright test find         # Search tests\nnpx claude-playwright test run          # Execute test\nnpx claude-playwright test list         # List all tests\nnpx claude-playwright test delete       # Delete tests\n```\n\n## Configuration\n\n### MCP Configuration\nThe `.mcp.json` file is created automatically during initialization:\n\n```json\n{\n  \"mcpServers\": {\n    \"playwright\": {\n      \"command\": \"node\",\n      \"args\": [\"node_modules/claude-playwright/dist/mcp/server.cjs\"],\n      \"env\": {\n        \"BASE_URL\": \"http://localhost:3000\"\n      }\n    }\n  }\n}\n```\n\n### Environment Variables\n- `BASE_URL`: Application base URL\n- `PLAYWRIGHT_HEADLESS`: Run headless (default: false)\n- `PLAYWRIGHT_SLOW_MO`: Slow down operations (ms)\n\n## Project Structure\n\nAll data is stored project-locally in `.claude-playwright/`:\n\n```\n.claude-playwright/\n├── cache/          # Selector cache and performance data\n├── sessions/       # Browser session storage\n├── profiles/       # Device profiles\n└── logs/           # Operation logs\n```\n\n## Troubleshooting\n\n### MCP Server Issues\n1. Check `.mcp.json` exists in project root\n2. Restart Claude Code after config changes\n3. Verify BASE_URL matches your application\n4. Run `npx claude-playwright mcp status`\n\n### Session Issues\n1. Check validity: `npx claude-playwright session health`\n2. Extend sessions: `npx claude-playwright session extend \u003cname\u003e`\n3. Sessions expire after 8 hours\n\n### Cache Issues\n1. Check status: `npx claude-playwright cache health`\n2. Clear cache: `npx claude-playwright cache clear`\n3. View debug info: `npx claude-playwright cache debug`\n\n## Requirements\n\n- Node.js 16+\n- npm 7+\n- Claude Code with MCP support\n\n## Contributing\n\n```bash\ngit clone https://github.com/smartlabsAT/claude-playwright.git\ncd claude-playwright\nnpm install\nnpm run build\nnpm test\n```\n\n## License\n\nMIT © [SmartLabs](https://smartlabs.at)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmartlabsat%2Fclaude-playwright","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmartlabsat%2Fclaude-playwright","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmartlabsat%2Fclaude-playwright/lists"}