mirror of
https://github.com/alirezarezvani/claude-skills.git
synced 2026-10-10 03:27:56 +00:00
49a6944805
Two doc nits from #981 review: (1) CLAUDE.md's 'Not auto-registered' paragraph used 'integrations/<name>/src/index.ts' in one sentence and 'integrations/<name>-mcp' two sentences later — <name> meant two different things; align both to <name>-mcp. (2) skills/pw/SKILL.md 'What's Included' listed '2 MCP servers ... integrations' with no caveat, unlike README's equivalent line — add '(optional — not auto-registered)'.
96 lines
4.3 KiB
Markdown
96 lines
4.3 KiB
Markdown
# Playwright Pro — Agent Context
|
|
|
|
You are working in a project with the Playwright Pro plugin installed. Follow these rules for all test-related work.
|
|
|
|
## Golden Rules (Non-Negotiable)
|
|
|
|
1. **`getByRole()` over CSS/XPath** — resilient to markup changes, mirrors how users see the page
|
|
2. **Never `page.waitForTimeout()`** — use `expect(locator).toBeVisible()` or `page.waitForURL()`
|
|
3. **Web-first assertions** — `expect(locator)` auto-retries; `expect(await locator.textContent())` does not
|
|
4. **Isolate every test** — no shared state, no execution-order dependencies
|
|
5. **`baseURL` in config** — zero hardcoded URLs in tests
|
|
6. **Retries: `2` in CI, `0` locally** — surface flakiness where it matters
|
|
7. **Traces: `'on-first-retry'`** — rich debugging without CI slowdown
|
|
8. **Fixtures over globals** — share state via `test.extend()`, not module-level variables
|
|
9. **One behavior per test** — multiple related `expect()` calls are fine
|
|
10. **Mock external services only** — never mock your own app
|
|
|
|
## Locator Priority
|
|
|
|
Always use the first option that works:
|
|
|
|
```typescript
|
|
page.getByRole('button', { name: 'Submit' }) // 1. Role (default)
|
|
page.getByLabel('Email address') // 2. Label (form fields)
|
|
page.getByText('Welcome back') // 3. Text (non-interactive)
|
|
page.getByPlaceholder('Search...') // 4. Placeholder
|
|
page.getByAltText('Company logo') // 5. Alt text (images)
|
|
page.getByTitle('Close dialog') // 6. Title attribute
|
|
page.getByTestId('checkout-summary') // 7. Test ID (last semantic)
|
|
page.locator('.legacy-widget') // 8. CSS (last resort)
|
|
```
|
|
|
|
## How to Use This Plugin
|
|
|
|
### Generating Tests
|
|
|
|
When generating tests, always:
|
|
|
|
1. Use the `Explore` subagent to scan the project structure first
|
|
2. Check `playwright.config.ts` for `testDir`, `baseURL`, and project settings
|
|
3. Load relevant templates from `templates/` directory
|
|
4. Match the project's language (check for `tsconfig.json` → TypeScript, else JavaScript)
|
|
5. Place tests in the configured `testDir` (default: `tests/` or `e2e/`)
|
|
6. Include a descriptive test name that explains the behavior being verified
|
|
|
|
### Reviewing Tests
|
|
|
|
When reviewing, check against:
|
|
|
|
1. All 10 golden rules above
|
|
2. The anti-patterns in `skills/review/anti-patterns.md`
|
|
3. Missing edge cases (empty state, error state, loading state)
|
|
4. Proper use of fixtures for shared setup
|
|
|
|
### Fixing Flaky Tests
|
|
|
|
When fixing flaky tests:
|
|
|
|
1. Categorize first: timing, isolation, environment, or infrastructure
|
|
2. Use `npx playwright test <file> --repeat-each=10` to reproduce
|
|
3. Use `--trace=on` for every attempt
|
|
4. Apply the targeted fix from `skills/fix/flaky-taxonomy.md`
|
|
|
|
### Using Built-in Commands
|
|
|
|
Leverage Claude Code's built-in capabilities:
|
|
|
|
- **Large migrations**: Use `/batch` for parallel file-by-file conversion
|
|
- **Post-generation cleanup**: Use `/simplify` after generating a test suite
|
|
- **Debugging sessions**: Use `/debug` alongside `/pw:fix` for trace analysis
|
|
- **Code review**: Use `/review` for general code quality, `/pw:pw-review` for Playwright-specific
|
|
|
|
### Integrations
|
|
|
|
- **TestRail**: `TESTRAIL_URL`, `TESTRAIL_USER`, `TESTRAIL_API_KEY` env vars
|
|
- **BrowserStack**: `BROWSERSTACK_USERNAME`, `BROWSERSTACK_ACCESS_KEY` env vars
|
|
- Both are optional. The plugin works fully without them.
|
|
|
|
**Not auto-registered (issue #978).** The `pw-testrail` and `pw-browserstack`
|
|
MCP servers are no longer declared in `.mcp.json`. They are launched with
|
|
`npx tsx integrations/<name>-mcp/src/index.ts`, but the plugin ships no
|
|
`node_modules` and nothing installs `@modelcontextprotocol/sdk`, so they failed
|
|
to connect for **every** user (permanent red lines in `claude mcp list`),
|
|
regardless of whether TestRail/BrowserStack was configured. Per this repo's
|
|
"no build systems" convention we leave them out of `.mcp.json` rather than
|
|
vendoring `node_modules`. To enable one manually: `cd integrations/<name>-mcp`
|
|
(i.e. `testrail-mcp` or `browserstack-mcp`),
|
|
`npm install`, then register it in your own user/project MCP config (not the
|
|
plugin's `.mcp.json`) with the env vars above.
|
|
|
|
## File Conventions
|
|
|
|
- Test files: `*.spec.ts` or `*.spec.js`
|
|
- Page objects: `*.page.ts` in a `pages/` directory
|
|
- Fixtures: `fixtures.ts` or `fixtures/` directory
|
|
- Test data: `test-data/` directory with JSON/factory files
|