integration-test

name	integration-test
description	Generate integration tests for APIs, databases, and external services. Auto-detects backend stack (Express, Fastify, NestJS, Django, FastAPI, Rails, Go), ORM (Prisma, TypeORM, SQLAlchemy, GORM), and database (PostgreSQL, MongoDB, Firestore), then creates tests covering endpoint CRUD, auth flows, DB transactions, and external service failures with proper fixtures and mocks. Self-heals failing tests up to 3 iterations. Use when you need to test API endpoints end-to-end, verify database operations, test service interactions, or validate auth and error handling.
version	2.0.0
category	test
platforms	["CLAUDE_CODE"]

You are in AUTONOMOUS MODE. Do NOT ask questions. Detect the project's stack, generate integration tests covering API endpoints, database operations, and service interactions, then run them with a self-healing fix loop.

INPUT: $ARGUMENTS

If arguments are provided, focus on those specific APIs, services, or modules. If no arguments are provided, generate integration tests for the ENTIRE project.

============================================================ PHASE 1: STACK AND SERVICE DISCOVERY

Step 1.1 -- Framework Detection

Detect the backend framework and test infrastructure:

Indicator	Framework
package.json with fastify	Fastify
package.json with express	Express
package.json with @nestjs/core	NestJS
manage.py + settings.py	Django
requirements.txt with fastapi	FastAPI
requirements.txt with flask	Flask
go.mod + net/http or gin or echo	Go
Gemfile with rails	Ruby on Rails
pubspec.yaml with shelf or dart_frog	Dart backend

Detect the ORM / database layer:

Indicator	ORM
prisma/ directory or schema.prisma	Prisma
ormconfig.* or typeorm in package.json	TypeORM
sequelize in package.json	Sequelize
drizzle.config.*	Drizzle
settings.py with DATABASES	Django ORM
requirements.txt with sqlalchemy	SQLAlchemy
go.mod with gorm	GORM
Gemfile with activerecord	ActiveRecord

Detect the database:

Indicator	Database
DATABASE_URL with postgres	PostgreSQL
DATABASE_URL with mysql	MySQL
*.sqlite or DATABASE_URL with sqlite	SQLite
firebase.json or firebaseConfig	Firestore
MONGODB_URI or mongoose in deps	MongoDB
REDIS_URL or redis in deps	Redis

Detect the test framework (same as /unit-test detection table).

Step 1.2 -- API Endpoint Discovery

Discover ALL API endpoints in the project:

Framework	Discovery Method
Fastify	Read route registration files, search for fastify.get/post/put/delete
Express	Search for app.get/post/put/patch/delete, router.*
NestJS	Read *.controller.ts, find @Get/@Post/@Put/@Delete/@Patch decorators
Django	Read urls.py, find path() and urlpatterns
FastAPI	Read *.py, find @app.get/@router.post decorators
Flask	Read *.py, find @app.route, @blueprint.route
Go	Search for http.HandleFunc, r.GET/POST (gin), e.GET/POST (echo)
Rails	Read config/routes.rb, run rake routes if available

Build the endpoint inventory:

#	Method	Path	Auth	Request Body	Response	Handler File

Step 1.3 -- Database Model Discovery

Discover ALL data models:

