@dsalazardev/ai-hub-cli 0.0.0-stage → 0.2.0

package/skills/shared/dynamodb/scripts/verify.sh

@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# verify.sh — dynamodb skill gate. Checks a key-design / access-pattern artifact.
+#
+# Usage:   scripts/verify.sh [path-to-key-design.{md,json}]
+#   With no argument it auto-discovers candidate files under the current directory
+#   (*key-design*, *access-pattern*, *.md/*.json containing a DynamoDB pattern table).
+#
+# What it enforces (the skill's core discipline — every access pattern is served by a
+# key or index, never a table scan):
+#   - every pattern row names a key target (pk/sk or a gsi) AND a query_type   -> [fail] if missing
+#   - any pattern whose query_type is Scan                                     -> [fail]
+#   - any pattern relying on FilterExpression                                  -> [warn]
+#   - declared index counts within quota: <=20 GSIs, <=5 LSIs                  -> [fail] if exceeded
+#
+# Read-only: never writes, never connects to AWS. Exit 0 on an empty or clean target
+# (no artifact found is a [skip], not a failure). Non-zero ONLY on a real violation.
+# Runs on stock macOS bash 3.2 (no mapfile/associative arrays).
+
+YELLOW=$'\033[33m'; GREEN=$'\033[32m'; RED=$'\033[31m'; NC=$'\033[0m'
+EXIT=0
+skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$NC" "$*"; }
+warn() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; }
+ok()   { printf '%s[ok]%s %s\n'   "$GREEN"  "$NC" "$*"; }
+err()  { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; EXIT=1; }
+
+# --- locate the artifact(s) -------------------------------------------------
+FILES=()
+if [ "$#" -ge 1 ]; then
+  if [ -f "$1" ]; then
+    FILES+=("$1")
+  else
+    err "no such file: $1"
+    exit 1
+  fi
+else
+  ROOT="$(pwd)"
+  while IFS= read -r -d '' f; do
+    # keep files that look like a key-design artifact
+    if grep -liE 'key.?design|access.?pattern|query_type|GSI[0-9]?PK|begins_with' "$f" >/dev/null 2>&1; then
+      FILES+=("$f")
+    fi
+  done < <(
+    find "$ROOT" \
+      \( -path '*/node_modules/*' -o -path '*/.git/*' -o -path '*/vendor/*' -o -path '*/.venv/*' \) -prune -o \
+      -type f \( -name '*.md' -o -name '*.json' \) -print0 2>/dev/null
+  )
+fi
+
+if [ "${#FILES[@]}" -eq 0 ]; then
+  skip "no key-design / access-pattern artifact found — nothing to verify"
+  exit 0
+fi
+
+PATTERNS=0 SCANS=0 FILTERS=0
+
+for f in "${FILES[@]}"; do
+  [ -s "$f" ] || { skip "empty file: $f"; continue; }
+
+  # Pattern rows only — not prose. A pattern row is either a Markdown TABLE row (starts with `|`)
+  # or a JSON "query_type": "..." field. This deliberately ignores narrative sentences that merely
+  # mention Scan/Query, so pointing the tool at documentation does not raise false failures.
+  ROW_RE='(^[[:space:]]*\|.*\b(GetItem|Query|Scan|BatchGetItem|TransactGetItems)\b)|("query_type"[[:space:]]*:[[:space:]]*"(GetItem|Query|Scan|BatchGetItem|TransactGetItems)")'
+  while IFS= read -r line; do
+    PATTERNS=$((PATTERNS + 1))
+    # A row is a Scan only when the query_type cell/field is Scan — not when "Scan" appears elsewhere
+    # in the row (e.g. a "Query / Scan response" doc note). Check the query_type position.
+    if printf '%s' "$line" | grep -qiE '("query_type"[[:space:]]*:[[:space:]]*"Scan")|(\|[[:space:]]*Scan[[:space:]]*\|)|(\|[[:space:]]*Scan[[:space:]]*$)'; then
+      SCANS=$((SCANS + 1))
+      err "pattern resolved by Scan in $f: $(printf '%s' "$line" | sed 's/^[[:space:]]*//' | cut -c1-80)"
+    fi
+  done < <(grep -iE "$ROW_RE" "$f" 2>/dev/null || true)
+
+  # FilterExpression usage anywhere is a smell (warn, not fail).
+  fc=$(grep -ciE 'FilterExpression' "$f" 2>/dev/null || true)
+  if [ "${fc:-0}" -gt 0 ]; then
+    FILTERS=$((FILTERS + fc))
+  fi
+
+done
+
+# Distinct index identifiers, not raw mentions, is what the quota bounds. Count distinctly,
+# taking the max across files (a single table's design is normally one file).
+GSI_COUNT=0; LSI_COUNT=0
+for f in "${FILES[@]}"; do
+  [ -s "$f" ] || continue
+  g=$( (grep -oiE 'GSI[0-9]+' "$f" 2>/dev/null || true) | tr 'A-Z' 'a-z' | sort -u | grep -c . || true)
+  l=$( (grep -oiE 'LSI[0-9]+' "$f" 2>/dev/null || true) | tr 'A-Z' 'a-z' | sort -u | grep -c . || true)
+  if [ "${g:-0}" -gt "$GSI_COUNT" ]; then GSI_COUNT="${g:-0}"; fi
+  if [ "${l:-0}" -gt "$LSI_COUNT" ]; then LSI_COUNT="${l:-0}"; fi
+done
+
+if [ "$PATTERNS" -eq 0 ]; then
+  skip "artifact found but no access-pattern rows detected (no GetItem/Query/Scan) — nothing to verify"
+  exit 0
+fi
+
+if [ "$FILTERS" -gt 0 ]; then warn "FilterExpression used $FILTERS time(s) — confirm each filters <=10% of a key-bounded result, not a Scan"; fi
+if [ "$GSI_COUNT" -gt 20 ]; then err "declared GSIs ($GSI_COUNT) exceed the 20-per-table quota"; fi
+if [ "$LSI_COUNT" -gt 5 ];  then err "declared LSIs ($LSI_COUNT) exceed the 5-per-table quota"; fi
+
+if [ "$SCANS" -eq 0 ]; then ok "no access pattern resolved by Scan"; fi
+
+printf 'summary: %d pattern row(s), %d scan(s), %d filter mention(s), GSIs declared=%d, LSIs declared=%d\n' \
+  "$PATTERNS" "$SCANS" "$FILTERS" "$GSI_COUNT" "$LSI_COUNT"
+
+exit "$EXIT"

