13. Running Tests

Tests are provided for package-level testing of the docker-mariadb-snapshot image. They are not intended for end-users, but rather for developers and maintainers to validate functionality.

This page provides comprehensive guidance for testing the docker-mariadb-snapshot image, including automated test suites and manual testing procedures.

13.1 Quick Start

The project includes an automated test suite in the testing/ directory. To run all tests:

cd testing
./run-tests.sh

The test runner is completely self-contained and will:

Clean up old images and snapshots
Build the Docker image
Start MySQL server
Wait for MySQL to be ready
Run all snapshot tests
Clean up containers

No manual setup required!

13.2 What the Tests Cover

The automated test suite validates all snapshot modes and features:

13.2.1 Snapshot Modes

Single Database Snapshot - Legacy mode backing up one database (app1)
Multiple Databases Snapshot - Explicit list of databases (app1, app2, app3)
Auto-Discovery Snapshot - Automatically discovers all non-system databases
Per-Database Config - Different structure-only table configurations per database
Combined Snapshot - Creates both individual files and ALL_DATABASES.gz

13.2.2 Validation Checks

For each snapshot mode, tests verify:

Snapshot files are created in correct locations
Files are valid gzipped SQL
Files contain expected database structures
Structure-only tables have schema but no data (cache_, sessions, temp_ tables)
Combined snapshot contains all databases
File sizes are reasonable (not empty or corrupt)

13.3 Test Output

A successful test run looks like this:

==================================================
MySQL/MariaDB Snapshot Container - Test Suite
==================================================

Cleaning up old test snapshots...

Waiting for MySQL to be ready...
MySQL is ready

Running snapshot tests...

Test 1: Single database snapshot...  PASS
Test 2: Multiple databases snapshot (app1)...  PASS
Test 3: Multiple databases snapshot (app2)...  PASS
Test 4: Multiple databases snapshot (app3)...  PASS
Test 5: Auto-discovery snapshot (app1)...  PASS
Test 6: Auto-discovery snapshot (app2)...  PASS
Test 7: Auto-discovery snapshot (app3)...  PASS
Test 8: Per-DB config snapshot (app1)...  PASS
Test 9: Per-DB config snapshot (app2)...  PASS
Test 10: Combined snapshot created...  PASS
Test 11: Combined snapshot includes all DBs...  PASS
Test 12: Structure-only tables (cache_data)...  PASS
Test 13: Structure-only tables (cache_pages)...  PASS
Test 14: Per-DB structure-only (app1 cache)...  PASS
Test 15: Per-DB structure-only (app2 temp_files)...  PASS

==================================================
All tests passed! (15/15)
==================================================

13.4 Manual Testing

If you need to test specific snapshot scenarios manually, use the following commands:

13.4.1 Single Database Snapshot

cd testing
docker compose run --rm snapshot-single hourly
ls -la snapshots/single/hourly.0/mysql/

Expected output: app1.gz file with cache and session tables structure-only

13.4.2 Multiple Databases

docker compose run --rm snapshot-multiple daily
ls -la snapshots/multiple/daily.0/mysql/

Expected output: app1.gz, app2.gz, app3.gz files

13.4.3 Auto-Discovery

docker compose run --rm snapshot-all weekly
ls -la snapshots/all/weekly.0/mysql/

Expected output: One .gz file per discovered database (app1, app2, app3)

13.4.4 Per-Database Configuration

docker compose run --rm snapshot-per-db-config hourly
ls -la snapshots/per-db/hourly.0/mysql/

Expected output: - app1.gz with cache, sessions, and watchdog tables structure-only - app2.gz with temp_files and cache tables structure-only

13.4.5 Combined Snapshot

docker compose run --rm snapshot-combined daily
ls -la snapshots/combined/daily.0/mysql/

Expected output: - Individual database files: app1.gz, app2.gz, app3.gz - Combined file: ALL_DATABASES.gz

13.5 Inspecting Snapshot Files

13.5.1 View Snapshot Contents

To decompress and view a snapshot without restoring:

gunzip -c snapshots/single/hourly.0/mysql/app1.gz | less

13.5.2 Check for Structure-Only Tables

Verify that structure-only tables have no INSERT statements:

gunzip -c snapshots/single/hourly.0/mysql/app1.gz | grep -i "INSERT INTO.*cache_data"

