वितरित प्रणाली परीक्षण कौशल

AI कोडिंग एजेंटों के लिए दो कौशल जो वितरित और स्टेटफुल प्रणालियों के लिए दावा-संचालित परीक्षण डिज़ाइन करते हैं और चलाते हैं। साथ में वे एक संरचित Markdown परीक्षण योजना और एक निष्कर्ष रिपोर्ट तैयार करते हैं, जिसमें 10-अवस्था वाले निर्णय और स्पष्ट SUT / हार्नेस / चेकर / परिवेश दोष वर्गीकरण होता है। एक समीक्षक दोनों आर्टिफैक्ट पढ़ता है और तय करता है कि शिप करना है या नहीं; कुछ और पुनः चलाने की आवश्यकता नहीं है।

Claude Code, Codex, Copilot CLI, Cursor, Gemini, या किसी भी ऐसे एजेंट के साथ काम करता है जो Markdown पढ़ता है और shell चलाता है। ये कौशल साधारण SKILL.md फ़ाइलें हैं। एजेंट उन्हें निष्पादित करता है; योजना और निष्कर्ष रिपोर्ट ही आउटपुट हैं।

एक कौशल योजना डिज़ाइन करता है। दूसरा उसे चलाता है। एक योजना उत्पाद के दावों से शुरू होती है, उन दावों से जुड़ी परिकल्पनाएँ उत्पन्न करती है, और ऐसे परिदृश्य लिखती है जिनका नाम उस दावे के नाम पर होता है जिसे प्रत्येक परिदृश्य गलत सिद्ध करने का प्रयास करता है। संगति-महत्वपूर्ण परिदृश्यों के लिए, प्रत्येक परिदृश्य एक अमूर्त मॉडल (register | queue | log | lock | lease | ledger | …) को एक ऑपरेशन-हिस्ट्री स्कीमा, एक नामित चेकर, और प्रेक्षणीय लैंडिंग साक्ष्य वाले नेमेसिस से भी बाँधता है। योजना कवरेज पर्याप्तता तर्क और एक रूढ़िवादी विश्वास कथन के साथ समाप्त होती है।

क्यों

वितरित और स्टेटफुल प्रणालियों के परीक्षण के लिए डिफ़ॉल्ट तरीका — कुछ इंटीग्रेशन टेस्ट लिखना और काम ख़त्म मान लेना — उन बगों का एक छोटा सा अंश पकड़ता है जो वास्तव में इन प्रणालियों को प्रोडक्शन में तोड़ देते हैं: आंशिक नेटवर्क विभाजन, गैर-नियतात्मक समवर्तीता, क्रैश-रिकवरी, अपग्रेड/रोलबैक, रीप्ले के अंतर्गत आइडेम्पोटेंसी, समय-संवेदनशील क्रमबद्धता।

ये कौशल एक विचार-आधारित वर्कफ़्लो लागू करते हैं जो क्षेत्र के कठिन-अर्जित ज्ञान से लिया गया है:

• दावा-संचालित, परीक्षण-संचालित नहीं। उससे शुरू करें जो उत्पाद वादा करता है। प्रत्येक परिदृश्य एक दोष के अंतर्गत एक दावे को गलत सिद्ध करता है। अपने दावे के नाम पर रखा गया परीक्षण अपने सेटअप के नाम पर रखे परीक्षण की तुलना में कमज़ोर किया जाना कठिन होता है।
• कवरेज पर्याप्तता एक डिलिवरेबल है। योजना इस तर्क के साथ समाप्त होती है कि चुने गए परिदृश्य शिप करने के लिए पर्याप्त हैं, साथ ही उन चीज़ों की एक ईमानदार सूची जो असत्यापित रहती हैं।
• SUT के अपने टूलबॉक्स का पुनः उपयोग करें। निष्पादन कौशल कुछ भी नया आविष्कार करने से पहले मौजूदा परीक्षणों, रनबुकों और दोष-इंजेक्शन स्कैफोल्डिंग की खोज करता है।
• मॉडल + हिस्ट्री + चेकर, केवल कैओस नहीं। सुरक्षा, स्थायित्व, आइडेम्पोटेंसी, अलगाव, क्रमबद्धता, या सदस्यता दावों के लिए, प्रत्येक परिदृश्य एक अमूर्त मॉडल, एक ऑपरेशन-हिस्ट्री स्कीमा, एक नामित चेकर (linearizability, serializability, session-consistency, no-lost-ack, exactly-once, …) घोषित करता है, और साथ ही यह कि वह अस्पष्ट परिणामों (टाइमआउट, अज्ञात कमिट, रीट्राइज़) के साथ कैसे व्यवहार करता है। कैओस प्लस मॉडल और चेकर, केवल कैओस नहीं।
• कोई मौन पास नहीं। प्रत्येक PASS ओरेकल निष्पादन साक्ष्य और उस संकेत का हवाला देता है जो सिद्ध करता है कि दोष वास्तव में सक्रिय हुआ। निर्णय 10-अवस्था वाले समुच्चय से आते हैं, इसलिए "कैओस स्क्रिप्ट सफाई से चली" को "दावा दोष से बच गया" के रूप में नहीं पढ़ा जा सकता। प्रत्येक FAIL पर SUT / हार्नेस / चेकर / परिवेश दोष टैग होता है ताकि रिप्रोड्यूसर सही कतार तक पहुँचें।

आपको क्या मिलता है

एंड-टू-एंड, दोनों कौशल यह उत्पन्न करते हैं:

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

निष्कर्ष-रिपोर्ट पंक्ति का उदाहरण

(पूर्ण निष्कर्ष टेम्पलेट में Oracle, Oracle निष्पादन साक्ष्य, आर्टिफैक्ट लिंक, पर्याप्तता-बनाम-योजना अनुभाग और विश्वास डेल्टा होता है — देखें skills/executing-distributed-system-tests/assets/findings-report-template.md।)

इंस्टॉल (एक पंक्ति, कोई भी एजेंट)

इसे किसी भी AI कोडिंग एजेंट (Claude Code, Codex, Copilot CLI, Cursor, Gemini, या कुछ और जो Markdown पढ़ता है और shell चलाता है) पर चिपकाएँ:

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 Code के लिए ~/.claude/skills/ के अंतर्गत सिमलिंक, अन्य एजेंटों के लिए ~/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.

कौशल विवरण "design a test plan", "execute the plan", "run stability tests", "design a release validation plan" आदि जैसे स्वाभाविक वाक्यांशों को पहचान लेते हैं।

किसी विशिष्ट मोड, आउटपुट पथ, या गैर-ऑटो-ट्रिगर एजेंट के लिए, USAGE.md में प्रत्येक वर्कफ़्लो के लिए कॉपी/पेस्ट प्रॉम्प्ट हैं (डिज़ाइन और निष्पादन, उनके संबंधित मोड में) साथ ही दायरे, env जाँच और लंबे रन चेकपॉइंटिंग के सुझाव भी।

दो कौशल

designing-distributed-system-tests

रिपो का सर्वेक्षण करता है, उत्पाद द्वारा किए गए दावों को निकालता है, उन दावों से जुड़ी परिकल्पनाएँ उत्पन्न करता है, कैटलॉग से तकनीकें चुनता है, और कवरेज पर्याप्तता तर्क तथा विश्वास कथन के साथ एक संरचित Markdown योजना लिखता है। संगति-महत्वपूर्ण परिदृश्यों के लिए, योजना प्रत्येक परिदृश्य के लिए एक §7.M ब्लॉक भरती है: परीक्षणाधीन मॉडल, ऑपरेशन-हिस्ट्री स्कीमा, नामित चेकर, नेमेसिस + लैंडिंग साक्ष्य, अस्पष्ट-परिणाम से निपटना, न्यूनीकरण योजना। विवरण: history-discipline.md।