package/skills/shared/e2e-testing/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: e2e-testing
+description: "Use when writing or stabilizing Playwright tests that drive a real browser through multi-step journeys — durable locators, web-first assertions, storageState auth, trace/retries, and flakes that only bite in CI. NOT in-process component tests (that is testing-web), NOT WCAG auditing (that is accessibility), NOT the pre-merge gate (that is verify)."
+tags: [playwright, e2e, browser-testing, flakiness, ci]
+recommends: [testing-web, accessibility, performance, github-actions, debug]
+origin: ai-hub
+---
+
+# e2e-testing — drive a real browser, keep it deterministic
+
+You write **Playwright** tests that walk a real browser through real user journeys — log in, fill a
+form, check out, navigate across pages — and you keep those tests deterministic enough to gate a
+merge. The whole game is one tension: e2e tests catch integration bugs nothing else can, and they
+are the slowest, flakiest layer you own. Every rule below exists to buy back determinism.
+
+Pin `@playwright/test` and provision browsers with `npx playwright install --with-deps`. Current
+line is **Playwright v1.60.x** (v1.60.0 shipped 2026-05-11). The `_react` / `_vue` selector engines
+and the `:light` Shadow-DOM suffix were **removed in v1.58.0** — at any version you should be pinning
+they are long gone, so do not reach for them.
+
+## Is this even an e2e test?
+
+E2e is the most expensive layer. Spend it only on journeys that cross pages or services. Route the rest out.
+
+| The goal is… | Layer | Why |
+|---|---|---|
+| A multi-step journey across pages/auth/services in a real browser | **e2e (here)** | Only a real browser proves the pieces integrate. |
+| One component or pure function, rendered in-process (Vitest/Jest, Testing Library) | `../testing-web/SKILL.md` | A browser round-trip to test render logic is slow and flaky for no gain. |
+| "Is this page accessible?" — WCAG/ARIA as the deliverable | `../accessibility/SKILL.md` | E2e may *call* axe inside a test, but auditing a11y is its own skill. |
+| "Is this page fast?" — LCP/CWV budgets | `../performance/SKILL.md` | Perf budgets are a different signal than journey correctness. |
+| The runner matrix, caching, the pipeline itself | `../github-actions/SKILL.md` | E2e contributes a *job*; owning the pipeline is theirs. |
+| "Is the change done?" — run the gate, collect evidence, then merge | `../verify/SKILL.md` | Running an existing suite as a pre-merge gate is not authoring or stabilizing one. |
+
+Rule: if you can prove it without launching a browser, you should. Push logic down to `testing-web`.
+
+## Locators: the priority ladder
+
+Pick the highest rung that uniquely identifies the element. Higher rungs track what the user
+perceives, so they survive markup churn.
+
+1. `getByRole('button', { name: 'Buy' })` — role + accessible name. Default choice; doubles as an a11y signal.
+2. `getByLabel('Email')` / `getByPlaceholder(...)` — form fields.
+3. `getByText('Order confirmed')` — visible copy that uniquely identifies content.
+4. `getByTestId('cart-total')` — when nothing user-facing is stable; requires a deliberate `data-testid`.
+5. CSS as a last resort, scoped and shallow.
+
+Never XPath, never `nth-child` chains, never the removed `_react`/`_vue`/`:light` engines.
+
+```ts
+// Bad — couples the test to DOM structure; one wrapper div breaks it.
+await page.locator('div.card > button:nth-child(2)').click();
+
+// Good — finds the button the way the user reads it.
+await page.getByRole('button', { name: 'Buy' }).click();
+```
+
+**Strict mode.** A locator that matches two nodes *throws* — that is the framework catching an
+ambiguous selector for you. Tighten the locator (`getByRole(...).and(...)`, scope with
+`page.getByRole('listitem').filter({ hasText: 'Pro' })`). Reaching for `.first()` to silence the
+error hides the ambiguity and is the next flake.
+
+## Assertions: web-first only
+
+```ts
+// Bad — reads the DOM once, before the async update lands; races the render.
+expect(await page.locator('#status').textContent()).toBe('Submitted');
+
+// Good — re-polls the element until it says 'Submitted' or the timeout fires.
+await expect(page.getByTestId('status')).toHaveText('Submitted');
+```
+
+`expect(locator)` assertions (`toBeVisible`, `toHaveText`, `toHaveURL`, `toHaveCount`) retry until
+the condition holds. A read-once value (`await locator.textContent()` then compare) captures a single
+frame and loses every race against a re-render. If you find `expect(await` in a test, it is a bug.
+
+## Auto-wait and the no-sleep rule
+
+Locator actions (`click`, `fill`, `check`) already auto-wait: they block until the element is
+visible, stable, enabled, and receiving events. So `waitForTimeout(2000)` is never the right wait —
+it is either too short (flake) or too long (slow), and it waits for wall-clock time instead of the
+thing you actually care about.
+
+| Instead of guessing with a sleep | Wait on the real signal |
+|---|---|
+| "give the button time to appear" | `await expect(locator).toBeVisible()` |
+| "wait for navigation" | `await page.waitForURL('**/checkout')` |
+| "wait for the XHR/fetch" | `const r = page.waitForResponse('**/api/order'); …action…; await r;` |
+| "wait for the list to fill" | `await expect(page.getByRole('row')).toHaveCount(5)` |
+
+The ordering trap: subscribe to a response (or register a `page.route` mock) **before** the action
+that triggers it, or you miss the event.
+
+```ts
+// Bad — handler registered after goto; the initial request already fired unmocked.
+await page.goto('/orders');
+await page.route('**/api/orders', route => route.fulfill({ json: [] }));
+
+// Good — mock in place before navigation, so the first request is intercepted.
+await page.route('**/api/orders', route => route.fulfill({ json: [] }));
+await page.goto('/orders');
+```
+
+## Fixtures and page objects
+
+Fixtures give every test a fresh, isolated setup and kill copy-pasted boilerplate. Extend the base
+`test` with your own; the code before `use(value)` is setup, after it is teardown.
+
+```ts
+import { test as base } from '@playwright/test';
+import { CheckoutPage } from './pages/checkout';
+
+type Fixtures = { checkout: CheckoutPage };
+
+export const test = base.extend<Fixtures>({
+  checkout: async ({ page }, use) => {
+    const checkout = new CheckoutPage(page); // setup: depends on the built-in `page`
+    await use(checkout);                      // hand it to the test
+    // teardown after the test goes here, if any
+  },
+});
+```
+
+Option fixtures (`['default', { option: true }]`) let a project or `test.use()` flip behavior
+without new fixtures. Keep page objects thin — locators and intent-named actions
+(`checkout.placeOrder()`), no assertions buried inside them. Full page-object recipe lives in
+[references/config-and-ci.md](references/config-and-ci.md).
+
+## Auth and storageState
+
+Logging in through the UI on every test is slow and a flake surface. Log in **once** in a `setup`
+project, save the authenticated session to JSON, and load it via `storageState` in the projects that
+depend on it.
+
+- A `setup` project runs the login spec and writes `playwright/.auth/<role>.json`.
+- Real test projects declare `dependencies: ['setup']` and `use: { storageState: '…/<role>.json' }`.
+- **One file per role** (admin, member, anon) — never share one mutated session across roles.
+- **Regenerate every CI run; gitignore the `.auth/` dir.** Committed session state leaks secrets and
+  goes stale.
+
+The full multi-role setup-project wiring is in [references/config-and-ci.md](references/config-and-ci.md).
+
+## playwright.config.ts (condensed)
+
+```ts
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './e2e',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,        // a stray test.only fails CI instead of skipping the suite
+  retries: process.env.CI ? 2 : 0,     // retry only in CI; locally a flake should hurt
+  workers: process.env.CI ? 1 : undefined,
+  reporter: process.env.CI ? [['github'], ['html']] : 'list',
+  use: {
+    baseURL: process.env.BASE_URL ?? 'http://localhost:3000',
+    trace: 'on-first-retry',           // full trace captured the first time a test retries
+  },
+  projects: [
+    { name: 'setup', testMatch: /.*\.setup\.ts/ },
+    { name: 'chromium', use: { ...devices['Desktop Chrome'] }, dependencies: ['setup'] },
+    { name: 'webkit',   use: { ...devices['Desktop Safari'] }, dependencies: ['setup'] },
+  ],
+  webServer: {
+    command: 'npm run start',
+    url: 'http://localhost:3000',
+    reuseExistingServer: !process.env.CI,
+  },
+});
+```
+
+Open a captured trace with `npx playwright show-trace`. The full annotated config (per-role
+storageState, firefox, blob reporter for sharding) is in
+[references/config-and-ci.md](references/config-and-ci.md).
+
+## CI (GitHub Actions)
+
+The shape: install browsers with OS deps, run, shard when one box can't finish inside the ~5–10 min
+budget, upload the trace and HTML report as artifacts.
+
+```yaml
+- run: npx playwright install --with-deps
+- run: npx playwright test --shard=${{ matrix.shard }}/4
+- uses: actions/upload-artifact@v4
+  if: ${{ !cancelled() }}
+  with: { name: report-${{ matrix.shard }}, path: playwright-report/, retention-days: 7 }
+```
+
+Scale: bump `workers` to use a single machine; add `--shard=i/N` across machines only once a single
+box overruns the budget. Sharded runs emit blob reports you merge with `npx playwright merge-reports`.
+Full workflow (matrix, blob report, merge job) is in [references/config-and-ci.md](references/config-and-ci.md).
+
+## Flakiness playbook
+
+A 3% flake rate on a 40-minute pipeline burns roughly an engineer-day a week on reruns, so treat
+flakes as bugs with named causes. **Open the trace first** (`show-trace`) — it replays the exact
+failing run with DOM, network, and console; guessing from a one-line CI log is how flakes survive.
+
+| Symptom in CI | Cause | Fix |
+|---|---|---|
+| Assertion races a re-render | Read-once value, not web-first | `await expect(locator).toHaveText(...)` |
+| Mock/intercept never fires | `page.route` registered after `goto` | Register the route before the navigation |
+| Test hangs / times out in an SPA | `networkidle` never settles (polling, websockets) | Wait on a locator/URL, not `networkidle` |
+| `waitForResponse` misses the call | Subscribed after the action fired | `const r = page.waitForResponse(...)` before the action |
+| "strict mode: resolved to 2 elements" | Ambiguous locator | Tighten with role+name/`filter`, not `.first()` |
+| Passes alone, fails in the suite | `storageState` leak / shared mutable state | Per-role state file; fresh context per test |
+| Wrong fixture/state in one file | `test.use()` scope confusion | Scope `test.use` to the right describe block |
+| Green headed, red headless (or vice-versa) | Viewport/animation/timing drift | Pin viewport; reduce motion; debug in the failing mode |
+
+Per-pattern reproduction and corrected code is in [references/flakiness-playbook.md](references/flakiness-playbook.md).
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+|---|---|---|
+| `await page.waitForTimeout(2000)` | Couples the test to wall-clock; too short flakes, too long drags | Wait on locator/URL/response |
+| XPath or `:nth-child` locators | Breaks on any markup refactor the user never sees | `getByRole`/`getByTestId` ladder |
+| `page.$(...)` / `page.$$(...)` element handles | No auto-wait, no retry — pre-locator API | `page.locator(...)` / `getBy*` |
+| `expect(await locator.textContent()).toBe(...)` | Reads one frame; races the async update | `await expect(locator).toHaveText(...)` |
+| Committing `storageState` JSON | Leaks session secrets, goes stale, false green | Gitignore `.auth/`; regenerate per run |
+| `trace: 'on'` always | Heavy artifacts, slows every run | `trace: 'on-first-retry'` |
+| Tests that depend on run order | One reorder cascades failures | Each test self-contained; fresh context |
+| Driving pure logic through the browser | Slow + flaky for a unit-level check | Push it to `../testing-web/SKILL.md` |
+| `.first()` to silence strict mode | Hides ambiguity → the next flake | Make the locator unique |
+
+When a flake resists the table, hand the trace to `../debug/SKILL.md` — reproduce as a rate (k/N
+runs), isolate one variable, fix the cause, not the symptom.
+
+## Verify
+
+Run `scripts/verify.sh [dir]` over the test/config files you emit. It is a read-only static lint
+(no browser, no network) that fails on the skill's own banlist: `waitForTimeout(`, XPath/`//`
+locators, `page.$(`/`page.$$(` handles, `expect(await` read-once assertions, and any
+`playwright.config.*` missing both `trace` and `retries`. Clean or empty target exits 0.

