Stratégia testovania

merql používa model testovania riadený referenčným výsledkom. Každý testovací scenár definuje známu množinu vstupov (tri stavy databázy), deterministický očakávaný výsledok (referenčný výsledok) a porovnáva s ním skutočný výstup zlúčenia. 32 scenárov pokrýva čisté zlúčenia, konflikty, určovanie identity, dátové typy, rozsah a okrajové prípady.

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

Príkazy na tejto stránke sa spúšťajú v kópii repozitára merql po composer install. Vývojové skripty v bin/, korpus scenarios/ a testy nie sú súčasťou balíka Composer. Medzi vývojové závislosti patrí PHPUnit 13, ktorý vyžaduje PHP 8.4 alebo novšiu verziu, hoci samotná knižnica funguje na PHP 8.2.

Testovanie riadené referenčným výsledkom

Neexistuje žiadny existujúci referenčný nástroj na trojcestné zlúčenie databáz, preto sa referenčný výsledok vypočítava zo známych vstupov, a nie pomocou externého nástroja. Každý scenár má deterministický očakávaný výsledok, ktorý možno overiť logicky:

1. Príprava -- vytvorte tri stavy databázy (base, ours, theirs) so známym obsahom.
2. Referenčný výsledok -- vypočítajte očakávaný výsledok zlúčenia zo známych vstupov.
3. Skutočný výsledok -- spustite zlúčenie troch stavov pomocou merql.
4. Porovnanie -- skutočný výsledok sa musí presne zhodovať s očakávaným.

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

Spúšťanie testov

Úplné overenie

Skript verify-all je záverečnou kontrolou. Spúšťa statickú analýzu, kontrolu štandardov kódovania, testy PHPUnit a regresnú sadu referenčných výsledkov:

./bin/verify-all

Pred dokončením akejkoľvek práce musí byť tento príkaz úspešný.

Regresná sada referenčných výsledkov

Spustite všetkých 32 scenárov:

./bin/test-regression

Spustite jednu kategóriu:

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

Kategórie sú názvy adresárov v scenarios/: clean, conflict, identity, types, scale a edge. Neznáma kategória vypíše No scenarios found a skončí úspešne. --category možno opakovať a spustiť tak viacero kategórií.

Skript prijíma aj --jobs, ale hodnotu ignoruje a spúšťa scenáre jeden po druhom (#5).

Spustite s minimálnym výstupom (iba úspech/neúspech):

./bin/test-regression --fast

Jeden scenár

Otestujte jeden scenár v rámci celého procesu:

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

Jednotlivé kroky referenčného výsledku

./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

Jednotkové testy

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 spúšťa iba PHPUnit. Sada oracle PHPUnit smeruje na tests/Oracle, ktorá obsahuje triedy spúšťača scenárov, ale žiadne testovacie prípady, takže 32 scenárov sa spúšťa iba cez composer test:oracle, composer verify alebo ./bin/verify-all.

Integračné testy MySQL sa preskočia, pokiaľ MERQL_MYSQL_HOST, MERQL_MYSQL_DATABASE a MERQL_MYSQL_USER (prípadne aj MERQL_MYSQL_PASSWORD a MERQL_MYSQL_PORT) neukazujú na testovaciu databázu.

Kvalita kódu

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

Kategórie scenárov

clean (8 scenárov)

Čisté zlúčenia bez konfliktov. Obe strany môžu meniť údaje, ale nikdy ten istý stĺpec v tom istom riadku.

conflict (6 scenárov)

Scenáre, pri ktorých musí dôjsť ku konfliktom.

identity (4 scenáre)

Okrajové prípady identity riadka.

types (6 scenárov)

Spracovanie všetkých typov stĺpcov.

scale (4 scenáre)

Výkon pri záťaži.

edge (4 scenáre)

Okrajové prípady a hraničné podmienky.

Štruktúra scenára

Každý scenár je adresár v scenarios/<category>/<name>/ s konfiguráciou 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"
    }
}

Pri konfliktných scenároch sú očakávané konflikty podrobne špecifikované:

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

Proces ScenarioRunner

ScenarioRunner::run() koordinuje jeden scenár:

1. OracleCapture::compute() vytvorí zo scenárových údajov JSON tri snímky a spustí zlúčenie.
2. ScenarioComparator::compare() overí výsledok zlúčenia podľa očakávaných hodnôt v scenario.json.
3. Vráti úspech/neúspech so zoznamom chybových hlásení.

use Merql\Tests\Oracle\ScenarioRunner;

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

ScenarioRunner::runAll() spúšťa všetky scenáre postupne:

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

Pridanie nového scenára

1. Vytvorte adresár: scenarios/<category>/<name>/.
2. Vytvorte scenario.json s metadátami a očakávanými výsledkami scenára.
3. V konfigurácii JSON definujte tri stavy databázy: základné údaje, zmeny ours a zmeny theirs.
4. Spustite scenár: ./bin/test-scenario <name>.
5. Overte celú sadu: ./bin/verify-all.

Štandardy kvality kódu

merql vyžaduje:

• Úroveň 10 PHPStan -- prísna statická analýza bez výnimiek v základnej konfigurácii.
• PSR-12 -- štandardy kódovania kontroluje phpcs.
• Regresné testy s referenčnými výsledkami -- všetkých 32 scenárov musí prejsť.
• Jednotkové testy -- izolované testy pre každý komponent.

Skript verify-all spúšťa všetky štyri kontroly postupne. Čiastočné schválenie sa neuznáva.

Priebežná integrácia

CI pri každom odoslaní zmien a každej požiadavke na zlúčenie do main spúšťa kontrolu štandardov kódovania, PHPStan, composer test, integračnú sadu proti MySQL 8.4 cez mysqli, pokrytie primitív zlúčenia a composer audit. Nespúšťa regresný korpus referenčných výsledkov (#6), preto pred tým, ako sa na zmenu spoľahnete, spustite lokálne composer test:oracle alebo ./bin/verify-all.