- Home
- JavaScript Testing Frameworks
- WSO2 Contract Test Runner
WSO2 Contract Test Runner
What it is
WSO2 Contract Test Runner is a free, Apache-2.0 licensed library for consumer-based testing of live REST API endpoints. It sends requests and compares returned responses with expectations defined in JSON contracts. A contract can contain a request, expected response, assertions, and optional post-conditions. Supported assertions cover status codes, JSON body and header paths, exact values, regular expressions, emptiness, structure, arrays, and objects. The documented Docker workflow places contract and configuration files in a mounted volume before running tests. Suites can run contracts before or after tests, with before-suite contracts running synchronously. Post-conditions can extract response values into suite-scoped or global environment variables for later contracts, and a contract can pause for a specified number of seconds after assertions. Sample authentication uses bearer authorization and a cookie supplied through environment variables. The example volume layout includes a certificate keystore and client truststore. The README lists XML path support as a todo.
For and against
For
- Free Apache-2.0 licensed library
- Runs tests against live REST endpoints
- Supports detailed JSON assertions
- Allows suite and global environment variables
- Works in self-hosted Docker workflows
Against
- XML path support is listed as a todo
- Contracts use JSON format
- Documented workflow requires Docker and mounted files
- No paid plans are listed
The verdict
Contract Test Runner provides a focused, self-hosted way to verify REST responses against consumer-defined JSON contracts. Teams should account for its JSON scope and listed XML limitation.
Who it suits
This library suits teams that define consumer contracts for live REST APIs and want a free, self-hosted Docker-based test workflow. It is relevant to API consumers and providers using JSON contracts.
Plans and prices
Contract Test Runner
Apache-2.0 licensed library · no paid plans listed
Read 5 Oct 2026 · github.com
On the record
- Assertions
- Supported checks include status codes, JSON body and header paths, exact values, regular expressions, emptiness, structure, arrays, and objects.github.com · read 5 Oct 2026
- Authentication inputs
- The README's sample request uses bearer authorization and a cookie, with values supplied through environment variables.github.com · read 5 Oct 2026
- Contract format
- Contracts are JSON files with request, expected response, assertions, and optional post-conditions.github.com · read 5 Oct 2026
- Docker execution
- The documented workflow runs tests by placing contract and configuration files in a mounted volume and running a Docker image.github.com · read 5 Oct 2026
- Environment variables
- Post-conditions can extract response values into suite-scoped or global environment variables for use by other contracts.github.com · read 5 Oct 2026
- Intended users
- The README describes a framework for testing live API endpoints against consumer-defined contracts.github.com · read 5 Oct 2026
- License
- The repository identifies its license as Apache-2.0.github.com · read 5 Oct 2026
- Maker security
- WSO2's security page lists ISO 27001:2022 certification and SOC 2 Type 2 compliance for the company, but does not specify coverage for this repository.wso2.com · read 5 Oct 2026
- Notable limitation
- The README lists XML path support as a todo.github.com · read 5 Oct 2026
- Purpose
- It is a consumer-based contract testing library that calls live REST API endpoints and compares their responses with predefined contract responses.github.com · read 5 Oct 2026
- Suite setup
- Suite configuration can run contracts before or after tests, and before-suite contracts run synchronously before suite tests.github.com · read 5 Oct 2026
- TLS configuration
- The example volume layout includes a certificate keystore and a client truststore.github.com · read 5 Oct 2026
- Waits
- A contract can specify a wait time in seconds to pause after its assertions finish.github.com · read 5 Oct 2026
