@schalkneethling/calavera-skill-frontend-testing 0.2.0-next.3 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@schalkneethling/calavera-skill-frontend-testing",
-  "version": "0.2.0-next.3",
+  "version": "0.2.1",
   "description": "Frontend testing artifact for Calavera.",
   "license": "MIT",
   "repository": {

package/payload/frontend-testing/SKILL.md

@@ -99,7 +99,7 @@ The distinction: acceptance tests should rarely change on refactor; implementati
 
 **ARIA snapshots** are particularly valuable for E2E tests. A single snapshot can replace multiple individual assertions while validating the accessibility tree structure.
 
-**DOM Environment for Unit Tests:** Prefer happy-dom over jsdom. It's faster, and its API limitations serve as a useful signal — if happy-dom doesn't support what you're testing, consider whether it belongs in an E2E test instead.
+**DOM Environment for Unit Tests:** Use happy-dom for fast tests that need a small DOM surface. Use jsdom when component tests require broader DOM APIs. Use Playwright when behavior depends on a real browser, layout, navigation, or browser accessibility APIs. A missing happy-dom API alone does not make a test E2E-worthy; choose the environment that matches the behavior under test and the project's declared dependencies.
 
 ### Step 5: Write Tests Before/Alongside Code
 
@@ -230,7 +230,7 @@ test.describe("Login Page", () => {
 Use locators that reflect how users and assistive technologies find elements. API names differ:
 
 - **Playwright**: prefer `getByRole`, then `getByLabel`, `getByPlaceholder`, `getByText`,
-  `getByAltText`, and finally `getByTestId`.
+  `getByAltText`, `getByTitle`, and finally `getByTestId`.
 - **Testing Library**: prefer `getByRole`, then `getByLabelText`, `getByPlaceholderText`,
   `getByText`, `getByAltText`, and finally `getByTestId`.
 

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

@@ -168,6 +168,7 @@ test("product page is accessible", async ({ page, makeAxeBuilder }) => {
 
 ```javascript
 const results = await new AxeBuilder({ page }).analyze();
+const includeRawHtml = process.env.AXE_LOG_RAW_HTML === "1" && !process.env.CI;
 
 // Structure of a violation
 results.violations.forEach((violation) => {
@@ -177,12 +178,15 @@ results.violations.forEach((violation) => {
   console.log(`Help: ${violation.helpUrl}`);
 
   violation.nodes.forEach((node) => {
-    console.log(`  Element: ${node.html}`);
+    console.log(`  Target: ${JSON.stringify(node.target)}`);
+    if (includeRawHtml) console.log(`  Element HTML: ${node.html}`);
     console.log(`  Fix: ${node.failureSummary}`);
   });
 });
 ```
 
+Raw HTML can contain rendered user data or form values. Keep it disabled in CI and require an explicit local opt-in when it is needed for diagnosis.
+
 ### Impact Levels
 
 | Level    | Description                  | Priority              |

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

@@ -479,8 +479,8 @@ await expect(locator).toMatchAriaSnapshot(`
 
 // GOOD: Testing structure with flexible matching
 await expect(locator).toMatchAriaSnapshot(`
-  - text /Order #\d+/
-  - text /Total: \$[\d.]+/
+  - text /Order #\\d+/
+  - text /Total: \\$[\\d.]+/
 `);
 ```
 
@@ -511,7 +511,7 @@ Always review snapshot updates:
 
 ```bash
 # See what changed
-git diff **/*.aria.yml
+git diff -- '**/*.aria.yml'
 
 # Verify changes are intentional before committing
 ```

package/payload/frontend-testing/references/visual-regression.md

@@ -80,8 +80,8 @@ Visual tests fail due to timing, rendering, or environment differences. Stabiliz
 test("page renders after loading", async ({ page }) => {
   await page.goto("/");
 
-  // Wait for network to be idle
-  await page.waitForLoadState("networkidle");
+  // The application sets this marker only after its data and UI are ready.
+  await expect(page.getByTestId("app-ready")).toBeVisible();
 
   // Wait for web fonts to load
   await page.evaluate(() => document.fonts.ready);
@@ -323,11 +323,12 @@ permissions:
 
 jobs:
   visual-tests:
+    runs-on: ubuntu-latest
     permissions:
       contents: read
     steps:
       - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v4.2.2 - re-resolve before use
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - re-resolve before use
         with:
           persist-credentials: false
 
@@ -347,32 +348,63 @@ jobs:
 For consistent baselines, generate in CI:
 
 ```yaml
+on:
+  workflow_dispatch:
+
 permissions:
   contents: read
 
 jobs:
+  visual-tests:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - re-resolve before use
+        with:
+          persist-credentials: false
+
+      - name: Run visual tests
+        run: npx playwright test --project=chromium
+
   update-baselines:
+    if: github.event_name == 'workflow_dispatch' && github.ref_name == github.event.repository.default_branch
+    runs-on: ubuntu-latest
     permissions:
       contents: write
     steps:
       - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v4.2.2 - re-resolve before use
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - re-resolve before use
         with:
+          ref: ${{ github.event.repository.default_branch }}
           persist-credentials: false
 
       - name: Update baselines
-        run: npx playwright test --update-snapshots
+        run: npx playwright test --project=chromium --update-snapshots
 
       - name: Commit baselines
         env:
+          DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
           GITHUB_TOKEN: ${{ github.token }}
+          PLAYWRIGHT_SNAPSHOT_DIR: tests/visual.spec.ts-snapshots
         run: |
+          test "$GITHUB_REF_NAME" = "$DEFAULT_BRANCH"
           git config user.name "CI Bot"
           git config user.email "github-actions[bot]@users.noreply.github.com"
-          git add "**/*.png"
+          git add -- "$PLAYWRIGHT_SNAPSHOT_DIR"
+          while IFS= read -r staged_file; do
+            case "$staged_file" in
+              "$PLAYWRIGHT_SNAPSHOT_DIR"/*) ;;
+              *)
+                echo "Unexpected staged file outside $PLAYWRIGHT_SNAPSHOT_DIR: $staged_file" >&2
+                exit 1
+                ;;
+            esac
+          done < <(git diff --cached --name-only)
           if ! git diff --cached --quiet; then
             git commit -m "Update visual baselines"
-            git -c http.https://github.com/.extraheader="AUTHORIZATION: bearer $GITHUB_TOKEN" push origin HEAD:refs/heads/${GITHUB_REF_NAME}
+            git -c http.https://github.com/.extraheader="AUTHORIZATION: bearer $GITHUB_TOKEN" push origin "HEAD:refs/heads/${DEFAULT_BRANCH}"
           fi
 ```
 
@@ -485,7 +517,8 @@ await expect(page).toHaveScreenshot();
 
 // GOOD: Wait for stable state
 await page.goto("/");
-await page.waitForLoadState("networkidle");
+// The application sets this marker only after its data and UI are ready.
+await expect(page.getByTestId("app-ready")).toBeVisible();
 await page.evaluate(() => document.fonts.ready);
 await expect(page).toHaveScreenshot();
 ```