Tesztelési stratégia

A merql oracle-alapú tesztelési modellt használ. Minden tesztforgatókönyv meghatározott bemeneteket (három adatbázis-állapotot), determinisztikus elvárt eredményt (az oracle-t) határoz meg, majd ezt veti össze a tényleges merge kimenetével. A 32 forgatókönyv tiszta merge-eket, ütközéseket, azonosítási feloldást, adattípusokat, méretezhetőséget és szélső eseteket fed le.

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

Az ezen az oldalon szereplő parancsok a merql repository egy checkoutjából futtathatók, a composer install után. A bin/ fejlesztői szkriptek, a scenarios/ korpusz és a tesztek nem részei a Composer csomagnak. A fejlesztői függőségek között szerepel a PHPUnit 13, amelyhez PHP 8.4-es vagy újabb verziója szükséges, noha maga a könyvtár PHP 8.2-n fut.

Oracle-alapú tesztelés

Nincs olyan meglévő referenciaeszköz, amely háromutas adatbázis-merge-et végezne, ezért az oracle ismert bemenetekből, nem pedig külső eszközből származik. Minden forgatókönyvhöz tartozik egy determinisztikus elvárt eredmény, amely logikai úton ellenőrizhető:

1. Előkészítés -- hozzon létre három adatbázis-állapotot (base, ours, theirs) ismert tartalommal.
2. Oracle -- számítsa ki az elvárt merge-eredményt az ismert bemenetekből.
3. Tényleges futtatás -- futtassa a merql merge műveletét a három állapoton.
4. Összehasonlítás -- a tényleges eredménynek pontosan egyeznie kell az elvárttal.

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

Tesztek futtatása

Teljes ellenőrzés

A verify-all szkript az utolsó ellenőrzési pont. Statikus elemzést, kódolási szabványok ellenőrzését, PHPUnit teszteket és oracle-regressziós tesztcsomagot futtat:

./bin/verify-all

Ezt teljesíteni kell, mielőtt bármely munka befejezettnek tekinthető.

Oracle-regressziós tesztcsomag

Futtassa mind a 32 forgatókönyvet:

./bin/test-regression

Futtasson egyetlen kategóriát:

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

A kategóriák a scenarios/ alatti könyvtárnevek: clean, conflict, identity, types, scale és edge. Ismeretlen kategória esetén kiírja a No scenarios found értéket, majd sikeresen kilép. A --category többször is megadható több kategória futtatásához.

A szkript a --jobs argumentumot is elfogadja, de az értékét figyelmen kívül hagyja, és egymás után futtatja a forgatókönyveket (#5).

Futtatás minimális kimenettel (csak sikeres/sikertelen):

./bin/test-regression --fast

Egyetlen forgatókönyv

Teszteljen egy forgatókönyvet a teljes folyamaton keresztül:

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

Egyedi oracle-lépések

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

Egységtesztek

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

A composer test csak a PHPUnit teszteket futtatja. A oracle PHPUnit tesztcsomag a tests/Oracle helyre mutat, amely a forgatókönyv-futtató osztályokat tartalmazza, de teszteseteket nem. Ezért a 32 forgatókönyv csak a composer test:oracle, a composer verify vagy a ./bin/verify-all használatával fut.

A MySQL integrációs tesztek kimaradnak, kivéve ha a MERQL_MYSQL_HOST, a MERQL_MYSQL_DATABASE és a MERQL_MYSQL_USER (valamint opcionálisan a MERQL_MYSQL_PASSWORD és a MERQL_MYSQL_PORT) egy tesztadatbázisra mutat.

Kódminőség

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

Forgatókönyv-kategóriák

clean (8 forgatókönyv)

Tiszta merge-ek ütközések nélkül. Mindkét oldal módosíthat adatokat, de ugyanannak a sornak ugyanazt az oszlopát soha.

conflict (6 forgatókönyv)

Ütközést okozó forgatókönyvek.

identity (4 forgatókönyv)

A sorazonosság szélső esetei.

types (6 forgatókönyv)

Adattípusok kezelése az összes oszloptípus esetén.

scale (4 forgatókönyv)

Terhelés alatti teljesítmény.

edge (4 forgatókönyv)

Szélső esetek és határfeltételek.

A forgatókönyvek felépítése

Minden forgatókönyv egy könyvtár a scenarios/<category>/<name>/ alatt, egy scenario.json konfigurációval:

{
    "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"
    }
}

Ütközési forgatókönyvek esetén a várt ütközések részletesen meg vannak adva:

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

A ScenarioRunner folyamatlépései

A ScenarioRunner::run() egyetlen forgatókönyvet vezényel le:

1. A OracleCapture::compute() létrehozza a három pillanatképet a forgatókönyv JSON adataiból, majd végrehajtja az összevonást.
2. A ScenarioComparator::compare() összeveti az összevonás eredményét a scenario.json fájlban megadott várt értékekkel.
3. Sikeres vagy sikertelen eredményt ad vissza a hibaüzenetek listájával.

use Merql\Tests\Oracle\ScenarioRunner;

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

A ScenarioRunner::runAll() sorban lefuttatja az összes forgatókönyvet:

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

Új forgatókönyv hozzáadása

1. Hozzon létre egy könyvtárat: scenarios/<category>/<name>/.
2. Hozza létre a scenario.json fájlt a forgatókönyv metaadataival és elvárásaival.
3. Határozza meg a három adatbázis-állapotot a JSON konfigurációban: alapadatok, a saját módosításaink és az ő módosításaik.
4. Futtassa a forgatókönyvet: ./bin/test-scenario <name>.
5. Ellenőrizze a teljes tesztcsomagot: ./bin/verify-all.

Kódminőségi szabványok

A merql az alábbiakat írja elő:

• PHPStan 10-es szint -- szigorú statikus elemzés, kivétel nélküli alapszabállyal.
• PSR-12 -- a kódolási szabványok ellenőrzését a phpcs végzi.
• Oracle-regresszió -- mind a 32 forgatókönyvnek sikeresen kell lefutnia.
• Egységtesztek -- minden komponens elszigetelt tesztjei.

A verify-all parancsfájl egymás után futtatja mind a négy ellenőrzést. Részleges jóváhagyás nem fogadható el.

Folyamatos integráció

A CI minden, a main-re irányuló push és pull request esetén lefuttatja a kódolási szabványok ellenőrzését, a PHPStan-t, a composer test-t, az integrációs tesztcsomagot a MySQL 8.4-es verziójával, mysqli-n keresztül, az összevonási alapműveletek lefedettségi ellenőrzését, valamint a composer audit-t. Az oracle-regressziós tesztkorpuszt nem futtatja (#6), ezért a változtatásra hagyatkozás előtt futtassa helyben a composer test:oracle-t vagy a ./bin/verify-all-t.