दो मोड: change-scoped (एक विशिष्ट कमिट या PR) और project-wide (मौजूदा-परीक्षण सूची और अंतराल विश्लेषण के साथ एक समग्र योजना)।

executing-distributed-system-tests

योजना पढ़ता है, SUT के टूलबॉक्स की खोज करता है, परिवेश की जाँच करता है, और चेकपॉइंट अनुशासन के साथ परिदृश्य चलाता है। प्रति परिदृश्य: दोष के लिए लैंडिंग साक्ष्य कैप्चर करता है, ग्रीन-बट-ब्रोकन और कमज़ोर-ओरेकल ऑडिट चलाता है, verdict-taxonomy.md में 10-अवस्था वाली वर्गीकरण प्रणाली से एक निर्णय निर्दिष्ट करता है, और दर्ज करने से पहले प्रत्येक FAIL को SUT / हार्नेस / चेकर / परिवेश में वर्गीकृत करता है। पर्याप्तता-बनाम-योजना मूल्यांकन और विश्वास डेल्टा के साथ एक निष्कर्ष रिपोर्ट तैयार करता है।

दो मोड: डिफ़ॉल्ट (SUT पर केवल-पठनीय, सत्र निर्देशिका के अंतर्गत अस्थायी हार्नेस) और author मोड (समीक्षा के लिए योजना के §7 में घोषित परिदृश्य स्केलेटन को SUT में लिखता है)।

तकनीक कैटलॉग

क्षेत्र के साहित्य से संक्षेपित आठ संदर्भ फ़ाइलें:

प्रत्येक एक ही ढाँचे का अनुसरण करता है: इसे कब उपयोग करें, यह क्या अच्छी तरह पहचानता है, यह क्या चूकता है, ठोस उपकरण, शोधपत्र, लागत संकेत, योजना जाँच-सूची। कैटलॉग इंडेक्स लक्षणों को संदर्भों से जोड़ता है।

रिपो संरचना

.
├── .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 एक PR के रूप में शिप, दो खुले)। कौशल निकाय हार्नेस अनुभव बढ़ने के साथ विकसित होते हैं; अगले कुछ पुनरावृत्तियों में SKILL.mds और टेम्पलेट्स में मामूली अपडेट की उम्मीद करें।

उन रनों के वास्तविक योजना आउटपुट, सत्र निर्देशिकाएँ और निष्कर्ष रिपोर्ट स्थानीय रूप से verification/ के अंतर्गत रखी जाती हैं (प्रति रन एक उपनिर्देशिका)। वह निर्देशिका gitignored है — कच्चे आर्टिफैक्ट बड़े और मशीन-विशिष्ट होते हैं, इसलिए वे इस रिपो का हिस्सा नहीं हैं। अब तक के रनों में AgentDB कमिट fab7d9d के लिए एक change-scoped योजना + निष्पादन (टिकाऊ आइडेम्पोटेंट ऐपेंड रीप्ले; सभी आठ विफलता-मोड श्रेणियों में 16 परिकल्पनाओं वाली 670-पंक्ति योजना), linearizability जाँच के साथ संगति + क्रैश-रिकवरी रन, पूर्ण कवरेज मैट्रिक्स वाली project-wide योजनाएँ, और LMCache के विरुद्ध एक क्रॉस-सर्वर मल्टी-टियर रन शामिल हैं।

evals/ निर्देशिका में मैन्युअल रिग्रेशन प्रॉम्प्ट हैं (डिज़ाइन और निष्पादन कौशल के लिए अलग-अलग evals.json) जिनका उपयोग पुनरावृत्तियों के बीच SKILL.md निकायों में व्यवहारिक परिवर्तनों की सत्यता-जाँच के लिए किया जाता है। वे लेखक के स्थानीय SUT चेकआउट का संदर्भ देते हैं, इसलिए वे हाथ से पुनः चलाने के प्रॉम्प्ट हैं, कोई स्वचालित सूट नहीं — देखें evals/README.md।

आभार

तकनीक कैटलॉग Andrey Satarin के व्यापक 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.