port-nuker 1.0.1 → 1.0.4

package/.agent/skills/skills/playwright-skill/API_REFERENCE.md

@@ -1,653 +0,0 @@
-# Playwright Skill - Complete API Reference
-
-This document contains the comprehensive Playwright API reference and advanced patterns. For quick-start execution patterns, see [SKILL.md](SKILL.md).
-
-## Table of Contents
-
-- [Installation & Setup](#installation--setup)
-- [Core Patterns](#core-patterns)
-- [Selectors & Locators](#selectors--locators)
-- [Common Actions](#common-actions)
-- [Waiting Strategies](#waiting-strategies)
-- [Assertions](#assertions)
-- [Page Object Model](#page-object-model-pom)
-- [Network & API Testing](#network--api-testing)
-- [Authentication & Session Management](#authentication--session-management)
-- [Visual Testing](#visual-testing)
-- [Mobile Testing](#mobile-testing)
-- [Debugging](#debugging)
-- [Performance Testing](#performance-testing)
-- [Parallel Execution](#parallel-execution)
-- [Data-Driven Testing](#data-driven-testing)
-- [Accessibility Testing](#accessibility-testing)
-- [CI/CD Integration](#cicd-integration)
-- [Best Practices](#best-practices)
-- [Common Patterns & Solutions](#common-patterns--solutions)
-- [Troubleshooting](#troubleshooting)
-
-## Installation & Setup
-
-### Prerequisites
-
-Before using this skill, ensure Playwright is available:
-
-```bash
-# Check if Playwright is installed
-npm list playwright 2>/dev/null || echo "Playwright not installed"
-
-# Install (if needed)
-cd ~/.claude/skills/playwright-skill
-npm run setup
-```
-
-### Basic Configuration
-
-Create `playwright.config.ts`:
-
-```typescript
-import { defineConfig, devices } from '@playwright/test';
-
-export default defineConfig({
-  testDir: './tests',
-  fullyParallel: true,
-  forbidOnly: !!process.env.CI,
-  retries: process.env.CI ? 2 : 0,
-  workers: process.env.CI ? 1 : undefined,
-  reporter: 'html',
-  use: {
-    baseURL: 'http://localhost:3000',
-    trace: 'on-first-retry',
-    screenshot: 'only-on-failure',
-    video: 'retain-on-failure',
-  },
-  projects: [
-    {
-      name: 'chromium',
-      use: { ...devices['Desktop Chrome'] },
-    },
-  ],
-  webServer: {
-    command: 'npm run start',
-    url: 'http://localhost:3000',
-    reuseExistingServer: !process.env.CI,
-  },
-});
-```
-
-## Core Patterns
-
-### Basic Browser Automation
-
-```javascript
-const { chromium } = require('playwright');
-
-(async () => {
-  // Launch browser
-  const browser = await chromium.launch({
-    headless: false,  // Set to true for headless mode
-    slowMo: 50       // Slow down operations by 50ms
-  });
-
-  const context = await browser.newContext({
-    viewport: { width: 1280, height: 720 },
-    userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36'
-  });
-
-  const page = await context.newPage();
-
-  // Navigate
-  await page.goto('https://example.com', {
-    waitUntil: 'networkidle'  // Wait for network to be idle
-  });
-
-  // Your automation here
-
-  await browser.close();
-})();
-```
-
-### Test Structure
-
-```typescript
-import { test, expect } from '@playwright/test';
-
-test.describe('Feature Name', () => {
-  test.beforeEach(async ({ page }) => {
-    await page.goto('/');
-  });
-
-  test('should do something', async ({ page }) => {
-    // Arrange
-    const button = page.locator('button[data-testid="submit"]');
-
-    // Act
-    await button.click();
-
-    // Assert
-    await expect(page).toHaveURL('/success');
-    await expect(page.locator('.message')).toHaveText('Success!');
-  });
-});
-```
-
-## Selectors & Locators
-
-### Best Practices for Selectors
-
-```javascript
-// PREFERRED: Data attributes (most stable)
-await page.locator('[data-testid="submit-button"]').click();
-await page.locator('[data-cy="user-input"]').fill('text');
-
-// GOOD: Role-based selectors (accessible)
-await page.getByRole('button', { name: 'Submit' }).click();
-await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');
-await page.getByRole('heading', { level: 1 }).click();
-
-// GOOD: Text content (for unique text)
-await page.getByText('Sign in').click();
-await page.getByText(/welcome back/i).click();
-
-// OK: Semantic HTML
-await page.locator('button[type="submit"]').click();
-await page.locator('input[name="email"]').fill('test@test.com');
-
-// AVOID: Classes and IDs (can change frequently)
-await page.locator('.btn-primary').click();  // Avoid
-await page.locator('#submit').click();       // Avoid
-
-// LAST RESORT: Complex CSS/XPath
-await page.locator('div.container > form > button').click();  // Fragile
-```
-
-### Advanced Locator Patterns
-
-```javascript
-// Filter and chain locators
-const row = page.locator('tr').filter({ hasText: 'John Doe' });
-await row.locator('button').click();
-
-// Nth element
-await page.locator('button').nth(2).click();
-
-// Combining conditions
-await page.locator('button').and(page.locator('[disabled]')).count();
-
-// Parent/child navigation
-const cell = page.locator('td').filter({ hasText: 'Active' });
-const row = cell.locator('..');
-await row.locator('button.edit').click();
-```
-
-## Common Actions
-
-### Form Interactions
-
-```javascript
-// Text input
-await page.getByLabel('Email').fill('user@example.com');
-await page.getByPlaceholder('Enter your name').fill('John Doe');
-
-// Clear and type
-await page.locator('#username').clear();
-await page.locator('#username').type('newuser', { delay: 100 });
-
-// Checkbox
-await page.getByLabel('I agree').check();
-await page.getByLabel('Subscribe').uncheck();
-
-// Radio button
-await page.getByLabel('Option 2').check();
-
-// Select dropdown
-await page.selectOption('select#country', 'usa');
-await page.selectOption('select#country', { label: 'United States' });
-await page.selectOption('select#country', { index: 2 });
-
-// Multi-select
-await page.selectOption('select#colors', ['red', 'blue', 'green']);
-
-// File upload
-await page.setInputFiles('input[type="file"]', 'path/to/file.pdf');
-await page.setInputFiles('input[type="file"]', [
-  'file1.pdf',
-  'file2.pdf'
-]);
-```
-
-### Mouse Actions
-
-```javascript
-// Click variations
-await page.click('button');                          // Left click
-await page.click('button', { button: 'right' });    // Right click
-await page.dblclick('button');                       // Double click
-await page.click('button', { position: { x: 10, y: 10 } });  // Click at position
-
-// Hover
-await page.hover('.menu-item');
-
-// Drag and drop
-await page.dragAndDrop('#source', '#target');
-
-// Manual drag
-await page.locator('#source').hover();
-await page.mouse.down();
-await page.locator('#target').hover();
-await page.mouse.up();
-```
-
-### Keyboard Actions
-
-```javascript
-// Type with delay
-await page.keyboard.type('Hello World', { delay: 100 });
-
-// Key combinations
-await page.keyboard.press('Control+A');
-await page.keyboard.press('Control+C');
-await page.keyboard.press('Control+V');
-
-// Special keys
-await page.keyboard.press('Enter');
-await page.keyboard.press('Tab');
-await page.keyboard.press('Escape');
-await page.keyboard.press('ArrowDown');
-```
-
-## Waiting Strategies
-
-### Smart Waiting
-
-```javascript
-// Wait for element states
-await page.locator('button').waitFor({ state: 'visible' });
-await page.locator('.spinner').waitFor({ state: 'hidden' });
-await page.locator('button').waitFor({ state: 'attached' });
-await page.locator('button').waitFor({ state: 'detached' });
-
-// Wait for specific conditions
-await page.waitForURL('**/success');
-await page.waitForURL(url => url.pathname === '/dashboard');
-
-// Wait for network
-await page.waitForLoadState('networkidle');
-await page.waitForLoadState('domcontentloaded');
-
-// Wait for function
-await page.waitForFunction(() => document.querySelector('.loaded'));
-await page.waitForFunction(
-  text => document.body.innerText.includes(text),
-  'Content loaded'
-);
-
-// Wait for response
-const responsePromise = page.waitForResponse('**/api/users');
-await page.click('button#load-users');
-const response = await responsePromise;
-
-// Wait for request
-await page.waitForRequest(request =>
-  request.url().includes('/api/') && request.method() === 'POST'
-);
-
-// Custom timeout
-await page.locator('.slow-element').waitFor({
-  state: 'visible',
-  timeout: 10000  // 10 seconds
-});
-```
-
-## Assertions
-
-### Common Assertions
-
-```javascript
-import { expect } from '@playwright/test';
-
-// Page assertions
-await expect(page).toHaveTitle('My App');
-await expect(page).toHaveURL('https://example.com/dashboard');
-await expect(page).toHaveURL(/.*dashboard/);
-
-// Element visibility
-await expect(page.locator('.message')).toBeVisible();
-await expect(page.locator('.spinner')).toBeHidden();
-await expect(page.locator('button')).toBeEnabled();
-await expect(page.locator('input')).toBeDisabled();
-
-// Text content
-await expect(page.locator('h1')).toHaveText('Welcome');
-await expect(page.locator('.message')).toContainText('success');
-await expect(page.locator('.items')).toHaveText(['Item 1', 'Item 2']);
-
-// Input values
-await expect(page.locator('input')).toHaveValue('test@example.com');
-await expect(page.locator('input')).toBeEmpty();
-
-// Attributes
-await expect(page.locator('button')).toHaveAttribute('type', 'submit');
-await expect(page.locator('img')).toHaveAttribute('src', /.*\.png/);
-
-// CSS properties
-await expect(page.locator('.error')).toHaveCSS('color', 'rgb(255, 0, 0)');
-
-// Count
-await expect(page.locator('.item')).toHaveCount(5);
-
-// Checkbox/Radio state
-await expect(page.locator('input[type="checkbox"]')).toBeChecked();
-```
-
-## Page Object Model (POM)
-
-### Basic Page Object
-
-```javascript
-// pages/LoginPage.js
-class LoginPage {
-  constructor(page) {
-    this.page = page;
-    this.usernameInput = page.locator('input[name="username"]');
-    this.passwordInput = page.locator('input[name="password"]');
-    this.submitButton = page.locator('button[type="submit"]');
-    this.errorMessage = page.locator('.error-message');
-  }
-
-  async navigate() {
-    await this.page.goto('/login');
-  }
-
-  async login(username, password) {
-    await this.usernameInput.fill(username);
-    await this.passwordInput.fill(password);
-    await this.submitButton.click();
-  }
-
-  async getErrorMessage() {
-    return await this.errorMessage.textContent();
-  }
-}
-
-// Usage in test
-test('login with valid credentials', async ({ page }) => {
-  const loginPage = new LoginPage(page);
-  await loginPage.navigate();
-  await loginPage.login('user@example.com', 'password123');
-  await expect(page).toHaveURL('/dashboard');
-});
-```
-
-## Network & API Testing
-
-### Intercepting Requests
-
-```javascript
-// Mock API responses
-await page.route('**/api/users', route => {
-  route.fulfill({
-    status: 200,
-    contentType: 'application/json',
-    body: JSON.stringify([
-      { id: 1, name: 'John' },
-      { id: 2, name: 'Jane' }
-    ])
-  });
-});
-
-// Modify requests
-await page.route('**/api/**', route => {
-  const headers = {
-    ...route.request().headers(),
-    'X-Custom-Header': 'value'
-  };
-  route.continue({ headers });
-});
-
-// Block resources
-await page.route('**/*.{png,jpg,jpeg,gif}', route => route.abort());
-```
-
-### Custom Headers via Environment Variables
-
-The skill supports automatic header injection via environment variables:
-
-```bash
-# Single header (simple)
-PW_HEADER_NAME=X-Automated-By PW_HEADER_VALUE=playwright-skill
-
-# Multiple headers (JSON)
-PW_EXTRA_HEADERS='{"X-Automated-By":"playwright-skill","X-Request-ID":"123"}'
-```
-
-These headers are automatically applied to all requests when using:
-- `helpers.createContext(browser)` - headers merged automatically
-- `getContextOptionsWithHeaders(options)` - utility injected by run.js wrapper
-
-**Precedence (highest to lowest):**
-1. Headers passed directly in `options.extraHTTPHeaders`
-2. Environment variable headers
-3. Playwright defaults
-
-**Use case:** Identify automated traffic so your backend can return LLM-optimized responses (e.g., plain text errors instead of styled HTML).
-
-## Visual Testing
-
-### Screenshots
-
-```javascript
-// Full page screenshot
-await page.screenshot({
-  path: 'screenshot.png',
-  fullPage: true
-});
-
-// Element screenshot
-await page.locator('.chart').screenshot({
-  path: 'chart.png'
-});
-
-// Visual comparison
-await expect(page).toHaveScreenshot('homepage.png');
-```
-
-## Mobile Testing
-
-```javascript
-// Device emulation
-const { devices } = require('playwright');
-const iPhone = devices['iPhone 12'];
-
-const context = await browser.newContext({
-  ...iPhone,
-  locale: 'en-US',
-  permissions: ['geolocation'],
-  geolocation: { latitude: 37.7749, longitude: -122.4194 }
-});
-```
-
-## Debugging
-
-### Debug Mode
-
-```bash
-# Run with inspector
-npx playwright test --debug
-
-# Headed mode
-npx playwright test --headed
-
-# Slow motion
-npx playwright test --headed --slowmo=1000
-```
-
-### In-Code Debugging
-
-```javascript
-// Pause execution
-await page.pause();
-
-// Console logs
-page.on('console', msg => console.log('Browser log:', msg.text()));
-page.on('pageerror', error => console.log('Page error:', error));
-```
-
-## Performance Testing
-
-```javascript
-// Measure page load time
-const startTime = Date.now();
-await page.goto('https://example.com');
-const loadTime = Date.now() - startTime;
-console.log(`Page loaded in ${loadTime}ms`);
-```
-
-## Parallel Execution
-
-```javascript
-// Run tests in parallel
-test.describe.parallel('Parallel suite', () => {
-  test('test 1', async ({ page }) => {
-    // Runs in parallel with test 2
-  });
-
-  test('test 2', async ({ page }) => {
-    // Runs in parallel with test 1
-  });
-});
-```
-
-## Data-Driven Testing
-
-```javascript
-// Parameterized tests
-const testData = [
-  { username: 'user1', password: 'pass1', expected: 'Welcome user1' },
-  { username: 'user2', password: 'pass2', expected: 'Welcome user2' },
-];
-
-testData.forEach(({ username, password, expected }) => {
-  test(`login with ${username}`, async ({ page }) => {
-    await page.goto('/login');
-    await page.fill('#username', username);
-    await page.fill('#password', password);
-    await page.click('button[type="submit"]');
-    await expect(page.locator('.message')).toHaveText(expected);
-  });
-});
-```
-
-## Accessibility Testing
-
-```javascript
-import { injectAxe, checkA11y } from 'axe-playwright';
-
-test('accessibility check', async ({ page }) => {
-  await page.goto('/');
-  await injectAxe(page);
-  await checkA11y(page);
-});
-```
-
-## CI/CD Integration
-
-### GitHub Actions
-
-```yaml
-name: Playwright Tests
-on:
-  push:
-    branches: [main, master]
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-node@v3
-      - name: Install dependencies
-        run: npm ci
-      - name: Install Playwright Browsers
-        run: npx playwright install --with-deps
-      - name: Run tests
-        run: npx playwright test
-```
-
-## Best Practices
-
-1. **Test Organization** - Use descriptive test names, group related tests
-2. **Selector Strategy** - Prefer data-testid attributes, use role-based selectors
-3. **Waiting** - Use Playwright's auto-waiting, avoid hard-coded delays
-4. **Error Handling** - Add proper error messages, take screenshots on failure
-5. **Performance** - Run tests in parallel, reuse authentication state
-
-## Common Patterns & Solutions
-
-### Handling Popups
-
-```javascript
-const [popup] = await Promise.all([
-  page.waitForEvent('popup'),
-  page.click('button.open-popup')
-]);
-await popup.waitForLoadState();
-```
-
-### File Downloads
-
-```javascript
-const [download] = await Promise.all([
-  page.waitForEvent('download'),
-  page.click('button.download')
-]);
-await download.saveAs(`./downloads/${download.suggestedFilename()}`);
-```
-
-### iFrames
-
-```javascript
-const frame = page.frameLocator('#my-iframe');
-await frame.locator('button').click();
-```
-
-### Infinite Scroll
-
-```javascript
-async function scrollToBottom(page) {
-  await page.evaluate(() => window.scrollTo(0, document.body.scrollHeight));
-  await page.waitForTimeout(500);
-}
-```
-
-## Troubleshooting
-
-### Common Issues
-
-1. **Element not found** - Check if element is in iframe, verify visibility
-2. **Timeout errors** - Increase timeout, check network conditions
-3. **Flaky tests** - Use proper waiting strategies, mock external dependencies
-4. **Authentication issues** - Verify auth state is properly saved
-
-## Quick Reference Commands
-
-```bash
-# Run tests
-npx playwright test
-
-# Run in headed mode
-npx playwright test --headed
-
-# Debug tests
-npx playwright test --debug
-
-# Generate code
-npx playwright codegen https://example.com
-
-# Show report
-npx playwright show-report
-```
-
-## Additional Resources
-
-- [Playwright Documentation](https://playwright.dev/docs/intro)
-- [API Reference](https://playwright.dev/docs/api/class-playwright)
-- [Best Practices](https://playwright.dev/docs/best-practices)