API Testing Patterns

Tools: Pact, Spring Cloud Contract

When to use: Microservices, distributed systems, third-party integrations

2. Integration Testing

Purpose: Verify API works with real dependencies (database, external services).

Pattern: Test with Real Dependencies

describe("Order API integration", () => {
  beforeEach(async () => {
    await db.migrate();
    await db.seed();
  });

  afterEach(async () => {
    await db.rollback();
  });

  it("creates order and updates inventory", async () => {
    const response = await api.post("/orders", {
      productId: "product-123",
      quantity: 2,
    });

    expect(response.status).toBe(201);

    // Verify side effects
    const inventory = await db.inventory.findById("product-123");
    expect(inventory.quantity).toBe(8); // Was 10, now 8
  });
});

When to use: Testing business logic that spans multiple components

3. Component Testing

Purpose: Test API in isolation with mocked dependencies.

Pattern: Mock External Dependencies

describe("Order API component", () => {
  it("handles payment service timeout", async () => {
    const paymentService = mockPaymentService({
      charge: () => {
        throw new TimeoutError();
      },
    });

    const api = createAPI({ paymentService });
    const response = await api.post("/orders", orderData);

    expect(response.status).toBe(503);
    expect(response.body.error).toBe("Payment service unavailable");
  });
});

When to use: Testing error handling, edge cases, without hitting real services

Critical Test Scenarios

Authentication & Authorization

describe("Authentication", () => {
  it("rejects requests without token", async () => {
    const response = await api.get("/orders");
    expect(response.status).toBe(401);
  });

  it("rejects requests with expired token", async () => {
    const expiredToken = generateExpiredToken();
    const response = await api.get("/orders", {
      headers: { Authorization: `Bearer ${expiredToken}` },
    });
    expect(response.status).toBe(401);
  });

  it("allows access only to authorized resources", async () => {
    const userAToken = generateToken({ userId: "A" });
    const response = await api.get("/orders/user-B-order", {
      headers: { Authorization: `Bearer ${userAToken}` },
    });
    expect(response.status).toBe(403);
  });
});

Input Validation

describe("Input validation", () => {
  it("validates required fields", async () => {
    const response = await api.post("/orders", {
      // Missing productId
      quantity: 2,
    });
    expect(response.status).toBe(400);
    expect(response.body.errors).toContain("productId is required");
  });

  it("validates data types", async () => {
    const response = await api.post("/orders", {
      productId: "abc",
      quantity: "two", // Should be number
    });
    expect(response.status).toBe(400);
  });

  it("validates value ranges", async () => {
    const response = await api.post("/orders", {
      productId: "abc",
      quantity: -5, // Negative quantity
    });
    expect(response.status).toBe(400);
  });
});

Error Handling

describe("Error handling", () => {
  it("handles database connection failure", async () => {
    db.disconnect();
    const response = await api.get("/orders");
    expect(response.status).toBe(503);
    expect(response.body.error).toMatch(/service unavailable/i);
  });

  it("handles malformed JSON", async () => {
    const response = await fetch("/orders", {
      method: "POST",
      body: "not-json",
    });
    expect(response.status).toBe(400);
  });

  it("handles unexpected errors gracefully", async () => {
    // Simulate internal error
    orderService.create = () => {
      throw new Error("Unexpected");
    };

    const response = await api.post("/orders", validOrder);
    expect(response.status).toBe(500);
    expect(response.body.error).not.toContain("Unexpected"); // Don't leak internals
  });
});

Idempotency

describe("Idempotent operations", () => {
  it("PUT is idempotent", async () => {
    const updateData = { status: "shipped" };

    await api.put("/orders/123", updateData);
    const response = await api.put("/orders/123", updateData);

    expect(response.status).toBe(200);
    // Verify state hasn't changed incorrectly
  });

  it("POST with idempotency key prevents duplicates", async () => {
    const idempotencyKey = "unique-key-123";
    const orderData = { productId: "abc", quantity: 2 };

    const response1 = await api.post("/orders", orderData, {
      headers: { "Idempotency-Key": idempotencyKey },
    });

    const response2 = await api.post("/orders", orderData, {
      headers: { "Idempotency-Key": idempotencyKey },
    });

    expect(response1.body.orderId).toBe(response2.body.orderId);
    // Verify only one order was created
  });
});

Concurrency

describe("Concurrent requests", () => {
  it("handles race condition on inventory update", async () => {
    const promises = Array(10)
      .fill()
      .map(() => api.post("/orders", { productId: "abc", quantity: 1 }));

    const responses = await Promise.all(promises);
    const successful = responses.filter((r) => r.status === 201);

    // Verify inventory wasn't oversold
    const inventory = await db.inventory.findById("abc");
    expect(inventory.quantity).toBe(initialQuantity - successful.length);
  });
});

REST API Testing Patterns

CRUD Operations

