maestro-bundle 1.3.1 → 1.4.0

package/templates/bundle-frontend-spa/skills/e2e-testing/SKILL.md

@@ -1,101 +1,263 @@
 ---
 name: e2e-testing
-description: Criar testes end-to-end com Playwright para fluxos completos da aplicação web. Use quando precisar testar fluxos de usuário, validar integração frontend-backend, ou automatizar testes de interface.
+description: Create end-to-end tests with Playwright for complete user flows in web applications. Use when you need to test user flows, validate frontend-backend integration, automate UI testing, or set up a Playwright test suite. Supports Playwright MCP tools for interactive testing.
+version: 1.0.0
+author: Maestro
 ---
 
-# E2E Testing com Playwright
-
-## Setup
-
-```python
-# tests/e2e/conftest.py
-import pytest
-from playwright.sync_api import sync_playwright
-
-@pytest.fixture(scope="session")
-def browser():
-    with sync_playwright() as p:
-        browser = p.chromium.launch(headless=True)
-        yield browser
-        browser.close()
-
-@pytest.fixture
-def page(browser):
-    context = browser.new_context()
-    page = context.new_page()
-    yield page
-    context.close()
-
-@pytest.fixture
-def authenticated_page(page):
-    page.goto("http://localhost:3000/login")
-    page.fill('[name="email"]', "admin@maestro.local")
-    page.fill('[name="password"]', "admin123")
-    page.click('button[type="submit"]')
-    page.wait_for_url("**/dashboard")
-    return page
+# E2E Testing with Playwright
+
+Write and run end-to-end tests for full user flows using Playwright, with support for both the Playwright test framework and Playwright MCP tools for interactive browser automation.
+
+## When to Use
+- User needs to test a complete user flow (login, create, edit, delete)
+- User wants to validate frontend-backend integration
+- User needs to set up a Playwright test suite from scratch
+- User wants to automate visual testing or screenshots
+- User needs to debug a failing E2E test
+
+## Available Operations
+1. Set up Playwright in a project
+2. Write tests for user flows (login, CRUD, navigation)
+3. Create Page Object Models for complex tests
+4. Run tests and debug failures
+5. Use Playwright MCP tools for interactive browser testing
+
+## Multi-Step Workflow
+
+### Step 1: Install and Set Up Playwright
+```bash
+npm init playwright@latest
+# Select TypeScript, tests folder, GitHub Actions workflow
+
+# Or add to existing project:
+npm install -D @playwright/test
+npx playwright install
+```
+
+Verify installation:
+```bash
+npx playwright --version
+```
+
+### Step 2: Configure Playwright
+```typescript
+// playwright.config.ts
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests/e2e',
+  fullyParallel: true,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: 'html',
+  use: {
+    baseURL: 'http://localhost:5173',
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+  },
+  projects: [
+    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
+    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
+    { name: 'mobile', use: { ...devices['iPhone 13'] } },
+  ],
+  webServer: {
+    command: 'npm run dev',
+    url: 'http://localhost:5173',
+    reuseExistingServer: !process.env.CI,
+  },
+});
+```
+
+### Step 3: Create Auth Setup (Reusable Login)
+```typescript
+// tests/e2e/auth.setup.ts
+import { test as setup, expect } from '@playwright/test';
+
+setup('authenticate', async ({ page }) => {
+  await page.goto('/login');
+  await page.fill('[name="email"]', 'admin@example.com');
+  await page.fill('[name="password"]', 'admin123');
+  await page.click('button[type="submit"]');
+  await page.waitForURL('**/dashboard');
+
+  // Save auth state for other tests to reuse
+  await page.context().storageState({ path: 'tests/e2e/.auth/user.json' });
+});
+```
+
+### Step 4: Write a User Flow Test
+```typescript
+// tests/e2e/items.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Item Management', () => {
+  test.use({ storageState: 'tests/e2e/.auth/user.json' });
+
+  test('should create a new item from the dashboard', async ({ page }) => {
+    // Navigate to items page
+    await page.goto('/items');
+    await expect(page.locator('h1')).toHaveText('Items');
+
+    // Click "New" button
+    await page.click('button:has-text("New")');
+    await expect(page.locator('dialog')).toBeVisible();
+
+    // Fill the form
+    await page.fill('[name="title"]', 'Test Item Created by E2E');
+    await page.fill('[name="description"]', 'This item was created during end-to-end testing');
+    await page.selectOption('[name="priority"]', 'high');
+
+    // Submit
+    await page.click('button:has-text("Create")');
+
+    // Verify creation
+    await expect(page.locator('text=Item created')).toBeVisible();
+    await expect(page.locator('text=Test Item Created by E2E')).toBeVisible();
+  });
+
+  test('should search and filter items', async ({ page }) => {
+    await page.goto('/items');
+
+    // Search
+    await page.fill('[data-testid="search"]', 'Test Item');
+    await page.press('[data-testid="search"]', 'Enter');
+
+    // Verify results
+    await expect(page.locator('[data-testid="item-card"]')).toHaveCount(1);
+  });
+
+  test('should show dashboard metrics', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // Verify key elements are visible
+    await expect(page.locator('[data-testid="metric-active-items"]')).toBeVisible();
+    await expect(page.locator('[data-testid="activity-feed"]')).toBeVisible();
+  });
+});
 ```
 
-## Testes de fluxo
+### Step 5: Create Page Object Model (for complex flows)
+```typescript
+// tests/e2e/pages/ItemPage.ts
+import { Page, expect } from '@playwright/test';
+
+export class ItemPage {
+  constructor(private page: Page) {}
+
+  async navigate() {
+    await this.page.goto('/items');
+    await expect(this.page.locator('h1')).toHaveText('Items');
+  }
 
-```python
-class TestCreateDemandFlow:
-    def test_should_create_demand_from_dashboard(self, authenticated_page):
-        page = authenticated_page
+  async create(title: string, description: string, priority = 'medium') {
+    await this.page.click('button:has-text("New")');
+    await this.page.fill('[name="title"]', title);
+    await this.page.fill('[name="description"]', description);
+    await this.page.selectOption('[name="priority"]', priority);
+    await this.page.click('button:has-text("Create")');
+    await expect(this.page.locator('text=Item created')).toBeVisible();
+  }
 
-        # Navegar para demands
-        page.click('a[href="/demands"]')
-        page.wait_for_selector('h1:has-text("Demandas")')
+  async search(query: string) {
+    await this.page.fill('[data-testid="search"]', query);
+    await this.page.press('[data-testid="search"]', 'Enter');
+  }
 
-        # Clicar em "Nova"
-        page.click('button:has-text("Nova")')
-        page.wait_for_selector('dialog')
+  async getItemCount(): Promise<number> {
+    return this.page.locator('[data-testid="item-card"]').count();
+  }
+}
+
+// Usage in test:
+// const itemPage = new ItemPage(page);
+// await itemPage.navigate();
+// await itemPage.create('My Item', 'Description', 'high');
+```
 
-        # Preencher formulário
-        page.fill('[name="title"]', "Criar CRUD de usuários")
-        page.fill('[name="description"]', "Implementar CRUD completo com API e frontend")
-        page.select_option('[name="priority"]', "high")
+### Step 6: Run Tests
+```bash
+# Run all tests
+npx playwright test
 
-        # Submeter
-        page.click('button:has-text("Criar")')
+# Run specific test file
+npx playwright test tests/e2e/items.spec.ts
 
-        # Verificar criação
-        page.wait_for_selector('text=Demanda criada')
-        assert page.locator('text=Criar CRUD de usuários').is_visible()
+# Run in headed mode (visible browser)
+npx playwright test --headed
 
-    def test_should_show_agent_activity_in_realtime(self, authenticated_page):
-        page = authenticated_page
-        page.goto("http://localhost:3000/dashboard")
+# Run with UI mode (interactive)
+npx playwright test --ui
 
-        # Verificar feed de atividades
-        feed = page.locator('[data-testid="activity-feed"]')
-        assert feed.is_visible()
+# Run specific browser only
+npx playwright test --project=chromium
 
-        # Verificar métricas
-        assert page.locator('[data-testid="metric-active-agents"]').is_visible()
-        assert page.locator('[data-testid="metric-compliance-rate"]').is_visible()
+# Show HTML report
+npx playwright show-report
 ```
 
-## Page Objects (para testes complexos)
+### Step 7: Debug Failing Tests
+```bash
+# Run with step-by-step debugging
+npx playwright test --debug
 
-```python
-class DemandPage:
-    def __init__(self, page):
-        self.page = page
+# Show trace viewer for last failed run
+npx playwright show-trace test-results/*/trace.zip
 
-    def navigate(self):
-        self.page.goto("http://localhost:3000/demands")
-        self.page.wait_for_selector('h1:has-text("Demandas")')
+# Generate screenshots for visual comparison
+npx playwright test --update-snapshots
+```
+
+### Using Playwright MCP Tools (Interactive Testing)
+For interactive browser testing during development, use the Playwright MCP tools:
+```
+# Navigate to a URL
+mcp__playwright__browser_navigate(url="http://localhost:5173/login")
+
+# Take a snapshot to see current page state
+mcp__playwright__browser_snapshot()
+
+# Fill a form field
+mcp__playwright__browser_fill_form(selector='[name="email"]', value="admin@example.com")
 
-    def create(self, title: str, description: str, priority: str = "medium"):
-        self.page.click('button:has-text("Nova")')
-        self.page.fill('[name="title"]', title)
-        self.page.fill('[name="description"]', description)
-        self.page.select_option('[name="priority"]', priority)
-        self.page.click('button:has-text("Criar")')
-        self.page.wait_for_selector('text=Demanda criada')
+# Click a button
+mcp__playwright__browser_click(selector='button[type="submit"]')
 
-    def search(self, query: str):
-        self.page.fill('[data-testid="search"]', query)
-        self.page.press('[data-testid="search"]', 'Enter')
+# Take a screenshot
+mcp__playwright__browser_take_screenshot()
+
+# Wait for navigation
+mcp__playwright__browser_wait_for(selector='h1:has-text("Dashboard")')
 ```
+
+## Resources
+- `references/playwright-selectors.md` - Selector strategies and best practices
+- `references/test-patterns.md` - Common E2E test patterns
+
+## Examples
+### Example 1: Test a Login Flow
+User asks: "Write E2E tests for our login page"
+Response approach:
+1. Set up Playwright config with webServer pointing to dev server
+2. Write test for successful login (fill form, submit, verify redirect)
+3. Write test for failed login (invalid credentials, verify error message)
+4. Write test for logout (click logout, verify redirect to login)
+5. Run tests with `npx playwright test --headed`
+
+### Example 2: Test CRUD Operations
+User asks: "Add E2E tests for creating, editing, and deleting items"
+Response approach:
+1. Create auth setup to reuse login state
+2. Write create test: navigate, fill form, submit, verify
+3. Write edit test: click item, modify fields, save, verify
+4. Write delete test: click delete, confirm, verify removal
+5. Use Page Object Model if flows are complex
+6. Run with `npx playwright test`
+
+## Notes
+- Always use `data-testid` attributes for test selectors -- more stable than CSS classes
+- Use auth setup with storage state to avoid logging in every test
+- Run tests in parallel by default, use `test.describe.serial` only when order matters
+- Enable trace recording on CI for debugging remote failures
+- Keep tests independent: each test should set up its own data, not depend on other tests
+- Use `expect` assertions (not raw conditionals) for clear failure messages

package/templates/bundle-frontend-spa/skills/e2e-testing/references/playwright-selectors.md

@@ -0,0 +1,66 @@
+# Playwright Selector Strategies
+
+## Recommended Priority Order
+1. `data-testid` attributes (most stable)
+2. ARIA roles and labels
+3. Text content
+4. CSS selectors (least stable)
+
+## data-testid (Best Practice)
+```typescript
+// HTML: <button data-testid="submit-btn">Submit</button>
+await page.click('[data-testid="submit-btn"]');
+await page.locator('[data-testid="item-list"]');
+```
+
+## Text Selectors
+```typescript
+await page.click('text=Submit');
+await page.click('button:has-text("Submit")');
+await page.locator('h1:has-text("Dashboard")');
+```
+
+## ARIA Selectors
+```typescript
+await page.getByRole('button', { name: 'Submit' });
+await page.getByRole('heading', { name: 'Dashboard' });
+await page.getByLabel('Email');
+await page.getByPlaceholder('Enter your email');
+```
+
+## Form Interactions
+```typescript
+// Fill input by name attribute
+await page.fill('[name="email"]', 'user@example.com');
+
+// Select dropdown option
+await page.selectOption('[name="priority"]', 'high');
+
+// Check/uncheck checkbox
+await page.check('[name="agree"]');
+await page.uncheck('[name="newsletter"]');
+
+// Upload file
+await page.setInputFiles('[type="file"]', 'path/to/file.pdf');
+```
+
+## Waiting Strategies
+```typescript
+// Wait for element to be visible
+await page.waitForSelector('[data-testid="results"]');
+
+// Wait for URL change
+await page.waitForURL('**/dashboard');
+
+// Wait for network idle
+await page.waitForLoadState('networkidle');
+
+// Wait for specific response
+await page.waitForResponse('**/api/items');
+```
+
+## Anti-Patterns to Avoid
+- Do NOT use CSS class selectors (`.btn-primary`) -- they change with styling
+- Do NOT use complex XPath -- hard to maintain
+- Do NOT use `page.waitForTimeout(ms)` -- use explicit waits instead
+- Do NOT rely on element index (`:nth-child`) -- fragile

package/templates/bundle-frontend-spa/skills/e2e-testing/references/test-patterns.md

@@ -0,0 +1,82 @@
+# E2E Test Patterns
+
+## Authentication Setup (Shared Login State)
+```typescript
+// auth.setup.ts
+import { test as setup } from '@playwright/test';
+
+setup('login', async ({ page }) => {
+  await page.goto('/login');
+  await page.fill('[name="email"]', 'admin@example.com');
+  await page.fill('[name="password"]', 'admin123');
+  await page.click('button[type="submit"]');
+  await page.waitForURL('**/dashboard');
+  await page.context().storageState({ path: '.auth/user.json' });
+});
+
+// In tests:
+test.use({ storageState: '.auth/user.json' });
+```
+
+## CRUD Test Pattern
+```typescript
+test.describe('Items CRUD', () => {
+  test('create', async ({ page }) => {
+    await page.goto('/items');
+    await page.click('button:has-text("New")');
+    await page.fill('[name="title"]', 'E2E Test Item');
+    await page.click('button:has-text("Save")');
+    await expect(page.locator('text=E2E Test Item')).toBeVisible();
+  });
+
+  test('read', async ({ page }) => {
+    await page.goto('/items');
+    await expect(page.locator('[data-testid="item-card"]').first()).toBeVisible();
+  });
+
+  test('update', async ({ page }) => {
+    await page.goto('/items');
+    await page.click('[data-testid="item-card"]');
+    await page.fill('[name="title"]', 'Updated Title');
+    await page.click('button:has-text("Save")');
+    await expect(page.locator('text=Updated Title')).toBeVisible();
+  });
+
+  test('delete', async ({ page }) => {
+    await page.goto('/items');
+    const count = await page.locator('[data-testid="item-card"]').count();
+    await page.click('[data-testid="delete-btn"]');
+    await page.click('button:has-text("Confirm")');
+    await expect(page.locator('[data-testid="item-card"]')).toHaveCount(count - 1);
+  });
+});
+```
+
+## Page Object Model Pattern
+```typescript
+class LoginPage {
+  constructor(private page: Page) {}
+
+  async login(email: string, password: string) {
+    await this.page.goto('/login');
+    await this.page.fill('[name="email"]', email);
+    await this.page.fill('[name="password"]', password);
+    await this.page.click('button[type="submit"]');
+  }
+
+  async expectError(message: string) {
+    await expect(this.page.locator('[data-testid="error"]')).toHaveText(message);
+  }
+}
+```
+
+## API Mocking Pattern
+```typescript
+test('shows empty state when API returns no items', async ({ page }) => {
+  await page.route('**/api/items', (route) => {
+    route.fulfill({ status: 200, body: JSON.stringify({ items: [], total: 0 }) });
+  });
+  await page.goto('/items');
+  await expect(page.locator('text=No items found')).toBeVisible();
+});
+```