Competenze di Testing per Sistemi Distribuiti

Due competenze per agenti di codifica IA che progettano ed eseguono test guidati da rivendicazioni per sistemi distribuiti e stateful. Insieme producono un piano di test Markdown strutturato e un report dei risultati con verdetti a 10 stati e una classificazione esplicita della colpa SUT / harness / checker / ambiente. Un revisore legge i due artefatti e decide se rilasciare; non è necessario rieseguire nient'altro.

Funziona con Claude Code, Codex, Copilot CLI, Cursor, Gemini o qualsiasi agente che legga Markdown ed esegua shell. Le competenze sono semplici file SKILL.md. L'agente le esegue; il piano e il report dei risultati sono l'output.

Una competenza progetta il piano. L'altra lo esegue. Un piano parte dalle rivendicazioni del prodotto, genera ipotesi legate a tali rivendicazioni e scrive scenari nominati in base alla rivendicazione che ciascuno tenta di falsificare. Per scenari critici per la coerenza, ogni scenario associa anche un modello astratto (register | queue | log | lock | lease | ledger | …) a uno schema di cronologia delle operazioni, un checker nominato e un nemesi con prove di atterraggio osservabili. Il piano termina con un argomento di adeguatezza della copertura e una dichiarazione di confidenza conservativa.

Perché

L'impostazione predefinita per testare sistemi distribuiti e stateful — scrivere pochi test di integrazione e concludere — trova una piccola frazione dei bug che effettivamente rompono questi sistemi in produzione: partizioni di rete parziali, concorrenza non deterministica, crash-recovery, aggiornamento/rollback, idempotenza sotto replay, ordinamento sensibile al tempo.

Queste competenze impongono un flusso di lavoro opinabile che attinge dalla conoscenza duramente conquistata sul campo:

• Guidato da rivendicazioni, non da test. Si parte da ciò che il prodotto promette. Ogni scenario falsifica una rivendicazione sotto un guasto. Un test nominato in base alla sua rivendicazione è più difficile da indebolire di uno nominato in base alla sua configurazione.
• L'adeguatezza della copertura è un risultato. Il piano termina con un argomento che gli scenari scelti sono sufficienti per rilasciare, più un elenco onesto di ciò che rimane non verificato.
• Riutilizza gli strumenti del SUT. La competenza di esecuzione scopre test esistenti, runbook e scaffolding per iniezione di guasti prima di inventare qualcosa di nuovo.
• Modello + cronologia + checker, non solo caos. Per rivendicazioni di sicurezza, durabilità, idempotenza, isolamento, ordinamento o appartenenza, ogni scenario dichiara un modello astratto, uno schema di cronologia delle operazioni, un checker nominato (linearizzabilità, serializzabilità, coerenza di sessione, nessun ack perso, esattamente-una-volta, …) e come tratta gli esiti ambigui (timeout, commit sconosciuti, tentativi). Caos più un modello e un checker, non solo caos.
• Nessun passaggio silenzioso. Ogni PASS cita prove di esecuzione dell'oracolo e il segnale che prova che il guasto è effettivamente scattato. I verdetti provengono da un insieme di 10 stati, quindi "lo script del caos è stato eseguito correttamente" non può essere letto come "la rivendicazione è sopravvissuta al guasto." Ogni FAIL porta un'etichetta di colpa SUT / harness / checker / ambiente in modo che i riproduttori raggiungano la coda giusta.

Cosa ottieni

End-to-end, le due competenze producono:

