cmd/litestream-test/scripts/README.md
Comprehensive test scripts for validating Litestream functionality across various scenarios. These scripts use the litestream-test CLI tool to orchestrate complex testing scenarios.
go build -o bin/litestream ./cmd/litestream
go build -o bin/litestream-test ./cmd/litestream-test
./cmd/litestream-test/scripts/verify-test-setup.sh
Note: Some tests have been migrated to Go integration tests in
tests/integration/. See tests/integration/README.md for the Go-based test suite.
| Script | Purpose | Duration | Status |
|---|---|---|---|
| verify-test-setup.sh | Environment validation | ~5s | ✅ Stable |
| reproduce-critical-bug.sh | Checkpoint during downtime bug | ~2min | 🐛 Reproduces #752 |
| test-754-s3-scenarios.sh | Issue #754 S3 vs file replication | ~10min | 🐛 Tests #754 |
| test-754-restore-focus.sh | Issue #754 restore focus | ~5min | 🐛 Tests #754 |
| test-simple-754-reproduction.sh | Minimal #754 reproduction | ~3min | 🐛 Tests #754 |
| test-v0.5-flag-reproduction.sh | ltx v0.5.0 flag issue | ~5min | 🐛 Tests #754 |
| test-v0.5-restart-scenarios.sh | v0.5 restart scenarios | ~5min | 🐛 Tests #754 |
| test-format-isolation.sh | Format version isolation | ~3min | ✅ Stable |
| test-quick-format-check.sh | Quick format validation | ~30s | ✅ Stable |
| test-upgrade-v0.3-to-v0.5.sh | v0.3 to v0.5 upgrade | ~10min | ✅ Stable |
| test-upgrade-large-db.sh | Large database upgrade | ~15min | ✅ Stable |
| test-massive-upgrade.sh | Massive database upgrade | ~20min | ✅ Stable |
| test-s3-retention-cleanup.sh | Basic S3 retention | ~8min | ✅ Stable |
| test-s3-retention-small-db.sh | S3 retention 50MB | ~8min | ✅ Stable |
| test-s3-retention-large-db.sh | S3 retention 1.5GB | ~20min | ✅ Stable |
| test-s3-retention-comprehensive.sh | Full S3 retention suite | ~30min | ✅ Stable |
| test-s3-access-point.sh | S3 Access Point ARN support | ~2min | ✅ Stable |
Verifies that the test environment is properly configured with required binaries and dependencies.
./cmd/litestream-test/scripts/verify-test-setup.sh
Checks:
Reproduces checkpoint during downtime bug that causes restore failures.
./cmd/litestream-test/scripts/reproduce-critical-bug.sh
Reproduces: Issue #752
Scenario:
Expected: Database should restore successfully Actual: Restore fails, causing data loss
Tests Issue #754 flag compatibility with S3 replication versus file replication.
./cmd/litestream-test/scripts/test-754-s3-scenarios.sh
Tests:
Focused testing of Issue #754 restore failures.
./cmd/litestream-test/scripts/test-754-restore-focus.sh
Tests:
Minimal reproduction case for Issue #754.
./cmd/litestream-test/scripts/test-simple-754-reproduction.sh
Reproduces: Issue #754 with minimal steps for debugging
Reproduces ltx v0.5.0 flag compatibility issue.
./cmd/litestream-test/scripts/test-v0.5-flag-reproduction.sh
Tests:
Tests various restart scenarios with ltx v0.5.0.
./cmd/litestream-test/scripts/test-v0.5-restart-scenarios.sh
Tests:
Tests isolation between different LTX format versions.
./cmd/litestream-test/scripts/test-format-isolation.sh
Tests:
Quick validation of LTX format handling.
./cmd/litestream-test/scripts/test-quick-format-check.sh
Duration: ~30 seconds
Tests:
Tests upgrade path from ltx v0.3 to v0.5.
./cmd/litestream-test/scripts/test-upgrade-v0.3-to-v0.5.sh
Tests:
Tests upgrade process with large databases (1GB+).
./cmd/litestream-test/scripts/test-upgrade-large-db.sh
Tests:
Tests upgrade with very large databases and long-running scenarios.
./cmd/litestream-test/scripts/test-massive-upgrade.sh
Tests:
For detailed S3 retention testing documentation, see S3-RETENTION-TESTING.md.
Tests S3 Access Point ARN support (Issue #923). Verifies that Access Point ARNs work automatically without manual endpoint configuration.
export LITESTREAM_S3_ACCESS_POINT_ARN='arn:aws:s3:us-east-2:123456789012:accesspoint/my-access-point'
./cmd/litestream-test/scripts/test-s3-access-point.sh
Tests:
Environment Variables:
LITESTREAM_S3_ACCESS_POINT_ARN - Full ARN of the S3 Access Point (required)LITESTREAM_S3_REGION - AWS region (optional, extracted from ARN)LITESTREAM_S3_PREFIX - Path prefix in bucket (optional)Basic S3 LTX retention cleanup testing.
./cmd/litestream-test/scripts/test-s3-retention-cleanup.sh
Tests:
S3 retention testing with 50MB database.
./cmd/litestream-test/scripts/test-s3-retention-small-db.sh
Configuration:
Tests:
S3 retention testing with 1.5GB database crossing lock page boundary.
./cmd/litestream-test/scripts/test-s3-retention-large-db.sh
Configuration:
Tests:
Master script running both small and large database retention tests with analysis.
./cmd/litestream-test/scripts/test-s3-retention-comprehensive.sh
./cmd/litestream-test/scripts/test-s3-retention-comprehensive.sh --small-only
./cmd/litestream-test/scripts/test-s3-retention-comprehensive.sh --large-only
./cmd/litestream-test/scripts/test-s3-retention-comprehensive.sh --no-cleanup
Duration: ~30 minutes for full suite
Features:
./cmd/litestream-test/scripts/test-fresh-start.sh
./cmd/litestream-test/scripts/verify-test-setup.sh
./cmd/litestream-test/scripts/test-rapid-checkpoints.sh
for script in test-fresh-start.sh test-rapid-checkpoints.sh test-database-integrity.sh; do
echo "Running $script..."
./cmd/litestream-test/scripts/$script
echo ""
done
The S3 tests automatically use the Python S3 mock server (./etc/s3_mock.py) for isolated testing:
./cmd/litestream-test/scripts/test-s3-retention-small-db.sh
Most tests create logs in /tmp/:
tail -f /tmp/fresh-test.log
tail -f /tmp/checkpoint-cycle.log
grep -i error /tmp/*.log
Tests typically create artifacts in /tmp/:
/tmp/*-test.db/tmp/*-replica//tmp/*-test.log/tmp/*.yml/tmp/*-restored.dbHistorical test results and analysis are stored in .local/test-results/ (git-ignored):
final-test-summary.md - Comprehensive test findingsvalidation-results-after-ltx-v0.5.0.md - ltx v0.5.0 impact analysiscomprehensive-test-findings.md - Initial test resultscritical-bug-analysis.md - Detailed bug analysisWhen adding new test scripts:
test-*.sh)/tmp/ for test artifactstrap