tests/

Migration Engine integration tests

Heavy scenario tests (Spectra, real queues, DuckDB on disk). They are package main runners under pkg/tests/traversal/ and pkg/tests/copy/, not go test packages—run them with go run or the shell/PowerShell scripts next to each scenario.

Do not rely on go test ./... for these; use the scripts when you want full validation.

Layout

pkg/tests/
├── traversal/
│   ├── shared/           # setup.go, verify.go, test_utils.go, spectra.json, cleanup scripts
│   ├── normal/           # Happy-path traversal (main.go, run.sh / run.ps1)
│   ├── ephemeral/        # Ephemeral Spectra mode
│   ├── local/            # Local-focused runner
│   ├── resumption/       # Shutdown + resume (run_resumption_test.sh / .ps1)
│   └── retry_sweep/      # Mark retry, subtree behavior, re-run sweep (main.go, run.sh / run.ps1)
│       └── scripts_for_quick_tests/   # Optional Windows permission scripts + README
└── copy/
    ├── shared/           # setup, verify, cleanup scripts
    ├── normal/
    └── local/

There is no top-level pkg/tests/normal/ or pkg/tests/retry_sweep/—those paths live under traversal/.

Shared utilities (traversal/shared, copy/shared)

• Build migration.Config with Spectra adapters, worker counts, log address, verification options.
• SetupTest-style helpers control whether to wipe Spectra DB and migration DuckDB before a run (see each setup.go).

Scenarios (short)

Running

Examples:

./pkg/tests/traversal/normal/run.sh
./pkg/tests/traversal/retry_sweep/run.sh
./pkg/tests/traversal/resumption/run_resumption_test.sh

Windows: use the matching .ps1 files in the same folders.

Troubleshooting

• Ensure pkg/configs/spectra.json (or ephemeral variant under traversal/shared/) matches your Spectra instance.
• Remove stale *.db / *.yaml artifacts under pkg/tests if a scenario expects a clean start (see per-test cleanup scripts).
• If resumption does not suspend, adjust timing in run_resumption_test.ps1 so SIGINT arrives before traversal finishes.

Outdated terminology

Older docs sometimes referred to “level-sharded” buckets and join tables outside DuckDB. The engine stores state in DuckDB (src_nodes, dst_nodes, src_status_events, dst_status_events, stats tables). When reading older notes, map them to these tables and pkg/db/README.md.