مهارات اختبار الأنظمة الموزعة

مهارتان لوكلاء الترميز بالذكاء الاصطناعي يصممان وينفذان اختبارات مدفوعة بالادعاءات للأنظمة الموزعة وذات الحالة. معًا ينتجان خطة اختبار Markdown منظمة وتقرير نتائج مع أحكام من 10 حالات وتصنيف صريح للمسؤولية (SUT / harness / checker / environment). يقرأ المراجع القطعتين ويقرر ما إذا كان سيتم الإصدار؛ لا شيء آخر يجب إعادة تشغيله.

يعمل مع Claude Code، Codex، Copilot CLI، Cursor، Gemini، أو أي وكيل يقرأ Markdown ويشغل الصدفة. المهارات هي ملفات SKILL.md عادية. ينفذها الوكيل؛ خطة الاختبار وتقرير النتائج هما المخرجات.

مهارة واحدة تصمم الخطة. الأخرى تنفذها. تبدأ الخطة من ادعاءات المنتج، وتولد فرضيات مرتبطة بتلك الادعاءات، وتكتب سيناريوهات مسماة باسم الادعاء الذي يحاول كل منها تزييفه. بالنسبة للسيناريوهات الحساسة للاتساق، يربط كل سيناريو أيضًا نموذجًا مجردًا (register | queue | log | lock | lease | ledger | …) بمخطط تاريخ العمليات، ومدقق مسمى، وخصم (nemesis) مع أدلة هبوط قابلة للملاحظة. تنتهي الخطة بحجة كفاية تغطية وبيان ثقة محافظ.

لماذا

الافتراضي لاختبار الأنظمة الموزعة وذات الحالة — كتابة بضعة اختبارات تكامل والانتهاء — يجد جزءًا صغيرًا من الأخطاء التي تكسر هذه الأنظمة بالفعل في الإنتاج: تجزئات الشبكة الجزئية، التزامن غير الحتمي، استرداد الأعطال، الترقية/الاسترجاع، القابلية للتكرار تحت إعادة التشغيل، الترتيب الحساس للتوقيت.

تفرض هذه المهارات سير عمل رأسي يستمد من المعرفة التي تم اكتسابها بشق الأنفس في المجال:

• مدفوعة بالادعاءات، وليس مدفوعة بالاختبارات. ابدأ مما يعد به المنتج. كل سيناريو يزيّف ادعاءً واحدًا تحت خطأ واحد. اختبار مسمى باسم ادعائه أصعب في إضعافه من اختبار مسمى باسم إعداده.
• كفاية التغطية هي مخرجات قابلة للتسليم. تنتهي الخطة بحجة أن السيناريوهات المختارة كافية للإصدار، بالإضافة إلى قائمة صادقة بما يبقى غير مُتحقق.
• إعادة استخدام صندوق أدوات النظام قيد الاختبار. تكتشف مهارة التنفيذ الاختبارات الحالية، ودفاتر التشغيل، وهيكل حقن الأعطال قبل اختراع أي شيء جديد.
• نموذج + تاريخ + مدقق، وليس مجرد فوضى. بالنسبة لادعاءات السلامة، المتانة، القابلية للتكرار، العزل، الترتيب، أو العضوية، يعلن كل سيناريو عن نموذج مجرد، ومخطط تاريخ العمليات، ومدقق مسمى (الخطية، التسلسلية، اتساق الجلسة، لا فقدان إقرار، مرة واحدة بالضبط، …)، وكيفية معالجته للنتائج الغامضة (المهلات، الإرساليات غير المعروفة، إعادة المحاولات). فوضى بالإضافة إلى نموذج ومدقق، وليس فوضى وحدها.
• لا نجاحات صامتة. يستشهد كل PASS بأدلة تنفيذ المراقب و الإشارة التي تثبت أن الخطأ قد أُطلق بالفعل. تأتي الأحكام من مجموعة من 10 حالات، لذلك لا يمكن قراءة "نص الفوضى تم تشغيله بنظافة" على أنها "الادعاء نجا من الخطأ." كل FAIL يحمل علامة مسؤولية SUT / harness / checker / environment حتى يصل المكررون إلى قائمة الانتظار الصحيحة.

ما تحصل عليه

من البداية إلى النهاية، تنتج المهارتان ما يلي:

docs/testing-plans/<slug>.md              ← plan with §0–§9 (see below)
test-sessions/<slug>/<UTC>/
  ├── session-log.md                       ← timeline + toolbox + env probe
  ├── logs/                                ← per-scenario stdout/stderr
  ├── metrics/                             ← metric snapshots
  ├── artifacts/                           ← ephemeral harnesses, dumps
  └── findings/
      ├── <scenario>.md                    ← per-scenario verdict (written as run proceeds)
      └── report.md                        ← summary + adequacy + confidence delta

