thanh-kit 2.5.0 → 2.5.2

package/templates/skills/web-testing/references/contract-testing.md

@@ -0,0 +1,146 @@
+# Contract Testing
+
+## When to Use
+
+- Microservices communicating via HTTP/REST
+- Frontend consuming backend APIs
+- Multiple teams working on separate services
+- Preventing integration failures at runtime
+
+## Pact (Consumer-Driven Contracts)
+
+### Consumer Side
+
+```typescript
+import { Pact } from '@pact-foundation/pact';
+
+const provider = new Pact({
+  consumer: 'Frontend',
+  provider: 'UserService',
+});
+
+describe('User API', () => {
+  beforeAll(() => provider.setup());
+  afterEach(() => provider.verify());
+  afterAll(() => provider.finalize());
+
+  it('gets user by id', async () => {
+    await provider.addInteraction({
+      state: 'user 123 exists',
+      uponReceiving: 'request for user 123',
+      withRequest: {
+        method: 'GET',
+        path: '/users/123',
+      },
+      willRespondWith: {
+        status: 200,
+        body: {
+          id: '123',
+          name: 'John Doe',
+          email: 'john@example.com',
+        },
+      },
+    });
+
+    const user = await userClient.getUser('123');
+    expect(user.name).toBe('John Doe');
+  });
+});
+```
+
+### Provider Side
+
+```typescript
+import { Verifier } from '@pact-foundation/pact';
+
+describe('Pact Verification', () => {
+  it('validates consumer expectations', async () => {
+    await new Verifier({
+      providerBaseUrl: 'http://localhost:3000',
+      pactBrokerUrl: process.env.PACT_BROKER_URL,
+      provider: 'UserService',
+      providerVersion: process.env.GIT_SHA,
+      stateHandlers: {
+        'user 123 exists': async () => {
+          await db.users.insert({ id: '123', name: 'John Doe' });
+        },
+      },
+    }).verifyProvider();
+  });
+});
+```
+
+## MSW (Mock Service Worker)
+
+### Setup
+
+```typescript
+import { setupServer } from 'msw/node';
+import { http, HttpResponse } from 'msw';
+
+const handlers = [
+  http.get('/api/users/:id', ({ params }) => {
+    return HttpResponse.json({
+      id: params.id,
+      name: 'John Doe',
+    });
+  }),
+];
+
+export const server = setupServer(...handlers);
+
+// In test setup
+beforeAll(() => server.listen());
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+```
+
+### Per-Test Override
+
+```typescript
+it('handles server error', async () => {
+  server.use(
+    http.get('/api/users/:id', () => {
+      return HttpResponse.json({ error: 'Not found' }, { status: 404 });
+    })
+  );
+
+  await expect(userClient.getUser('123')).rejects.toThrow();
+});
+```
+
+## Pact + MSW Combined
+
+```typescript
+// Use MSW to simulate provider during Pact consumer tests
+const pactMswHandler = http.get('/api/users/:id', () => {
+  return HttpResponse.json(expectedPactResponse);
+});
+```
+
+## CI Integration
+
+```yaml
+# Consumer publishes contract
+- run: npx pact-broker publish ./pacts
+    --consumer-app-version=${{ github.sha }}
+    --broker-base-url=${{ secrets.PACT_BROKER_URL }}
+
+# Provider verifies
+- run: npm run test:pact:verify
+    --provider-app-version=${{ github.sha }}
+
+# Can-I-Deploy check
+- run: npx pact-broker can-i-deploy
+    --pacticipant=Frontend
+    --version=${{ github.sha }}
+    --to-environment=production
+```
+
+## Best Practices
+
+- **Consumer-first:** Consumers define expectations
+- **Version contracts:** Tie to git SHA
+- **Pact Broker:** Central contract management
+- **can-i-deploy:** Gate deployments on contract verification
+- **State handlers:** Prepare provider data for each scenario

package/templates/skills/web-testing/references/cross-browser-checklist.md

