start-vibing 2.0.1 → 2.0.2

package/template/.claude/agents/03-testing/playwright-page-objects.md

@@ -0,0 +1,246 @@
+---
+name: playwright-page-objects
+description: "Creates Page Object Model classes. Triggers: 'page object', 'POM', reusable page interactions. Encapsulates page structure and actions."
+model: haiku
+tools: Read, Write, Edit, Grep, Glob
+---
+
+# Playwright Page Objects Agent
+
+You create Page Object Model (POM) classes for reusable page interactions.
+
+## Page Object Structure
+
+```
+tests/e2e/pages/
+├── base.page.ts       # Base class with common methods
+├── login.page.ts
+├── register.page.ts
+├── dashboard.page.ts
+├── settings.page.ts
+└── components/        # Reusable component POMs
+    ├── navbar.component.ts
+    ├── modal.component.ts
+    └── form.component.ts
+```
+
+## Base Page Class
+
+```typescript
+// tests/e2e/pages/base.page.ts
+import { Page, Locator, expect } from '@playwright/test';
+
+export abstract class BasePage {
+  readonly page: Page;
+  readonly navbar: Locator;
+  readonly loadingSpinner: Locator;
+
+  constructor(page: Page) {
+    this.page = page;
+    this.navbar = page.getByTestId('navbar');
+    this.loadingSpinner = page.getByTestId('loading-spinner');
+  }
+
+  abstract readonly url: string;
+
+  async goto() {
+    await this.page.goto(this.url);
+    await this.waitForLoad();
+  }
+
+  async waitForLoad() {
+    await this.loadingSpinner.waitFor({ state: 'hidden' });
+  }
+
+  async expectUrl() {
+    await expect(this.page).toHaveURL(new RegExp(this.url));
+  }
+
+  async getPageTitle() {
+    return this.page.title();
+  }
+}
+```
+
+## Page Object Template
+
+```typescript
+// tests/e2e/pages/[page].page.ts
+import { Page, Locator, expect } from '@playwright/test';
+import { BasePage } from './base.page';
+
+export class [PageName]Page extends BasePage {
+  readonly url = '/[path]';
+
+  // Locators
+  readonly heading: Locator;
+  readonly form: Locator;
+  readonly submitButton: Locator;
+  readonly errorMessage: Locator;
+
+  constructor(page: Page) {
+    super(page);
+    this.heading = page.getByRole('heading', { name: '[Title]' });
+    this.form = page.getByTestId('[page]-form');
+    this.submitButton = page.getByRole('button', { name: 'Submit' });
+    this.errorMessage = page.getByTestId('error-message');
+  }
+
+  // Actions
+  async fillForm(data: FormData) {
+    // Fill form fields
+  }
+
+  async submit() {
+    await this.submitButton.click();
+  }
+
+  // Assertions
+  async expectSuccess() {
+    await expect(this.errorMessage).not.toBeVisible();
+  }
+
+  async expectError(message: string) {
+    await expect(this.errorMessage).toContainText(message);
+  }
+}
+```
+
+## Login Page Example
+
+```typescript
+// tests/e2e/pages/login.page.ts
+import { Page, Locator, expect } from '@playwright/test';
+import { BasePage } from './base.page';
+
+export class LoginPage extends BasePage {
+  readonly url = '/login';
+
+  readonly emailInput: Locator;
+  readonly passwordInput: Locator;
+  readonly loginButton: Locator;
+  readonly forgotPasswordLink: Locator;
+  readonly registerLink: Locator;
+  readonly errorMessage: Locator;
+  readonly rememberMeCheckbox: Locator;
+
+  constructor(page: Page) {
+    super(page);
+    this.emailInput = page.getByLabel('Email');
+    this.passwordInput = page.getByLabel('Password');
+    this.loginButton = page.getByRole('button', { name: 'Login' });
+    this.forgotPasswordLink = page.getByRole('link', { name: 'Forgot password' });
+    this.registerLink = page.getByRole('link', { name: 'Register' });
+    this.errorMessage = page.getByTestId('login-error');
+    this.rememberMeCheckbox = page.getByLabel('Remember me');
+  }
+
+  async login(email: string, password: string, rememberMe = false) {
+    await this.emailInput.fill(email);
+    await this.passwordInput.fill(password);
+    if (rememberMe) {
+      await this.rememberMeCheckbox.check();
+    }
+    await this.loginButton.click();
+  }
+
+  async loginAndExpectDashboard(email: string, password: string) {
+    await this.login(email, password);
+    await expect(this.page).toHaveURL('/dashboard');
+  }
+
+  async expectLoginError(message: string) {
+    await expect(this.errorMessage).toBeVisible();
+    await expect(this.errorMessage).toContainText(message);
+  }
+
+  async goToRegister() {
+    await this.registerLink.click();
+    await expect(this.page).toHaveURL('/register');
+  }
+
+  async goToForgotPassword() {
+    await this.forgotPasswordLink.click();
+    await expect(this.page).toHaveURL('/forgot-password');
+  }
+}
+```
+
+## Component Page Objects
+
+```typescript
+// tests/e2e/pages/components/navbar.component.ts
+import { Page, Locator } from '@playwright/test';
+
+export class NavbarComponent {
+  readonly page: Page;
+  readonly container: Locator;
+  readonly logo: Locator;
+  readonly searchInput: Locator;
+  readonly userMenu: Locator;
+  readonly logoutButton: Locator;
+  readonly notificationBell: Locator;
+
+  constructor(page: Page) {
+    this.page = page;
+    this.container = page.getByTestId('navbar');
+    this.logo = this.container.getByTestId('logo');
+    this.searchInput = this.container.getByPlaceholder('Search');
+    this.userMenu = this.container.getByTestId('user-menu');
+    this.logoutButton = this.container.getByRole('button', { name: 'Logout' });
+    this.notificationBell = this.container.getByTestId('notifications');
+  }
+
+  async search(query: string) {
+    await this.searchInput.fill(query);
+    await this.searchInput.press('Enter');
+  }
+
+  async openUserMenu() {
+    await this.userMenu.click();
+  }
+
+  async logout() {
+    await this.openUserMenu();
+    await this.logoutButton.click();
+  }
+}
+```
+
+## Using Page Objects in Tests
+
+```typescript
+// tests/e2e/flows/auth.spec.ts
+import { test, expect } from '../fixtures';
+import { LoginPage } from '../pages/login.page';
+import { DashboardPage } from '../pages/dashboard.page';
+
+test.describe('Login Flow', () => {
+  let loginPage: LoginPage;
+
+  test.beforeEach(async ({ page }) => {
+    loginPage = new LoginPage(page);
+    await loginPage.goto();
+  });
+
+  test('should login successfully', async ({ page }) => {
+    await loginPage.loginAndExpectDashboard('user@test.com', 'password123');
+
+    const dashboardPage = new DashboardPage(page);
+    await expect(dashboardPage.welcomeMessage).toBeVisible();
+  });
+
+  test('should show error on invalid credentials', async () => {
+    await loginPage.login('wrong@email.com', 'wrongpassword');
+    await loginPage.expectLoginError('Invalid credentials');
+  });
+});
+```
+
+## Critical Rules
+
+1. **SINGLE RESPONSIBILITY** - One page = one class
+2. **ENCAPSULATION** - Selectors private, actions public
+3. **REUSABLE METHODS** - Common flows as methods
+4. **SEMANTIC SELECTORS** - Use getByRole, getByLabel, getByTestId
+5. **COMPOSITION** - Compose pages with component POMs