ORM	Discovery Method
Prisma	Read schema.prisma for model definitions
TypeORM	Read *.entity.ts files
Sequelize	Read *.model.ts or models/ directory
Django	Read models.py files
SQLAlchemy	Read models.py, find class inheriting Base
GORM	Read *.go files with gorm struct tags
ActiveRecord	Read app/models/*.rb
Drizzle	Read schema.ts or drizzle/ directory

Build the model inventory:

Model	Fields	Relations	Unique Constraints	Validation Rules

Step 1.4 -- External Service Discovery

Identify all external service integrations:

• HTTP clients (Axios, fetch, got, httpx, requests)
• Message queues (RabbitMQ, SQS, Redis pub/sub)
• Email services (SendGrid, SES, Nodemailer)
• Payment processors (Stripe, PayPal)
• Auth providers (Auth0, Clerk, Firebase Auth, Supabase Auth)
• Storage services (S3, GCS, Firebase Storage)
• Search engines (Elasticsearch, Algolia, Meilisearch)

============================================================ PHASE 2: TEST INFRASTRUCTURE SETUP

Step 2.1 -- Test Database Configuration

Set up an isolated test database:

FOR POSTGRESQL / MYSQL:

• Check for existing test database URL in .env.test or test config
• If none exists, create a test-specific connection using the same DB with a test schema or a separate test database
• Ensure migrations run against the test database

FOR SQLITE:

• Use an in-memory database or a temporary file

FOR MONGODB:

• Use mongodb-memory-server (Node.js) or mongomock (Python)

FOR FIRESTORE:

• Use Firebase emulators (firebase emulators:start --only firestore)

Step 2.2 -- Test Helpers

Create shared test helpers based on the detected framework:

FOR NODE.JS (Vitest/Jest + Supertest):

Create test helpers with:

• buildApp(): Creates and configures the app instance for supertest
• createTestUser(role?): Registers a user and returns auth token
• seedTestData(fixtures): Loads fixture data into the test database
• cleanDatabase(): Truncates all tables between tests
• authenticatedRequest(method, path, token): Shorthand for auth requests

FOR PYTHON (pytest):

Create conftest.py fixtures:

• client: TestClient or AsyncClient with the app
• db_session: Database session with transaction rollback
• auth_headers: Returns headers with a valid JWT for a test user
• seed_data: Loads fixtures into the test database

FOR GO:

Create test helpers:

• setupTestServer(): Returns httptest.Server with the app handler
• createTestUser(t): Creates a user and returns the auth token
• seedDB(t, fixtures): Loads test data
• cleanDB(t): Truncates tables

Step 2.3 -- Mock Setup for External Services

Create mocks/stubs for every external service discovered in Phase 1:

• HTTP calls: Use nock (Node.js), responses (Python), httpmock (Go)
• Email: Mock the email client, capture sent emails for assertion
• Payment: Mock Stripe/PayPal client, return realistic responses
• Storage: Mock upload/download, use local filesystem or memory
• Message queues: Mock publish, capture messages for assertion

Each mock must:

• Return realistic response structures matching the real service
• Support configurable failure scenarios (timeout, 500, rate limit)
• Track call count and arguments for assertion

============================================================ PHASE 3: TEST GENERATION

Step 3.1 -- API Endpoint Tests

For EACH endpoint discovered in Phase 1, generate tests covering:

HAPPY PATH:

• Send valid request with realistic data
• Verify correct HTTP status (200, 201, 204)
• Verify response body shape and values
• Verify database state changed correctly (read back from DB)

VALIDATION AND ERRORS:

• Missing required fields -> 400
• Invalid field types -> 400
• Invalid field values (out of range, wrong format) -> 400
• Empty request body when required -> 400

AUTHENTICATION AND AUTHORIZATION:

• No auth token on protected endpoint -> 401
• Expired or malformed token -> 401
• Wrong role accessing restricted endpoint -> 403
• Accessing another user's resource -> 403 or 404

RESOURCE LIFECYCLE:

• Create -> Read (verify) -> Update -> Read (verify) -> Delete -> Read (verify 404)
• Duplicate creation (unique constraint) -> 409
• Update non-existent resource -> 404
• Delete non-existent resource -> 404

QUERY AND FILTERING (for list endpoints):

• Pagination: first page, middle page, last page, beyond last page
• Filtering: each filter field individually, combined filters
• Sorting: ascending, descending, by different fields
• Search: matching term, no results, partial match

Step 3.2 -- Database Operation Tests

For EACH model discovered in Phase 1, generate tests covering:

CRUD OPERATIONS:

• Create with all required fields -> record persisted
• Create with optional fields -> defaults applied correctly
• Read by primary key -> correct record returned
• Read by unique field -> correct record returned
• Update single field -> only that field changes
• Update multiple fields -> all fields updated
• Delete -> record removed, related records handled per cascade rules

CONSTRAINTS:

• Unique constraint violation -> appropriate error
• Foreign key constraint -> cannot delete parent with children (or cascades)
• Not-null constraint -> cannot create with null required field
• Check constraints -> out-of-range values rejected

TRANSACTIONS:

• Multi-step operation succeeds atomically
• Multi-step operation rolls back on failure in any step
• Concurrent updates to the same record (optimistic locking if present)

QUERIES:

• Complex queries with joins return correct data shape
• Aggregation queries return correct counts/sums
• Queries with pagination return correct slices

Step 3.3 -- Service Interaction Tests

For EACH external service integration, generate tests covering:

SUCCESS SCENARIOS:

• Service called with correct parameters
• Response parsed and transformed correctly
• Side effects triggered (database updated, event emitted)

FAILURE SCENARIOS:

• Service returns 500 -> error handled gracefully, no crash
• Service times out -> timeout handled, appropriate error returned
• Service returns unexpected response shape -> error logged, fallback behavior
• Service rate-limits (429) -> retry or backoff behavior
• Network error -> appropriate error message to caller

MOCK VERIFICATION:

• Correct endpoint called
• Correct HTTP method used
• Correct headers sent (auth, content-type)
• Correct request body sent
• Correct number of calls made (no duplicate calls)

============================================================ PHASE 4: EXECUTION AND SELF-HEALING

Step 4.1 -- Start Required Services

Start any services needed for integration tests:

• Database: ensure test DB is running and migrated
• Docker: docker compose up -d if compose file exists
• Firebase emulators: firebase emulators:start if Firebase detected
• App server: start in test mode if needed for supertest/httptest

Step 4.2 -- Run Tests

Execute all generated integration tests:

Framework	Command
Vitest	npx vitest run tests/integration/ --reporter=verbose
Jest	npx jest tests/integration/ --verbose --forceExit --runInBand
pytest	pytest tests/integration/ -v --tb=short
go test	go test -v -count=1 ./tests/integration/...
RSpec	bundle exec rspec spec/integration/ --format documentation

Note: Use --runInBand or equivalent for integration tests to avoid parallel database conflicts.

Step 4.3 -- Self-Healing Loop (max 3 iterations)

For each failure, diagnose:

TEST BUG: Wrong URL, missing mock, incorrect assertion, async timing -> Fix the test

APP BUG: Missing validation, wrong status code, broken query, unhandled error -> Fix the application code

INFRASTRUCTURE: Database not running, port conflict, migration not applied -> Fix the environment, restart services

Apply fixes, re-run ONLY failing tests. Repeat up to 3 iterations.

Never delete tests. Never weaken assertions. Never skip failures.

Step 4.4 -- Full Suite Run

After healing, run ALL tests (existing + new) to verify no regressions.

============================================================ OUTPUT

Integration Test Report

Stack Detected

• Framework: [name]
• ORM: [name]
• Database: [type]
• External services: [list]
• Test framework: [name]

Endpoints Tested

Method	Path	Happy Path	Validation	Auth	Edge Cases	Status

Database Operations Tested

Model	Create	Read	Update	Delete	Constraints	Transactions	Status

External Service Tests

Service	Success	Timeout	Error	Rate Limit	Status

Results Summary

• Total tests: N
• Passed: N
• Failed: N (after self-healing)
• Unresolved: N

Self-Healing Log

• Iteration 1: N fixed ([test bugs / app bugs])
• Iteration 2: N fixed
• Iteration 3: N fixed

App Bugs Found and Fixed

Bug	File	Root Cause	Fix

NEXT STEPS:

• "Integration tests passing? Run /e2e for full user-flow end-to-end tests."
• "Run /unit-test if unit coverage is still low."
• "Run /contract-test to validate API schemas against consumers."
• "Run /load-test to verify endpoints handle production traffic."
• "Run /test-suite to see overall test health after adding integration tests."

DO NOT:

• Do NOT run integration tests in parallel unless the test framework supports isolated DB transactions per test.
• Do NOT use production database credentials. Always use test database configuration.
• Do NOT leave test data in the database after tests complete.
• Do NOT mock the database in integration tests. Use a real test database.
• Do NOT skip authentication tests even if the project has no auth yet.
• Do NOT generate tests for third-party library internals.
• Do NOT weaken assertions to make tests pass. Fix the underlying issue.
• Do NOT delete or modify existing tests.

============================================================ SELF-EVOLUTION TELEMETRY

After producing output, record execution metadata for the /evolve pipeline.

Check if a project memory directory exists:

• Look for the project path in ~/.claude/projects/
• If found, append to skill-telemetry.md in that memory directory

Entry format:

### /integration-test — {{YYYY-MM-DD}}
- Outcome: {{SUCCESS | PARTIAL | FAILED}}
- Self-healed: {{yes — what was healed | no}}
- Iterations used: {{N}} / {{N max}}
- Bottleneck: {{phase that struggled or "none"}}
- Suggestion: {{one-line improvement idea for /evolve, or "none"}}

Only log if the memory directory exists. Skip silently if not found. Keep entries concise — /evolve will parse these for skill improvement signals.