---
name: test-harness
description: "Build a project's verification harness on day one (factory phase 1, by the coordinator), shaped by what the project is: web app, API/backend, Flutter/Android app, Windows app, Telegram bot, realtime/multi-user. Produces gates.sh layers (lint/types/unit/integration/e2e of every VISION flow), seed data, preview-per-branch, visual baselines, performance budgets, an app-lab build recipe, a post-deploy smoke, and the role matrix that decides which QA roles run on which change. Use when starting a project in the software factory, when a repo has no real tests/gates, or when QA keeps finding the same class of bug (the harness is missing a layer)."
---

# Test Harness: التحقق بيتبني قبل الميزة

القاعدة: **أي حاجة ممكن تتحقق بشكل حتمي تدخل `gates.sh`، والأدوار الذكية (QA و UX و visual و perf و security) تدور على اللي مش ممكن يتحقق بالشكل ده.** وأي bug الـ QA بيلاقيه مرتين من نفس النوع، يبقى طبقة ناقصة هنا. وساعتها بنصلح المصنع مش الحالة.

## اللي لازم يخرج من مرحلة 1 (لأي مشروع)
| الملف | فيه إيه |
|---|---|
| `gates.sh` | بالترتيب: format/lint ← types ← unit ← integration ← e2e للـ flows الأساسية. سريع (هدفه أقل من 10 دقايق على Actions). `gates` بيشغّله. |
| `tests/e2e/` | **اختبار e2e لكل flow في `.factory/qa/flows.md`**، باسم الـ V-رقم (`v3-checkout.e2e.ts`). الـ flow الأساسي من غير e2e = الـ harness مش جاهز. |
| `scripts/seed` | بيزرع الداتا اللي في `.factory/qa/data.md` على dev أو preview أو staging، وبيرفض يشتغل على production (يتأكد من الـ env). |
| preview لكل branch | Vercel أو Cloudflare Pages preview، أو staging على med-vps. لينك ثابت يتكتب في `STATE.md`. |
| `.factory/qa/budgets.yaml` | حدود الأداء والـ a11y (الافتراضي في ROLE بتاع perf-qa)، وتتظبط حسب المشروع. |
| `.factory/qa/visual/baseline/` | سكرينشوتس مرجعية للشاشات الأساسية بعد ما العميل يوافق على الشكل. |
| `.app-lab/build-android.sh` أو `build-windows.sh` | لو تطبيق: وصفة debug/QA build، فيها screenshots مسموحة. |
| `scripts/smoke` | بعد أي deploy: الصفحة الرئيسية، والـ health، والـ flow الأساسي بقراية بس، في أقل من دقيقة. |
| `.factory/qa/matrix.md` | مين من الأدوار بيشتغل على أنهي نوع تعديل (الجدول تحت، معدّل للمشروع). |

اختبر الـ harness نفسه: `gates <dir>` يبقى PASS على الـ skeleton، واختبار واحد على الأقل يفشل لو كسرت الـ flow الأساسي بإيدك (وبعدين رجّعه). **harness مبيفشلش أبداً يبقى harness مش شغال.**

## حسب نوع المشروع
**موقع / web app (Vite و Next و Astro):**
- eslint و tsc و vitest، و Playwright e2e (موبايل 390 وديسكتوب).
- `toHaveScreenshot` للـ baselines.
- axe في e2e: `@axe-core/playwright`، و violations = fail.
- lighthouse-ci budget على الصفحة الرئيسية (اختياري في gates، وإلزامي في perf-qa).

**API / backend (Node و FastAPI و Supabase و Firebase Functions):**
- unit، و integration على DB حقيقية مؤقتة (Supabase local، أو Firebase emulator، أو Postgres في docker على Actions).
- contract tests للـ endpoints اللي الفرونت أو التطبيق بيستخدمها.
- **اختبار صلاحيات لكل endpoint:** مستخدم تاني، ومن غير توكن، وأدمن.
- migrations: up على نسخة فاضية + up على snapshot من staging.
- **الأوامر التشغيلية جوه الـ production image** (create-owner، وseed، وimport، وmigrate): لو الـ API في Docker، طبقة في gates (أو smoke) بتبني الـ runtime image وبتشغّل كل أمر منهم بـ `docker compose exec -T api npm run <cmd>`. الأوامر اللي مكتوبة `tsx src/...` بتعدّي في dev وبتقع في image فيها dist بس، والداتا اللي برا مجلد الـ API بتبقى مش موجودة. (سديم 2026-11-15: نفس العطل اتكرر مرتين، في create-owner وبعده import-content، وgates كانت PASS في المرتين.)

**Flutter / Android:**
- `dart analyze` و `flutter test` (unit و widget)، و `integration_test` للـ flows على emulator (app-lab أو Actions).
- `.app-lab/build-android.sh` (debug أو QA flavor من غير FLAG_SECURE).
- Test Lab robo على release مرة في كل إصدار.
- golden tests للشاشات الأساسية بدل الـ baselines.

**Windows (Flutter desktop أو غيره):** analyze و unit، و `.app-lab/build-windows.sh`، و smoke بيفتح التطبيق ويقفله على `windows-latest` (app-lab أو `windows-build`).

**بوت تيليجرام:**
- handlers متقسمة عن الـ I/O، و unit لكل أمر.
- اختبار محادثة على بوت test بحساب اختبار (telegram-mcp).
- صلاحيات الأوامر الإدارية.
- الـ webhook secret.

**realtime / multi-user (Med Royale وأمثاله):**
- سكربت N عميل في نفس الوقت (Playwright contexts أو ws)، بيتشغّل في gates بـ N صغير، وفي perf-qa بـ N الهدف.
- اختبارات سباق للحالات الحرجة: نفس الحاجة لاتنين، أو انقطاع وإعادة اتصال.

## مصفوفة الأدوار (الافتراضي، وتتعدل في `.factory/qa/matrix.md`)
| التعديل بيلمس | global-qa | novice-ux | visual | perf | security |
|---|---|---|---|---|---|
| UI (شاشات، نصوص، layout) | ✓ | ✓ | ✓ | | |
| flow أساسي أو منطق بيزنس | ✓ | ✓ | | | |
| API، DB، auth، فلوس، صلاحيات | ✓ | | | ✓ | ✓ |
| أداء أو حجم أو dependencies | | | | ✓ | ✓ |
| إصدار (release candidate) | ✓ | ✓ | ✓ | ✓ | ✓ |

- **design-explorer** بيشتغل في مرحلة التصميم (بعد Discovery) وقبل أي redesign.
- **security-verifier** بيشتغل في re-verify على كل `type:security` اتقفلت.
- الأدوار اللي ملهاش ✓ مبتشتغلش، عشان الكوتا.

مرتبط: سكيلز `software-factory` و `ci-context`، و `e2e` (agentic e2e runner)، و `webapp-testing`، و `test-driven-development`.