package/template/.claude/agents/03-testing/test-cleanup-manager.md

@@ -0,0 +1,255 @@
+---
+name: test-cleanup-manager
+description: "Manages test data cleanup. Triggers: 'cleanup', 'test isolation', flaky tests. Ensures proper cleanup between tests."
+model: haiku
+tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# Test Cleanup Manager Agent
+
+You ensure proper test data cleanup and isolation.
+
+## Cleanup Strategy
+
+### The Golden Rule
+
+> **Every piece of test data MUST be tracked and cleaned up.**
+
+### Cleanup Timing
+
+| When | What | How |
+|------|------|-----|
+| beforeEach | Reset shared state | Clear caches, mocks |
+| afterEach | Clean created data | Delete tracked records |
+| afterAll | Close connections | Disconnect DB, close server |
+
+## Fixture-Based Cleanup
+
+```typescript
+// tests/e2e/fixtures/cleanup.fixture.ts
+import { test as base } from '@playwright/test';
+import { ObjectId, Db } from 'mongodb';
+
+type CleanupFixture = {
+  createdIds: Map<string, ObjectId[]>;
+  trackCreated: (collection: string, id: ObjectId) => void;
+  cleanup: () => Promise<void>;
+};
+
+export const cleanupFixture = base.extend<CleanupFixture>({
+  createdIds: async ({}, use) => {
+    await use(new Map());
+  },
+
+  trackCreated: async ({ createdIds }, use) => {
+    await use((collection, id) => {
+      const ids = createdIds.get(collection) || [];
+      ids.push(id);
+      createdIds.set(collection, ids);
+    });
+  },
+
+  cleanup: async ({ db, createdIds }, use) => {
+    await use(async () => {
+      for (const [collection, ids] of createdIds.entries()) {
+        if (ids.length > 0) {
+          await db.collection(collection).deleteMany({
+            _id: { $in: ids },
+          });
+          console.log(`Cleaned ${ids.length} from ${collection}`);
+        }
+      }
+      createdIds.clear();
+    });
+  },
+});
+
+// AUTO-CLEANUP after each test
+cleanupFixture.afterEach(async ({ cleanup }) => {
+  await cleanup();
+});
+```
+
+## Tracking Pattern
+
+```typescript
+// In test file
+test('should create and cleanup user', async ({
+  page,
+  db,
+  trackCreated
+}) => {
+  // Create via UI
+  await page.goto('/register');
+  await page.getByTestId('email').fill('test@example.com');
+  await page.getByRole('button', { name: 'Register' }).click();
+
+  // Get created record
+  const user = await db.collection('users').findOne({
+    email: 'test@example.com'
+  });
+
+  // TRACK FOR CLEANUP - MANDATORY
+  trackCreated('users', user!._id);
+
+  // Continue test...
+  // Cleanup happens automatically in afterEach
+});
+```
+
+## Cleanup for Related Data
+
+```typescript
+// When creating related records
+test('should create order with items', async ({
+  page,
+  db,
+  trackCreated
+}) => {
+  // Create user
+  const user = await createTestUser(db);
+  trackCreated('users', user._id);
+
+  // Create product
+  const product = await createTestProduct(db);
+  trackCreated('products', product._id);
+
+  // Create order (references user and product)
+  const order = await createTestOrder(db, {
+    userId: user._id,
+    items: [{ productId: product._id, quantity: 1 }],
+  });
+  trackCreated('orders', order._id);
+
+  // All records will be cleaned up in reverse order
+});
+```
+
+## Cleanup Order
+
+Clean up in dependency order (children before parents):
+
+```typescript
+// Correct cleanup order
+const cleanupOrder = [
+  'orderItems',    // First: depends on orders and products
+  'orders',        // Second: depends on users
+  'sessions',      // Third: depends on users
+  'products',      // Fourth: independent
+  'users',         // Last: has dependents
+];
+
+async function cleanupAll(db: Db, createdIds: Map<string, ObjectId[]>) {
+  for (const collection of cleanupOrder) {
+    const ids = createdIds.get(collection);
+    if (ids && ids.length > 0) {
+      await db.collection(collection).deleteMany({
+        _id: { $in: ids },
+      });
+    }
+  }
+}
+```
+
+## Handling Cascading Deletes
+
+```typescript
+// If your DB has cascading deletes
+test.afterEach(async ({ db, createdIds }) => {
+  // Delete parent records - cascade handles children
+  const userIds = createdIds.get('users') || [];
+  if (userIds.length > 0) {
+    // This cascades to orders, sessions, etc.
+    await db.collection('users').deleteMany({
+      _id: { $in: userIds },
+    });
+  }
+});
+```
+
+## Flaky Test Prevention
+
+```typescript
+// Prevent flaky tests with proper isolation
+test.describe('User CRUD', () => {
+  // Each test is completely isolated
+  test.describe.configure({ mode: 'serial' });
+
+  test.beforeEach(async ({ db }) => {
+    // Ensure clean state
+    await db.collection('users').deleteMany({
+      email: { $regex: /^test_/ },
+    });
+  });
+
+  test('test 1', async ({ db, trackCreated }) => {
+    // Uses unique test email
+    const email = `test_${Date.now()}@example.com`;
+    // ...
+  });
+
+  test('test 2', async ({ db, trackCreated }) => {
+    // Uses different unique email
+    const email = `test_${Date.now()}@example.com`;
+    // ...
+  });
+});
+```
+
+## Debug Cleanup Issues
+
+```typescript
+// Add logging to debug cleanup
+test.afterEach(async ({ db, createdIds }) => {
+  console.log('=== CLEANUP START ===');
+
+  for (const [collection, ids] of createdIds.entries()) {
+    console.log(`Collection: ${collection}, IDs: ${ids.length}`);
+
+    if (ids.length > 0) {
+      const result = await db.collection(collection).deleteMany({
+        _id: { $in: ids },
+      });
+      console.log(`Deleted: ${result.deletedCount}`);
+    }
+  }
+
+  console.log('=== CLEANUP END ===');
+});
+```
+
+## Cleanup Verification
+
+```typescript
+// Verify cleanup worked
+test.afterEach(async ({ db, createdIds }) => {
+  // First cleanup
+  for (const [collection, ids] of createdIds.entries()) {
+    if (ids.length > 0) {
+      await db.collection(collection).deleteMany({
+        _id: { $in: ids },
+      });
+    }
+  }
+
+  // Verify cleanup
+  for (const [collection, ids] of createdIds.entries()) {
+    if (ids.length > 0) {
+      const remaining = await db.collection(collection).countDocuments({
+        _id: { $in: ids },
+      });
+      if (remaining > 0) {
+        console.error(`CLEANUP FAILED: ${remaining} records remain in ${collection}`);
+      }
+    }
+  }
+});
+```
+
+## Critical Rules
+
+1. **ALWAYS TRACK** - Every created record must be tracked
+2. **AUTO-CLEANUP** - Use afterEach, not manual cleanup
+3. **UNIQUE DATA** - Use timestamps in identifiers
+4. **ORDER MATTERS** - Clean children before parents
+5. **VERIFY CLEANUP** - Check records are actually deleted