noir-test-flow

name: noir-test-flow description: Visual + behavioral testing protocol for NOIR — triple-mode checks (light/dark/VI/responsive), interactive element testing, data consistency verification, and bug fix workflow. Used by /noir-qa orchestrator.

NOIR Test Flow — Visual + Behavioral Testing Protocol

Purpose: Defines HOW to test each page/feature. Called by /noir-qa and /noir-qa-run or used standalone. Standalone usage: /noir-test-flow — applies the full protocol to a specific page or set of pages. As sub-protocol: Referenced by /noir-qa Phase 4 (Execution) and /noir-qa-run Execute phase.

CORE PRINCIPLE

"If a human QA engineer would catch it, you must catch it."

Dark mode, Vietnamese, and responsive are NOT separate phases — they are tested on EVERY visual state (page, tab, dialog, popup). This catches the bugs that single-mode testing misses.

TRIPLE-MODE VISUAL AUDIT (Page Level)

For each page's initial view, execute 4 modes:

Light Mode (Baseline)

1. browser_navigate → page URL (or SPA sidebar click — see Technical Notes)
2. browser_wait_for → network idle / specific element visible
3. browser_take_screenshot → temp/qa-{page}-light.png
4. READ screenshot and analyze:
   - Layout: alignment, spacing, overflow, content clipping
   - Components: broken images, missing icons, wrong empty states
   - Typography: font consistency, text truncation, ellipsis working
   - Colors: theme consistency, contrast, hover states visible
   - Loading: skeleton → data (no flash of empty)
   - Card shadows: shadow-sm + hover:shadow-lg per design standard

Dark Mode

5. browser_evaluate → document.documentElement.classList.add('dark')
6. browser_take_screenshot → temp/qa-{page}-dark.png
7. READ screenshot and verify:
   - Text readable (no white-on-white, no black-on-black)
   - Borders visible (not disappearing into background)
   - Status badges maintain contrast
   - Charts/graphs readable
   - No hardcoded colors overriding theme variables
   - Input fields: background distinguishable from page background
   - Dropdown menus / popovers: correct dark background (not white)

Vietnamese

8. browser_evaluate → localStorage.setItem('i18nextLng','vi'); location.reload()
9. browser_wait_for → content loaded
10. browser_take_screenshot → temp/qa-{page}-vi.png
11. READ screenshot and verify:
    - No raw i18n keys (e.g., "products.searchPlaceholder" as literal text)
    - No English text remaining (except allowed: CRM, API, SMTP, Blog)
    - No text overflow from longer Vietnamese strings (buttons, headers, labels)
    - Date format matches Vietnamese locale (DD/MM/YYYY)
    - Sidebar labels are pure Vietnamese (no "Blog Posts", must be "Bài viết")
    - Vietnamese + dark mode: switch to dark briefly → screenshot → verify no issues
    - Switch back to light mode after

Responsive

12. Restore to light mode + English before responsive checks
13. For each viewport [1440, 1024, 768]:
    - browser_resize → {width}px
    - browser_take_screenshot → temp/qa-{page}-{width}px.png
    - READ and verify:
      - 1440: full layout, sidebar visible, all columns shown
      - 1024: sidebar may collapse, table columns may hide, no overflow
      - 768: mobile/tablet layout, content stacks vertically, no horizontal scroll on body
    - Specific: tables horizontal scroll within container, buttons not cut off,
      cards stack vertically, PageHeader wraps correctly, search remains usable
14. browser_resize → restore 1440px

MINI TRIPLE CHECK (Element Level)

For EACH interactive element type on the page. Every distinct visual state gets this protocol:

1. Screenshot in light mode (baseline)
2. Switch to dark mode → screenshot → verify: text readable, borders visible, inputs distinguishable
3. Switch to Vietnamese → screenshot → verify: all text translated, no overflow, no raw i18n keys
4. Resize to 768px → screenshot → verify: layout adapts, content accessible, no overflow
5. Restore light mode + English + 1440px before proceeding

Required Visual States (100% Matrix)

Efficiency: Shared components (DataTablePagination, etc.) need full Mini Triple Check only on FIRST occurrence. Subsequent pages: quick dark mode spot-check. Page-specific dialogs/tabs: always full check.

INTERACTIVE ELEMENT TESTING

Tables (DataTable)

