Compétences de test des systèmes distribués

Deux compétences pour les agents de codage IA qui conçoivent et exécutent des tests pilotés par les revendications (claim-driven) pour les systèmes distribués et avec état. Ensemble, elles produisent un plan de test Markdown structuré et un rapport de résultats avec des verdicts à 10 états et une classification explicite de la responsabilité SUT / harnais / vérificateur / environnement. Un relecteur lit les deux artefacts et décide s'il faut livrer ; rien d'autre n'a besoin d'être réexécuté.

Fonctionne avec Claude Code, Codex, Copilot CLI, Cursor, Gemini ou tout agent qui lit le Markdown et exécute des commandes shell. Les compétences sont de simples fichiers SKILL.md. L'agent les exécute ; le plan et le rapport de résultats sont la sortie.

Une compétence conçoit le plan. L'autre l'exécute. Un plan part des revendications du produit, génère des hypothèses liées à ces revendications et écrit des scénarios nommés d'après la revendication que chacun tente de falsifier. Pour les scénarios critiques en matière de cohérence, chaque scénario associe également un modèle abstrait (register | queue | log | lock | lease | ledger | …) à un schéma d'historique d'opérations, un vérificateur nommé et un nemesis avec des preuves d'atterrissage observables. Le plan se termine par un argument d'adéquation de la couverture et une déclaration de confiance prudente.

Pourquoi

L'approche par défaut pour tester les systèmes distribués et avec état — écrire quelques tests d'intégration et considérer le travail terminé — ne détecte qu'une petite fraction des bugs qui cassent réellement ces systèmes en production : partitions réseau partielles, concurrence non déterministe, reprise après crash, mise à niveau / retour arrière, idempotence sous rejeu, ordonnancement sensible au temps.

Ces compétences imposent un workflow affirmé qui s'appuie sur les connaissances durement acquises du domaine :

• Piloté par les revendications, pas par les tests. Partez de ce que le produit promet. Chaque scénario falsifie une revendication sous une panne. Un test nommé d'après sa revendication est plus difficile à affaiblir qu'un test nommé d'après sa configuration.
• L'adéquation de la couverture est un livrable. Le plan se termine par un argument démontrant que les scénarios choisis sont suffisants pour livrer, ainsi qu'une liste honnête de ce qui reste non vérifié.
• Réutilisez la boîte à outils du SUT lui-même. La compétence d'exécution découvre les tests existants, les runbooks et l'infrastructure d'injection de pannes avant d'inventer quoi que ce soit de nouveau.
• Modèle + historique + vérificateur, pas seulement le chaos. Pour les revendications de sécurité, de durabilité, d'idempotence, d'isolation, d'ordonnancement ou d'appartenance, chaque scénario déclare un modèle abstrait, un schéma d'historique d'opérations, un vérificateur nommé (linéarisabilité, sérialisabilité, cohérence de session, no-lost-ack, exactly-once, …) et la manière dont il traite les résultats ambigus (timeouts, commits inconnus, nouvelles tentatives). Le chaos plus un modèle et un vérificateur, pas le chaos seul.
• Aucun PASS silencieux. Chaque PASS cite les preuves d'exécution de l'oracle et le signal prouvant que la panne s'est réellement déclenchée. Les verdicts proviennent d'un ensemble de 10 états, de sorte que « le script de chaos s'est exécuté proprement » ne peut pas être lu comme « la revendication a survécu à la panne ». Chaque FAIL porte une étiquette de responsabilité SUT / harnais / vérificateur / environnement afin que les reproducteurs atteignent la bonne file d'attente.

Ce que vous obtenez

De bout en bout, les deux compétences produisent :

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

La structure du plan (un relecteur peut la lire et décider de livrer sans réexécuter les tests) :

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