هيكل الخطة (يمكن للمراجع قراءة هذا وتقرير ما إذا كان سيتم الإصدار دون إعادة تشغيل الاختبارات):

0. Architectural summary            — system as it actually exists
1. Scope
1b. Claims under test               — the spine
1c. Missing claims discovered       — docs ↔ code drift
2. SUT model
3. Existing test inventory          — what's already covered
4. Failure-mode hypotheses          — tied to claim IDs
5. Coverage matrix                  — claim × hypothesis
6. Technique selection              — from the catalog
6b. Environment requirements
7. Scenarios                        — each named after the claim, with
                                        Target test file + Skeleton
   7.M Model / history /            — mandatory when the scenario falsifies
       checker discipline             a claim in {safety, durability,
                                       idempotency, isolation, ordering,
                                       membership}: model under test,
                                       operation-history schema, named
                                       checker, nemesis + landing evidence,
                                       ambiguous-outcome handling, reduction
                                       plan (SUT/harness/checker/env blame)
7b. Coverage adequacy argument      — why these tests are enough
7c. Residual uncertainty            — what stays unverified, and why ok
7d. Confidence statement            — the reviewer's verdict
8. What this plan does NOT cover
9. Open questions / followups

مثال كتلة §7.M (مقتطف من خطة)

### Scenario S3: linearizable_append_under_partition
- Falsifies if it FAILs: C1 (every acknowledged append is durable
  and linearisable), C5 (leader election completes within 5s)
- Workload: 8 clients, 70% append / 30% read, 5min, key-skew zipf
- Faults: asymmetric partition isolating current leader at T+60s
  for 30s
- Oracle: linearizability via Porcupine over per-key histories

§7.M (model / history / checker discipline)
- Model under test:    log
- Operation history:   default 11-field schema (op id, process id,
                       invoke/complete ts, op type, key, input,
                       output, error, timeout marker, node seen,
                       fault epoch). Recorded in-process + server-
                       side audit.
- Checker:             linearizability (Porcupine) per-key, then
                       no-lost-ack against final state
- Nemesis + landing:   asymmetric-partition (iptables drop one
                       direction). Landing evidence = iptables drop
                       counter goes 0 → 14,712 over the 30s window
                       AND raft log emits "leader-lost; starting
                       election" within 2s of injection.
- Ambiguous outcomes:  timeouts → timeout_marker=true, complete_ts
                       =null, treated as could-have-succeeded;
                       retries are separate ops sharing input
- Reduction plan:      if FAIL, bisect fault window + fix seed, then
                       classify SUT / harness / checker / environment
                       per references/test-case-reduction.md

مثال صف من تقرير النتائج

(يحمل قالب النتائج الكامل المراقب، أدلة تنفيذ المراقب، روابط القطع الأثرية، قسم كفاية مقابل خطة، وفارق الثقة — انظر skills/executing-distributed-system-tests/assets/findings-report-template.md.)

التثبيت (سطر واحد، أي وكيل)

الصق هذا في أي وكيل ترميز بالذكاء الاصطناعي (Claude Code، Codex، Copilot CLI، Cursor، Gemini، أو أي شيء آخر يقرأ Markdown ويشغل الصدفة):

Read https://raw.githubusercontent.com/shenli/distributed-system-testing/main/INSTALL.md
and follow the instructions to install and configure
distributed-testing-skills for this agent.

يجلب الوكيل INSTALL.md، ويستنسخ المستودع إلى ~/.local/share/distributed-testing-skills/، ويُدخل المهارات (روابط رمزية تحت ~/.claude/skills/ لـ Claude Code، كتلة مؤشر في ~/AGENTS.md للوكلاء الآخرين).

بعد ذلك، اطلب من أي وكيل على الجهاز "تصميم خطة اختبار لهذا النظام" أو "تنفيذ الخطة في X" وسيتبع سير عمل SKILL.md.

التحديث

الصق نفس السطر مرة أخرى. INSTALL.md عديم التأثير: إذا كان مسار التثبيت موجودًا، يقوم بـ git pull --ff-only؛ وإلا، يقوم بـ git clone. تشير الروابط الرمزية دائمًا إلى المحتوى المستنسخ لتحصل على الإصدار الجديد تلقائيًا. تستخدم كتلة المؤشر ~/AGENTS.md علامات HTML ويتم استبدالها نظيفًا في كل تشغيل — لا ازدواجية.

إذا كان لديك تعديلات محلية على المهارات المستنسخة، فسيفشل git pull --ff-only؛ سيتوقف الوكيل ويسأل قبل التخلص منها.

