Skip to content
SPECIFICTION
Get listed

WSO2 Contract Test Runner

github.com

Free plan LinuxSelf-hosted
Visit github.com
Spec score 7.1 #19 of 23 in JavaScript Testing Frameworks

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 data with expected responses defined in JSON contracts. A contract can include a request, expected response, assertions, and optional post-conditions. Assertions cover status codes, JSON body and header paths, exact values, regular expressions, emptiness, structures, arrays, and objects. Tests run through Docker by mounting contract and configuration files into the documented image workflow. Suites can run contracts before or after tests, with before-suite contracts running synchronously. Post-conditions can place extracted values into suite-scoped or global environment variables, and contracts can pause for a specified number of seconds. The sample setup uses bearer authorization, cookies, a certificate keystore, and a client truststore. XML path support is listed as a todo. Deployment is Linux and self-hosted.

Spec sheet

Purpose
It is a consumer-based contract testing library that calls live REST API endpoints and compares their responses with predefined contract responses.Read 5 Oct 2026 · github.com
Intended users
The README describes a framework for testing live API endpoints against consumer-defined contracts.Read 5 Oct 2026 · github.com
License
The repository identifies its license as Apache-2.0.Read 5 Oct 2026 · github.com
Assertions
Supported checks include status codes, JSON body and header paths, exact values, regular expressions, emptiness, structure, arrays, and objects.Read 5 Oct 2026 · github.com
Authentication inputs
The README's sample request uses bearer authorization and a cookie, with values supplied through environment variables.Read 5 Oct 2026 · github.com
Contract format
Contracts are JSON files with request, expected response, assertions, and optional post-conditions.Read 5 Oct 2026 · github.com
Docker execution
The documented workflow runs tests by placing contract and configuration files in a mounted volume and running a Docker image.Read 5 Oct 2026 · github.com
Environment variables
Post-conditions can extract response values into suite-scoped or global environment variables for use by other contracts.Read 5 Oct 2026 · github.com
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.Read 5 Oct 2026 · wso2.com
Notable limitation
The README lists XML path support as a todo.Read 5 Oct 2026 · github.com
Suite setup
Suite configuration can run contracts before or after tests, and before-suite contracts run synchronously before suite tests.Read 5 Oct 2026 · github.com
TLS configuration
The example volume layout includes a certificate keystore and a client truststore.Read 5 Oct 2026 · github.com
Waits
A contract can specify a wait time in seconds to pause after its assertions finish.Read 5 Oct 2026 · github.com

Plans and prices

Contract Test Runner Free Apache-2.0 licensed library · no paid plans listed Read 5 Oct 2026 · github.com

Every WSO2 Contract Test Runner plan and price →

Strong points and limits

Strong points

  • Free open-source Apache-2.0 library
  • Checks live REST endpoints against JSON contracts
  • Runs in Docker with mounted files
  • Supports extensive response assertions
  • Shares extracted values through environment variables

Limits

  • XML path support is listed as unfinished
  • Requires self-hosted Linux deployment
  • No paid plans or free trial are listed

Who it suits

It suits developers and test teams verifying live REST APIs against consumer-defined contracts. Self-hosted teams comfortable with Docker and JSON configuration can use its workflow.

Verdict

Contract Test Runner focuses on consumer verification of live REST APIs, with detailed assertions and suite orchestration. Its Docker workflow and JSON contracts are clearly described, while XML path checking remains incomplete.

Where Specifiction places it

Alternatives to WSO2 Contract Test RunnerAll alternatives →