Exemple de bloc §7.M (extrait d'un plan)

### 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

Exemple de ligne du rapport de résultats

(Le modèle complet du rapport de résultats comporte Oracle, les preuves d'exécution de l'oracle, les liens vers les artefacts, une section adéquation-vs-plan et un delta de confiance — voir skills/executing-distributed-system-tests/assets/findings-report-template.md.)

Installation (une ligne, n'importe quel agent)

Collez ceci dans n'importe quel agent de codage IA (Claude Code, Codex, Copilot CLI, Cursor, Gemini ou tout autre outil qui lit le Markdown et exécute des commandes 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.

L'agent récupère INSTALL.md, clone le dépôt vers ~/.local/share/distributed-testing-skills/ et branche les compétences (liens symboliques sous ~/.claude/skills/ pour Claude Code, un bloc pointeur dans ~/AGENTS.md pour les autres agents).

Ensuite, demandez à n'importe quel agent de la machine de « concevoir un plan de test pour ce système » ou « exécuter le plan à X » et il suivra le workflow SKILL.md.

Mise à jour

Recollez la même ligne de commande. INSTALL.md est idempotent : si le chemin d'installation existe, il fait git pull --ff-only ; sinon, il fait git clone. Les liens symboliques pointent toujours vers le contenu cloné et récupèrent donc automatiquement la nouvelle version. Le bloc pointeur ~/AGENTS.md utilise des marqueurs HTML et est remplacé proprement à chaque exécution — aucune duplication.

Si vous avez des modifications locales dans les compétences clonées, git pull --ff-only échouera ; l'agent s'arrêtera et demandera avant de les supprimer.

Installation manuelle (si vous préférez voir ce qui se passe)

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

En tant que plugin Claude Code (alternative)

Le dépôt contient un manifeste de plugin et un manifeste de marketplace sous .claude-plugin/, afin que Claude Code puisse l'installer comme plugin au lieu de créer des liens symboliques :

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

Les deux compétences sont automatiquement découvertes depuis skills/. Le flux INSTALL.md en une ligne ci-dessus reste le chemin agnostique à l'agent (Codex, Copilot CLI, Cursor, Gemini).

Utilisation

Une fois les compétences installées, vous avez deux façons de les piloter :

Demande informelle (Claude Code avec déclenchement automatique) :

Design a project-wide test plan for this codebase.

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

Les descriptions des compétences détectent les formulations naturelles comme « concevoir un plan de test », « exécuter le plan », « exécuter des tests de stabilité », « concevoir un plan de validation de version », etc.

Pour un mode spécifique, un chemin de sortie ou un agent sans déclenchement automatique, USAGE.md contient des invites copier-coller pour chaque workflow (conception et exécution, dans leurs modes respectifs) ainsi que des conseils sur le périmètre, le sondage de l'environnement et les points de contrôle des exécutions longues.

Les deux compétences

designing-distributed-system-tests

Parcourt le dépôt, extrait les revendications que le produit formule, génère des hypothèses liées à ces revendications, choisit des techniques dans le catalogue et rédige un plan Markdown structuré avec un argument d'adéquation de la couverture et une déclaration de confiance. Pour les scénarios critiques en matière de cohérence, le plan remplit un bloc §7.M par scénario : modèle testé, schéma d'historique d'opérations, vérificateur nommé, nemesis + preuves d'atterrissage, gestion des résultats ambigus, plan de réduction. Détails : history-discipline.md.

Deux modes : ciblé sur une modification (un commit ou une PR spécifique) et à l'échelle du projet (un plan holistique avec inventaire des tests existants et analyse des lacunes).

executing-distributed-system-tests

Lit le plan, découvre la boîte à outils du SUT, sonde l'environnement et exécute les scénarios avec une discipline de point de contrôle. Par scénario : capture les preuves d'atterrissage de la panne, exécute les audits « vert mais cassé » et « oracle faible », attribue un verdict issu de la taxonomie à 10 états dans verdict-taxonomy.md et classe chaque FAIL dans SUT / harnais / vérificateur / environnement avant de le consigner. Produit un rapport de résultats avec une évaluation adéquation-vs-plan et un delta de confiance.

Deux modes : par défaut (lecture seule sur le SUT, harnais éphémères dans le répertoire de session) et mode auteur (écrit dans le SUT les squelettes de scénarios déclarés dans la section §7 du plan, pour examen).

Catalogue de techniques

Huit fichiers de référence distillés à partir de la littérature du domaine :

Chacun suit la même forme : quand l'utiliser, ce qu'il détecte bien, ce qu'il ne détecte pas, outils concrets, articles, signal de coût, liste de contrôle du plan. L'index du catalogue associe les symptômes aux références.

Structure du dépôt

.
├── .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)

État

Encore jeune, mais déjà éprouvé. Les deux compétences ont été pilotées de bout en bout contre AgentDB (un runtime d'agents distribué en Rust) à plusieurs reprises, révélant six résultats (un candidat P0 désormais clos, deux P1 livrés via une PR, deux ouverts). Les corps des compétences évoluent à mesure que l'expérience des harnais s'accumule ; attendez-vous à des mises à jour mineures des SKILL.md et des modèles au cours des prochaines itérations.

Les vrais plans produits, répertoires de session et rapports de résultats de ces exécutions sont conservés localement sous verification/ (un sous-répertoire par exécution). Ce répertoire est gitignoré — les artefacts bruts sont volumineux et spécifiques à la machine, ils ne font donc pas partie de ce dépôt. Les exécutions à ce jour comprennent un plan ciblé sur une modification + une exécution pour le commit AgentDB fab7d9d (rejeu d'append idempotent durable ; un plan de 670 lignes avec 16 hypothèses couvrant les huit catégories de modes de panne), des exécutions cohérence + reprise après crash avec vérification de la linéarisabilité, des plans à l'échelle du projet avec une matrice de couverture complète, et une exécution multi-niveaux inter-serveurs contre LMCache.

Le répertoire evals/ contient des invites de régression manuelles (un evals.json séparé pour les compétences de conception et d'exécution) utilisées pour vérifier les changements de comportement des corps des SKILL.md entre les itérations. Elles référencent les checkouts locaux du SUT de l'auteur, ce sont donc des invites à réexécuter à la main, et non une suite automatisée — voir evals/README.md.

Remerciements

Le catalogue de techniques est distillé à partir du catalogue complet testing-distributed-systems d'Andrey Satarin. Les articles fondateurs qui ancrent le catalogue comprennent :

• 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)

Licence

MIT.