التثبيت اليدوي (إذا كنت تفضل رؤية ما يحدث)

git clone https://github.com/shenli/distributed-system-testing.git \
    ~/.local/share/distributed-testing-skills

# Claude Code: symlink under ~/.claude/skills/
mkdir -p ~/.claude/skills
ln -snf ~/.local/share/distributed-testing-skills/skills/designing-distributed-system-tests \
    ~/.claude/skills/designing-distributed-system-tests
ln -snf ~/.local/share/distributed-testing-skills/skills/executing-distributed-system-tests \
    ~/.claude/skills/executing-distributed-system-tests

# Codex / Copilot CLI / Cursor / Gemini / others: see INSTALL.md

كمكوّن إضافي لـ Claude Code (بديل)

يحمل المستودع بيان المكوّن الإضافي وبيان المتجر تحت .claude-plugin/، لذا يمكن لـ Claude Code تثبيته كمكوّن إضافي بدلاً من الربط الرمزي:

/plugin marketplace add shenli/distributed-system-testing
/plugin install distributed-testing-skills@distributed-testing-skills

يتم اكتشاف كلتا المهارتين تلقائيًا من skills/. تدفق INSTALL.md ذو السطر الواحد أعلاه يبقى المسار المستقل عن الوكيل (Codex، Copilot CLI، Cursor، Gemini).

الاستخدام

بمجرد تثبيت المهارات، لديك طريقتان لاستخدامهما:

طلب عادي (Claude Code مع تشغيل تلقائي):

Design a project-wide test plan for this codebase.

Execute the plan at ./testing-plans/<slug>.md against this codebase.

تلتقط أوصاف المهارات العبارات الطبيعية مثل "تصميم خطة اختبار"، "تنفيذ الخطة"، "تشغيل اختبارات الاستقرار"، "تصميم خطة التحقق من الإصدار"، إلخ.

لوضع معين، مسار مخرجات، أو وكيل غير تلقائي التشغيل، يحتوي USAGE.md على نصوص نسخ/لصق لكل سير عمل (تصميم وتنفيذ، في أوضاعهما المناسبة) بالإضافة إلى نصائح حول النطاق، وفحص البيئة، ونقاط التفتيش للتشغيل الطويل.

المهارتان

designing-distributed-system-tests

يتجول في المستودع، يستخرج الادعاءات التي يقدمها المنتج، يولد فرضيات مرتبطة بتلك الادعاءات، يختار تقنيات من الكتالوج، ويكتب خطة Markdown منظمة بحجة كفاية تغطية وبيان ثقة. بالنسبة للسيناريوهات الحساسة للاتساق، تملأ الخطة كتلة §7.M لكل سيناريو: النموذج قيد الاختبار، مخطط تاريخ العمليات، المدقق المسمى، الخصم + أدلة الهبوط، معالجة النتائج الغامضة، خطة التخفيض. التفاصيل: history-discipline.md.

وضعان: محدد النطاق بالتغيير (إيداع محدد أو طلب سحب) وعلى مستوى المشروع (خطة شاملة مع جرد للاختبارات الحالية وتحليل الفجوات).

executing-distributed-system-tests

يقرأ الخطة، يكتشف صندوق أدوات النظام قيد الاختبار، يفحص البيئة، وينفذ السيناريوهات مع انضباط نقاط التفتيش. لكل سيناريو: يلتقط أدلة هبوط الخطأ، يدير تدقيقات "الأخضر ولكن المكسور" و"المراقب الضعيف"، يعين حكمًا من تصنيف 10 حالات في verdict-taxonomy.md، ويصنف كل FAIL إلى SUT / harness / checker / environment قبل الحفظ. ينتج تقرير نتائج مع تقييم كفاية مقابل خطة وفارق ثقة.

وضعان: الوضع الافتراضي (قراءة فقط على النظام قيد الاختبار، أدوات اختبار مؤقتة تحت دليل الجلسة) ووضع المؤلف (يكتب هياكل السيناريوهات المعلنة في §7 من الخطة إلى النظام قيد الاختبار للمراجعة).

كتالوج التقنيات

ثمانية ملفات مرجعية مستخلصة من أدبيات المجال:

كل منها يتبع نفس الشكل: متى تستخدمه، ما يكتشفه جيدًا، ما يفوته، أدوات ملموسة، أوراق بحثية، إشارة تكلفة، قائمة مراجعة الخطة. يقرن فهرس الكتالوج الأعراض بالمراجع.

تخطيط المستودع

