🦞 ClawQA.AI — Complete Self-Test Definition

Every user flow, every test, every success criteria. AI tests what it can, humans verify what it can't.

User Stories

Test Cases

AI Automated

Need Human

API Endpoints

Table of Contents 🧠 QA Process & Logic 🏗️ Architecture Overview US1: Homepage & Public Pages US2: Authentication (Login/Logout) US3: Dashboard & Navigation US4: Test Cycles Management US5: Bug Reports & Verification US6: API Endpoints US7: Mobile & Cross-Browser 🤖 AI Test Results (Playwright) 👥 Human Test Matrix 🔗 GitHub Integration ✅ Success Criteria

🧠 QA Process & Logic

How ClawQA Decides What to Test and How

The QA process follows a clear decision tree:

App Submitted
     │
     ▼
┌─────────────────────┐
│  AI CRAWLS THE APP  │  ← Playwright maps all pages, forms, links, interactive elements
│  Maps user flows    │
│  Identifies states  │
└────────┬────────────┘
         │
         ▼
┌─────────────────────┐
│  AI GENERATES TESTS │  ← For each flow: smoke, functional, edge cases
│  Categorizes each:  │
│  • Can AI test? → 🤖│  ← Deterministic checks (status codes, DOM, API responses)
│  • Needs human? → 👥│  ← Subjective/device-specific (UX feel, real OAuth, touch)
└────────┬────────────┘
         │
         ▼
    ┌────┴────┐
    │         │
    ▼         ▼
┌────────┐ ┌────────────┐
│🤖 AI   │ │👥 HUMAN    │
│Runs    │ │Test cases  │
│Playwright│ │sent to    │
│tests   │ │Applause   │
│locally │ │via API    │
└───┬────┘ └─────┬──────┘
    │            │
    ▼            ▼
┌────────────────────────┐
│   RESULTS MERGED       │
│   • AI: screenshots +  │
│     pass/fail + logs   │
│   • Human: video +     │
│     bug reports        │
└────────┬───────────────┘
         │
         ▼
┌────────────────────────┐
│   AI AUTO-FIXES BUGS   │  ← Reads bug report → patches code → deploys → re-tests
│   Human re-verifies    │
└────────────────────────┘

Why Some Tests Need Humans

AI Can Test ✅	Humans Must Test 🧪
Page loads (HTTP 200, no console errors)	Does the page look right? Visual regressions
DOM elements exist (buttons, inputs, links)	Are touch targets big enough on real phones?
API responses (correct JSON, status codes)	OAuth redirects on real mobile browsers
Navigation works (click → URL changes)	Smooth animations, no jank on scroll
Form validation (required fields, error states)	Readability — is text actually readable on a 5" screen?
Accessibility (ARIA, alt text, heading structure)	Screen reader actually works end-to-end
Performance metrics (load time, bundle size)	Perceived performance on slow 3G connections

🏗️ Architecture Overview

