Strategia di test

merql usa un modello di test guidato da un oracolo. Ogni scenario di test definisce un insieme noto di input (tre stati del database), un risultato atteso deterministico (l'oracolo) e confronta l'output effettivo della fusione con quello atteso. 32 scenari coprono fusioni senza conflitti, conflitti, risoluzione dell'identità, tipi di dati, scalabilità e casi limite.

# Run the full verification suite.
./bin/verify-all

I comandi di questa pagina si eseguono dopo composer install nella copia locale del repository merql. Gli script di sviluppo in bin/, il corpus scenarios/ e i test non fanno parte del pacchetto Composer. Le dipendenze di sviluppo includono PHPUnit 13, che richiede PHP 8.4 o successivo, anche se la libreria stessa funziona con PHP 8.2.

Test guidati da un oracolo

Non esiste uno strumento di riferimento che esegua una fusione di database a tre vie, quindi l'oracolo viene calcolato a partire da input noti anziché essere generato da uno strumento esterno. Ogni scenario ha un risultato atteso deterministico che può essere verificato tramite logica:

1. Configurazione -- crea tre stati del database (base, ours, theirs) con contenuti noti.
2. Oracolo -- calcola il risultato atteso della fusione a partire dagli input noti.
3. Effettivo -- esegue la fusione di merql sui tre stati.
4. Confronto -- il risultato effettivo deve corrispondere esattamente a quello atteso.

Known inputs (base, ours, theirs)
         |                    |
    Deterministic          merql merge
    computation
         |                    |
    Expected result       Actual result
         |                    |
         -----> Compare <-----
                  |
            Pass or Fail

Esecuzione dei test

Verifica completa

Lo script verify-all è il controllo finale. Esegue l'analisi statica, verifica gli standard di codifica, i test PHPUnit e la suite di regressione dell'oracolo:

./bin/verify-all

Tutto questo deve essere superato prima di considerare completo qualsiasi lavoro.

Suite di regressione dell'oracolo

Eseguire tutti i 32 scenari:

./bin/test-regression

Eseguire una singola categoria:

./bin/test-regression --category clean
./bin/test-regression --category conflict
./bin/test-regression --category identity

Le categorie corrispondono ai nomi delle directory in scenarios/: clean, conflict, identity, types, scale e edge. Una categoria sconosciuta stampa No scenarios found e termina con successo. È possibile ripetere --category per eseguire più categorie.

Lo script accetta anche --jobs, ma ignora il valore ed esegue gli scenari uno dopo l'altro (#5).

Eseguire con output minimo (solo esito positivo/negativo):

./bin/test-regression --fast

Singolo scenario

Testare uno scenario attraverso l'intera pipeline:

./bin/test-scenario column-level-clean

Singoli passaggi dell'oracolo

./bin/oracle column-level-clean    # Compute expected result
./bin/actual column-level-clean    # Run merql, capture output
./bin/compare column-level-clean   # Diff oracle vs actual

Test unitari

composer test:unit         # Isolated component tests
composer test:integration  # Integration tests (SQLite, plus MySQL when configured)
composer test              # All PHPUnit suites
composer test:oracle       # Oracle regression corpus (bin/test-regression)
composer verify            # analyse + cs + test + test:oracle

composer test esegue solo PHPUnit. La suite oracle PHPUnit punta a tests/Oracle, che contiene le classi del runner degli scenari ma nessun caso di test, quindi i 32 scenari vengono eseguiti solo tramite composer test:oracle, composer verify o ./bin/verify-all.

I test di integrazione MySQL vengono esclusi a meno che MERQL_MYSQL_HOST, MERQL_MYSQL_DATABASE e MERQL_MYSQL_USER (ed eventualmente anche MERQL_MYSQL_PASSWORD e MERQL_MYSQL_PORT) non puntino a un database di test.

Qualità del codice

composer cs            # PSR-12 coding standards check
composer cs:fix        # Auto-fix coding standards
composer analyse       # PHPStan level 10 static analysis

Categorie di scenari

clean (8 scenari)

Fusioni senza conflitti. Entrambi i lati possono modificare i dati, ma mai la stessa colonna della stessa riga.

conflict (6 scenari)

Scenari che devono generare conflitti.

identity (4 scenari)

Casi limite relativi all'identità delle righe.

types (6 scenari)

Gestione dei tipi di dati per tutti i tipi di colonna.

scale (4 scenari)

Prestazioni sotto carico.

edge (4 scenari)

Casi limite e condizioni al confine.

Struttura degli scenari

Ogni scenario è una directory in scenarios/<category>/<name>/ con una configurazione scenario.json:

{
    "name": "column-level-clean",
    "category": "clean",
    "description": "Both sides modify same row but different columns",
    "tables": ["test_posts"],
    "expectations": {
        "conflicts": 0,
        "operations": 3,
        "changeset_match": "exact",
        "merge_match": "exact",
        "sql_match": "semantic"
    }
}

Per gli scenari con conflitti, i conflitti attesi sono specificati nel dettaglio:

{
    "expectations": {
        "conflicts": 1,
        "conflict_details": [
            {
                "table": "test_posts",
                "primary_key": {"id": 42},
                "column": "title",
                "ours_value": "Welcome",
                "theirs_value": "Greetings"
            }
        ]
    }
}

La pipeline ScenarioRunner

ScenarioRunner::run() orchestra un singolo scenario:

1. OracleCapture::compute() crea tre snapshot dai dati JSON dello scenario ed esegue la fusione.
2. ScenarioComparator::compare() verifica il risultato della fusione rispetto ai valori attesi in scenario.json.
3. Restituisce l'esito positivo/negativo con un elenco di messaggi di errore.

use Merql\Tests\Oracle\ScenarioRunner;

$result = ScenarioRunner::run($scenario);
// ['name' => 'column-level-clean', 'pass' => true, 'failures' => []]

ScenarioRunner::runAll() esegue tutti gli scenari in sequenza:

$results = ScenarioRunner::runAll($scenarios);

Aggiungere un nuovo scenario

1. Create una directory: scenarios/<category>/<name>/.
2. Create scenario.json con i metadati e le aspettative dello scenario.
3. Definite i tre stati del database nella configurazione JSON: dati base, modifiche di ours, modifiche di theirs.
4. Eseguite lo scenario: ./bin/test-scenario <name>.
5. Verificate la suite completa: ./bin/verify-all.

Standard di qualità del codice

merql applica:

• PHPStan livello 10 -- analisi statica rigorosa senza eccezioni nella baseline.
• PSR-12 -- standard di codifica verificati da phpcs.
• Regressione dell'oracolo -- tutti i 32 scenari devono essere superati.
• Test unitari -- test isolati per ogni componente.

Lo script verify-all esegue tutti e quattro i controlli in sequenza. Non sono ammesse approvazioni parziali.

Integrazione continua

L'integrazione continua esegue gli standard di codifica, PHPStan, composer test, la suite di integrazione con MySQL 8.4 tramite mysqli, la copertura delle primitive di fusione e composer audit a ogni push e richiesta di pull verso main. Non esegue il corpus di regressione dell'oracolo (#6), quindi eseguite composer test:oracle o ./bin/verify-all in locale prima di affidarvi a una modifica.