API Integration Test Scaffolder Workflow

This skill creates comprehensive integration tests that validate the complete data flow from frontend to backend to AI flows.

Workflow Steps

1. Identify integration to test:

   • Ask for frontend service function (e.g.,

     aiServices.generateKscResponses

     )
   • Find corresponding backend endpoint
   • Identify associated Genkit flow (if any)
   • Determine test scenario (success, validation, error)

2. Generate integration test file:

   • Read template:

     .claude/skills/api-integration-test-scaffolder/templates/integration_test.py.tpl

   • Replace placeholders:

     • {{TEST_NAME}}

       - Descriptive test name

     • {{ENDPOINT_PATH}}

       - API endpoint path

     • {{REQUEST_DATA}}

       - Sample request payload

     • {{EXPECTED_RESPONSE}}

       - Expected response structure

     • {{GENKIT_FLOW}}

       - Associated Genkit flow name
   • Write to:

     backend/app/tests/integration/test_{{feature_name}}_integration.py

3. Include test scenarios:

   • ✅ Happy path: Valid request → successful response
   • ⚠️ Validation: Invalid data → 422 validation error
   • 🔒 Authentication: Unauthorized → 401 error
   • ❌ Error handling: Server error → 500 with proper message
   • 🔄 Genkit flow: Verify flow execution and caching
   • 📊 Response validation: Type checking, required fields

4. Add mock setup:

   • Mock Firebase Auth dependencies
   • Mock Genkit flow responses (optional)
   • Mock external services (email, storage, etc.)
   • Set up test database/Firestore

5. Report success:

   • Show test file path
   • Display test coverage (scenarios included)
   • Provide command to run tests
   • Show example test execution output

Template Structure

# backend/app/tests/integration/test_{{FEATURE}}_integration.py

import pytest
from httpx import AsyncClient
from unittest.mock import AsyncMock, patch

from app.main import app
from app.models.{{MODEL}} import {{REQUEST_MODEL}}, {{RESPONSE_MODEL}}


@pytest.fixture
async def async_client():
    async with AsyncClient(app=app, base_url="http://test") as client:
        yield client


class Test{{FEATURE}}Integration:
    \"\"\"Integration tests for {{FEATURE}} frontend → backend → flow.\"\"\"

    @patch("app.core.dependencies.get_current_user")
    async def test_complete_flow_success(self, mock_auth, async_client):
        # Test implementation
        pass

    # Additional test methods...

Example Usage

User: Create an integration test for the KSC generation feature
Assistant: I'll create a comprehensive integration test...

Files created:
- backend/app/tests/integration/test_ksc_generation_integration.py

Test scenarios included:
✅ Happy path: Valid job description → KSC responses
⚠️ Validation: Empty job description → 422 error
🔒 Authentication: No auth token → 401 error
🔄 Genkit flow: Verify generateKscResponse flow execution
📊 Response validation: Check response structure and types

Run tests:
pytest backend/app/tests/integration/test_ksc_generation_integration.py -v