Expected: No output (table data was excluded)

Check that structure exists:

gunzip -c snapshots/single/hourly.0/mysql/app1.gz | grep -i "CREATE TABLE.*cache_data"

Expected: CREATE TABLE statement found

13.5.3 Restore to MySQL for Testing

Restore a snapshot to your test MySQL server:

gunzip -c snapshots/single/hourly.0/mysql/app1.gz | \
  docker compose exec -T mysql mysql -u root -prootpassword app1

Or restore to a different database name:

# Create new database
docker compose exec mysql mysql -u root -prootpassword -e "CREATE DATABASE app1_restored"

# Restore snapshot
gunzip -c snapshots/single/hourly.0/mysql/app1.gz | \
  docker compose exec -T mysql mysql -u root -prootpassword app1_restored

13.6 Test Database Structure

The test MySQL server is initialized with three databases for comprehensive testing:

13.6.1 app1 Database

Tables: - cache_data - Structure-only (matches cache_* pattern) - cache_pages - Structure-only (matches cache_* pattern) - sessions - Structure-only - watchdog - Structure-only in per-DB config tests - users - Regular table with full data snapshot

13.6.2 app2 Database

Tables: - temp_files - Structure-only in per-DB config (matches temp_* pattern) - cache - Structure-only in per-DB config - posts - Regular table with full data snapshot

13.6.3 app3 Database

Tables: - products - Regular table with full data snapshot - orders - Regular table with full data snapshot

This structure ensures tests cover: - Pattern matching with wildcards (cache_*, temp_*) - Exact table name matching (sessions, watchdog, cache) - Per-database configuration variations - Databases without structure-only tables

13.7 Cleanup

13.7.1 Clean Up Test Data

To remove all test containers and snapshots:

cd testing
docker compose down -v
rm -rf snapshots

13.7.2 Clean Up Individual Snapshot Directories

rm -rf snapshots/single
rm -rf snapshots/multiple
rm -rf snapshots/all
rm -rf snapshots/per-db
rm -rf snapshots/combined

13.8 Troubleshooting

13.8.1 Tests Fail with "MySQL is not ready"

Cause: MySQL container is still initializing.

Solution: Wait a few seconds for MySQL to finish starting, then run tests again:

# Check MySQL status
docker compose ps mysql

# Wait for healthy status
docker compose up -d mysql
sleep 10

# Run tests
./run-tests.sh

13.8.2 Permission Errors When Running Tests

Cause: run-tests.sh script is not executable.

Solution: Make the script executable:

chmod +x run-tests.sh

13.8.3 Snapshot Files Not Found

Cause: MySQL server not running before snapshot execution.

Solution: Start MySQL first:

docker compose up -d mysql

# Wait for healthy status
docker compose ps mysql

# Run snapshot
docker compose run --rm snapshot-single hourly

13.8.4 Structure-Only Table Validation Fails

Cause: Test data was not properly initialized.

Solution: Recreate the MySQL container with fresh data:

docker compose down -v
docker compose up -d mysql

# Wait for initialization
sleep 10

# Run tests
./run-tests.sh

13.8.5 Docker Compose Command Not Found

Cause: Docker Compose not installed or using old syntax.

Solution: Update Docker Compose:

# Modern Docker with integrated compose
docker compose version

# If using old standalone compose
docker-compose version

Replace docker compose with docker-compose if using the standalone version.

13.9 Continuous Integration

The project uses GitHub Actions for automated testing. See .github/workflows/ci.yml for the CI configuration.

Tests run automatically on: - Push to main branches - Pull requests - Manual workflow dispatch

13.10 Writing Custom Tests

To add your own test scenarios, create a new service in testing/docker-compose.yml:

services:
  snapshot-custom:
    build:
      context: ..
      dockerfile: Dockerfile
    environment:
      # Your custom configuration
      DB_HOSTNAME: mysql
      DB_DATABASE: mydb
      # Add other settings
    volumes:
      - ./snapshots/custom:/data
    depends_on:
      mysql:
        condition: service_healthy

Run your custom test:

docker compose run --rm snapshot-custom hourly
ls -la snapshots/custom/hourly.0/mysql/

13.11 Next Steps

Configuration Reference - Learn about all environment variables
Docker Compose Examples - See production-ready configurations
Quick Start Guide - Basic usage examples