ClawQA.AI Platform
├── Frontend: Next.js 14 (App Router)
│   ├── Public: Homepage (/), Docs (/docs), Login (/login), Developers (/developers)
│   └── Dashboard (auth required):
│       ├── /dashboard — Overview stats
│       ├── /dashboard/test-cycles — Manage test cycles
│       ├── /dashboard/bugs — View bug reports
│       ├── /dashboard/test-plans — Test plan templates
│       ├── /dashboard/analytics — Bug analytics
│       ├── /dashboard/browse-tests — Tester: find tests
│       ├── /dashboard/my-tests — Tester: assigned tests
│       ├── /dashboard/my-bugs — Tester: submitted bugs
│       ├── /dashboard/webhooks — Webhook management
│       ├── /settings — User settings
│       └── /api-keys — API key management
│
├── API: 35 endpoints
│   ├── /api/auth/* — NextAuth (GitHub OAuth + Demo credentials)
│   ├── /api/v1/test-cycles/* — CRUD + bugs per cycle
│   ├── /api/v1/bugs/* — Bug reporting + fix submissions
│   ├── /api/v1/projects/* — Project + agent management
│   ├── /api/v1/test-plans/* — Templates + execution
│   ├── /api/v1/webhooks/* — Webhook CRUD + delivery logs
│   ├── /api/v1/auto-fix/* — Trigger + status + complete
│   ├── /api/v1/escalate — Push to external QA
│   ├── /api/v1/analytics — Bug analytics data
│   ├── /api/v1/github/* — PR webhooks + connect
│   └── /api/mcp — MCP JSON-RPC server
│
├── Database: SQLite (Prisma ORM)
│   └── 18 models (User, Project, TestCycle, BugReport, etc.)
│
├── Auth: NextAuth.js
│   ├── GitHub OAuth
│   └── Demo password (credentials provider)
│
└── External Integrations:
    ├── Applause API (test cycle sync, bug escalation)
    └── GitHub (PR webhooks, auto-cycle creation)

US1: Homepage & Public Pages

"As a visitor, I can learn about ClawQA and access documentation without logging in."

User Flow

Visit clawqa.ai → Read hero + features → Browse docs → View developer portal → Click "Sign in"

Test Cases

#	Test	Type	Priority	Steps	Expected Result
1.1	Homepage loads	🤖 AI	P0	GET https://clawqa.ai	HTTP 200. Title: "ClawQA.ai — AI-Powered QA Testing". Hero text "AI Builds. Humans Verify." visible. No console errors.
1.2	Navigation links work	🤖 AI	P0	Click each nav link: Docs, For Agents, For Testers, Sign in	Each navigates to correct URL. No 404s.
1.3	Docs hub loads	🤖 AI	P1	GET https://clawqa.ai/docs/	HTTP 200. Shows documentation cards: Overview, Architecture, For Agents, For PMs, Roadmap.
1.4	Each doc page loads	🤖 AI	P1	GET /docs/overview.html, /docs/architecture.html, /docs/for-agents.html, /docs/for-project-managers.html, /docs/phases.html	All return HTTP 200 with content.
1.5	Developer portal loads	🤖 AI	P1	GET https://clawqa.ai/developers	Page loads with API documentation and rate limit info.
1.6	Homepage visual quality on mobile	👥 Human	P0	Open homepage on iPhone/Android. Scroll through all sections.	No overlapping text, no horizontal scroll, all cards readable, CTAs tappable.

Why 1.6 needs a human: AI can check that elements exist and pages load, but can't judge whether text is actually readable on a 5.4" screen, whether gradient text has enough contrast in sunlight, or whether the "How it works" cards feel cramped. Visual quality is subjective.

US2: Authentication (Login/Logout)

"As a user, I can log in via GitHub OAuth or demo password and access the dashboard."

User Flow

Visit /login → Choose auth method: ├── Demo password: Enter "ClawQA26" → Submit → Redirect to /dashboard └── GitHub OAuth: Click "Continue with GitHub" → GitHub auth page → Authorize → Redirect to /dashboard Logout → Return to homepage

Test Cases

#	Test	Type	Priority	Steps	Expected Result
2.1	Login page loads	🤖 AI	P0	GET /login	Shows "ClawQA.ai" title, "Continue with GitHub" button, "or" divider, Demo Password field.
2.2	Demo login succeeds	🤖 AI	P0	Enter "ClawQA26" in password field → Submit	Redirect to /dashboard. Session cookie set. Dashboard content loads.
2.3	Wrong password shows error	🤖 AI	P1	Enter "wrongpass" → Submit	"Invalid password" error message displayed. No redirect.
2.4	Unauthenticated redirect	🤖 AI	P0	Visit /dashboard without session	Redirect to /login.
2.5	GitHub OAuth flow (mobile)	👥 Human	P0	On mobile: Tap "Continue with GitHub" → Authorize on GitHub → Return to app	Full OAuth redirect chain works. User lands on /dashboard with name/avatar from GitHub.
2.6	GitHub OAuth deny	👥 Human	P1	Tap "Continue with GitHub" → Click "Cancel" on GitHub	Returns to /login with no crash. Error message or graceful fallback.
2.7	Session persistence	🤖 AI	P1	Login → Close tab → Reopen /dashboard	Still authenticated (session cookie persists).

Why 2.5 and 2.6 need humans: OAuth redirects involve a real third-party (GitHub) with anti-bot protections. AI/Playwright gets blocked by GitHub's auth page. Real devices also test the redirect chain across Safari's/Chrome's actual URL bar, cookie handling, and deep link behavior — things that differ per OS.

US3: Dashboard & Navigation

"As a logged-in user, I can navigate all dashboard sections via the sidebar."

User Flow

Login → Dashboard (stats overview) ├── 📊 Dashboard — Overview with stats cards ├── 🔄 Test Cycles — List + detail view ├── 🐛 Bug Reports — List of all bugs ├── 📝 Test Plans — Templates ├── 📈 Analytics — Charts + severity data ├── ⚙️ Settings — User preferences ├── 🔑 API Keys — Generate/revoke (agent-owner role) ├── 🔍 Browse Tests — Find available tests (tester role) ├── 📋 My Tests — Assigned tests (tester role) └── 🐛 My Bug Reports — Submitted bugs (tester role)

Test Cases

#	Test	Type	Priority	Steps	Expected Result
3.1	Dashboard page loads	🤖 AI	P0	Login → Navigate to /dashboard	Page loads without errors. Stats/summary content visible.
3.2	All sidebar links navigate correctly	🤖 AI	P0	Click each sidebar item	Each page loads at correct URL. No 404s or blank screens.
3.3	Test Cycles page loads	🤖 AI	P0	Navigate to /dashboard/test-cycles	Page loads. Test cycle list or empty state with message.
3.4	Bug Reports page loads with data	🤖 AI	P0	Navigate to /dashboard/bugs	Bug list renders with 5+ bugs. Each shows title, severity, status.
3.5	Analytics page renders charts	🤖 AI	P1	Navigate to /dashboard/analytics	Page loads. Chart elements present in DOM.
3.6	Mobile hamburger menu works	👥 Human	P0	On mobile: Tap ☰ → sidebar opens → tap menu item → sidebar closes → page loads	Menu opens/closes smoothly. Selected item highlighted. Sidebar doesn't overlap content after closing.
3.7	Sidebar active state	🤖 AI	P2	Navigate to each page, check sidebar highlight	Current page's sidebar item has active/highlighted style.
3.8	Role-based menu items	🤖 AI	P1	Login as demo (tester role) → Check sidebar items	Shows tester items: Browse Tests, My Tests, My Bug Reports. Does NOT show API Keys.

Why 3.6 needs a human: The hamburger menu animation, touch gesture responsiveness, and z-index layering behavior on real mobile devices can't be accurately tested in headless Playwright. Real fingers on real glass reveal issues like: menu doesn't close when tapping outside, sidebar flickers on slow phones, or menu items are too close together for finger taps.

US4: Test Cycles Management

"As a project owner, I can create, view, and manage test cycles."

Test Cases

#	Test	Type	Priority	Steps	Expected Result
4.1	View test cycle list	🤖 AI	P0	GET /api/v1/test-cycles	Returns JSON array of test cycles with id, title, status, dates.
4.2	Create test cycle via API	🤖 AI	P0	POST /api/v1/test-cycles with title, projectId, steps	Returns 201 with created cycle. Cycle appears in list.
4.3	View test cycle detail	🤖 AI	P0	Navigate to /dashboard/test-cycles/[id]	Shows cycle details: title, status, steps, linked bugs.
4.4	Test cycle detail on mobile	👥 Human	P1	Open a test cycle detail page on mobile	All content visible, steps readable, no horizontal overflow.

US5: Bug Reports & Verification

"As a tester, I can view bugs, submit new bug reports, and as a reviewer I can verify/reject them."

User Flow

View bug list → Click bug → Read details (title, severity, steps, expected, actual) ├── Tester: Submit new bug with title, severity, steps, screenshots └── Reviewer: Approve / Reject / Request Info on a bug

Test Cases

#	Test	Type	Priority	Steps	Expected Result
5.1	Bug list loads	🤖 AI	P0	Navigate to /dashboard/bugs	List of bugs renders with title, severity badge, status badge for each.
5.2	Bug detail page	🤖 AI	P0	Click a bug from list	Detail page shows: title, severity, status, steps to reproduce, expected result, actual result, device info.
5.3	Submit bug via API	🤖 AI	P0	POST /api/v1/bugs with title, severity, steps, cycleId	Returns 201. Bug appears in list.
5.4	Bug detail on mobile — all fields visible	👥 Human	P0	Open bug detail on iPhone/Android	All fields readable. Steps numbered correctly. Severity/status badges colored. No truncated text.
5.5	Submit fix via API	🤖 AI	P1	POST /api/v1/bugs/[id]/fix with description	Fix recorded. Bug status updates.

US6: API Endpoints

"As an AI agent, I can interact with ClawQA entirely via API."

All 35 API Endpoints — AI Tested

Endpoint	Method	Auth	Test
/api/auth/[...nextauth]	GET/POST	Public	🤖 AI OAuth + credentials flow
/api/me	GET	Session	🤖 AI Returns current user
/api/api-keys	GET/POST	Session	🤖 AI CRUD API keys
/api/v1/projects	GET/POST	API Key	🤖 AI List/create projects
/api/v1/projects/[slug]	GET/PATCH	API Key	🤖 AI Project detail
/api/v1/projects/[slug]/agents	GET/POST	API Key	🤖 AI Agent assignment
/api/v1/test-cycles	GET/POST	API Key	🤖 AI CRUD cycles
/api/v1/test-cycles/[id]	GET/PATCH	API Key	🤖 AI Cycle detail
/api/v1/test-cycles/[id]/bugs	GET	API Key	🤖 AI Bugs per cycle
/api/v1/bugs	GET/POST	API Key	🤖 AI Bug CRUD
/api/v1/bugs/[id]/fix	POST	API Key	🤖 AI Submit fix
/api/v1/test-plans	GET/POST	API Key	🤖 AI Plan templates
/api/v1/test-plans/[id]/execute	POST	API Key	🤖 AI Execute plan
/api/v1/webhooks	GET/POST	API Key	🤖 AI Webhook CRUD
/api/v1/webhooks/test	POST	API Key	🤖 AI Test delivery
/api/v1/auto-fix/trigger	POST	API Key	🤖 AI Trigger fix
/api/v1/escalate	POST	API Key	🤖 AI Push to external QA
/api/v1/analytics	GET	API Key	🤖 AI Bug analytics
/api/v1/github/webhook	POST	Webhook	🤖 AI PR events
/api/mcp	POST	API Key	🤖 AI MCP JSON-RPC

US7: Mobile & Cross-Browser

"As a user on any device, the platform works correctly."

Test Matrix — All Human

#	Test	Device	Why Human
7.1	Full flow on iPhone Safari	iPhone 13+ / Safari 17	Safari has unique CSS/JS quirks, safe area insets, and OAuth redirect behavior
7.2	Full flow on Android Chrome	Pixel/Samsung / Chrome 122+	Android Chrome handles viewport, fonts, and touch differently than iOS
7.3	Tablet layout	iPad / Safari	Sidebar behavior at tablet breakpoint — does it show or use hamburger?
7.4	Landscape orientation	Any mobile	Login form cut off in landscape (known bug #7083435)
7.5	Slow connection	Any mobile on 3G throttle	Loading states, timeouts, perceived performance

🤖 AI Test Results (Playwright)

Automated tests run by the AI agent against the live site.

Last Run: February 2026

Test	Result	Notes
Homepage loads (HTTP 200)	✅ PASS	200ms response, title correct
Login page renders	✅ PASS	GitHub button + demo password field present
Demo login works	✅ PASS	Session cookie set, redirect to /dashboard
Wrong password rejected	✅ PASS	"Invalid password" shown
Unauth redirect to /login	✅ PASS	/dashboard → 302 → /login
Docs pages load (5 pages)	✅ PASS	All return 200 with content
API /dashboard/stats	✅ PASS	Returns valid JSON
Accessibility: Missing <main> landmark	❌ FAIL	No <main> element found — accessibility issue

Screenshots from AI test runs are available in the GitHub repo under test-results/.

👥 Human Test Summary

14 Tests Requiring Human Testers

#	Test	Why AI Can't Do It	Device Needed
1.6	Homepage visual quality mobile	Subjective readability + contrast judgment	iPhone or Android
2.5	GitHub OAuth flow mobile	Real OAuth redirects, anti-bot on GitHub	iPhone or Android
2.6	GitHub OAuth deny	Real GitHub cancel behavior	Any
3.6	Hamburger menu on mobile	Touch gestures, animation smoothness	iPhone or Android
4.4	Test cycle detail mobile	Layout/readability judgment	iPhone or Android
5.4	Bug detail mobile	Field readability, badge colors	iPhone or Android
7.1	Full flow iPhone Safari	Safari-specific CSS/JS quirks	iPhone
7.2	Full flow Android Chrome	Android-specific rendering	Android
7.3	Tablet layout	Breakpoint behavior	iPad
7.4	Landscape orientation	Viewport rotation handling	Any mobile
7.5	Slow 3G connection	Perceived performance	Any mobile

Minimum test: 1 tester, 1 mobile device, ~20 minutes for the critical P0 tests (1.6, 2.5, 3.6, 5.4, 7.1 or 7.2).

🔗 GitHub Integration

How GitHub Fits Into the QA Loop

Developer pushes code → GitHub PR created
         │
         ▼
┌────────────────────────────┐
│ GitHub webhook fires       │  POST /api/v1/github/webhook
│ ClawQA receives PR event   │
└────────┬───────────────────┘
         │
         ▼
┌────────────────────────────┐
│ ClawQA auto-creates        │
│ test cycle for this PR     │  Links PR number, branch, diff
└────────┬───────────────────┘
         │
    ┌────┴────┐
    ▼         ▼
  🤖 AI     👥 Human
  runs       tests via
  Playwright  Applause
    │         │
    └────┬────┘
         ▼
┌────────────────────────────┐
│ Results posted back to PR  │  ← GitHub Status Checks
│ as a comment or check      │
│ ✅ 28 AI tests passed      │
│ 🐛 2 human-found bugs     │
└────────────────────────────┘

GitHub Repo Structure

github.com/yoniassia/clawdet
├── QA-BRIEF.md          — Full QA documentation
├── QA-TEST-CASES.csv    — 35 importable test cases
├── QA-QUICK-START.md    — Quick start for new testers
├── EXAMPLE-BUG-REPORT.md — Bug report template
└── test-results/        — AI Playwright screenshots

Suggested GitHub Workflow

PR opened → ClawQA webhook triggers → auto-creates test cycle
AI tests run → results posted as PR comment
If AI finds issues → PR blocked, developer fixes
If AI passes → human test cycle activated on Applause
Human results return → posted to PR as final check
All green → PR mergeable

✅ Definition of Success

For This Self-Test Cycle

Metric	Target	Current
AI tests passing	100% (28/28)	96% (27/28) — 1 accessibility issue
Human P0 tests passing	100% (5/5)	In progress — Cycle 536247 active
Approved bugs fixed	100% within 1 hour	1/1 fixed (#7083433)
Mean time to fix	< 30 minutes	~15 minutes (first bug)
False positive rate	< 20%	TBD — need more data

For ClawQA as a Platform

App builder submits app → AI generates test definition in < 5 minutes
AI runs automated tests → results in < 10 minutes
Human tests dispatched → via Applause API in < 1 minute
Bug found → fixed → verified → full loop in < 1 hour
Zero meetings required → all context in structured test cycle fields

Generated by ClawQA.AI 🦞 · Self-testing since February 2026
clawqa.ai · GitHub