Skip to content

README-local-testing.md

Latest commit

 

History

History
218 lines (153 loc) · 5.89 KB

README-local-testing.md

File metadata and controls

218 lines (153 loc) · 5.89 KB

Local Testing Guide for Cachier

This guide explains how to run cachier tests locally with Docker containers for external backends.

Quick Start

# Test a single backend
./scripts/test-local.sh mongo

# Test multiple backends
./scripts/test-local.sh redis sql

# Test all backends
./scripts/test-local.sh all

# Test all external backends (mongo, redis, sql)
./scripts/test-local.sh external

# Test with options
./scripts/test-local.sh mongo redis -v -k

Available Cores

  • mongo - MongoDB backend tests
  • redis - Redis backend tests
  • sql - SQL (PostgreSQL) backend tests
  • memory - Memory backend tests (no Docker needed)
  • pickle - Pickle backend tests (no Docker needed)

Core Groups

  • all - All backends (mongo, redis, sql, memory, pickle)
  • external - All external backends requiring Docker (mongo, redis, sql)
  • local - All local backends (memory, pickle)

Command Line Options

  • -v, --verbose - Show verbose pytest output
  • -k, --keep-running - Keep Docker containers running after tests
  • -h, --html-coverage - Generate HTML coverage report
  • -f, --files - Specify test files to run (can be used multiple times)
  • -p, --parallel - Run tests in parallel using pytest-xdist
  • -w, --workers - Number of parallel workers (default: auto)
  • --help - Show help message

Examples

Basic Usage

# Run MongoDB tests
./scripts/test-local.sh mongo

# Run Redis and SQL tests
./scripts/test-local.sh redis sql

# Run all tests
./scripts/test-local.sh all

Using Make

# Run specific backends
make test-local CORES="mongo redis"

# Run all tests
make test-all-local

# Run external backends only
make test-external

# Run individual backends
make test-mongo-local
make test-redis-local
make test-sql-local

Advanced Usage

# Keep containers running for debugging
./scripts/test-local.sh mongo redis -k

# Verbose output with HTML coverage
./scripts/test-local.sh all -v -h

# Using environment variable
CACHIER_TEST_CORES="mongo redis" ./scripts/test-local.sh

# Test specific files with MongoDB backend
./scripts/test-local.sh mongo -f tests/test_mongo_core.py

# Test multiple files across all backends
./scripts/test-local.sh all -f tests/test_main.py -f tests/test_redis_core_coverage.py

# Combine file selection with other options
./scripts/test-local.sh redis sql -f tests/test_sql_core.py -v -k

# Run tests in parallel with automatic worker detection
./scripts/test-local.sh all -p

# Run tests in parallel with 4 workers
./scripts/test-local.sh external -p -w 4

# Run local tests in parallel (memory and pickle)
./scripts/test-local.sh memory pickle -p

# Combine parallel testing with other options
./scripts/test-local.sh mongo redis -p -v -k

Docker Compose

# Start all services
make services-start

# Run tests manually
CACHIER_TEST_HOST=localhost CACHIER_TEST_PORT=27017 CACHIER_TEST_VS_DOCKERIZED_MONGO=true \
CACHIER_TEST_REDIS_HOST=localhost CACHIER_TEST_REDIS_PORT=6379 CACHIER_TEST_VS_DOCKERIZED_REDIS=true \
SQLALCHEMY_DATABASE_URL="postgresql://testuser:testpass@localhost:5432/testdb" \
pytest -m "mongo or redis or sql"

# Stop all services
make services-stop

# View logs
make services-logs

Docker Containers

The script manages the following containers:

Backend Container Name Port Image
MongoDB cachier-test-mongo 27017 mongo:latest
Redis cachier-test-redis 6379 redis:7-alpine
PostgreSQL cachier-test-postgres 5432 postgres:15

Environment Variables

The script automatically sets the required environment variables:

MongoDB

  • CACHIER_TEST_HOST=localhost
  • CACHIER_TEST_PORT=27017
  • CACHIER_TEST_VS_DOCKERIZED_MONGO=true

Redis

  • CACHIER_TEST_REDIS_HOST=localhost
  • CACHIER_TEST_REDIS_PORT=6379
  • CACHIER_TEST_REDIS_DB=0
  • CACHIER_TEST_VS_DOCKERIZED_REDIS=true

SQL/PostgreSQL

  • SQLALCHEMY_DATABASE_URL=postgresql://testuser:testpass@localhost:5432/testdb

Prerequisites

  1. Docker - Required for external backends (mongo, redis, sql)
  2. Python dependencies - Install test requirements: 
    pip install -r tests/requirements.txt
pip install -r tests/mongodb_requirements.txt  # For MongoDB tests
pip install -r tests/redis_requirements.txt    # For Redis tests
pip install -r tests/sql_requirements.txt      # For SQL tests

Troubleshooting

Docker not found

Port conflicts

  • The script will fail if required ports are already in use
  • Stop conflicting services or use docker ps to check running containers

Tests failing

  • Check container logs: docker logs cachier-test-<backend>
  • Ensure all dependencies are installed
  • Try running with -v for verbose output

Cleanup issues

  • If containers aren't cleaned up properly: 
    make services-stop
# or manually
docker stop cachier-test-mongo cachier-test-redis cachier-test-postgres
docker rm cachier-test-mongo cachier-test-redis cachier-test-postgres

Best Practices

  1. Before committing: Run ./scripts/test-local.sh external to test all external backends
  2. For quick iteration: Use memory and pickle tests (no Docker required)
  3. For debugging: Use -k to keep containers running and inspect them
  4. For CI parity: Test with the same backends that CI uses
  5. For faster test runs: Use -p to run tests in parallel, especially when testing multiple backends
  6. For parallel testing: The script automatically installs pytest-xdist when needed
  7. Worker count: Use -w auto (default) to let pytest-xdist determine optimal workers, or specify a number based on your CPU cores

Future Enhancements

  • Add MySQL/MariaDB support
  • Add Elasticsearch support
  • Add performance benchmarking mode