@schalkneethling/toolkit 0.5.0 → 0.5.3

package/skills/frontend-testing/references/accessibility-testing.md

@@ -5,6 +5,7 @@ Automated accessibility testing catches common issues early. Combine with manual
 ## Limitations of Automated Testing
 
 Automated tools detect approximately 30-40% of accessibility issues. They catch:
+
 - Missing labels and alt text
 - Color contrast violations
 - Invalid ARIA attributes
@@ -12,6 +13,7 @@ Automated tools detect approximately 30-40% of accessibility issues. They catch:
 - Missing landmark regions
 
 They cannot catch:
+
 - Logical reading order
 - Meaningful link text in context
 - Appropriate focus management
@@ -37,9 +39,9 @@ import AxeBuilder from "@axe-core/playwright";
 test.describe("Homepage", () => {
   test("has no automatically detectable accessibility violations", async ({ page }) => {
     await page.goto("/");
-    
+
     const accessibilityScanResults = await new AxeBuilder({ page }).analyze();
-    
+
     expect(accessibilityScanResults.violations).toEqual([]);
   });
 });
@@ -52,15 +54,15 @@ Always ensure the page is in the expected state before scanning:
 ```javascript
 test("navigation menu is accessible when open", async ({ page }) => {
   await page.goto("/");
-  
+
   // Open the menu
   await page.getByRole("button", { name: /menu/i }).click();
-  
+
   // Wait for menu to be visible before scanning
   await page.getByRole("navigation", { name: /main/i }).waitFor();
-  
+
   const results = await new AxeBuilder({ page }).analyze();
-  
+
   expect(results.violations).toEqual([]);
 });
 ```
@@ -72,11 +74,11 @@ Focus on components you're testing:
 ```javascript
 test("checkout form is accessible", async ({ page }) => {
   await page.goto("/checkout");
-  
+
   const results = await new AxeBuilder({ page })
-    .include("#checkout-form")  // Only scan this region
+    .include("#checkout-form") // Only scan this region
     .analyze();
-  
+
   expect(results.violations).toEqual([]);
 });
 ```
@@ -87,8 +89,8 @@ Temporarily exclude elements while fixing issues:
 
 ```javascript
 const results = await new AxeBuilder({ page })
-  .exclude("#third-party-widget")      // Can't control this
-  .exclude("[data-ad-unit]")           // Ads managed externally
+  .exclude("#third-party-widget") // Can't control this
+  .exclude("[data-ad-unit]") // Ads managed externally
   .analyze();
 ```
 
@@ -110,19 +112,17 @@ const results = await new AxeBuilder({ page })
   .analyze();
 
 // Best practices (not WCAG requirements but recommended)
-const results = await new AxeBuilder({ page })
-  .withTags(["best-practice"])
-  .analyze();
+const results = await new AxeBuilder({ page }).withTags(["best-practice"]).analyze();
 ```
 
 ### Common Tag Sets
 
-| Target | Tags |
-|--------|------|
-| WCAG 2.1 AA | `["wcag2a", "wcag2aa", "wcag21a", "wcag21aa"]` |
-| WCAG 2.2 AA | Add `"wcag22aa"` |
-| Section 508 | `["section508"]` |
-| Best practices | `["best-practice"]` |
+| Target         | Tags                                           |
+| -------------- | ---------------------------------------------- |
+| WCAG 2.1 AA    | `["wcag2a", "wcag2aa", "wcag21a", "wcag21aa"]` |
+| WCAG 2.2 AA    | Add `"wcag22aa"`                               |
+| Section 508    | `["section508"]`                               |
+| Best practices | `["best-practice"]`                            |
 
 ## Creating Reusable Fixtures
 
@@ -135,11 +135,12 @@ import AxeBuilder from "@axe-core/playwright";
 
 export const test = base.extend({
   makeAxeBuilder: async ({ page }, use) => {
-    const makeAxeBuilder = () => new AxeBuilder({ page })
-      .withTags(["wcag2a", "wcag2aa", "wcag21a", "wcag21aa"])
-      .exclude("#cookie-banner")  // Known third-party issue
-      .exclude("[data-testid='ad-unit']");
-    
+    const makeAxeBuilder = () =>
+      new AxeBuilder({ page })
+        .withTags(["wcag2a", "wcag2aa", "wcag21a", "wcag21aa"])
+        .exclude("#cookie-banner") // Known third-party issue
+        .exclude("[data-testid='ad-unit']");
+
     await use(makeAxeBuilder);
   },
 });
@@ -154,9 +155,9 @@ import { test, expect } from "./fixtures/axe";
 
 test("product page is accessible", async ({ page, makeAxeBuilder }) => {
   await page.goto("/products/123");
-  
+
   const results = await makeAxeBuilder().analyze();
-  
+
   expect(results.violations).toEqual([]);
 });
 ```
