alphaonedev/testing-integration

Purpose

This skill facilitates integration testing for APIs and services, focusing on tools like Supertest (Node.js), httpx (Python), Testcontainers for managing test environments, and Pact for contract testing. It ensures end-to-end verification of service interactions, database integrations, and API contracts.

When to Use

Use this skill when verifying API endpoints in a real environment, testing service integrations (e.g., with databases or external services), running containerized tests, or enforcing contracts between microservices. Apply it in CI/CD pipelines for regression testing or when mocking dependencies is insufficient.

Key Capabilities

• Perform HTTP API testing with Supertest for Node.js apps, including mocking and assertions.
• Use httpx in Python for asynchronous HTTP requests and integration with databases.
• Manage test containers via Testcontainers to spin up isolated environments (e.g., Docker-based databases).
• Conduct contract testing with Pact to define and verify API provider-consumer agreements.
• Support for service integration testing, such as linking APIs to external services or databases.

Usage Patterns

To use this skill, first install required dependencies (e.g., via npm or pip). Set up test files in your project, configure environments with variables like $API_BASE_URL, and run tests using a test runner. For API tests, structure code to send requests and assert responses. For contract testing, define pacts in separate files and verify them against providers. Always isolate tests with containers to avoid side effects. Example pattern: Import the tool, define a test function, send requests, and handle assertions within 2-3 lines.

Common Commands/API

• Supertest (Node.js): Use supertest to test Express apps. Command: npm install supertest. Code snippet:

  const request = require('supertest');
  const app = require('./app');
  request(app).get('/api/users').expect(200);
  

  CLI flag: Run with npx jest --runInBand for sequential tests.
• httpx (Python): For async HTTP testing. Command: pip install httpx. Code snippet:

  import httpx
  response = httpx.get('http://example.com/api/data', headers={'Authorization': f'Bearer {os.environ.get("API_KEY")}'}).json()
  assert response['status'] == 'success'
  

  API endpoint: Pass URLs like https://api.service.com/endpoint with query params (e.g., ?limit=10).
• Testcontainers: Spin up containers for integration. Command: Add to pom.xml or requirements. Code snippet:

  GenericContainer container = new GenericContainer("postgres:13").withExposedPorts(5432);
  container.start();
  String jdbcUrl = container.getJdbcUrl();
  

  Config format: Use Docker image specs in YAML, e.g., image: postgres:13 with env vars like $DB_PASSWORD.
• Pact (Contract Testing): Define and verify contracts. Command: npm install @pact-foundation/pact or pip install pact-python. Code snippet:

  const { Pact } = require('@pact-foundation/pact');
  const pact = new Pact({ consumer: 'MyConsumer', provider: 'MyProvider' });
  pact.addInteraction({ state: 'default', uponReceiving: 'a request' });
  

  API: Use endpoints like /pacts/provider/MyProvider/consumer/MyConsumer/verification for verification, with auth via $PACT_BROKER_TOKEN.

Integration Notes

Integrate this skill by adding it to your build tools: For Node.js, include in Jest or Mocha configs; for Python, use pytest fixtures. Set env vars like $DATABASE_URL for database connections or $SERVICE_API_KEY for authenticated requests. For container integration, ensure Docker is installed and use Testcontainers to link services (e.g., expose ports via withExposedPorts(8080)). When combining with Pact, publish pacts to a broker (e.g., via pact-broker publish --broker-url=$PACT_BROKER_URL). Config format: Use JSON for Pact files, e.g., { "interactions": [...] }, and ensure compatibility with CI tools like GitHub Actions by adding steps like run: docker-compose up -d.

Error Handling

Handle errors by wrapping requests in try-catch blocks. For Supertest, check response status and body: e.g., if .expect(200) fails, log the error with console.error(response.error). In httpx, catch httpx.HTTPError for network issues, e.g.:

try:
    response = httpx.get(url)
    response.raise_for_status()
except httpx.HTTPError as e:
    print(f"Error: {e} - Check $API_BASE_URL")

For Testcontainers, verify container startup with container.isRunning() before tests. In Pact, use pact.verify() and handle mismatches by reviewing pact files. Common patterns: Use env vars for retries (e.g., $RETRY_COUNT=3) and log detailed errors with stack traces.

Concrete Usage Examples

1. API Integration Test with Supertest: To test a user endpoint in a Node.js app with a database, first set $DB_URL=postgres://user:pass@localhost:5432/db. Write a test file: Import Supertest, send a GET request, and assert the response. Run with npx jest tests/integration.test.js. This verifies the API connects to the database and returns data.

2. Contract Test with Pact: For a consumer-provider setup, define a pact in a file (e.g., pacts/my-pact.json) with interactions. Use pact.verify() against the provider endpoint (e.g., http://provider.com), passing $PACT_BROKER_TOKEN. Run via npx pact-verifier --provider-base-url=$PROVIDER_URL. This ensures the consumer's expectations match the provider's implementation.

Graph Relationships

• Related to cluster: "testing" (e.g., shares tags with unit-testing skills).
• Connected to skills: "api-development" via integration-test tag for API workflows.
• Links to: "contract-management" through contract-test tag for Pact-based verification.
• Associated with: "database-integration" due to test containers for database testing.