test-a11y

name	test-a11y
description	[Tier 2 — Non-Functional: Usability · ISO 25010] Accessibility test workflow — WCAG 2.1 AA compliance via axe-core + Playwright. Creates tests if missing, augments if exists. Run after Tier 1 functional tests pass.

Helix — Accessibility Test (a11y)

📚 Knowledge References (loaded automatically):
a11y-patterns.md — WCAG rules, axe violation types, common fixes

ตรวจ WCAG 2.1 violations อัตโนมัติ — จับปัญหา contrast, labels, keyboard nav ก่อน user รายงาน

Step 1: Repo Structure Check

# หา a11y test folder
find . -type d \( -name "a11y" -o -name "accessibility" \) \
  | grep -v node_modules | grep -v .git

# ตรวจว่า Playwright + axe ติดตั้งแล้วไหม
cat package.json 2>/dev/null | grep -E "playwright|axe-playwright|@axe-core"
npx playwright --version 2>/dev/null || echo "playwright not installed"

กรณี A: ยังไม่มี a11y test

ต้องการ Playwright + axe-core/playwright:

# ถ้ายังไม่มี Playwright — แจ้ง user ก่อน (browser download ~250MB)
npm init playwright@latest

# เพิ่ม axe integration (ฟรี)
npm install -D @axe-core/playwright

สร้าง structure:

tests/a11y/
├── pages/           ← list of pages/routes to scan
└── specs/
    └── accessibility.spec.ts

กรณี B: มี Playwright แล้ว

เพิ่ม axe เข้าไปใน setup ที่มีอยู่:

npm install -D @axe-core/playwright

แล้วสร้าง tests/a11y/ หรือเพิ่มเข้าใน tests/e2e/ เดิม

Step 2: Test Case Planning

สแกนทุก page/route สำคัญ:

| Page / Route | Auth required? | WCAG level | Priority |
|-------------|---------------|------------|---------|
| /           | No  | AA | High |
| /login      | No  | AA | High |
| /dashboard  | Yes | AA | High |
| /settings   | Yes | AA | Medium |

Step 3: Write Tests

// tests/a11y/specs/accessibility.spec.ts
import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';

const PAGES = [
  { name: 'Home',      path: '/',          auth: false },
  { name: 'Login',     path: '/login',     auth: false },
  { name: 'Dashboard', path: '/dashboard', auth: true  },
  { name: 'Settings',  path: '/settings',  auth: true  },
];

for (const page of PAGES) {
  test(`${page.name} has no WCAG violations`, async ({ page: playwright }) => {
    if (page.auth) {
      // use stored auth state (same as E2E)
      await playwright.context().addCookies(/* auth cookies */);
    }
    await playwright.goto(page.);
     playwright.();

     results =   ({ : playwright })
      .([, , ])
      .();

    (results.).([]);
  });
}

การ handle known violations ที่ยังแก้ไม่ได้:

const results = await new AxeBuilder({ page })
  .withTags(['wcag2a', 'wcag2aa'])
  .exclude('#third-party-widget')  // ระบุ element ที่ข้าม
  .analyze();

Step 4: Run & Fix

npx playwright test tests/a11y/ --reporter=html

เมื่อมี violations:

1. อ่าน violation description — axe บอก rule ID + element + วิธีแก้
2. ดู results.violations[0].helpUrl — link ไปยัง WCAG documentation
3. แก้ใน source code
4. Re-run เฉพาะหน้าที่ fail ก่อน
5. Re-run ทั้งหมด

รายงานทุก 10 นาที:

| Page | Violations | Severity | Fixed |
|------|-----------|---------|-------|

Severity Levels

Impact	ความหมาย	Action
critical	ทำให้ user บางกลุ่มใช้ไม่ได้เลย	แก้ก่อน merge
serious	ขัดขวาง user อย่างมีนัยสำคัญ	แก้ใน sprint นี้
moderate	ทำให้ยากขึ้น แต่ยังใช้ได้	แก้ใน sprint ถัดไป
minor	best practice	ทำได้ตามโอกาส

Done

แจ้ง user ผลสรุป violations ตาม page + severity
ถามว่าต้องการต่อ /helix:test-visual ไหม

HTML Report

# รัน พร้อม HTML report
npx playwright test --reporter=html

# เปิด report
npx playwright show-report

---

Self-Evaluation Loop

ก่อนส่ง output ให้ user ทำ self-check ทุกครั้ง:

1. Output ครบถ้วนตาม scope ที่รับมาไหม?
2. มีจุดไหนที่ยังไม่แน่ใจ ควรถามก่อนไหม?
3. Format ถูกต้องตามที่กำหนดในสกิลไหม?
4. มีอะไรที่อาจทำให้งานพัง / เกิด side effect ที่ไม่ตั้งใจไหม?

ตอบ "ไม่ใช่" ข้อไหน → แก้ก่อนส่ง เสมอ