@@ -169,13 +170,13 @@ test("product page is accessible", async ({ page, makeAxeBuilder }) => {
 const results = await new AxeBuilder({ page }).analyze();
 
 // Structure of a violation
-results.violations.forEach(violation => {
+results.violations.forEach((violation) => {
   console.log(`Rule: ${violation.id}`);
-  console.log(`Impact: ${violation.impact}`);  // minor, moderate, serious, critical
+  console.log(`Impact: ${violation.impact}`); // minor, moderate, serious, critical
   console.log(`Description: ${violation.description}`);
   console.log(`Help: ${violation.helpUrl}`);
-  
-  violation.nodes.forEach(node => {
+
+  violation.nodes.forEach((node) => {
     console.log(`  Element: ${node.html}`);
     console.log(`  Fix: ${node.failureSummary}`);
   });
@@ -184,12 +185,12 @@ results.violations.forEach(violation => {
 
 ### Impact Levels
 
-| Level | Description | Priority |
-|-------|-------------|----------|
-| Critical | Blocks access for some users | Fix immediately |
-| Serious | Major barriers | Fix soon |
-| Moderate | Inconsistencies | Plan to fix |
-| Minor | Annoyances | Improve when possible |
+| Level    | Description                  | Priority              |
+| -------- | ---------------------------- | --------------------- |
+| Critical | Blocks access for some users | Fix immediately       |
+| Serious  | Major barriers               | Fix soon              |
+| Moderate | Inconsistencies              | Plan to fix           |
+| Minor    | Annoyances                   | Improve when possible |
 
 ### Progressive Enforcement
 
@@ -197,14 +198,12 @@ Start permissive, tighten over time:
 
 ```javascript
 // Phase 1: Only critical issues fail
-const criticalViolations = results.violations.filter(
-  v => v.impact === "critical"
-);
+const criticalViolations = results.violations.filter((v) => v.impact === "critical");
 expect(criticalViolations).toEqual([]);
 
 // Phase 2: Critical and serious
-const seriousViolations = results.violations.filter(
-  v => ["critical", "serious"].includes(v.impact)
+const seriousViolations = results.violations.filter((v) =>
+  ["critical", "serious"].includes(v.impact),
 );
 expect(seriousViolations).toEqual([]);
 
@@ -218,7 +217,7 @@ When you have a known issue being addressed:
 
 ```javascript
 const results = await new AxeBuilder({ page })
-  .disableRules(["color-contrast"])  // Tracked in JIRA-123
+  .disableRules(["color-contrast"]) // Tracked in JIRA-123
   .analyze();
 ```
 
@@ -234,17 +233,13 @@ Test components in isolation:
 test.describe("Button component", () => {
   test("default button is accessible", async ({ page }) => {
     await page.goto("/storybook/button--default");
-    const results = await new AxeBuilder({ page })
-      .include("#storybook-root")
-      .analyze();
+    const results = await new AxeBuilder({ page }).include("#storybook-root").analyze();
     expect(results.violations).toEqual([]);
   });
-  
+
   test("disabled button is accessible", async ({ page }) => {
     await page.goto("/storybook/button--disabled");
-    const results = await new AxeBuilder({ page })
-      .include("#storybook-root")
-      .analyze();
+    const results = await new AxeBuilder({ page }).include("#storybook-root").analyze();
     expect(results.violations).toEqual([]);
   });
 });
@@ -260,13 +255,13 @@ test("checkout flow is accessible at each step", async ({ page }) => {
   await page.goto("/cart");
   let results = await new AxeBuilder({ page }).analyze();
   expect(results.violations).toEqual([]);
-  
+
   // Shipping form
   await page.getByRole("link", { name: /checkout/i }).click();
   await page.getByRole("heading", { name: /shipping/i }).waitFor();
   results = await new AxeBuilder({ page }).analyze();
   expect(results.violations).toEqual([]);
-  
+
   // Payment form
   await page.getByRole("button", { name: /continue/i }).click();
   await page.getByRole("heading", { name: /payment/i }).waitFor();
@@ -282,19 +277,17 @@ Always re-scan after content changes:
 ```javascript
 test("modal is accessible when opened", async ({ page }) => {
   await page.goto("/");
-  
+
   // Initial page scan
   let results = await new AxeBuilder({ page }).analyze();
   expect(results.violations).toEqual([]);
-  
+
   // Open modal
   await page.getByRole("button", { name: /settings/i }).click();
   await page.getByRole("dialog").waitFor();
-  
+
   // Scan modal
-  results = await new AxeBuilder({ page })
-    .include("[role='dialog']")
-    .analyze();
+  results = await new AxeBuilder({ page }).include("[role='dialog']").analyze();
   expect(results.violations).toEqual([]);
 });
 ```
@@ -305,15 +298,15 @@ test("modal is accessible when opened", async ({ page }) => {
 
 ```html
 <!-- BAD -->
-<input type="email" placeholder="Email">
+<input type="email" placeholder="Email" />
 
 <!-- GOOD -->
 <label for="email">Email address</label>
-<input id="email" type="email">
+<input id="email" type="email" />
 
 <!-- ALSO GOOD (visually hidden label) -->
 <label for="search" class="visually-hidden">Search products</label>
-<input id="search" type="search" placeholder="Search...">
+<input id="search" type="search" placeholder="Search..." />
 ```
 
 ### Color Contrast
@@ -353,7 +346,8 @@ test("modal is accessible when opened", async ({ page }) => {
 ```html
 <!-- BAD -->
 <input id="email" />
-<input id="email" />  <!-- Duplicate! -->
+<input id="email" />
+<!-- Duplicate! -->
 
 <!-- GOOD -->
 <input id="billing-email" />

package/skills/frontend-testing/references/aria-snapshots.md

@@ -31,14 +31,14 @@ await expect(page.getByRole("main")).toMatchAriaSnapshot(`
 
 ### Benefits Over Visual Snapshots
 
-| Aspect | ARIA Snapshot | Visual Screenshot |
-|--------|---------------|-------------------|
-| Styling changes | Unaffected | Fails |
-| Font rendering | Unaffected | Varies by OS |
-| Cross-browser | Consistent | Different per browser |
-| What it validates | Semantic structure | Pixel appearance |
-| Accessibility | Validates a11y tree | No a11y validation |
-| File size | Tiny (YAML text) | Large (PNG images) |
+| Aspect            | ARIA Snapshot       | Visual Screenshot     |
+| ----------------- | ------------------- | --------------------- |
+| Styling changes   | Unaffected          | Fails                 |
+| Font rendering    | Unaffected          | Varies by OS          |
+| Cross-browser     | Consistent          | Different per browser |
+| What it validates | Semantic structure  | Pixel appearance      |
+| Accessibility     | Validates a11y tree | No a11y validation    |
+| File size         | Tiny (YAML text)    | Large (PNG images)    |
 
 ### What It Catches
 
@@ -122,7 +122,7 @@ State and properties in square brackets:
 
 # Link URLs (newer feature)
 - link "Documentation":
-  - /url: "https://docs.example.com"
+    - /url: "https://docs.example.com"
 ```
 
 ### Nesting
@@ -131,18 +131,18 @@ Indentation shows hierarchy:
 
 ```yaml
 - navigation:
-  - list:
-    - listitem:
-      - link "Home"
-    - listitem:
-      - link "Products"
-    - listitem:
-      - link "About"
+    - list:
+        - listitem:
+            - link "Home"
+        - listitem:
+            - link "Products"
+        - listitem:
+            - link "About"
 - main:
-  - heading "Products" [level=1]
-  - list:
-    - listitem "Product A"
-    - listitem "Product B"
+    - heading "Products" [level=1]
+    - list:
+        - listitem "Product A"
+        - listitem "Product B"
 ```
 
 ## Basic Usage
@@ -154,7 +154,7 @@ import { test, expect } from "@playwright/test";
 
 test("login form structure", async ({ page }) => {
   await page.goto("/login");
-  
+
   await expect(page.getByRole("main")).toMatchAriaSnapshot(`
     - heading "Sign In" [level=1]
     - textbox "Email"
@@ -173,7 +173,7 @@ Store snapshots in separate YAML files:
 ```javascript
 test("dashboard structure", async ({ page }) => {
   await page.goto("/dashboard");
-  
+
   await expect(page.getByRole("main")).toMatchAriaSnapshot({
     name: "dashboard-main.aria.yml",
   });
@@ -280,6 +280,7 @@ npx playwright codegen example.com
 ```
 
 In the recorder:
+
 1. Click "Assert snapshot" action
 2. Select the element
 3. ARIA snapshot is generated
@@ -289,7 +290,7 @@ In the recorder:
 ```javascript
 test("generate snapshot for review", async ({ page }) => {
   await page.goto("/products");
-  
+
   // Get the YAML representation
   const snapshot = await page.getByRole("main").ariaSnapshot();
   console.log(snapshot);
@@ -320,16 +321,16 @@ Test different states of the same component:
 test.describe("Accordion", () => {
   test("collapsed state", async ({ page }) => {
     await page.goto("/accordion");
-    
+
     await expect(page.getByRole("region", { name: /details/i })).toMatchAriaSnapshot(`
       - button "Details" [expanded=false]
     `);
   });
-  
+
   test("expanded state", async ({ page }) => {
     await page.goto("/accordion");
     await page.getByRole("button", { name: /details/i }).click();
-    
+
     await expect(page.getByRole("region", { name: /details/i })).toMatchAriaSnapshot(`
       - button "Details" [expanded=true]
       - text "Additional information here"
@@ -344,7 +345,7 @@ test.describe("Accordion", () => {
 test("shows validation errors", async ({ page }) => {
   await page.goto("/signup");
   await page.getByRole("button", { name: /submit/i }).click();
-  
+
   await expect(page.getByRole("form")).toMatchAriaSnapshot(`
     - textbox "Email"
     - text "Email is required"
@@ -360,7 +361,7 @@ test("shows validation errors", async ({ page }) => {
 ```javascript
 test("cart shows item count", async ({ page }) => {
   await page.goto("/cart");
-  
+
   await expect(page.getByRole("banner")).toMatchAriaSnapshot(`
     - link "Home"
     - link /\\d+ items?/ 
@@ -373,15 +374,15 @@ test("cart shows item count", async ({ page }) => {
 ```javascript
 test("dialog opens and closes", async ({ page }) => {
   await page.goto("/");
-  
+
   // Before: no dialog
   await expect(page.getByRole("main")).toMatchAriaSnapshot(`
     - button "Open Settings"
   `);
-  
+
   // Open dialog
   await page.getByRole("button", { name: /settings/i }).click();
-  
+
   // After: dialog visible
   await expect(page.getByRole("dialog")).toMatchAriaSnapshot(`
     - dialog "Settings":
@@ -401,7 +402,7 @@ ARIA snapshots validate structure. Combine with other assertions for complete co
 ```javascript
 test("product page", async ({ page }) => {
   await page.goto("/products/123");
-  
+
   // Structure validation
   await expect(page.getByRole("main")).toMatchAriaSnapshot(`
     - img "Product photo"
@@ -409,11 +410,11 @@ test("product page", async ({ page }) => {
     - text "$49.99"
     - button "Add to cart"
   `);
-  
+
   // Functional validation
   await page.getByRole("button", { name: /add to cart/i }).click();
   await expect(page.getByRole("alert")).toContainText("Added to cart");
-  
+
   // Accessibility validation (axe-core)
   const results = await new AxeBuilder({ page }).analyze();
   expect(results.violations).toEqual([]);

package/skills/frontend-testing/references/locator-strategies.md

@@ -12,15 +12,15 @@ Query the accessibility tree. If this fails, the UI likely has accessibility iss
 
 ```javascript
 // Playwright
-page.getByRole("button", { name: /submit/i })
-page.getByRole("textbox", { name: /email/i })
-page.getByRole("heading", { level: 1 })
-page.getByRole("navigation")
-page.getByRole("listitem")
+page.getByRole("button", { name: /submit/i });
+page.getByRole("textbox", { name: /email/i });
+page.getByRole("heading", { level: 1 });
+page.getByRole("navigation");
+page.getByRole("listitem");
 
 // Testing Library
-screen.getByRole("button", { name: /submit/i })
-screen.getByRole("checkbox", { checked: true })
+screen.getByRole("button", { name: /submit/i });
+screen.getByRole("checkbox", { checked: true });
 ```
 
 **Why first**: Users and assistive technologies perceive the page through roles. Testing with roles validates both functionality and accessibility.
@@ -29,12 +29,13 @@ screen.getByRole("checkbox", { checked: true })
 
 ```javascript
 // Multiple buttons? Filter by name
-page.getByRole("button", { name: /save/i })      // Save button
-page.getByRole("button", { name: /cancel/i })    // Cancel button
-page.getByRole("button", { name: /delete/i })    // Delete button
+page.getByRole("button", { name: /save/i }); // Save button
+page.getByRole("button", { name: /cancel/i }); // Cancel button
+page.getByRole("button", { name: /delete/i }); // Delete button
 ```
 
 **Common roles**:
+
 - `button`, `link`, `textbox`, `checkbox`, `radio`
 - `combobox` (select), `listbox`, `option`
 - `heading`, `navigation`, `main`, `article`
@@ -48,12 +49,12 @@ How users find form fields. Validates label-input association.
 
 ```javascript
 // Playwright
-page.getByLabel("Email address")
-page.getByLabel(/password/i)
+page.getByLabel("Email address");
+page.getByLabel(/password/i);
 
 // Testing Library
-screen.getByLabelText("Email address")
-screen.getByLabelText(/confirm password/i)
+screen.getByLabelText("Email address");
+screen.getByLabelText(/confirm password/i);
 ```
 
 **Why second**: Form users navigate by labels. Tests using labels fail if labels are missing or improperly associated—catching real accessibility bugs.
@@ -63,8 +64,8 @@ screen.getByLabelText(/confirm password/i)
 Use only when labels aren't available. Placeholder is not a label substitute.
 
 ```javascript
-page.getByPlaceholder("Search products...")
-screen.getByPlaceholderText("Enter your query")
+page.getByPlaceholder("Search products...");
+screen.getByPlaceholderText("Enter your query");
 ```
 
 **Why third**: Better than test IDs, but UI should have proper labels.
@@ -75,12 +76,12 @@ For elements identified by their content.
 
 ```javascript
 // Playwright
-page.getByText("Welcome back, Sarah")
-page.getByText(/order confirmed/i)
+page.getByText("Welcome back, Sarah");
+page.getByText(/order confirmed/i);
 
 // Testing Library
-screen.getByText("No results found")
-screen.getByText(/loading/i)
+screen.getByText("No results found");
+screen.getByText(/loading/i);
 ```
 
 **Why fourth**: Useful for assertions on content, but doesn't verify semantic structure.
@@ -90,8 +91,8 @@ screen.getByText(/loading/i)
 For images with meaningful alt text.
 
 ```javascript
-page.getByAltText("Company logo")
-screen.getByAltText(/product photo/i)
+page.getByAltText("Company logo");
+screen.getByAltText(/product photo/i);
 ```
 
 ### 6. Title Attribute
@@ -99,8 +100,8 @@ screen.getByAltText(/product photo/i)
 Rarely used. Most elements shouldn't rely on title for identification.
 
 ```javascript
-page.getByTitle("Close dialog")
-screen.getByTitle(/help/i)
+page.getByTitle("Close dialog");
+screen.getByTitle(/help/i);
 ```
 
 ### 7. Test IDs (Last Resort)
@@ -109,18 +110,20 @@ Escape hatch when semantic queries fail. Provides no accessibility verification.
 
 ```javascript
 // Playwright
-page.getByTestId("pricing-calculator")
+page.getByTestId("pricing-calculator");
 
 // Testing Library
-screen.getByTestId("data-grid")
+screen.getByTestId("data-grid");
 ```
 
 **When appropriate**:
+
 - Complex dynamic components (data grids, charts)
 - Elements with no stable accessible name
 - Third-party components you can't modify
 
 **When to avoid**:
+
 - Any element that has text, label, or semantic role
 - As a default choice to "make tests easier"
 
@@ -163,12 +166,8 @@ When strict matching fails:
 ```javascript
 // Get all, then filter
 const buttons = await page.getByRole("button").all();
-const buttonTexts = await Promise.all(
-  buttons.map(button => button.textContent())
-);
-const deleteButtons = buttons.filter((button, index) =>
-  buttonTexts[index]?.includes("Delete")
-);
+const buttonTexts = await Promise.all(buttons.map((button) => button.textContent()));
+const deleteButtons = buttons.filter((button, index) => buttonTexts[index]?.includes("Delete"));
 
 // Or be more specific with the query
 page.getByRole("button", { name: "Delete", exact: true });
@@ -178,11 +177,11 @@ page.getByRole("button", { name: "Delete", exact: true });
 
 ### get vs query vs find
 
-| Variant | No match | Multiple matches | Async |
-|---------|----------|------------------|-------|
-| `getBy` | Throws | Throws | No |
-| `queryBy` | Returns null | Throws | No |
-| `findBy` | Throws | Throws | Yes (waits) |
+| Variant   | No match     | Multiple matches | Async       |
+| --------- | ------------ | ---------------- | ----------- |
+| `getBy`   | Throws       | Throws           | No          |
+| `queryBy` | Returns null | Throws           | No          |
+| `findBy`  | Throws       | Throws           | Yes (waits) |
 
 ```javascript
 // Element should exist now
@@ -262,9 +261,7 @@ page.getByRole("alert");
 
 ```javascript
 // Log all accessible elements
-await page.getByRole("button").evaluateAll(buttons => 
-  buttons.map(b => b.textContent)
-);
+await page.getByRole("button").evaluateAll((buttons) => buttons.map((b) => b.textContent));
 
 // Use Playwright Inspector
 // npx playwright test --debug