Contract Testing with Postman + Newman
Repeatable regression and smoke testing for REST APIs. Validate contracts, catch breaking changes, and ensure API stability across deployments.
Newman CLI Execution Flow
✓ GET /api/schema/:tableId [200 OK, 87ms]
✓ POST /api/validate-sql [200 OK, 156ms]
What is Contract Testing?
Contract testing validates that APIs honor their interface agreements. Instead of testing implementation details, you verify that the contract (request/response schema, status codes, headers) remains consistent.
I use Postman for collection authoring and Newman for CI/CD execution. This provides:
Schema Validation
Ensure response bodies match expected JSON schemas. Catch breaking changes like missing fields or type mismatches.
pm.expect(jsonData.status).to.be.a('string');
Environment-Driven Tests
Run the same collection against dev, staging, and production environments using different variable sets.
Authorization: Bearer {{api_token}}
Real Use Case: Text2SQL Query API Validation
How contract testing caught a breaking response format change before production deployment
Challenge: The Text2SQL Query API had multiple consumers (BI dashboards, Slack integrations, internal analytics tools). A response format change could break all downstream integrations.
Solution: Created a comprehensive Postman collection covering all endpoints:
- Natural language query to SQL translation
- Schema discovery and table metadata
- SQL validation and execution
- Error handling for ambiguous queries
Discovery: During an optimization, a developer changed the generatedSQL field to sql and renamed queryConfidence to confidence. Newman tests failed in CI:
at Object.eval (test-script.js:15)
Impact: Caught the breaking change before merging. The team added backward-compatible aliases and versioned the API response format.
How It Helps
Regression Prevention
Detect breaking changes before they reach production. Every deployment is validated against the contract.
Living Documentation
Postman collections serve as executable documentation. New developers can see how the API works by running tests.
CI/CD Integration
Newman runs in pipelines, blocking deployments if contracts are violated. Automated enforcement with zero manual intervention.