• Column headers render correctly, all have labels
• Sort: click each sortable column header, verify order + indicator
• Pagination: page 2, change page size, verify "Showing X of Y" updates
• Search: type query → verify filtering → clear → verify reset
• Column visibility: open dropdown, hide column, verify gone, show back
• Column reorder: if supported, drag column, verify new order
• Density toggle: switch compact/normal/comfortable if available
• Empty state: search nonsense → verify <EmptyState> component (not plain text) → Mini Triple Check on empty state
• Row selection: check/uncheck rows, verify bulk action toolbar appears
• Actions dropdown: click ⋮ → verify menu items → verify each action works
• Group by: if supported, group → verify group headers with correct count

Forms (Create/Edit Dialogs)

• Open Create dialog → screenshot → Mini Triple Check
• Field-by-field testing for EVERY field:
  • Focus → verify focus ring/border
  • Tab to next → verify tab order (top-to-bottom, left-to-right)
  • Required fields → verify red asterisk * on label
  • Type invalid → blur → verify error (NOT while typing)
  • Type valid → verify error clears
  • Dropdowns: open → select → verify selection
  • Date pickers: open → select → verify format. Dark mode: calendar popup screenshot
  • Rich text editors: type → verify toolbar works
  • File uploads: upload → verify preview
  • Color pickers: select → verify preview
• Submit empty → verify ALL required field errors at once
• Submit invalid → verify specific field errors (not generic toast)
• Submit valid → verify: toast + dialog closes + list updates + data matches
• Cancel → closes, no data changed
• Click outside → closes (Credenza behavior)
• ESC → closes
• Edit mode: open existing → verify fields pre-populated → Mini Triple Check

Filters

• Apply each filter individually → verify results update
• Apply combination → verify AND logic
• Verify active filter indicator/badge shows count
• Clear individual → verify results update
• Clear all → verify full reset
• Filter persists across pagination

Destructive Actions

• Click delete/archive → verify confirmation dialog appears (NEVER instant delete)
• Mini Triple Check on confirmation dialog
• Cancel → nothing changed
• Confirm → item removed/updated + toast + related data updated + activity timeline

Tabs

• For EACH tab:
  1. Click tab → verify content loads
  2. Verify URL updates with ?tab=xxx
  3. Mini Triple Check on tab content
  4. Direct-navigate to ?tab=xxx → verify correct tab active + content loaded
  5. Verify no flash/flicker on tab switch

Messages & Notifications

• Toasts: trigger success action → verify position, auto-dismiss, text → Mini Triple Check
• Error banners: trigger server error → verify shows, dismiss works, clears on retry → Mini Triple Check
• Validation messages: submit invalid → verify under field → Mini Triple Check
• Date picker popup: open → verify calendar → Mini Triple Check
• Select/Combobox: open → verify options → Mini Triple Check
• Tooltip: hover icon button → verify shows → Dark + VI check (no resize needed)

Navigation

• Breadcrumbs: correct path, each segment clickable
• Sidebar: current page highlighted
• Back navigation: browser back works correctly
• Deep link: navigate to URL directly → verify same state loads

DATA CONSISTENCY CHECKS

After EACH CRUD operation, verify:

Create

• Item appears in list with correct data
• List total count incremented
• Dashboard widgets updated (if applicable)
• Activity timeline shows "Created ..." entry
• Related entities reflect change (e.g., department employee count)
• Search returns the new item

Edit

• ALL changed fields persisted (re-open edit dialog to verify)
• List row updated with new values
• Detail page (if exists) shows updated data
• Activity timeline shows "Updated ..." entry
• Related views reflect change

Delete (Soft)

• Item removed from active list
• List total count decremented
• Related entities updated (counts, references)
• Activity timeline shows "Deleted ..." entry
• Dashboard widgets updated

CROSS-FEATURE FLOW TEMPLATES

Use these as templates when creating flow definitions in .qa/flows/.

Flow: Product → Order → Payment Lifecycle

Create Product → Add Variants → Set Inventory (StockIn, confirm)
→ Dashboard product count increased
→ Create Customer → Create Order with product variant
→ Confirm → inventory decreased → Process → Ship → Deliver → Complete
→ Payment in Payments list with correct amount
→ Revenue in Dashboard
→ Customer writes Review → Approve → review count on product detail

Flow: Customer Journey

