Add a script for running MongoDB core tests locally

.gitignore

@@ -107,4 +107,9 @@ Pipfile.lock
 
 tags
 
+# cursor rules, etc.
 .cursor
+
+# created by backlog.md
+# https://github.com/MrLesk/Backlog.md
+backlog

CLAUDE.md

@@ -177,6 +177,42 @@ ______________________________________________________________________
 - **Run example:** `python examples/redis_example.py`
 - **Update requirements:** Edit `tests/*_requirements.txt` as needed (sql_requirements.txt, redis_requirements.txt).
 
+### MongoDB Local Testing
+
+**Quick Start for MongoDB Testing:**
+
+```bash
+# Option 1: Using the shell script (recommended)
+./scripts/test-mongo-local.sh                    # MongoDB tests only
+./scripts/test-mongo-local.sh --mode also-local # MongoDB + memory, pickle, maxage tests
+
+# Option 2: Using make
+make test-mongo-local
+
+# Option 3: Using docker-compose
+docker-compose -f scripts/docker-compose.mongodb.yml up -d
+CACHIER_TEST_HOST=localhost CACHIER_TEST_PORT=27017 CACHIER_TEST_VS_DOCKERIZED_MONGO=true pytest -m mongo
+docker-compose -f scripts/docker-compose.mongodb.yml down
+```
+
+**Available Options:**
+
+- `./scripts/test-mongo-local.sh` - Run MongoDB tests only (default)
+- `./scripts/test-mongo-local.sh --mode also-local` - Include memory, pickle, and maxage tests
+- `./scripts/test-mongo-local.sh --keep-running` - Keep MongoDB running after tests
+- `./scripts/test-mongo-local.sh --verbose` - Show verbose output
+- `./scripts/test-mongo-local.sh --coverage-html` - Generate HTML coverage report
+
+**Make Targets:**
+
+- `make test-mongo-local` - Run MongoDB tests with Docker
+- `make test-mongo-inmemory` - Run with in-memory MongoDB (default)
+- `make mongo-start` - Start MongoDB container
+- `make mongo-stop` - Stop MongoDB container
+- `make mongo-logs` - View MongoDB logs
+
+**Note:** By default, MongoDB tests use `pymongo_inmemory` which doesn't require Docker. The above commands let you test against a real MongoDB instance matching the CI environment.
+
 ______________________________________________________________________
 
 ## 🧩 Claude Code Integration

Makefile

@@ -0,0 +1,107 @@
+# Cachier Makefile
+# Development tasks and shortcuts
+
+.PHONY: help test test-all test-mongo-local test-mongo-docker test-mongo-inmemory \
+        test-mongo-also-local mongo-start mongo-stop mongo-logs lint type-check format clean \
+        install install-dev install-all
+
+# Default target
+help:
+	@echo "Cachier Development Commands:"
+	@echo ""
+	@echo "Testing:"
+	@echo "  make test               - Run all tests"
+	@echo "  make test-mongo-local   - Run MongoDB tests with Docker"
+	@echo "  make test-mongo-also-local - Run MongoDB + memory, pickle, maxage tests with Docker"
+	@echo "  make test-mongo-inmemory - Run MongoDB tests with in-memory backend"
+	@echo "  make mongo-start        - Start MongoDB container"
+	@echo "  make mongo-stop         - Stop MongoDB container"
+	@echo "  make mongo-logs         - View MongoDB container logs"
+	@echo ""
+	@echo "Code Quality:"
+	@echo "  make lint               - Run ruff linter"
+	@echo "  make type-check         - Run mypy type checker"
+	@echo "  make format             - Format code with ruff"
+	@echo ""
+	@echo "Installation:"
+	@echo "  make install            - Install package"
+	@echo "  make install-dev        - Install with development dependencies"
+	@echo "  make install-all        - Install with all optional dependencies"
+	@echo ""
+	@echo "Other:"
+	@echo "  make clean              - Clean build artifacts"
+
+# Installation targets
+install:
+	pip install -e .
+
+install-dev:
+	pip install -e .
+	pip install -r tests/requirements.txt
+
+install-all:
+	pip install -e .[all]
+	pip install -r tests/requirements.txt
+	pip install -r tests/sql_requirements.txt
+	pip install -r tests/redis_requirements.txt
+
+# Testing targets
+test:
+	pytest
+
+test-all: test
+
+# MongoDB testing targets
+test-mongo-inmemory:
+	@echo "Running MongoDB tests with in-memory backend..."
+	pytest -m mongo --cov=cachier --cov-report=term
+
+test-mongo-docker:
+	@echo "Running MongoDB tests against Docker MongoDB..."
+	./scripts/test-mongo-local.sh
+
+test-mongo-local: test-mongo-docker
+
+test-mongo-also-local:
+	@echo "Running MongoDB tests with local core tests..."
+	./scripts/test-mongo-local.sh --mode also-local
+
+# MongoDB container management
+mongo-start:
+	@echo "Starting MongoDB container..."
+	@docker ps -q -f name=cachier-test-mongo | grep -q . && \
+		(echo "MongoDB container already running" && exit 0) || \
+		(docker run -d -p 27017:27017 --name cachier-test-mongo mongo:latest && \
+		echo "Waiting for MongoDB to start..." && sleep 5)
+
+mongo-stop:
+	@echo "Stopping MongoDB container..."
+	@docker ps -q -f name=cachier-test-mongo | grep -q . && \
+		(docker stop cachier-test-mongo && docker rm cachier-test-mongo) || \
+		echo "MongoDB container not running"
+
+mongo-logs:
+	@docker logs cachier-test-mongo
+
+# Code quality targets
+lint:
+	ruff check .
+
+type-check:
+	mypy src/cachier/
+
+format:
+	ruff format .
+
+# Clean targets
+clean:
+	rm -rf build/
+	rm -rf dist/
+	rm -rf *.egg-info
+	rm -rf .coverage
+	rm -rf htmlcov/
+	rm -rf .pytest_cache/
+	rm -rf .mypy_cache/
+	rm -rf .ruff_cache/
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+	find . -type f -name "*.pyc" -delete