describe("Product CRUD", () => {
  let productId;

  it("CREATE: creates new product", async () => {
    const response = await api.post("/products", {
      name: "Widget",
      price: 10.0,
    });
    expect(response.status).toBe(201);
    expect(response.headers.location).toMatch(/\/products\/\w+/);
    productId = response.body.id;
  });

  it("READ: retrieves product", async () => {
    const response = await api.get(`/products/${productId}`);
    expect(response.status).toBe(200);
    expect(response.body.name).toBe("Widget");
  });

  it("UPDATE: modifies product", async () => {
    const response = await api.put(`/products/${productId}`, {
      name: "Widget",
      price: 12.0,
    });
    expect(response.status).toBe(200);
    expect(response.body.price).toBe(12.0);
  });

  it("DELETE: removes product", async () => {
    const response = await api.delete(`/products/${productId}`);
    expect(response.status).toBe(204);

    const getResponse = await api.get(`/products/${productId}`);
    expect(getResponse.status).toBe(404);
  });
});

Pagination

describe("Pagination", () => {
  it("returns first page by default", async () => {
    const response = await api.get("/products");
    expect(response.body.items).toHaveLength(20); // Default page size
    expect(response.body.page).toBe(1);
  });

  it("supports custom page size", async () => {
    const response = await api.get("/products?pageSize=50");
    expect(response.body.items).toHaveLength(50);
  });

  it("includes pagination metadata", async () => {
    const response = await api.get("/products");
    expect(response.body).toHaveProperty("totalItems");
    expect(response.body).toHaveProperty("totalPages");
    expect(response.body).toHaveProperty("nextPage");
  });
});

Filtering & Sorting

describe("Filtering and sorting", () => {
  it("filters by category", async () => {
    const response = await api.get("/products?category=electronics");
    expect(response.body.items.every((p) => p.category === "electronics")).toBe(true);
  });

  it("sorts by price ascending", async () => {
    const response = await api.get("/products?sort=price:asc");
    const prices = response.body.items.map((p) => p.price);
    expect(prices).toEqual([...prices].sort((a, b) => a - b));
  });

  it("combines multiple filters", async () => {
    const response = await api.get("/products?category=electronics&minPrice=100");
    expect(response.body.items.every((p) => p.category === "electronics" && p.price >= 100)).toBe(
      true
    );
  });
});

GraphQL Testing Patterns

describe("GraphQL API", () => {
  it("queries nested data", async () => {
    const query = `
      query {
        order(id: "123") {
          id
          items {
            product {
              name
              price
            }
            quantity
          }
          total
        }
      }
    `;

    const response = await graphql.query(query);
    expect(response.data.order.items).toBeDefined();
  });

  it("handles query complexity limits", async () => {
    const complexQuery = `
      query {
        orders {
          items {
            product {
              reviews {
                author {
                  orders { ... }
                }
              }
            }
          }
        }
      }
    `;

    const response = await graphql.query(complexQuery);
    expect(response.errors[0].message).toMatch(/query too complex/i);
  });
});

Performance Testing

describe("API performance", () => {
  it("responds within acceptable time", async () => {
    const start = Date.now();
    await api.get("/products");
    const duration = Date.now() - start;

    expect(duration).toBeLessThan(200); // 200ms SLA
  });

  it("handles load of 100 concurrent requests", async () => {
    const requests = Array(100)
      .fill()
      .map(() => api.get("/products"));
    const responses = await Promise.all(requests);

    const successful = responses.filter((r) => r.status === 200);
    expect(successful.length).toBeGreaterThan(95); // 95% success rate
  });
});

Testing Tools

REST APIs

• Supertest (Node.js) - HTTP assertions
• REST-assured (Java) - Fluent API testing
• Postman/Newman - Collection-based testing
• Playwright API - E2E with API calls

Contract Testing

• Pact - Consumer-driven contracts
• Spring Cloud Contract - JVM contract testing

Load Testing

• k6 - Modern load testing
• Apache JMeter - Enterprise load testing
• Artillery - Modern performance testing

Common Pitfalls

❌ Testing Implementation, Not Contract

Don't test internal database queries. Test the API response.

❌ Ignoring HTTP Semantics

Use correct status codes (200, 201, 400, 404, 500) and methods (GET, POST, PUT, DELETE).

❌ No Negative Testing

Always test error cases, not just happy paths.

❌ Brittle Tests

Don't assert on field order or extra fields. Focus on contract.

❌ Slow Tests

Mock external services. Don't wait for real third-party APIs.

Best Practices

✅ Test from Consumer Perspective

Write tests as if you're using the API, not implementing it.

✅ Use Schema Validation

Validate response structure, not exact values.

✅ Test Error Scenarios

Network failures, timeouts, invalid input, authorization errors.

✅ Version Your API Tests

Keep tests for each API version to prevent breaking changes.

✅ Automate in CI/CD

Run API tests on every commit, not just before release.

Real-World Example: E-Commerce API