Create Customer → Add to Group → group count updated
→ Create Order → Customer Detail → order in history tab
→ Cancel order → status updates in: Order detail, Customer history, Dashboard
→ Activity Timeline shows all actions with correct descriptions
→ Vietnamese → activity descriptions translated

Flow: Content Publishing

Create Blog Category → Create Blog Tags (2+)
→ Create Post with image → Assign category + tags → Draft
→ Media Library shows image
→ Edit → Publish → status badge changes
→ Delete tag → post's tag list updates (no crash)
→ Edit category name → post shows updated category

Flow: HR Workflow

Create Department (child) → tree shows it
→ Create Employee in department → Add Tags
→ Department detail: employee count = 1
→ Edit employee → changes persist
→ Export CSV → CSV contains employee
→ Import modified CSV → change applied
→ Move to different department → both counts update

Flow: CRM Pipeline

Create Company → Create Contact linked → company shows contact count
→ Create Lead → Kanban shows in first stage
→ Drag through stages → Win → dashboard metrics update
→ Activity on contact → timeline shows
→ Delete company → contacts still accessible (soft delete)

Flow: PM Workflow

Create Project → auto-code PRJ-xxx
→ Add columns → Create tasks in different columns
→ Drag task → status changes in detail
→ Subtask → complete → parent progress
→ Comment → timestamp correct
→ Attachment → download works
→ Archive → gone from Kanban, in Archived view

Flow: Data Integrity & Edge Cases

Delete Brand with products → products still display
Disable Module (CRM) → sidebar gone, URL → 404, dashboard widgets hidden, re-enable → returns
Test user with custom role → remove permission → verify sidebar/URL/actions restricted
Language switch EN→VI→EN → all labels correct, no raw keys, date formats change
Theme switch light→dark→light → no artifacts

Flow: Error Handling

Navigate to /portal/entity/00000000-...0 → 404 or graceful redirect
Stop backend → Submit form → error banner (not crash) → Restart backend
Delete entity via API while edit dialog open → Save → conflict handling
Rapid pagination clicks → final page correct (no stale data)
Rapid double-click Submit → only ONE entity created

TEST CASE PRIORITY LEVELS

BUG SEVERITY CLASSIFICATION

Priority vs Severity: Priority is the test's urgency (when to run). Severity is the bug's impact (how bad). A P2 edge-case test can find a CRITICAL bug — that's the point of edge-case testing.

BUG FIX WORKFLOW

When you find a bug:

1. Log it — add to results with severity + description + screenshot
2. Analyze root cause — read relevant source code
3. Fix it — minimal code change
4. Restart if needed:
   • Frontend CSS/TSX/JSON → HMR, wait 2s
   • Backend handler/service → dotnet watch auto-reloads, wait 3-5s
   • DI/Program.cs → restart backend
   • vite.config → restart frontend
5. Build check (only if logic change):
   • Frontend: cd src/NOIR.Web/frontend && pnpm run build
   • Backend: dotnet build src/NOIR.sln
6. Health check:

   curl -sf http://localhost:4000/robots.txt -o /dev/null && echo "Backend: OK"
   curl -sf http://localhost:3000 -o /dev/null && echo "Frontend: OK"
   

7. Re-verify — exact same test that found the bug
8. Screenshot fixed state → temp/qa-{page}-fixed-{BUG-ID}.png
9. Update result status to FIXED+VERIFIED
10. Regression check — if shared component changed, note affected pages

Bug Decision Tree

