feat: Introduce dual testing with redis and bitmapist-server (#84)

* feat: Introduce dual testing with redis and bitmapist-server
* fix: Stabilize backend connection in tests
* chore: Report storage backend in pytest header
* chore: ignore bitmapist.db (bitmapist-server artifact)
* feat: Refuse to clear data storage if there are more than 20 keys
Since the tests now support a previously running instance of the backend, this introduces a protection in case the tests get accidentally connected to production data.

* feat: Run CI tests with redis and bitmapist-server
* fix(test): Add future annotations import for Python 3.9 type hint compatibility
* chore(test): Avoid installing unnecessary dependencies

We only need the dev group and:
https://docs.astral.sh/uv/concepts/projects/sync/#syncing-development-dependencies
> The dev group is special-cased and synced by default.

Author: jacobo-doist

.github/workflows/tests.yml

@@ -10,10 +10,11 @@ jobs:
   test:
     runs-on: ubuntu-latest
     timeout-minutes: 60
-    name: "Python ${{ matrix.python-version }}"
+    name: "Python ${{ matrix.python-version }} / ${{ matrix.backend }}"
     strategy:
       matrix:
         python-version: ['3.9', '3.10', '3.11', '3.12', '3.13']
+        backend: ['redis', 'bitmapist-server']
     steps:
       - name: Checkout Repo
         uses: actions/checkout@v5
@@ -26,11 +27,53 @@ jobs:
 
       - name: Install dependencies
         run: |
-          uv sync --locked --all-extras --dev
+          uv sync --locked
 
-      - name: Install redis
+      - name: Install Redis
+        if: matrix.backend == 'redis'
         run: |
           sudo apt-get install redis -y
 
+      - name: Get bitmapist-server latest version
+        if: matrix.backend == 'bitmapist-server'
+        id: bitmapist-version
+        run: |
+          VERSION=$(curl -s https://api.github.com/repos/Doist/bitmapist-server/releases/latest | jq -r .tag_name)
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+
+      - name: Cache bitmapist-server
+        if: matrix.backend == 'bitmapist-server'
+        id: cache-bitmapist
+        uses: actions/cache@v4
+        with:
+          path: ~/bitmapist-server
+          key: bitmapist-server-${{ steps.bitmapist-version.outputs.version }}
+
+      - name: Download bitmapist-server
+        if: matrix.backend == 'bitmapist-server' && steps.cache-bitmapist.outputs.cache-hit != 'true'
+        run: |
+          wget https://github.com/Doist/bitmapist-server/releases/latest/download/bitmapist-server-linux-amd64.tar.gz
+          tar -xzf bitmapist-server-linux-amd64.tar.gz
+          chmod +x bitmapist-server
+          mv bitmapist-server ~/bitmapist-server
+
+      - name: Install bitmapist-server
+        if: matrix.backend == 'bitmapist-server'
+        run: |
+          sudo cp ~/bitmapist-server /usr/local/bin/bitmapist-server
+          sudo chmod +x /usr/local/bin/bitmapist-server
+
+      - name: Verify Redis is available
+        if: matrix.backend == 'redis'
+        run: |
+          command -v redis-server || exit 1
+          redis-server --version
+
+      - name: Verify bitmapist-server is available
+        if: matrix.backend == 'bitmapist-server'
+        run: |
+          command -v bitmapist-server || exit 1
+          bitmapist-server --version
+
       - name: Run tests
         run: uv run pytest -vv

.gitignore

@@ -3,4 +3,5 @@
 *.egg-info
 /dist
 .tox
-dump.rdb
+dump.rdb
+bitmapist.db

README.md

@@ -342,22 +342,70 @@ uv sync
 
 ## Testing
 
-To run our tests will need to ensure a local redis server is installed.
+### Quick Start with Docker (Recommended)
 
-You can use these environment variables to tell the tests about Redis:
+The easiest way to run tests locally is with Docker:
 
-- `BITMAPIST_REDIS_SERVER_PATH`: Path to the Redis server executable (defaults to the first one in the path or `/usr/bin/redis-server`)
-- `BITMAPIST_REDIS_PORT`: Port number for the Redis server (defaults to 6399)
+```bash
+# Start both backend servers
+docker compose up -d
+
+# Run tests
+uv run pytest
+
+# Stop servers when done
+docker compose down
+```
+
+This runs tests against both Redis and bitmapist-server backends automatically.
 
-We use `pytest` to run unit tests, which you can run with:
+### Alternative: Native Binaries
 
+To run tests with native binaries, you'll need at least one backend server installed:
+
+**Redis:**
+- Install `redis-server` using your package manager
+- Ensure it's in your `PATH`, or set `BITMAPIST_REDIS_SERVER_PATH`
+
+**Bitmapist-server:**
+- Download from the [releases page](https://github.com/Doist/bitmapist-server/releases)
+- Ensure it's in your PATH, or set `BITMAPIST_SERVER_PATH`
+
+Then run:
 ```bash
 uv run pytest
 ```
 
-> [!TIP]
-> You can also run tests against the [bitmapist-server](https://github.com/Doist/bitmapist-server) backend instead of Redis.
-> To do this, set the `BITMAPIST_REDIS_SERVER_PATH` variable to the path of the `bitmapist-server` executable.
+The test suite auto-detects available backends and runs accordingly:
+- **Docker containers running?** Uses them
+- **Native binaries available?** Starts them automatically
+- **Nothing available?** Shows error
+
+### Configuration
+
+#### Environment Variables
+
+Customize backend locations and ports if needed:
+
+```bash
+# Backend binary paths (optional - auto-detected from PATH by default)
+export BITMAPIST_REDIS_SERVER_PATH=/custom/path/to/redis-server
+export BITMAPIST_SERVER_PATH=/custom/path/to/bitmapist-server
+
+# Backend ports (optional - defaults shown)
+export BITMAPIST_REDIS_PORT=6399
+export BITMAPIST_SERVER_PORT=6400
+```
+
+#### Testing Specific Backends
+
+```bash
+# Test only Redis
+uv run pytest -k redis
+
+# Test only bitmapist-server
+uv run pytest -k bitmapist-server
+```
 
 ## Releasing new versions
 

docker-compose.yml

@@ -0,0 +1,14 @@
+# This file is used to start the Redis and bitmapist-server services for local
+# development and testing.
+
+services:
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "${BITMAPIST_REDIS_PORT:-6399}:6379"
+    command: redis-server --port 6379
+
+  bitmapist-server:
+    image: ghcr.io/doist/bitmapist-server:v1.9.8
+    ports:
+      - "${BITMAPIST_SERVER_PORT:-6400}:6379"