chore(tests): Integrate VCR tests in the CI and introduce a Makefile

Issue: APPAI-157

Author: timothedelion

.github/workflows/ci.yml

@@ -56,9 +56,9 @@ jobs:
       - name: Run mypy
         run: uv run mypy packages/
 
-  test:
+  test-unit:
     runs-on: ubuntu-latest
-    name: Run Tests
+    name: Run Unit Tests
 
     steps:
       - uses: actions/checkout@v4
@@ -76,8 +76,35 @@ jobs:
       - name: Install dependencies
         run: uv sync --all-groups
 
-      - name: Run tests
-        run: uv run pytest tests/
+      - name: Run unit tests
+        env:
+          ENABLE_LOCAL_OAUTH: "false"
+        run: make test-unit
+
+  test-vcr:
+    runs-on: ubuntu-latest
+    name: Run VCR Tests
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --all-groups
+
+      - name: Run VCR tests
+        env:
+          ENABLE_LOCAL_OAUTH: "false"
+        run: make test-vcr
 
   docker-build:
     runs-on: ubuntu-latest

Makefile

@@ -0,0 +1,46 @@
+SHELL := /bin/bash
+.PHONY: test test-vcr test-unit test-with-env test-vcr-with-env lint format typecheck
+
+# =============================================================================
+# CI commands (no .env sourcing)
+# =============================================================================
+
+# Run all tests
+test:
+	ENABLE_LOCAL_OAUTH=false uv run pytest
+
+# Run VCR cassette tests only (tests marked with @pytest.mark.vcr_test)
+test-vcr:
+	ENABLE_LOCAL_OAUTH=false uv run pytest -m vcr_test -v
+
+# Run unit tests (tests NOT marked with @pytest.mark.vcr_test)
+test-unit:
+	ENABLE_LOCAL_OAUTH=false uv run pytest -m "not vcr_test"
+
+# =============================================================================
+# Local dev commands (sources .env for API key)
+# =============================================================================
+
+# Run all tests with .env loaded
+test-with-env:
+	set -a && source .env && set +a && make test
+
+# Run VCR tests with .env loaded (for recording cassettes)
+test-vcr-with-env:
+	set -a && source .env && set +a && make test-vcr
+
+# =============================================================================
+# Code quality
+# =============================================================================
+
+# Linting
+lint:
+	uv run ruff check .
+
+# Format code
+format:
+	uv run ruff format .
+
+# Type checking
+typecheck:
+	uv run mypy .

tests/cassettes/README.md

@@ -2,6 +2,18 @@
 
 This directory contains VCR cassettes - recorded HTTP interactions with the GitGuardian API.
 
+> **Important**: Cassettes are **recorded locally** and committed to the repository. CI replays from these committed cassettes without requiring API credentials. Developers should **periodically re-record cassettes** to keep them in sync with API changes.
+
+## Recording Workflow
+
+```
+Local (with API key)                CI (no API key)
+┌───────────────────────────┐       ┌─────────────────────┐
+│ make test-vcr-with-env    │ ───▶  │ make test-vcr       │
+│ (real API calls)          │ git   │ (replay only)       │
+└───────────────────────────┘ push  └─────────────────────┘
+```
+
 ## What are VCR Cassettes?
 
 VCR cassettes record real HTTP requests and responses the first time a test runs, then replay those recorded responses on subsequent runs. This provides:
@@ -113,11 +125,12 @@ version: 1
 
 Cassettes are **automatically scrubbed** of sensitive data:
 
-- `Authorization` headers are filtered
-- `X-Api-Key` headers are filtered
-- Query parameters `api_key` and `token` are filtered
+- Request headers are filtered (only safe headers like `content-type` are kept)
+- Response body fields are redacted: `secret_key`, `access_token_id`, `token`, `api_key`, `password`, `secret`, `credential`, `share_url`
+- Share URLs containing incident tokens are redacted
+- POST data parameters are filtered: `api_key`, `secret`, `client_id`, `client_secret`, `token`, `password`
 
-However, **always review cassettes before committing** to ensure no sensitive data remains in response bodies.
+Redacted values appear as `[REDACTED]` in cassette files.
 
 ## Replay Mode
 
@@ -128,23 +141,23 @@ By default, VCR uses `record_mode="once"`:
 
 ## Troubleshooting
 
-### "GITGUARDIAN_API_KEY is not set" warning
-Set the environment variable before running tests:
-```bash
-export GITGUARDIAN_API_KEY="your-token"
-```
-
-### Test fails with 401 Unauthorized
+### Test fails with 401 Unauthorized (when recording)
 Your API key may be invalid or expired. Generate a new PAT from the GitGuardian dashboard.
 
 ### Cassette not being created
-1. Ensure `record_mode` is set to `"once"` (default)
+1. Ensure `GITGUARDIAN_API_KEY` is set in your `.env` file
 2. Check that the cassettes directory exists
 3. Verify network connectivity to the API
 
 ### Tests fail after API changes
-Delete the cassette and re-record:
+Delete the cassette and re-record locally:
 ```bash
 rm tests/cassettes/test_name.yaml
-ENABLE_LOCAL_OAUTH=false uv run pytest tests/path::test_name -v
+make test-vcr-with-env
+```
+
+### Re-record all cassettes
+```bash
+rm tests/cassettes/*.yaml
+make test-vcr-with-env
 ```

tests/conftest.py

@@ -130,12 +130,13 @@ def _before_record_response(response):
 @pytest.fixture(scope="session")
 def real_client():
     """
-    Create a real GitGuardianClient for recording cassettes.
+    Create a real GitGuardianClient for recording/replaying cassettes.
 
-    This fixture creates a client that makes actual API calls.
-    Use this with VCR cassettes to record real HTTP interactions.
+    This fixture creates a client for use with VCR cassettes.
+    - When cassettes exist: VCR replays recorded responses (no real API calls)
+    - When recording new cassettes: Requires GITGUARDIAN_API_KEY env var
 
-    Environment variables required for recording:
+    Environment variables (only needed for recording new cassettes):
         - GITGUARDIAN_API_KEY: Your GitGuardian API key (Personal Access Token)
         - GITGUARDIAN_URL: (Optional) Custom GitGuardian URL, defaults to SaaS
 
@@ -148,13 +149,9 @@ async def test_something(real_client):
     """
     from gg_api_core.client import GitGuardianClient
 
-    api_key = os.getenv("GITGUARDIAN_API_KEY")
-    if not api_key:
-        raise ValueError(
-            "GITGUARDIAN_API_KEY is not set, recording VCR cassettes won't work. "
-            "Set this environment variable to record new cassettes."
-        )
-
+    # Use real key if available, otherwise use dummy key for cassette replay
+    # VCR will intercept requests and replay from cassettes, so the key doesn't matter
+    api_key = os.getenv("GITGUARDIAN_API_KEY", "dummy-key-for-cassette-replay")
     gitguardian_url = os.getenv("GITGUARDIAN_URL", "https://dashboard.gitguardian.com")
 
     # Create client with PAT (bypasses OAuth)