stably 4.5.3 → 4.5.4

package/dist/stably-plugin/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "stably-agent",
+  "description": "Internal skills for the Stably CLI agent",
+  "version": "1.0.0"
+}

package/dist/stably-plugin/skills/playwright-best-practices/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: playwright-best-practices
+description: Provides comprehensive guidance for writing, debugging, and maintaining Playwright tests in TypeScript. Use when writing Playwright tests, fixing flaky tests, debugging failures, implementing Page Object Model, configuring CI/CD, optimizing performance, mocking APIs, handling authentication or OAuth, testing accessibility (axe-core), file uploads/downloads, date/time mocking, WebSockets, geolocation, permissions, multi-tab/popup flows, mobile/responsive layouts, touch gestures, GraphQL, error handling, offline mode, multi-user collaboration, third-party services (payments, email verification), console error monitoring, global setup/teardown, test annotations (skip, fixme, slow), project dependencies, security testing (XSS, CSRF, auth), performance budgets (Web Vitals, Lighthouse), iframes, component testing, canvas/WebGL, service workers/PWA, test coverage, i18n/localization, Electron apps, or browser extension testing. Covers E2E, component, API, visual, accessibility, security, Electron, and extension testing.
+license: MIT
+metadata:
+  author: currents.dev
+  version: "1.0"
+---
+
+# Playwright Best Practices
+
+This skill provides comprehensive guidance for all aspects of Playwright test development, from writing new tests to debugging and maintaining existing test suites.
+
+## Activity-Based Reference Guide
+
+Consult these references based on what you're doing:
+
+### Writing New Tests
+
+**When to use**: Creating new test files, writing test cases, implementing test scenarios
+
+| Activity                            | Reference Files                                                                                                                                           |
+| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Writing E2E tests**               | [test-organization.md](references/test-organization.md), [locators.md](references/locators.md), [assertions-waiting.md](references/assertions-waiting.md) |
+| **Writing component tests**         | [component-testing.md](references/component-testing.md), [test-organization.md](references/test-organization.md)                                          |
+| **Writing API tests**               | [test-organization.md](references/test-organization.md), [assertions-waiting.md](references/assertions-waiting.md)                                        |
+| **Writing visual regression tests** | [test-organization.md](references/test-organization.md), [canvas-webgl.md](references/canvas-webgl.md)                                                    |
+| **Structuring test code with POM**  | [page-object-model.md](references/page-object-model.md), [test-organization.md](references/test-organization.md)                                          |
+| **Setting up test data/fixtures**   | [fixtures-hooks.md](references/fixtures-hooks.md), [test-data.md](references/test-data.md)                                                                |
+| **Handling authentication**         | [fixtures-hooks.md](references/fixtures-hooks.md), [third-party.md](references/third-party.md)                                                            |
+| **Testing date/time features**      | [clock-mocking.md](references/clock-mocking.md)                                                                                                           |
+| **Testing file upload/download**    | [file-operations.md](references/file-operations.md)                                                                                                       |
+| **Testing accessibility**           | [accessibility.md](references/accessibility.md)                                                                                                           |
+| **Testing security (XSS, CSRF)**    | [security-testing.md](references/security-testing.md)                                                                                                     |
+| **Using test annotations**          | [annotations.md](references/annotations.md)                                                                                                               |
+| **Testing iframes**                 | [iframes.md](references/iframes.md)                                                                                                                       |
+| **Testing canvas/WebGL**            | [canvas-webgl.md](references/canvas-webgl.md)                                                                                                             |
+| **Internationalization (i18n)**     | [i18n.md](references/i18n.md)                                                                                                                             |
+| **Testing Electron apps**           | [electron.md](references/electron.md)                                                                                                                     |
+| **Testing browser extensions**      | [browser-extensions.md](references/browser-extensions.md)                                                                                                 |
+
+### Mobile & Responsive Testing
+
+**When to use**: Testing mobile devices, touch interactions, responsive layouts
+
+| Activity                        | Reference Files                                                                          |
+| ------------------------------- | ---------------------------------------------------------------------------------------- |
+| **Device emulation**            | [mobile-testing.md](references/mobile-testing.md)                                        |
+| **Touch gestures (swipe, tap)** | [mobile-testing.md](references/mobile-testing.md)                                        |
+| **Viewport/breakpoint testing** | [mobile-testing.md](references/mobile-testing.md)                                        |
+| **Mobile-specific UI**          | [mobile-testing.md](references/mobile-testing.md), [locators.md](references/locators.md) |
+
+### Real-Time & Browser APIs
+
+**When to use**: Testing WebSockets, geolocation, permissions, multi-tab flows
+
+| Activity                        | Reference Files                                                                              |
+| ------------------------------- | -------------------------------------------------------------------------------------------- |
+| **WebSocket/real-time testing** | [websockets.md](references/websockets.md)                                                    |
+| **Geolocation mocking**         | [browser-apis.md](references/browser-apis.md)                                                |
+| **Permission handling**         | [browser-apis.md](references/browser-apis.md)                                                |
+| **Clipboard testing**           | [browser-apis.md](references/browser-apis.md)                                                |
+| **Camera/microphone mocking**   | [browser-apis.md](references/browser-apis.md)                                                |
+| **Multi-tab/popup flows**       | [multi-context.md](references/multi-context.md)                                              |
+| **OAuth popup handling**        | [third-party.md](references/third-party.md), [multi-context.md](references/multi-context.md) |
+
+### Debugging & Troubleshooting
+
+**When to use**: Test failures, element not found, timeouts, unexpected behavior
+
+| Activity                                          | Reference Files                                                                                                                                 |
+| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Debugging test failures**                       | [debugging.md](references/debugging.md), [assertions-waiting.md](references/assertions-waiting.md)                                              |
+| **Fixing flaky tests**                            | [flaky-tests.md](references/flaky-tests.md), [debugging.md](references/debugging.md), [assertions-waiting.md](references/assertions-waiting.md) |
+| **Debugging flaky parallel runs**                 | [flaky-tests.md](references/flaky-tests.md), [performance.md](references/performance.md), [fixtures-hooks.md](references/fixtures-hooks.md)     |
+| **Ensuring test isolation / avoiding state leak** | [flaky-tests.md](references/flaky-tests.md), [fixtures-hooks.md](references/fixtures-hooks.md), [performance.md](references/performance.md)     |
+| **Fixing selector issues**                        | [locators.md](references/locators.md), [debugging.md](references/debugging.md)                                                                  |
+| **Investigating timeout issues**                  | [assertions-waiting.md](references/assertions-waiting.md), [debugging.md](references/debugging.md)                                              |
+| **Using trace viewer**                            | [debugging.md](references/debugging.md)                                                                                                         |
+| **Debugging race conditions**                     | [flaky-tests.md](references/flaky-tests.md), [debugging.md](references/debugging.md), [assertions-waiting.md](references/assertions-waiting.md) |
+| **Debugging console/JS errors**                   | [console-errors.md](references/console-errors.md), [debugging.md](references/debugging.md)                                                      |
+
+### Error & Edge Case Testing
+
+**When to use**: Testing error states, offline mode, network failures, validation
+
+| Activity                       | Reference Files                                                                                        |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------ |
+| **Error boundary testing**     | [error-testing.md](references/error-testing.md)                                                        |
+| **Network failure simulation** | [error-testing.md](references/error-testing.md), [network-advanced.md](references/network-advanced.md) |
+| **Offline mode testing**       | [error-testing.md](references/error-testing.md), [service-workers.md](references/service-workers.md)   |
+| **Service worker testing**     | [service-workers.md](references/service-workers.md)                                                    |
+| **Loading state testing**      | [error-testing.md](references/error-testing.md)                                                        |
+| **Form validation testing**    | [error-testing.md](references/error-testing.md)                                                        |
+
+### Multi-User & Collaboration Testing
+
+**When to use**: Testing features involving multiple users, roles, or real-time collaboration
+
+| Activity                       | Reference Files                                                                      |
+| ------------------------------ | ------------------------------------------------------------------------------------ |
+| **Multiple users in one test** | [multi-user.md](references/multi-user.md)                                            |
+| **Real-time collaboration**    | [multi-user.md](references/multi-user.md), [websockets.md](references/websockets.md) |
+| **Role-based access testing**  | [multi-user.md](references/multi-user.md)                                            |
+| **Concurrent action testing**  | [multi-user.md](references/multi-user.md)                                            |
+
+### Refactoring & Maintenance
+
+**When to use**: Improving existing tests, code review, reducing duplication
+
+| Activity                             | Reference Files                                                                                                  |
+| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
+| **Refactoring to Page Object Model** | [page-object-model.md](references/page-object-model.md), [test-organization.md](references/test-organization.md) |
+| **Improving test organization**      | [test-organization.md](references/test-organization.md), [page-object-model.md](references/page-object-model.md) |
+| **Extracting common setup/teardown** | [fixtures-hooks.md](references/fixtures-hooks.md)                                                                |
+| **Replacing brittle selectors**      | [locators.md](references/locators.md)                                                                            |
+| **Removing explicit waits**          | [assertions-waiting.md](references/assertions-waiting.md)                                                        |
+| **Creating test data factories**     | [test-data.md](references/test-data.md)                                                                          |
+
+### Infrastructure & Configuration
+
+**When to use**: Setting up projects, configuring CI/CD, optimizing performance
+
+| Activity                                | Reference Files                                                                                                          |
+| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| **Configuring Playwright project**      | [test-organization.md](references/test-organization.md), [projects-dependencies.md](references/projects-dependencies.md) |
+| **Setting up CI/CD pipelines**          | [ci-cd.md](references/ci-cd.md), [performance.md](references/performance.md)                                             |
+| **Global setup & teardown**             | [global-setup.md](references/global-setup.md)                                                                            |
+| **Project dependencies**                | [projects-dependencies.md](references/projects-dependencies.md)                                                          |
+| **Optimizing test performance**         | [performance.md](references/performance.md), [test-organization.md](references/test-organization.md)                     |
+| **Configuring parallel execution**      | [performance.md](references/performance.md)                                                                              |
+| **Isolating test data between workers** | [fixtures-hooks.md](references/fixtures-hooks.md), [performance.md](references/performance.md)                           |
+| **Test coverage**                       | [test-coverage.md](references/test-coverage.md)                                                                          |
+
+### Advanced Patterns
+
+**When to use**: Complex scenarios, API mocking, network interception
+
+| Activity                             | Reference Files                                                                                                  |
+| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
+| **Mocking API responses**            | [test-organization.md](references/test-organization.md), [network-advanced.md](references/network-advanced.md)   |
+| **Network interception**             | [network-advanced.md](references/network-advanced.md), [assertions-waiting.md](references/assertions-waiting.md) |
+| **GraphQL mocking**                  | [network-advanced.md](references/network-advanced.md)                                                            |
+| **HAR recording/playback**           | [network-advanced.md](references/network-advanced.md)                                                            |
+| **Custom fixtures**                  | [fixtures-hooks.md](references/fixtures-hooks.md)                                                                |
+| **Advanced waiting strategies**      | [assertions-waiting.md](references/assertions-waiting.md)                                                        |
+| **OAuth/SSO mocking**                | [third-party.md](references/third-party.md), [multi-context.md](references/multi-context.md)                     |
+| **Payment gateway mocking**          | [third-party.md](references/third-party.md)                                                                      |
+| **Email/SMS verification mocking**   | [third-party.md](references/third-party.md)                                                                      |
+| **Failing on console errors**        | [console-errors.md](references/console-errors.md)                                                                |
+| **Security testing (XSS, CSRF)**     | [security-testing.md](references/security-testing.md)                                                            |
+| **Performance budgets & Web Vitals** | [performance-testing.md](references/performance-testing.md)                                                      |
+| **Lighthouse integration**           | [performance-testing.md](references/performance-testing.md)                                                      |
+| **Test annotations (skip, fixme)**   | [annotations.md](references/annotations.md)                                                                      |
+| **Test steps for reporting**         | [annotations.md](references/annotations.md)                                                                      |
+
+## Quick Decision Tree
+
+```
+What are you doing?
+│
+├─ Writing a new test?
+│  ├─ E2E test → test-organization.md, locators.md, assertions-waiting.md
+│  ├─ Component test → component-testing.md
+│  ├─ API test → test-organization.md, assertions-waiting.md
+│  ├─ Visual/canvas test → canvas-webgl.md, test-organization.md
+│  ├─ Accessibility test → accessibility.md
+│  ├─ Mobile/responsive test → mobile-testing.md
+│  ├─ i18n/locale test → i18n.md
+│  ├─ Electron app test → electron.md
+│  ├─ Browser extension test → browser-extensions.md
+│  └─ Multi-user test → multi-user.md
+│
+├─ Testing specific features?
+│  ├─ File upload/download → file-operations.md
+│  ├─ Date/time dependent → clock-mocking.md
+│  ├─ WebSocket/real-time → websockets.md
+│  ├─ Geolocation/permissions → browser-apis.md
+│  ├─ OAuth/SSO mocking → third-party.md, multi-context.md
+│  ├─ Payments/email/SMS → third-party.md
+│  ├─ iFrames → iframes.md
+│  ├─ Canvas/WebGL/charts → canvas-webgl.md
+│  ├─ Service workers/PWA → service-workers.md
+│  ├─ i18n/localization → i18n.md
+│  ├─ Security (XSS, CSRF) → security-testing.md
+│  └─ Performance/Web Vitals → performance-testing.md
+│
+├─ Test is failing/flaky?
+│  ├─ Flaky test investigation → flaky-tests.md
+│  ├─ Element not found → locators.md, debugging.md
+│  ├─ Timeout issues → assertions-waiting.md, debugging.md
+│  ├─ Race conditions → flaky-tests.md, debugging.md
+│  ├─ Flaky only with multiple workers → flaky-tests.md, performance.md
+│  ├─ State leak / isolation → flaky-tests.md, fixtures-hooks.md
+│  ├─ Console/JS errors → console-errors.md, debugging.md
+│  └─ General debugging → debugging.md
+│
+├─ Testing error scenarios?
+│  ├─ Network failures → error-testing.md, network-advanced.md
+│  ├─ Offline (unexpected) → error-testing.md
+│  ├─ Offline-first/PWA → service-workers.md
+│  ├─ Error boundaries → error-testing.md
+│  └─ Form validation → error-testing.md
+│
+├─ Refactoring existing code?
+│  ├─ Implementing POM → page-object-model.md
+│  ├─ Improving selectors → locators.md
+│  ├─ Extracting fixtures → fixtures-hooks.md
+│  └─ Creating data factories → test-data.md
+│
+├─ Setting up infrastructure?
+│  ├─ CI/CD → ci-cd.md
+│  ├─ Global setup/teardown → global-setup.md
+│  ├─ Project dependencies → projects-dependencies.md
+│  ├─ Test performance → performance.md
+│  ├─ Test coverage → test-coverage.md
+│  └─ Project config → test-organization.md, projects-dependencies.md
+│
+└─ Organizing tests?
+   ├─ Skip/fixme/slow tests → annotations.md
+   ├─ Test steps → annotations.md
+   └─ Conditional execution → annotations.md
+```
+
+## Test Validation Loop
+
+After writing or modifying tests:
+
+1. **Run tests**: `npx playwright test --reporter=list`
+2. **If tests fail**:
+   - Review error output and trace (`npx playwright show-trace`)
+   - Fix locators, waits, or assertions
+   - Re-run tests
+3. **Only proceed when all tests pass**
+4. **Run multiple times** for critical tests: `npx playwright test --repeat-each=5`