describe("E-Commerce Order API", () => {
  describe("Happy path", () => {
    it("complete order flow", async () => {
      // Add to cart
      const cart = await api.post("/cart", { productId: "abc", quantity: 2 });

      // Apply discount
      await api.post("/cart/discount", { code: "SAVE10" });

      // Checkout
      const order = await api.post("/orders", {
        cartId: cart.body.id,
        payment: { method: "card", token: "tok_123" },
      });

      expect(order.status).toBe(201);
      expect(order.body.status).toBe("pending");
    });
  });

  describe("Edge cases", () => {
    it("handles out of stock during checkout", async () => {
      // Product sold out between cart and checkout
      const order = await api.post("/orders", {
        cartId: "cart-with-sold-out-item",
      });

      expect(order.status).toBe(409); // Conflict
      expect(order.body.error).toMatch(/out of stock/i);
    });
  });
});

Using with QE Agents

Automated Contract Testing

qe-api-contract-validator ensures API contracts are maintained:

// Agent validates API contract against specification
await agent.validateContract({
  spec: "openapi.yaml",
  endpoint: "/orders",
  method: "POST",
  checkBreakingChanges: true,
});

// Returns:
// {
//   valid: false,
//   breakingChanges: [
//     'Field "orderId" changed from string to number'
//   ],
//   warnings: ['New optional field "metadata" added']
// }

Agent-Generated API Test Suites

qe-test-generator creates comprehensive API tests:

// Generate tests from OpenAPI spec
await agent.generateFromSpec({
  spec: "openapi.yaml",
  coverage: "comprehensive",
  include: [
    "happy-paths",
    "input-validation",
    "auth-scenarios",
    "error-handling",
    "idempotency",
    "concurrency",
  ],
});

// → Creates 200+ tests covering all API patterns

Real-Time API Test Execution

qe-test-executor runs API tests with smart retry logic:

// Execute API tests with intelligent retry for flakiness
await agent.executeAPITests({
  suite: "integration",
  parallel: true,
  retryStrategy: "exponential-backoff",
  flakyDetection: true,
});

// → Detects and reports network-related flakiness
// → Auto-retries transient failures (503, timeout)
// → Fails fast on persistent errors (401, 404)

Contract-Based Integration Testing

// Agent coordinates contract testing between services
const contractFleet = await FleetManager.coordinate({
  strategy: "contract-testing",
  agents: [
    "qe-api-contract-validator", // Validate contracts
    "qe-test-generator", // Generate consumer tests
    "qe-test-executor", // Execute against provider
  ],
  topology: "mesh", // Consumer-provider pairs
});

// Microservices contract validation
await contractFleet.execute({
  services: [
    { name: "orders-api", consumers: ["checkout-ui", "admin-api"] },
    { name: "payment-api", consumers: ["orders-api"] },
  ],
});

Performance Testing for APIs

qe-performance-tester load tests critical endpoints:

// Agent runs load tests on API endpoints
await agent.loadTest({
  endpoint: "/orders",
  method: "POST",
  rps: 1000, // 1000 requests per second
  duration: "5min",
  scenarios: ["create-order", "concurrent-checkouts", "bulk-operations"],
});

// Returns:
// {
//   avgResponseTime: '45ms',
//   p95: '120ms',
//   p99: '250ms',
//   errorRate: 0.02,  // 2% error rate
//   bottlenecks: ['database connection pool']
// }

Security Testing for APIs

qe-security-scanner tests API vulnerabilities:

// Agent scans for API security issues
await agent.scanAPI({
  spec: "openapi.yaml",
  checks: [
    "sql-injection",
    "xss",
    "broken-auth",
    "excessive-data-exposure",
    "rate-limiting",
    "input-validation",
  ],
});

// Identifies:
// - Missing rate limiting on /login
// - No input sanitization on /search
// - Exposed internal IDs in responses

Continuous Contract Monitoring

qe-production-intelligence monitors live API contracts:

// Agent monitors production API for contract drift
await agent.monitorAPIContract({
  endpoint: "/orders",
  spec: "openapi.yaml",
  alertOn: "breaking-changes",
  sampleRate: 0.01, // Monitor 1% of traffic
});

// Alerts:
// "⚠️  Production API returning extra field not in spec: 'internalProcessId'"
// "🔴 Breaking change detected: 'quantity' changed from int to string"

Related Skills

Core Quality Practices:

• agentic-quality-engineering - API testing with agent coordination
• holistic-testing-pact - APIs in test quadrants

Testing Approaches:

• test-automation-strategy - API tests in automation pyramid
• risk-based-testing - Risk-based API test prioritization
• performance-testing - API load testing patterns
• security-testing - API security validation

Development Practices:

• tdd-london-chicago - London school for API testing (mocking)
• code-review-quality - Review API test quality

Remember

API testing is about verifying contracts and behavior, not implementation details. Focus on what matters to API consumers: correct responses, proper error handling, and acceptable performance.

With Agents: Agents automate contract validation, generate comprehensive API test suites from specifications, and continuously monitor production APIs for contract drift. Use agents to maintain API quality across microservices at scale.