package/skills/shared/e2e-testing/evals/README.md

@@ -0,0 +1,10 @@
+# e2e-testing evals
+
+`cases.yaml` holds three groups scored by an LLM judge, not a runtime test of Playwright itself.
+`should_trigger` lists prompts where the skill must load (each with a `why`, including the non-obvious
+flakiness and strict-mode cases and a Catalan phrasing); `should_not_trigger` lists near-misses that
+must route to a real sibling (`route_to`) instead of loading here; `capability` is one end-to-end
+scenario with a `must_include` rubric that the judge grades a skill-guided answer against. Run them
+through the repo's eval harness, which loads the skill, replays each prompt, and checks routing plus
+rubric coverage. Nothing here launches a browser or runs Playwright — that lives in the produced test
+suite, which `scripts/verify.sh` statically lints.

package/skills/shared/e2e-testing/evals/cases.yaml

@@ -0,0 +1,64 @@
+skill: e2e-testing
+
+# Prompts that MUST load e2e-testing. This skill owns driving a real browser
+# through user journeys with Playwright and keeping those tests deterministic:
+# durable locators, web-first assertions, storageState auth, retries/trace, and
+# the flakiness playbook. Flakiness is the non-obvious core — half the reason
+# e2e exists as a discipline is that the tests rot into reruns otherwise.
+should_trigger:
+  - prompt: "Write a Playwright test for the login then checkout flow."
+    why: "A multi-step journey across auth and pages in a real browser is the canonical e2e case; the skill drives the locator/assertion/auth choices."
+
+  - prompt: "My e2e tests pass locally but flake on CI — how do I make them deterministic?"
+    why: "Non-obvious core: flakiness is the central failure mode of e2e, and the skill carries the named-pattern playbook (route-after-goto, networkidle, read-once, storageState leak)."
+
+  - prompt: "How do I set up storageState so I don't log in through the UI on every test?"
+    why: "Auth via a setup project that writes session JSON and dependent projects loading it is exactly the storageState recipe this skill owns."
+
+  - prompt: "Should I use getByRole or a CSS selector for this submit button?"
+    why: "Locator strategy — the role>label/text>testId>CSS ladder and the v1.58.0 removal of _react/_vue — is core e2e judgment."
+
+  - prompt: "Els tests d'extrem a extrem fallen aleatòriament al pipeline, com els estabilitzo?"
+    why: "Catalan for 'the end-to-end tests fail randomly in the pipeline' — flaky CI e2e, the skill's central concern."
+
+  - prompt: "How do I shard my Playwright suite across CI machines and merge the reports?"
+    why: "Scale-out via --shard with blob reports merged by merge-reports is the CI section of this skill."
+
+  - prompt: "Strict mode says my locator resolved to 2 elements — how do I fix it the right way?"
+    why: "Non-obvious: the fix is tightening the locator, not .first(); recognizing strict mode as a caught ambiguity is e2e locator discipline."
+
+# NEAR-MISS prompts that must NOT load e2e-testing. Each routes to a sibling that
+# exists in the catalog. The trap: not every test or browser-shaped task is a
+# real-browser user journey kept deterministic.
+should_not_trigger:
+  - prompt: "Write a Vitest component test for my Button component."
+    route_to: testing-web
+    why: "An in-process component/unit test rendered without a real browser round-trip belongs to testing-web; driving a browser here would be slow and pointless."
+
+  - prompt: "Add pytest tests for my FastAPI orders service."
+    route_to: testing-py
+    why: "Python backend unit/integration testing is testing-py; there is no browser journey to drive."
+
+  - prompt: "Audit this page for WCAG accessibility violations and fix the ARIA issues."
+    route_to: accessibility
+    why: "When the deliverable is the a11y audit itself, it is accessibility; e2e may call axe inside a test but auditing is not its job."
+
+  - prompt: "Set up the GitHub Actions runner matrix and dependency caching for the whole repo."
+    route_to: github-actions
+    why: "Owning the pipeline — runners, caching, matrices — is github-actions; e2e only contributes a test job."
+
+# One end-to-end scenario graded WITH vs WITHOUT the skill. A skill-guided answer
+# builds for determinism from the start (user-facing locators, web-first
+# assertions, storageState setup project, trace-on-retry, no sleeps); an
+# ungrounded answer reaches for CSS/XPath, read-once asserts, waitForTimeout,
+# and reruns to mask the flake.
+capability:
+  - scenario: "An authenticated checkout e2e suite flakes intermittently in CI but passes locally. Stabilize it: write a representative test, the playwright.config.ts, the auth setup, and the CI job."
+    must_include:
+      - "User-facing locators (getByRole/getByLabel/getByTestId) for the journey; no XPath, no :nth-child chains, no removed _react/_vue/:light engines."
+      - "Web-first assertions (await expect(locator).toHaveText/toBeVisible/toHaveURL) — never expect(await locator.textContent())."
+      - "Auth via a setup project writing session JSON, dependent projects loading it with storageState and dependencies:['setup'], one file per role, .auth/ gitignored and regenerated per CI run."
+      - "playwright.config.ts with retries: process.env.CI ? 2 : 0 and use:{ trace: 'on-first-retry' }, baseURL, and a projects array including the setup project."
+      - "No waitForTimeout anywhere; waits on locator assertions, waitForURL, or waitForResponse subscribed BEFORE the action, and route mocks registered before goto."
+      - "CI job runs npx playwright install --with-deps, runs the suite (optionally --shard with blob report + merge-reports), and uploads trace + HTML report as artifacts."
+      - "Treats the flake as a cause to diagnose (open the trace first, measure as a rate) rather than papering over it with retries or sleeps."