CSS/layout bug? → Fix Tailwind classes → No restart (HMR)
Missing translation? → Add to BOTH en/*.json AND vi/*.json → No restart (HMR)
Dark mode bug? → Fix hardcoded color or missing dark: variant → No restart
Data display bug? → Trace component → hook → handler → spec → Fix at correct layer → Watch reload
Form validation? → Check Zod + FluentValidation → Fix both if needed → Watch reload
State management? → Check TanStack Query invalidation → No restart
Navigation/routing? → Check router, useUrlTab/useUrlDialog → No restart
DI/startup? → Fix Program.cs/DI → Restart backend
Field-level UX? → Fix FormField/FormItem props → No restart

FIX-THEN-COMMIT Strategy

After fixing ALL bugs on a single page (not per-bug), create ONE commit:

git add [specific files only]
git commit -m "$(cat <<'EOF'
fix(qa): [page-name] — [N] bugs fixed

- BUG-001: [brief description]
- BUG-002: [brief description]

QA: NOIR QA Agent

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
EOF
)"

TECHNICAL NOTES

Playwright MCP Tools

Use mcp__playwright__* for ALL browser interactions:

• browser_navigate — go to URLs (initial load only — see SPA bug below)
• browser_click — click elements (use accessible name or CSS selector)
• browser_fill_form — fill multiple form fields at once
• browser_take_screenshot — capture to temp/
• browser_snapshot — accessibility tree (for finding elements)
• browser_select_option — <select> dropdowns
• browser_press_key — keyboard (Escape, Enter, Tab)
• browser_wait_for — network idle or element visible
• browser_hover — hover states
• browser_drag — drag-and-drop (Kanban, tree reorder)
• browser_type — type character by character
• browser_resize — responsive breakpoints

Strategy: browser_snapshot first to understand page structure, then use accessible names for clicking/filling. More robust than CSS selectors.

CRITICAL: MCP Direct — No Scripts

NEVER write Playwright test scripts (.js/.ts files). Always use mcp__playwright__* tools directly with AI reasoning (max effort, Opus model). The AI reads screenshots, analyzes accessibility trees, and makes intelligent decisions about what to click/verify — this catches visual bugs that scripted tests miss.

❌ WRONG: Write a .js file → run it with npx playwright test
✅ RIGHT: mcp__playwright__browser_navigate → mcp__playwright__browser_snapshot → AI analyzes → mcp__playwright__browser_click

The entire value of this QA system is AI visual reasoning + interactive exploration, not scripted automation.

Windows SPA Navigation Bug (CRITICAL)

On Windows, browser_navigate / page.goto() often produces blank white pages for React SPA routes. HTML shell loads but React doesn't mount.

Workaround: Navigate via SPA sidebar clicks instead of direct URL. Use browser_navigate ONLY for initial page load (/portal), then sidebar clicks for all subsequent pages. For detail pages without sidebar links, click table rows from parent list.

Context Efficiency

• Save browser_snapshot output to files (filename param) instead of inline
• NEVER dump full sidebar accessibility tree — 100+ lines of identical content
• Only read <main> content area
• For DataTable pattern pages, screenshot is sufficient — skip tree dump

Login Flow

1. browser_navigate → http://localhost:3000/login
2. browser_snapshot → find email/password fields
3. browser_fill_form → email: admin@noir.local, password: 123qwe
4. browser_click → Sign In button
5. browser_wait_for → dashboard loaded
6. For Platform Admin tests: logout, login as platform@noir.local / 123qwe

Screenshot Naming

temp/qa-{page}-{variant}.png

Page-level:  -light, -dark, -vi, -1024px, -768px
Element-level: -tab-{name}-{mode}, -create-dialog-{mode}, -edit-dialog-{mode}
               -confirm-dialog-{mode}, -empty-state-{mode}
Action:      -create-error, -create-valid, -fixed-{BUG-ID}

SERVICE LIFECYCLE

Restart Protocol

Restart Commands

# Restart backend
netstat -ano | grep ":4000 " | grep "LISTEN" | awk '{print $5}' | sort -u | while read pid; do taskkill //F //PID "$pid" 2>/dev/null; done
sleep 2
cd src/NOIR.Web && dotnet build --nologo -v q -c Debug > /dev/null 2>&1
ASPNETCORE_ENVIRONMENT=Development ASPNETCORE_URLS="http://localhost:4000" dotnet watch run --no-launch-profile > ../../.backend.log 2>&1 &

# Restart frontend
netstat -ano | grep ":3000 " | grep "LISTEN" | awk '{print $5}' | sort -u | while read pid; do taskkill //F //PID "$pid" 2>/dev/null; done
sleep 1
powershell -Command "Start-Process cmd -ArgumentList '/c cd /d src\NOIR.Web\frontend && pnpm run dev > ..\..\..\.frontend.log 2>&1'"

# Health check
curl -sf http://localhost:4000/robots.txt -o /dev/null && echo "Backend: OK" || echo "Backend: FAILED"
curl -sf http://localhost:3000 -o /dev/null && echo "Frontend: OK" || echo "Frontend: FAILED"

Crash Recovery

1. Check which service is down: tail -20 .backend.log or .frontend.log
2. If crash caused by your fix → revert fix first
3. Restart crashed service
4. Wait for health check
5. Resume testing