README.rst

@@ -535,9 +535,45 @@ To run all tests EXCEPT memory core AND MongoDB core related tests, use:
 Running MongoDB tests against a live MongoDB instance
 -----------------------------------------------------
 
-**Note to developers:** By default, all MongoDB tests are run against a mocked MongoDB instance, provided by the ``pymongo_inmemory`` package. To run them against a live MongoDB instance, the ``CACHIER_TEST_VS_DOCKERIZED_MONGO`` environment variable is set to ``True`` in the ``test`` environment of this repository (and additional environment variables are populated with the appropriate credentials), used by the GitHub Action running tests on every commit and pull request.
+**Note to developers:** By default, all MongoDB tests are run against a mocked MongoDB instance, provided by the ``pymongo_inmemory`` package. To run them against a live MongoDB instance, you now have several options:
 
-Contributors are not expected to run these tests against a live MongoDB instance when developing, as credentials for the testing instance used will NOT be shared, but rather use the testing against the in-memory MongoDB instance as a good proxy.
+**Option 1: Using the test script (recommended)**
+
+.. code-block:: bash
+
+  ./scripts/test-mongo-local.sh                    # MongoDB tests only (default)
+  ./scripts/test-mongo-local.sh --mode also-local # MongoDB + memory, pickle, maxage tests
+
+This script automatically handles Docker container lifecycle, environment variables, and cleanup. Additional options:
+
+- ``--mode also-local``: Include memory, pickle, and maxage tests alongside MongoDB tests
+- ``--keep-running``: Keep MongoDB container running after tests
+- ``--verbose``: Show verbose output
+- ``--coverage-html``: Generate HTML coverage report
+
+**Option 2: Using Make**
+
+.. code-block:: bash
+
+  make test-mongo-local  # Run tests with Docker MongoDB
+  make test-mongo-inmemory  # Run tests with in-memory MongoDB (default)
+
+**Option 3: Manual setup**
+
+.. code-block:: bash
+
+  # Start MongoDB with Docker
+  docker run -d -p 27017:27017 --name cachier-test-mongo mongo:latest
+
+  # Run tests
+  CACHIER_TEST_HOST=localhost CACHIER_TEST_PORT=27017 CACHIER_TEST_VS_DOCKERIZED_MONGO=true pytest -m mongo
+
+  # Clean up
+  docker stop cachier-test-mongo && docker rm cachier-test-mongo
+
+**CI Environment:** The ``CACHIER_TEST_VS_DOCKERIZED_MONGO`` environment variable is set to ``True`` in the GitHub Actions CI environment, which runs tests against a real MongoDB instance on every commit and pull request.
+
+Contributors are encouraged to test against a real MongoDB instance before submitting PRs to ensure compatibility, though the in-memory MongoDB instance serves as a good proxy for most development.
 
 **HOWEVER, the tests run against a live MongoDB instance when you submit a PR are the determining tests for deciding whether your code functions correctly against MongoDB.**
 

scripts/docker-compose.mongodb.yml

@@ -0,0 +1,42 @@
+# Docker Compose configuration for local MongoDB testing
+# This file provides an alternative to the shell script approach
+
+version: "3.8"
+
+services:
+  mongodb:
+    image: mongo:latest
+    container_name: cachier-test-mongo
+    ports:
+      - "27017:27017"
+    environment:
+      MONGO_INITDB_DATABASE: cachier_test
+    healthcheck:
+      test: echo 'db.runCommand("ping").ok' | mongosh localhost:27017/test --quiet
+      interval: 5s
+      timeout: 5s
+      retries: 5
+      start_period: 10s
+    volumes:
+      # Optional: persist data between test runs
+      # - cachier-mongo-data:/data/db
+      # Optional: custom initialization scripts
+      # - ./scripts/mongo-init:/docker-entrypoint-initdb.d
+    networks:
+      - cachier-test
+
+networks:
+  cachier-test:
+    driver: bridge
+# Optional: volume for data persistence
+# volumes:
+#   cachier-mongo-data:
+
+# Usage:
+# 1. Start MongoDB: docker-compose -f scripts/docker-compose.mongodb.yml up -d
+# 2. Run tests with environment variables:
+#    CACHIER_TEST_HOST=localhost CACHIER_TEST_PORT=27017 CACHIER_TEST_VS_DOCKERIZED_MONGO=true pytest -m "mongo"
+# 3. Stop MongoDB: docker-compose -f scripts/docker-compose.mongodb.yml down
+
+# Alternative one-liner:
+# docker-compose -f scripts/docker-compose.mongodb.yml run --rm -e CACHIER_TEST_HOST=localhost -e CACHIER_TEST_PORT=27017 -e CACHIER_TEST_VS_DOCKERIZED_MONGO=true test