@@ -0,0 +1,72 @@
+# Cross-Browser & Responsive Testing
+
+## Browser Coverage
+
+| Browser | Priority |
+|---------|----------|
+| Chrome | Mandatory |
+| Safari | Mandatory (mobile) |
+| Edge | Mandatory |
+| Firefox | Recommended |
+
+## Device Breakpoints
+
+| Device | Viewport | Priority |
+|--------|----------|----------|
+| Mobile S | 320px | High |
+| Mobile M | 375px | High |
+| Tablet | 768px | High |
+| Laptop | 1024px | High |
+| Desktop | 1440px | High |
+
+## Playwright Config
+
+```typescript
+import { devices } from '@playwright/test';
+
+export default defineConfig({
+  projects: [
+    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
+    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
+    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
+    { name: 'mobile-chrome', use: { ...devices['Pixel 5'] } },
+    { name: 'mobile-safari', use: { ...devices['iPhone 12'] } },
+  ],
+});
+```
+
+## Responsive Checklist
+
+### Layout
+- [ ] Content reflows at all breakpoints
+- [ ] No horizontal scrolling on mobile
+- [ ] Navigation transforms to mobile menu
+- [ ] Touch targets 44px minimum
+
+### Forms
+- [ ] Input fields usable on mobile
+- [ ] Touch keyboard doesn't obscure inputs
+- [ ] Date pickers mobile-friendly
+
+### Interactive
+- [ ] Hover states have touch alternatives
+- [ ] Modals size appropriate per device
+
+## Browser-Specific Issues
+
+- **Safari**: flexbox gap, date input, WebP
+- **Firefox**: CSS grid subgrid, custom scrollbars
+- **Edge**: Same as Chromium (verify anyway)
+
+## Commands
+
+```bash
+npx playwright test --project=chromium
+npx playwright test --project=mobile-chrome --project=mobile-safari
+```
+
+## Testing Services
+
+- **BrowserStack**: Real device cloud
+- **Sauce Labs**: Cross-browser cloud
+- **Playwright**: Local emulation (free)

package/templates/skills/web-testing/references/database-testing.md

@@ -0,0 +1,139 @@
+# Database Testing
+
+## Testcontainers (Real Database Instances)
+
+### Setup
+
+```bash
+npm install -D @testcontainers/postgresql
+# or
+npm install -D @testcontainers/mongodb
+```
+
+### PostgreSQL Example
+
+```typescript
+import { PostgreSqlContainer } from '@testcontainers/postgresql';
+import { Pool } from 'pg';
+
+describe('User Repository', () => {
+  let container: PostgreSqlContainer;
+  let pool: Pool;
+
+  beforeAll(async () => {
+    container = await new PostgreSqlContainer()
+      .withDatabase('testdb')
+      .start();
+
+    pool = new Pool({ connectionString: container.getConnectionUri() });
+    await runMigrations(pool);
+  }, 60000); // 60s timeout for container start
+
+  afterAll(async () => {
+    await pool.end();
+    await container.stop();
+  });
+
+  afterEach(async () => {
+    await pool.query('TRUNCATE users RESTART IDENTITY CASCADE');
+  });
+
+  it('creates user', async () => {
+    const repo = new UserRepository(pool);
+    const user = await repo.create({ email: 'test@example.com' });
+    expect(user.id).toBeDefined();
+  });
+});
+```
+
+### MongoDB Example
+
+```typescript
+import { MongoDBContainer } from '@testcontainers/mongodb';
+import mongoose from 'mongoose';
+
+describe('User Repository', () => {
+  let container: MongoDBContainer;
+
+  beforeAll(async () => {
+    container = await new MongoDBContainer().start();
+    await mongoose.connect(container.getConnectionString(), {
+      directConnection: true,
+    });
+  }, 60000);
+
+  afterAll(async () => {
+    await mongoose.disconnect();
+    await container.stop();
+  });
+
+  afterEach(async () => {
+    await mongoose.connection.dropDatabase();
+  });
+});
+```
+
+## Transaction Rollback Pattern
+
+```typescript
+describe('User Service', () => {
+  let transaction: Transaction;
+
+  beforeEach(async () => {
+    transaction = await db.transaction();
+  });
+
+  afterEach(async () => {
+    await transaction.rollback(); // Always rollback
+  });
+
+  it('creates user within transaction', async () => {
+    const service = new UserService(transaction);
+    await service.create({ email: 'test@example.com' });
+    // Transaction rolls back - no cleanup needed
+  });
+});
+```
+
+## Playwright Database Fixture
+
+```typescript
+// fixtures/db.ts
+import { test as base } from '@playwright/test';
+import { PostgreSqlContainer } from '@testcontainers/postgresql';
+
+export const test = base.extend<{ db: Pool }>({
+  db: [async ({}, use, testInfo) => {
+    const container = await new PostgreSqlContainer().start();
+    const pool = new Pool({ connectionString: container.getConnectionUri() });
+
+    // Seed per-worker data
+    await seedData(pool, testInfo.workerIndex);
+
+    await use(pool);
+
+    await pool.end();
+    await container.stop();
+  }, { scope: 'worker' }]
+});
+```
+
+## In-Memory Alternatives
+
+```typescript
+// SQLite in-memory (faster, less realistic)
+const db = new Database(':memory:');
+
+// PGlite (Postgres in browser/Node)
+import { PGlite } from '@electric-sql/pglite';
+const db = new PGlite();
+```
+
+## Best Practices
+
+- **Real DB in CI:** Use Testcontainers for high fidelity
+- **In-memory locally:** Faster iteration during development
+- **Isolation:** Worker-scoped containers for parallel tests
+- **Migrations:** Always run migrations before tests
+- **Cleanup:** Truncate after each test, stop containers after all
+- **Timeouts:** Increase timeout for container startup (60s)

