API & Integration Testing Framework

Recruiter signal: distributed-system Test Architecture beyond endpoint checks—covering contracts, persistence, asynchronous events, authorization, dependency failures, retries, idempotency and evidence-based release gates.

Part of the broader AI Quality Engineering portfolio: Live AI Assurance Portfolio

An HTTP 200 does not prove a business workflow is correct. A request can succeed while persisting the wrong state, losing an event, duplicating a payment or exposing another customer's data.

This framework validates the behavior across boundaries and after failure, not just the API response.

flowchart TB
    T[Pytest suites] --> REST[REST + GraphQL clients]
    T --> PACT[Pact contracts]
    T --> INT[Integration + resilience tests]
    REST --> API[Acme Commerce API]
    PACT --> API
    INT --> API
    API --> DB[(SQLite / PostgreSQL)]
    API --> WM[WireMock payment provider]
    API --> OUTBOX[(Transactional outbox)]
    OUTBOX --> RP[Redpanda]
    T --> REPORTS[JUnit + HTML]
    REPORTS --> GATE{Release quality gate}

python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev,messaging,postgres]"
pytest -m smoke

Windows PowerShell:

py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev,messaging,postgres]"
pytest -m smoke

Expected proof: isolated API/integration evidence without an external service account.

Create Customer + Product
→ Create Order
→ Persist Items
→ Emit OrderCreated
→ Authorize Payment
→ Confirm Order
→ Decrement Inventory Once
→ Persist One Payment
→ Emit One OrderConfirmed
→ Validate API + DB + Events + Correlation

This demonstrates that the test verifies state and side effects, not merely response status.

Payment Dependency Returns 503
→ Bounded Retry Policy Executes
→ Order Remains PAYMENT_FAILED
→ Inventory Remains Unchanged
→ One Terminal Payment Record
→ PaymentFailed Event
→ No OrderConfirmed Event

This demonstrates resilience and safe failure behavior.

Load testing and offensive penetration testing are intentionally separate disciplines.

• Thin typed HTTPX domain clients
• Pydantic v2 request/response/error/event models
• REST + GraphQL
• Pact V4 contracts
• WireMock service virtualization
• SQLAlchemy persistence validation
• Transactional outbox event model
• Redpanda Kafka-compatible integration
• Retry and idempotency validation
• Parallel-safe synthetic test data
• SQLite local isolation
• PostgreSQL/Redpanda Docker environment
• GitHub Actions, Jenkins and Azure DevOps examples
• JUnit/HTML reporting and quality gates

The reference implementation includes:

• Missing/invalid/expired authentication cases
• Role enforcement for ADMIN, CUSTOMER and SUPPORT
• Ownership checks for cross-customer access
• Sensitive-field masking
• Environment-only credentials
• Least-privilege CI

The project is a functional QE framework, not a penetration-testing product.

Pact consumer tests drive the real typed clients against a contract mock, while provider verification replays the contract against the FastAPI provider. Contract tests detect interface drift quickly; integration tests prove wiring and state. Neither replaces the other.

The transactional outbox gives events durable, queryable semantics before broker delivery. Tests validate event ID, type, payload, timestamp, ordering and correlation. Docker execution publishes committed records to Redpanda and consumes the real Kafka-compatible message using bounded polling rather than sleeps.

WireMock scenarios cover:

• Approval
• Decline
• 500
• 503
• Timeout
• Malformed JSON
• Stateful 503 → 503 → 200 recovery

Generic API clients do not blindly retry every request; retries are validated as business behavior.

pytest --junitxml=reports/junit.xml --html=reports/report.html --self-contained-html
quality-gate --junit reports/junit.xml --threshold 100

The gate fails on test failures/errors and enforces the configured pass-rate threshold. Missing or unexecuted evidence is never reported as PASS.

export POSTGRES_PASSWORD="$(openssl rand -hex 24)"
docker compose build
docker compose up -d
python scripts/wait_for_services.py
RUN_DOCKER_TESTS=1 pytest -m docker
docker compose down -v

Services include FastAPI, PostgreSQL, WireMock, Redpanda and an outbox worker.

config/                 DEV/QA/UAT configuration
framework/              clients, models, assertions, DB, messaging, utilities, gate
demo_system/            stable FastAPI test target
tests/                  API, GraphQL, contract, integration, DB, messaging, resilience
contracts/pacts/        committed consumer contract
mocks/wiremock/         deterministic payment behaviors
scripts/                startup, readiness, cleanup, validation
docs/                   strategy, architecture, CI, interview material
.github/workflows/      PR, contract and nightly pipelines

1. Explain why 200 OK is not enough.
2. Show typed REST/GraphQL clients.
3. Open the Pact consumer/provider contract path.
4. Trace one correlation ID through API → DB → payment → outbox/event.
5. Demonstrate the 503 failure scenario and bounded retry.
6. Show idempotency preventing duplicate side effects.
7. Finish with JUnit/HTML evidence and the release gate.
8. Connect the framework to the live AI Assurance portfolio.

• Contract Testing
• CI/CD
• Validation Report
• Interview Walkthrough
• Troubleshooting

The local identity provider uses deterministic test tokens. The demo is intentionally one modular service rather than theatre-level microservices. Fast local event assertions use the outbox; full broker delivery is exercised in Docker. Response-time assertions are functional thresholds, not capacity testing.

Test Architect · API Test Architect · Integration Test Architect · Quality Engineering Architect · Principal/Senior SDET

See CONTRIBUTING.md, SECURITY.md and the MIT License.