package/dist/stably-plugin/skills/playwright-best-practices/references/accessibility.md

@@ -0,0 +1,359 @@
+# Accessibility Testing
+
+## Table of Contents
+
+1. [Axe-Core Integration](#axe-core-integration)
+2. [Keyboard Navigation](#keyboard-navigation)
+3. [ARIA Validation](#aria-validation)
+4. [Focus Management](#focus-management)
+5. [Color & Contrast](#color--contrast)
+
+## Axe-Core Integration
+
+### Setup
+
+```bash
+npm install -D @axe-core/playwright
+```
+
+### Basic A11y Test
+
+```typescript
+import { test, expect } from "@playwright/test";
+import AxeBuilder from "@axe-core/playwright";
+
+test("homepage should have no a11y violations", async ({ page }) => {
+  await page.goto("/");
+
+  const results = await new AxeBuilder({ page }).analyze();
+
+  expect(results.violations).toEqual([]);
+});
+```
+
+### Scoped Analysis
+
+```typescript
+test("form accessibility", async ({ page }) => {
+  await page.goto("/contact");
+
+  // Analyze only the form
+  const results = await new AxeBuilder({ page })
+    .include("#contact-form")
+    .analyze();
+
+  expect(results.violations).toEqual([]);
+});
+
+test("ignore known issues", async ({ page }) => {
+  await page.goto("/legacy-page");
+
+  const results = await new AxeBuilder({ page })
+    .exclude(".legacy-widget") // Skip legacy component
+    .disableRules(["color-contrast"]) // Disable specific rule
+    .analyze();
+
+  expect(results.violations).toEqual([]);
+});
+```
+
+### A11y Fixture
+
+```typescript
+// fixtures/a11y.fixture.ts
+import { test as base } from "@playwright/test";
+import AxeBuilder from "@axe-core/playwright";
+
+type A11yFixtures = {
+  makeAxeBuilder: () => AxeBuilder;
+};
+
+export const test = base.extend<A11yFixtures>({
+  makeAxeBuilder: async ({ page }, use) => {
+    await use(() =>
+      new AxeBuilder({ page }).withTags([
+        "wcag2a",
+        "wcag2aa",
+        "wcag21a",
+        "wcag21aa",
+      ]),
+    );
+  },
+});
+
+// Usage
+test("dashboard a11y", async ({ page, makeAxeBuilder }) => {
+  await page.goto("/dashboard");
+  const results = await makeAxeBuilder().analyze();
+  expect(results.violations).toEqual([]);
+});
+```
+
+### Detailed Violation Reporting
+
+```typescript
+test("report a11y issues", async ({ page }) => {
+  await page.goto("/");
+
+  const results = await new AxeBuilder({ page }).analyze();
+
+  // Custom failure message with details
+  const violations = results.violations.map((v) => ({
+    id: v.id,
+    impact: v.impact,
+    description: v.description,
+    nodes: v.nodes.map((n) => n.html),
+  }));
+
+  expect(violations, JSON.stringify(violations, null, 2)).toHaveLength(0);
+});
+```
+
+## Keyboard Navigation
+
+### Tab Order Testing
+
+```typescript
+test("correct tab order in form", async ({ page }) => {
+  await page.goto("/signup");
+
+  // Start from the beginning
+  await page.keyboard.press("Tab");
+  await expect(page.getByLabel("Email")).toBeFocused();
+
+  await page.keyboard.press("Tab");
+  await expect(page.getByLabel("Password")).toBeFocused();
+
+  await page.keyboard.press("Tab");
+  await expect(page.getByRole("button", { name: "Sign up" })).toBeFocused();
+});
+```
+
+### Keyboard-Only Interaction
+
+```typescript
+test("complete flow with keyboard only", async ({ page }) => {
+  await page.goto("/products");
+
+  // Navigate to product with keyboard
+  await page.keyboard.press("Tab"); // Skip to main content
+  await page.keyboard.press("Tab"); // First product
+  await page.keyboard.press("Enter"); // Open product
+
+  await expect(page).toHaveURL(/\/products\/\d+/);
+
+  // Add to cart with keyboard
+  await page.keyboard.press("Tab");
+  await page.keyboard.press("Tab"); // Navigate to "Add to Cart"
+  await page.keyboard.press("Enter");
+
+  await expect(page.getByRole("alert")).toContainText("Added to cart");
+});
+```
+
+### Skip Links
+
+```typescript
+test("skip link works", async ({ page }) => {
+  await page.goto("/");
+
+  await page.keyboard.press("Tab");
+  const skipLink = page.getByRole("link", { name: /skip to main/i });
+  await expect(skipLink).toBeFocused();
+
+  await page.keyboard.press("Enter");
+
+  // Focus should move to main content
+  await expect(page.getByRole("main")).toBeFocused();
+});
+```
+
+### Escape Key Handling
+
+```typescript
+test("escape closes modal", async ({ page }) => {
+  await page.goto("/dashboard");
+  await page.getByRole("button", { name: "Settings" }).click();
+
+  const modal = page.getByRole("dialog");
+  await expect(modal).toBeVisible();
+
+  await page.keyboard.press("Escape");
+
+  await expect(modal).toBeHidden();
+  // Focus should return to trigger
+  await expect(page.getByRole("button", { name: "Settings" })).toBeFocused();
+});
+```
+
+## ARIA Validation
+
+### Role Verification
+
+```typescript
+test("correct ARIA roles", async ({ page }) => {
+  await page.goto("/dashboard");
+
+  // Verify landmark roles
+  await expect(page.getByRole("navigation")).toBeVisible();
+  await expect(page.getByRole("main")).toBeVisible();
+  await expect(page.getByRole("contentinfo")).toBeVisible(); // footer
+
+  // Verify interactive roles
+  await expect(page.getByRole("button", { name: "Menu" })).toBeVisible();
+  await expect(page.getByRole("search")).toBeVisible();
+});
+```
+
+### ARIA States
+
+```typescript
+test("aria-expanded updates correctly", async ({ page }) => {
+  await page.goto("/faq");
+
+  const accordion = page.getByRole("button", { name: "Shipping" });
+
+  // Initially collapsed
+  await expect(accordion).toHaveAttribute("aria-expanded", "false");
+
+  await accordion.click();
+
+  // Now expanded
+  await expect(accordion).toHaveAttribute("aria-expanded", "true");
+
+  // Content is visible
+  const panel = page.getByRole("region", { name: "Shipping" });
+  await expect(panel).toBeVisible();
+});
+```
+
+### Live Regions
+
+```typescript
+test("live region announces updates", async ({ page }) => {
+  await page.goto("/checkout");
+
+  // Find live region
+  const liveRegion = page.locator('[aria-live="polite"]');
+
+  await page.getByLabel("Quantity").fill("3");
+
+  // Live region should update with new total
+  await expect(liveRegion).toContainText("Total: $29.97");
+});
+```
+
+## Focus Management
+
+### Focus Trap in Modal
+
+```typescript
+test("focus trapped in modal", async ({ page }) => {
+  await page.goto("/");
+  await page.getByRole("button", { name: "Open Modal" }).click();
+
+  const modal = page.getByRole("dialog");
+  await expect(modal).toBeVisible();
+
+  // Get all focusable elements in modal
+  const focusableElements = modal.locator(
+    'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])',
+  );
+  const count = await focusableElements.count();
+
+  // Tab through all elements, should stay in modal
+  for (let i = 0; i < count + 1; i++) {
+    await page.keyboard.press("Tab");
+    const focused = page.locator(":focus");
+    await expect(modal).toContainText((await focused.textContent()) || "");
+  }
+});
+```
+
+### Focus Restoration
+
+```typescript
+test("focus returns after modal close", async ({ page }) => {
+  await page.goto("/");
+
+  const trigger = page.getByRole("button", { name: "Delete Item" });
+  await trigger.click();
+
+  await page.getByRole("button", { name: "Cancel" }).click();
+
+  // Focus should return to the trigger
+  await expect(trigger).toBeFocused();
+});
+```
+
+## Color & Contrast
+
+### High Contrast Mode
+
+```typescript
+test("works in high contrast mode", async ({ page }) => {
+  await page.emulateMedia({ forcedColors: "active" });
+  await page.goto("/");
+
+  // Verify key elements are visible
+  await expect(page.getByRole("navigation")).toBeVisible();
+  await expect(page.getByRole("button", { name: "Sign In" })).toBeVisible();
+
+  // Take screenshot for visual verification
+  await expect(page).toHaveScreenshot("high-contrast.png");
+});
+```
+
+### Reduced Motion
+
+```typescript
+test("respects reduced motion preference", async ({ page }) => {
+  await page.emulateMedia({ reducedMotion: "reduce" });
+  await page.goto("/");
+
+  // Animations should be disabled
+  const hero = page.getByTestId("hero-animation");
+  const animation = await hero.evaluate(
+    (el) => getComputedStyle(el).animationDuration,
+  );
+
+  expect(animation).toBe("0s");
+});
+```
+
+## CI Integration
+
+### A11y as CI Gate
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+  projects: [
+    {
+      name: "a11y",
+      testMatch: /.*\.a11y\.spec\.ts/,
+      use: { ...devices["Desktop Chrome"] },
+    },
+  ],
+});
+```
+
+```yaml
+# .github/workflows/a11y.yml
+- name: Run accessibility tests
+  run: npx playwright test --project=a11y
+```
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern                  | Problem                      | Solution                                   |
+| ----------------------------- | ---------------------------- | ------------------------------------------ |
+| Testing a11y only on homepage | Misses issues on other pages | Test all critical user flows               |
+| Ignoring all violations       | No value from tests          | Address or explicitly exclude known issues |
+| Only automated testing        | Misses many a11y issues      | Combine with manual testing                |
+| Testing without screen reader | Misses interaction issues    | Test with VoiceOver/NVDA periodically      |
+
+## Related References
+
+- **Locators**: See [locators.md](locators.md) for role-based selectors
+- **Visual testing**: See [test-organization.md](test-organization.md) for screenshot comparison