docs/testing-plans/<slug>.md              ← piano con §0–§9 (vedi sotto)
test-sessions/<slug>/<UTC>/
  ├── session-log.md                       ← linea temporale + toolbox + sonda ambiente
  ├── logs/                                ← stdout/stderr per scenario
  ├── metrics/                             ← snapshot metriche
  ├── artifacts/                           ← harness temporanei, dump
  └── findings/
      ├── <scenario>.md                    ← verdetto per scenario (scritto durante l'esecuzione)
      └── report.md                        ← riepilogo + adeguatezza + delta confidenza

La struttura del piano (un revisore può leggerlo e decidere se rilasciare senza rieseguire i test):

0. Riepilogo architetturale     — sistema come realmente esiste
1. Ambito
1b. Rivendicazioni sotto test    — la spina dorsale
1c. Rivendicazioni mancanti scoperte  — deriva documentazione ↔ codice
2. Modello SUT
3. Inventario test esistenti    — ciò che è già coperto
4. Ipotesi modalità di guasto    — legate agli ID rivendicazione
5. Matrice di copertura          — rivendicazione × ipotesi
6. Selezione delle tecniche     — dal catalogo
6b. Requisiti ambientali
7. Scenari                      — ciascuno nominato in base alla rivendicazione, con
                                  File test target + Scheletro
   7.M Disciplina modello /     — obbligatorio quando lo scenario falsifica
       cronologia / checker       una rivendicazione in {sicurezza, durabilità,
                                  idempotenza, isolamento, ordinamento,
                                  appartenenza}: modello sotto test, schema
                                  cronologia operazioni, checker nominato,
                                  nemesi + prove di atterraggio, gestione esito
                                  ambiguo, piano di riduzione (colpa SUT/harness/checker/ambiente)
7b. Argomento di adeguatezza copertura — perché questi test sono sufficienti
7c. Incertezza residua          — ciò che rimane non verificato e perché ok
7d. Dichiarazione di confidenza — il verdetto del revisore
8. Cosa questo piano NON copre
9. Domande aperte / followup

Esempio blocco §7.M (estratto da un piano)

### Scenario S3: linearizable_append_under_partition
- Falsifies if it FAILs: C1 (ogni append riconosciuta è durevole
  e linearizzabile), C5 (elezione leader completata entro 5s)
- Carico: 8 client, 70% append / 30% lettura, 5min, skew chiavi zipf
- Guasti: partizione asimmetrica che isola il leader corrente a T+60s
  per 30s
- Oracolo: linearizzabilità tramite Porcupine su cronologie per chiave

§7.M (disciplina modello / cronologia / checker)
- Modello sotto test:    log
- Cronologia operazioni: schema predefinito a 11 campi (id op, id processo,
                       ts invocazione/completamento, tipo op, chiave, input,
                       output, errore, marcatore timeout, nodo visto,
                       epoca guasto). Registrato in-process + audit lato server.
- Checker:               linearizzabilità (Porcupine) per chiave, poi
                         nessun ack perso rispetto allo stato finale
- Nemesi + atterraggio:   partizione asimmetrica (iptables drop una
                         direzione). Prova di atterraggio = contatore drop iptables
                         va da 0 a 14.712 nell'arco di 30 secondi
                         E il log raft emette "leader-lost; starting
                         election" entro 2 secondi dall'iniezione.
- Esiti ambigui:          timeout → timeout_marker=true, complete_ts
                         =null, trattato come potrebbe-essere-riuscito;
                         i tentativi sono op separate che condividono l'input
- Piano di riduzione:     se FAIL, biseca finestra guasto + fissa seme, quindi
                         classifica SUT / harness / checker / ambiente
                         per references/test-case-reduction.md

Esempio riga report dei risultati

(Il template completo dei risultati porta Oracolo, prove di esecuzione dell'Oracolo, link agli artefatti, una sezione adeguatezza-vs-piano e un delta confidenza — vedi skills/executing-distributed-system-tests/assets/findings-report-template.md.)

Installazione (una riga, qualsiasi agente)

Incolla questo in qualsiasi agente di codifica IA (Claude Code, Codex, Copilot CLI, Cursor, Gemini o qualsiasi altra cosa che legga Markdown ed esegua 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'agente recupera INSTALL.md, clona il repository in ~/.local/share/distributed-testing-skills/, e collega le competenze (symlink in ~/.claude/skills/ per Claude Code, un blocco puntatore in ~/AGENTS.md per altri agenti).

Dopo, è sufficiente chiedere a qualsiasi agente sulla macchina di "progettare un piano di test per questo sistema" o "eseguire il piano in X" e seguirà il flusso di lavoro SKILL.md.

Aggiornamento

Incolla di nuovo la stessa riga. INSTALL.md è idempotente: se il percorso di installazione esiste, esegue git pull --ff-only; altrimenti, esegue git clone. I symlink puntano sempre al contenuto clonato, quindi raccolgono automaticamente la nuova versione. Il blocco puntatore ~/AGENTS.md utilizza marcatori HTML e viene sostituito pulitamente a ogni esecuzione — nessuna duplicazione.

Se hai modifiche locali alle competenze clonate, git pull --ff-only fallirà; l'agente si fermerà e chiederà prima di scartarle.

Installazione manuale (se preferisci vedere cosa succede)

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

# Claude Code: symlink in ~/.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 / altri: vedi INSTALL.md

Come plugin di Claude Code (alternativa)

Il repository contiene un manifest del plugin e un manifest del marketplace in .claude-plugin/, quindi Claude Code può installarlo come plugin invece del symlink:

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

Entrambe le competenze vengono scoperte automaticamente da skills/. Il flusso a riga singola INSTALL.md rimane il percorso agnostico (Codex, Copilot CLI, Cursor, Gemini).

Utilizzo

Una volta installate le competenze, hai due modi per guidarle:

Richiesta informale (Claude Code con attivazione automatica):

Design a project-wide test plan for this codebase.

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

Le descrizioni delle competenze catturano frasi naturali come "progetta un piano di test", "esegui il piano", "esegui test di stabilità", "progetta un piano di validazione del rilascio", ecc.

Per una modalità specifica, percorso di output o un agente senza attivazione automatica, USAGE.md contiene prompt copia/incolla per ogni flusso di lavoro (progetta ed esegui, nelle rispettive modalità) più suggerimenti su ambito, sondaggio ambiente e checkpoint per esecuzioni lunghe.

Le due competenze

designing-distributed-system-tests

Analizza il repository, estrae le rivendicazioni che il prodotto fa, genera ipotesi legate a tali rivendicazioni, seleziona tecniche dal catalogo e scrive un piano Markdown strutturato con un argomento di adeguatezza della copertura e una dichiarazione di confidenza. Per gli scenari critici per la coerenza, il piano riempie un blocco §7.M per scenario: modello sotto test, schema cronologia operazioni, checker nominato, nemesi + prove di atterraggio, gestione esito ambiguo, piano di riduzione. Dettagli: history-discipline.md.

Due modalità: con ambito modifica (un commit o PR specifico) e a livello di progetto (un piano olistico con inventario test esistenti e analisi delle lacune).

executing-distributed-system-tests

Legge il piano, scopre la toolbox del SUT, sonda l'ambiente ed esegue gli scenari con disciplina di checkpoint. Per scenario: cattura le prove di atterraggio per il guasto, esegue gli audit green-ma-rotto e oracolo-debole, assegna un verdetto dalla tassonomia a 10 stati in verdict-taxonomy.md, e classifica ogni FAIL in SUT / harness / checker / ambiente prima di archiviarlo. Produce un report dei risultati con valutazione adeguatezza-vs-piano e delta confidenza.

Due modalità: predefinita (sola lettura sul SUT, harness temporanei sotto la directory di sessione) e modalità autore (scrive scheletri degli scenari dichiarati nel §7 del piano nel SUT per la revisione).

Catalogo tecniche

Otto file di riferimento distillati dalla letteratura del settore:

Ciascuno segue la stessa forma: quando usarlo, cosa rileva bene, cosa perde, strumenti concreti, articoli, segnale di costo, lista di controllo del piano. L'indice del catalogo abbina sintomi ai riferimenti.

Struttura del repository

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

Stato

Early ma esercitato. Entrambe le competenze sono state guidate contro AgentDB (un runtime agente distribuito in Rust) end-to-end più volte, portando alla luce sei risultati (un P0-candidato ora chiuso, due P1 inviati come PR, due aperti). I corpi delle competenze evolvono man mano che l'esperienza con gli harness si accumula; aspettati aggiornamenti minori ai file SKILL.md e ai template nelle prossime iterazioni.

Piani di test reali, directory di sessione e report dei risultati da quelle esecuzioni sono mantenuti localmente in verification/ (una sottodirectory per esecuzione). Quella directory è gitignored — gli artefatti grezzi sono grandi e specifici della macchina, quindi non fanno parte di questo repo. Le esecuzioni fino ad oggi includono un piano con ambito modifica + esecuzione per AgentDB commit fab7d9d (replay append idempotente durevole; un piano di 670 righe con 16 ipotesi in tutte le otto categorie di modalità di guasto), esecuzioni di coerenza + crash-recovery con controllo di linearizzabilità, piani a livello di progetto con una matrice di copertura completa e un'esecuzione cross-server multi-tier contro LMCache.

La directory evals/ contiene prompt di regressione manuale (evals.json separati per le competenze di progettazione ed esecuzione) utilizzati per verificare la sanità dei cambiamenti comportamentali ai corpi dei file SKILL.md tra iterazioni. Fanno riferimento ai checkout locali del SUT dell'autore, quindi sono prompt da rieseguire a mano, non una suite automatizzata — vedi evals/README.md.

Riconoscimenti

Il catalogo tecniche è distillato dal catalogo completo testing-distributed-systems di Andrey Satarin. Articoli fondamentali che ancorano il catalogo includono:

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

Licenza

MIT.