.
├── .claude-plugin/                             ← plugin + marketplace manifests
├── README.md                                   ← this file
├── INSTALL.md                                  ← idempotent install / update (paste-this)
├── USAGE.md                                    ← copy/paste prompts for every workflow
├── LICENSE
├── skills/
│   ├── designing-distributed-system-tests/
│   │   ├── SKILL.md                            ← the design workflow
│   │   ├── assets/plan-template.md             ← §0–§9 incl. gated §7.M
│   │   └── references/                         ← 8-file technique catalog + index,
│   │                                             common-distributed-systems-pitfalls,
│   │                                             history-discipline,
│   │                                             boundary-and-isolation-testing
│   └── executing-distributed-system-tests/
│       ├── SKILL.md                            ← the execute workflow
│       ├── assets/
│       │   ├── session-log-template.md
│       │   └── findings-report-template.md     ← 10-state verdicts + landing evidence
│       └── references/                         ← oracle-patterns (checker picker + 14
│                                                 patterns), fault-injection-howto
│                                                 (22-row nemesis taxonomy),
│                                                 test-case-reduction (with blame
│                                                 classification), green-but-broken-
│                                                 red-flags (incl. weak-oracle audit),
│                                                 finding-classification (TaxDC),
│                                                 verdict-taxonomy (10-state)
├── evals/                                      ← manual regression prompts (see evals/README.md)
├── verification/                               ← real local runs (gitignored — not in the repo)
└── specs/                                      ← original design spec (historical snapshot)

الحالة

مبكر لكنه تم تمرينه. تم تشغيل كلتا المهارتين ضد AgentDB (بيئة تشغيل وكيل موزعة بلغة Rust) من البداية إلى النهاية عدة مرات، مما أسفر عن ستة نتائج (واحد P0-مرشح مغلق الآن، اثنان P1 تم إصدارهما كطلب سحب، اثنان مفتوحان). تتطور نصوص المهارات مع تراكم خبرة الأدوات؛ توقع تحديثات طفيفة على ملفات SKILL.md والقوالب خلال التكرارات القليلة القادمة.

مخرجات الخطة الفعلية، أدلة الجلسات، وتقارير النتائج من تلك التشغيلات محفوظة محليًا تحت verification/ (دليل فرعي لكل تشغيل). هذا الدليل مُهمَل في git — القطع الأثرية الخام كبيرة ومحددة بالجهاز، لذا فهي ليست جزءًا من هذا المستودع. تشمل التشغيلات حتى الآن خطة محددة النطاق بالتغيير + تنفيذ لإيداع AgentDB fab7d9d (إعادة تشغيل إلحاق قابل للتكرار ومتين؛ خطة من 670 سطرًا مع 16 فرضية عبر جميع فئات الأعطال الثمانية)، تشغيلات الاتساق + استرداد الأعطال مع فحص الخطية، خطط على مستوى المشروع مع مصفوفة تغطية كاملة، وتشغيل متعدد المستويات بين الخوادم ضد LMCache.

يحتوي دليل evals/ على نصوص انحدار يدوية (ملفا evals.json منفصلان لمهارتي التصميم والتنفيذ) تُستخدم للتحقق من سلامة التغييرات السلوكية في نصوص SKILL.md بين التكرارات. تشير إلى نسخ النظام قيد الاختبار المحلية للمؤلف، لذا فهي نصوص لإعادة التشغيل يدويًا، وليست مجموعة اختبارات آلية — انظر evals/README.md.

شكر وتقدير

كتالوج التقنيات مستخلص من الكتالوج الشامل testing-distributed-systems لأندريه ساتارين. الأوراق البحثية الأساسية التي ترسخ الكتالوج تشمل:

• Yuan et al., "Simple Testing Can Prevent Most Critical Failures" (OSDI'14)
• Gunawi et al., "What Bugs Live in the Cloud?" (SoCC'14)
• Zheng et al., "Torturing Databases for Fun and Profit" (OSDI'14)
• Kingsbury & Alvaro, "Elle: Inferring Isolation Anomalies from Experimental Observations" (VLDB'20)
• Alfatafta et al., "Toward a Generic Fault Tolerance Technique for Partial Network Partitioning" (OSDI'20)
• Lou et al., "Understanding, Detecting and Localizing Partial Failures in Large System Software" (NSDI'20)
• Gao et al., "An Empirical Study on Crash Recovery Bugs in Large-Scale Distributed Systems" (FSE'18)
• Zhang et al., "Understanding and Detecting Software Upgrade Failures in Distributed Systems" (SOSP'21)
• Bornholt et al., "Using Lightweight Formal Methods to Validate a Key-Value Storage Node in Amazon S3" (SOSP'21)
• Newcombe et al., "How Amazon Web Services Uses Formal Methods" (CACM'15)

الرخصة

MIT.