# الاختبار ومرجع git

تتعامل Pitmaster مع الملف الثنائي المعتمد `git` بوصفه مرجعًا: إذا قبل `git` ما يكتبه Pitmaster، وقرأ Pitmaster ما يكتبه `git`، يكون السلوك صحيحًا. توجد بنية الاختبارات في مستودع Pitmaster. لا تتضمن حزمة Composer سوى `src/` و`bin/pitmaster`، لذا شغّل كل ما يلي من نسخة مستنسخة بعد `composer install`.

## مجموعات الاختبارات

| الأمر | ما الذي يشغّله | هل يحتاج إلى `git` |
|---------|--------------|-------------|
| `composer test:unit` | مجموعة PHPUnit `unit`: اختبارات مكونات معزولة | لا |
| `composer test:integration` | مجموعة PHPUnit `integration`: Pitmaster و`git` يعملان على المستودعات نفسها | نعم |
| `composer test:oracle` | `bin/test-regression`: كل سيناريوهات المرجع | نعم |
| `composer test` | PHPUnit (المجموعتان) واختبار تراجع المرجع | نعم |
| `./bin/verify-all` | `composer verify`: أدلة الدعم، والانحراف عن upstream، وأثر الإثبات، واختبار الدخان للطفرات، و`composer audit` وPHPStan ومعايير البرمجة و`composer test` | نعم |

تشغّل CI مجموعة اختبارات الوحدة على إصدارات PHP متعددة، ومجموعة التكامل، واختبار تراجع المرجع (`PITMASTER_TEST_JOBS=4`)، وفحوص أدلة الدعم والانحراف عن upstream.

## سيناريوهات المرجع

كل سيناريو هو مجلد ضمن `scenarios/<category>/` (المجموع 761، منها 156 كُتبت لـ Pitmaster و605 استُوردت من تطبيقات Git أخرى):

```
scenarios/diff/diff-add-lines/
  scenario.json   # commands and expectations
  setup.sh        # builds the starting repository
  oracle/         # outputs captured from git
```

يحدد `scenario.json` الأمر الذي يجب تشغيله باستخدام `git` والأمر المكافئ Pitmaster، وما يجب أن يتطابق:

```json
{
    "name": "diff-add-lines",
    "category": "diff",
    "operations": ["diff"],
    "oracle_commands": { "diff": "git -c color.ui=never diff" },
    "actual_commands": { "diff": "php \"{{ROOT}}/bin/pitmaster\" diff | perl -pe 's/\\e\\[[0-9;]*m//g'" },
    "expectations": { "exact_match": ["diff"], "fsck_clean": true }
}
```

ينسخ التشغيل المستودع الذي أنشأه `setup.sh`، ثم يشغّل أوامر المرجع وPitmaster على نسخ منفصلة، ويقارن المخرجات والكائنات والمراجع والسجل. كما يتطلب `fsck_clean` أن يقبل `git fsck` المستودع الذي كتبه Pitmaster. يُلتقط خرج المرجع من `git` إذا كان مفقودًا أو عند تحديثه؛ وإلا فتُستخدم ملفات `oracle/` المضمّنة في المستودع.

يغطي السيناريو الحالات التي ينشئها الإعداد فقط. فمثلًا، تقارن سيناريوهات diff الملفات المعدّلة، ولهذا لا ترصد اختلافات خرج diff للملفات الجديدة والمحذوفة والثنائية المدرجة في [Diff](https://pitmaster.inline0.dev/ar/docs/operations/diff).

### العمل مع السيناريوهات

```bash
./bin/test-scenario <name>                 # oracle, actual, compare for one scenario
./bin/test-regression                      # all scenarios
./bin/test-regression --jobs 4             # in parallel (or PITMASTER_TEST_JOBS=4)
./bin/test-regression --category diff      # one category
./bin/test-regression --fast               # pass/fail only, no reports

./bin/oracle <name>                        # capture git output for a scenario
./bin/oracle --refresh <name>              # re-capture, for example after a git upgrade
./bin/actual <name>                        # run Pitmaster and capture its output
./bin/compare <name>                       # compare oracle and actual output
```

للتحقق من عدة إصدارات من git، أدرجها في `PITMASTER_TEST_GIT_BINARIES` وشغّل اختبار الدخان:

```bash
PITMASTER_TEST_GIT_BINARIES=/path/to/git-2.45:/path/to/git-2.46 \
  vendor/bin/phpunit --filter MultiGitVersionSmokeTest
```

## مجموعات الاختبارات upstream

استُوردت السيناريوهات ضمن `scenarios/upstream/` من مجموعات اختبارات تطبيقات أخرى: مجموعة اختبارات git نفسها (412)، وisomorphic-git (71)، وlibgit2 (63)، وgo-git (46)، وJGit (7)، وdulwich (6). توجد أشجار ملفات الاختبار اللازمة ضمن `fixtures/upstream/`، لذا تعمل المجموعة كاملةً من نسخة مستنسخة حديثًا دون اتصال بالشبكة أو الاعتماد على مسارات محلية خاصة بالجهاز. وتعثر عليها نصوص الإعداد عبر متغير البيئة `PITMASTER_ROOT`.

يتحقق `composer verify:drift` (`bin/audit-upstream-drift`) من ربط كل حالة upstream مضمّنة بسيناريو.

## مصفوفة الدعم

يسرد `SUPPORT_MATRIX.md` في المستودع كل ميزة git ضمن النطاق وحالتها:

| الحالة | المعنى |
|--------|---------|
| `DONE` | منفذة وتم التحقق منها بمرجع ضمن نطاق التكافؤ المعلن |
| `PART` | منفذة جزئيًا |
| `TODO` | ضمن النطاق ولم تُنفذ بعد |
| `DEFER` | غير مخطط لها حاليًا |
| `N/A` | خارج النطاق |

ينشئ `bin/support-matrix` الملف من `config/support-matrix.json`. ويربط `config/support-evidence.json` كل صف `DONE` و`PART` باختبارات وسيناريوهات مرجعية محددة، ويفشل `composer verify:evidence` إذا لم يكن للصف أي دليل. يعيد CI إنشاء المصفوفة ويفشل إذا اختلف الملف الملتزم به.

يعني صف `DONE` أن السيناريوهات المسجلة له تطابق git. وقد يظل السلوك مختلفًا خارج هذه السيناريوهات؛ وتُسجّل الاختلافات المعروفة في [متعقّب المشكلات](https://github.com/inline0/pitmaster/issues).

## قياسات الأداء

تستخدم أعمال تحسين الأداء أداة الاختبار ضمن `bench/`:

```bash
composer bench -- --suite=smoke --runs=1 --warmups=0   # quick check
composer bench:baseline                                # full report
composer bench:compare -- <before.json> <after.json>   # compare two reports
composer bench:verify -- <report.json> bench/reports/smoke-thresholds.json
```

يتحقق CI من تقرير اختبار الدخان بمقارنته بالحدود المضمّنة في المستودع.