package/templates/skills/web-testing/references/e2e-testing-playwright.md

@@ -0,0 +1,119 @@
+# E2E Testing with Playwright
+
+## Setup
+
+```bash
+npm init playwright@latest
+npx playwright install
+```
+
+## Test Structure
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('User Login', () => {
+  test('should login successfully', async ({ page }) => {
+    await page.goto('/login');
+    await page.getByLabel('Email').fill('user@example.com');
+    await page.getByLabel('Password').fill('password123');
+    await page.getByRole('button', { name: 'Login' }).click();
+    await expect(page).toHaveURL('/dashboard');
+  });
+});
+```
+
+## Selector Priority (Accessibility-First)
+
+1. `getByRole('button', { name: 'Submit' })` - Most preferred
+2. `getByLabel('Email')` - Form fields
+3. `getByPlaceholderText('Search')` - Inputs
+4. `getByText('Welcome')` - Static text
+5. `getByTestId('submit-btn')` - Last resort
+
+## Advanced Fixtures
+
+### Worker-Scoped Authentication
+
+```typescript
+// fixtures/auth.ts
+export const test = baseTest.extend<{ authPage: Page }>({
+  authPage: [async ({ browser, request }, use, testInfo) => {
+    // API login per worker
+    const res = await request.post('/api/auth', {
+      data: { email: 'test@example.com', password: 'pass' }
+    });
+    const { token } = await res.json();
+
+    const context = await browser.newContext();
+    await context.addCookies([
+      { name: 'token', value: token, domain: 'localhost', path: '/' }
+    ]);
+    const page = await context.newPage();
+    await use(page);
+    await context.close();
+  }, { scope: 'worker' }]
+});
+```
+
+### Database Seeding Fixture
+
+```typescript
+// See ./database-testing.md for Testcontainers patterns
+```
+
+## Network Patterns
+
+### Wait for API
+
+```typescript
+const responsePromise = page.waitForResponse('**/api/users');
+await page.click('button:text("Load")');
+await responsePromise;
+```
+
+### Mock API
+
+```typescript
+await page.route('**/api/users', route =>
+  route.fulfill({ status: 200, body: JSON.stringify([]) })
+);
+```
+
+## Configuration
+
+```typescript
+export default defineConfig({
+  workers: process.env.CI ? 1 : undefined,
+  fullyParallel: true,
+  retries: process.env.CI ? 2 : 0,
+  use: {
+    screenshot: 'only-on-failure',
+    trace: 'on-first-retry',
+    video: 'retain-on-failure',
+  },
+});
+```
+
+## Sharding (CI)
+
+```bash
+npx playwright test --shard=1/4
+npx playwright test --shard=2/4
+```
+
+## Commands
+
+```bash
+npx playwright test                    # Run all
+npx playwright test --ui               # UI mode
+npx playwright test --project=chromium # Specific browser
+npx playwright codegen https://example.com  # Generate
+npx playwright show-report             # View report
+```
+
+## Related
+
+- `./playwright-component-testing.md` - CT patterns
+- `./playwright-fixtures-advanced.md` - Complex fixtures
+- `./database-testing.md` - DB fixtures

package/templates/skills/web-testing/references/functional-testing-checklist.md

@@ -0,0 +1,88 @@
+# Functional Testing Checklist
+
+## Core Features
+
+- [ ] Primary user workflows execute end-to-end
+- [ ] CRUD operations work (create, read, update, delete)
+- [ ] Error states handled gracefully
+- [ ] Validation rules enforced (email, phone, dates)
+- [ ] Search/filter functions correctly
+- [ ] Sorting works in both directions
+- [ ] Pagination displays correct data
+
+## User Workflows
+
+- [ ] Signup flow completes successfully
+- [ ] Login flow works with valid credentials
+- [ ] Password reset flow sends email and resets
+- [ ] Multi-step forms retain data between steps
+- [ ] Data persists after page refresh/navigation
+- [ ] Logout clears session completely
+- [ ] Deep links work correctly
+
+## Business Logic
+
+- [ ] Calculations correct (totals, discounts, taxes)
+- [ ] Rules enforced (age verification, region restrictions)
+- [ ] Edge cases handled (zero, negative, max values)
+- [ ] Date/time operations account for timezones
+- [ ] Currency formatting correct
+- [ ] Quantity limits enforced
+
+## Form Validation
+
+- [ ] Required fields show error when empty
+- [ ] Email format validation works
+- [ ] Password strength requirements shown
+- [ ] Phone number format accepted
+- [ ] Date picker prevents invalid dates
+- [ ] File upload validates type/size
+- [ ] Form submits only when valid
+
+## Integration Points
+
+- [ ] API calls succeed with correct parameters
+- [ ] Database operations persist
+- [ ] Third-party integrations work (payment, auth)
+- [ ] Error responses handled gracefully
+- [ ] Loading states displayed during async ops
+- [ ] Timeout handling for slow responses
+- [ ] Retry logic works on failures
+
+## Error Handling
+
+- [ ] Network errors show retry option
+- [ ] Invalid input shows helpful message
+- [ ] 401 errors trigger re-authentication
+- [ ] 403 errors show access denied
+- [ ] 404 errors show not found page
+- [ ] 500 errors logged, user sees friendly message
+- [ ] Validation errors highlight specific fields
+
+## State Management
+
+- [ ] URL reflects application state
+- [ ] Browser back/forward works correctly
+- [ ] Bookmarking preserves state
+- [ ] Shared links open correct view
+- [ ] State persists through refresh (when appropriate)
+
+## Test Priority Matrix
+
+| Priority | Category | Examples |
+|----------|----------|----------|
+| P0 (Critical) | Core flows | Signup, login, checkout, payment |
+| P1 (High) | Major features | Search, CRUD, navigation |
+| P2 (Medium) | Secondary features | Filters, sorting, pagination |
+| P3 (Low) | Edge cases | Empty states, max limits |
+
+## Test Data Checklist
+
+- [ ] Happy path data
+- [ ] Empty/null values
+- [ ] Boundary values (min, max)
+- [ ] Invalid data types
+- [ ] Unicode/special characters
+- [ ] Long strings
+- [ ] Whitespace (leading, trailing)
+- [ ] Duplicate data scenarios

package/templates/skills/web-testing/references/interactive-testing-patterns.md

@@ -0,0 +1,89 @@
+# Interactive Testing Patterns
+
+## Form Testing
+
+```javascript
+// Text input validation
+test('validates email format', async ({ page }) => {
+  await page.fill('[name="email"]', 'invalid');
+  await page.click('button[type="submit"]');
+  await expect(page.locator('.error')).toContainText('Invalid email');
+});
+
+// Select dropdowns
+await page.selectOption('select#country', 'US');
+await page.selectOption('select#country', { label: 'United States' });
+await page.selectOption('select#tags', ['tag1', 'tag2']); // Multi-select
+
+// Checkboxes & radios
+await page.check('input[name="terms"]');
+await expect(page.locator('input[name="terms"]')).toBeChecked();
+await page.uncheck('input[name="newsletter"]');
+await page.check('input[value="premium"]'); // Radio
+
+// File uploads
+await page.setInputFiles('input[type="file"]', 'path/to/file.pdf');
+await page.setInputFiles('input[type="file"]', ['file1.pdf', 'file2.pdf']);
+
+// Date picker
+await page.fill('input[type="date"]', '2025-12-25');
+await page.click('.date-picker-trigger');
+await page.click('.calendar-day:text("25")');
+```
+
+## Keyboard Navigation
+
+```javascript
+test('keyboard accessibility', async ({ page }) => {
+  await page.keyboard.press('Tab');
+  await expect(page.locator(':focus')).toHaveAttribute('data-testid', 'first-btn');
+  await page.keyboard.press('Enter'); // Activate
+  await page.keyboard.press('Escape'); // Close modal
+  await page.keyboard.press('Shift+Tab'); // Navigate backward
+});
+```
+
+## Drag & Drop
+
+```javascript
+await page.dragAndDrop('#source', '#target');
+
+// Manual control
+const source = page.locator('#draggable');
+await source.hover();
+await page.mouse.down();
+await page.locator('#dropzone').hover();
+await page.mouse.up();
+```
+
+## Hover & Modals
+
+```javascript
+await button.hover();
+await expect(page.locator('.tooltip')).toBeVisible();
+
+// Modal workflow
+await page.click('button:text("Open")');
+await expect(page.locator('[role="dialog"]')).toBeVisible();
+await page.click('[aria-label="Close"]');
+await expect(page.locator('[role="dialog"]')).not.toBeVisible();
+```
+
+## Scroll & Wait Patterns
+
+```javascript
+await page.locator('#footer').scrollIntoViewIfNeeded();
+await page.evaluate(() => window.scrollTo(0, document.body.scrollHeight));
+
+// Wait patterns
+await page.waitForLoadState('networkidle');
+await Promise.all([page.waitForResponse('**/api/data'), page.click('button.load')]);
+```
+
+## Disable Animations
+
+```javascript
+await page.addStyleTag({
+  content: '* { animation-duration: 0s !important; transition-duration: 0s !important; }'
+});
+```