package/skills/shared/e2e-testing/references/config-and-ci.md

@@ -0,0 +1,156 @@
+# config-and-ci — full Playwright config, multi-role auth, and the CI workflow
+
+Everything the SKILL condenses. Current line is Playwright v1.60.x; install browsers with
+`npx playwright install --with-deps`.
+
+## Full annotated playwright.config.ts
+
+```ts
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './e2e',
+  outputDir: './test-results',
+  fullyParallel: true,                 // run files in parallel, tests within a file in parallel
+  forbidOnly: !!process.env.CI,        // a stray test.only fails CI rather than silently skipping the rest
+  retries: process.env.CI ? 2 : 0,     // CI absorbs infra blips; locally a flake should fail loud
+  workers: process.env.CI ? 1 : undefined, // 1 worker/shard in CI when sharding; uncapped locally
+  timeout: 30_000,                     // per-test cap
+  expect: { timeout: 5_000 },          // per web-first-assertion poll cap
+
+  reporter: process.env.CI
+    ? [['blob'], ['github']]           // blob = mergeable across shards; github = inline annotations
+    : [['html', { open: 'never' }], ['list']],
+
+  use: {
+    baseURL: process.env.BASE_URL ?? 'http://localhost:3000',
+    trace: 'on-first-retry',           // full DOM/network/console trace the first time a test retries
+    screenshot: 'only-on-failure',
+    video: 'retain-on-failure',
+  },
+
+  projects: [
+    // 1. Auth setup projects — one per role. They run first and write session JSON.
+    { name: 'setup-admin',  testMatch: /admin\.setup\.ts/ },
+    { name: 'setup-member', testMatch: /member\.setup\.ts/ },
+
+    // 2. Real test projects load the right storageState and depend on their setup.
+    {
+      name: 'chromium-admin',
+      use: { ...devices['Desktop Chrome'], storageState: 'playwright/.auth/admin.json' },
+      dependencies: ['setup-admin'],
+      testMatch: /.*admin.*\.spec\.ts/,
+    },
+    {
+      name: 'chromium-member',
+      use: { ...devices['Desktop Chrome'], storageState: 'playwright/.auth/member.json' },
+      dependencies: ['setup-member'],
+      testMatch: /.*member.*\.spec\.ts/,
+    },
+    {
+      name: 'webkit-member',
+      use: { ...devices['Desktop Safari'], storageState: 'playwright/.auth/member.json' },
+      dependencies: ['setup-member'],
+      testMatch: /.*member.*\.spec\.ts/,
+    },
+  ],
+
+  webServer: {
+    command: 'npm run start',
+    url: 'http://localhost:3000',
+    reuseExistingServer: !process.env.CI, // reuse the dev server locally; always fresh in CI
+    timeout: 120_000,
+  },
+});
+```
+
+## Multi-role storageState setup project
+
+One spec per role. Each logs in once and saves the session; the dependent projects above load it.
+
+```ts
+// e2e/auth/member.setup.ts
+import { test as setup, expect } from '@playwright/test';
+
+const memberFile = 'playwright/.auth/member.json';
+
+setup('authenticate as member', async ({ page }) => {
+  await page.goto('/login');
+  await page.getByLabel('Email').fill(process.env.MEMBER_EMAIL!);
+  await page.getByLabel('Password').fill(process.env.MEMBER_PASSWORD!);
+  await page.getByRole('button', { name: 'Sign in' }).click();
+
+  // Wait on a real post-login signal before saving, or you save a half-authenticated state.
+  await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
+
+  await page.context().storageState({ path: memberFile });
+});
+```
+
+Duplicate for `admin.setup.ts` with admin credentials and `playwright/.auth/admin.json`.
+
+Always gitignore the auth dir — committed sessions leak secrets and go stale:
+
+```gitignore
+playwright/.auth/
+test-results/
+playwright-report/
+blob-report/
+```
+
+Faster path when you have a programmatic login: skip the UI entirely and seed `storageState` from an
+API token or a `request` call inside the setup project — same output JSON, no browser round-trip.
+
+## GitHub Actions workflow (shard + merge + artifacts)
+
+```yaml
+name: e2e
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: [1, 2, 3, 4]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 20, cache: npm }
+      - run: npm ci
+      - run: npx playwright install --with-deps      # browsers + OS libs
+      - run: npx playwright test --shard=${{ matrix.shard }}/4
+        env:
+          CI: 'true'
+          BASE_URL: http://localhost:3000
+          MEMBER_EMAIL: ${{ secrets.MEMBER_EMAIL }}
+          MEMBER_PASSWORD: ${{ secrets.MEMBER_PASSWORD }}
+      - uses: actions/upload-artifact@v4
+        if: ${{ !cancelled() }}                       # keep the trace even when the job fails
+        with:
+          name: blob-report-${{ matrix.shard }}
+          path: blob-report/
+          retention-days: 7
+
+  merge-report:
+    if: ${{ !cancelled() }}
+    needs: [test]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 20, cache: npm }
+      - run: npm ci
+      - uses: actions/download-artifact@v4
+        with: { path: all-blob-reports, pattern: blob-report-*, merge-multiple: true }
+      - run: npx playwright merge-reports --reporter=html ./all-blob-reports
+      - uses: actions/upload-artifact@v4
+        with: { name: html-report, path: playwright-report/, retention-days: 14 }
+```
+
+Sharding only earns its complexity once a single runner overruns the ~5–10 min budget. Below that,
+raise `workers` on one machine first. Each shard emits a `blob` report; the merge job stitches them
+into one HTML report so reviewers see the whole suite, not four fragments.
+
+Download `html-report`, run `npx playwright show-report`, and open any failed test's trace inline.