property-testing-openapi — generate valid and invalid OpenAPI requests from a contract and check them in-process. With openapi-contract
$ composer require --dev rasuvaeff/property-testing-openapi
$contract = Contract::fromArray($document);$operation = $contract->operation('pets.get');$case = (new RequestCaseArbitrary())->forOperation($operation)->generate(new Random(42))->value;$request = (new RequestMaterializer(new Psr17Factory(), new Psr17Factory()))->materialize($operation, $case); $contract->validateRequest($request)->assertValid();
Request cases generated from an OpenAPI document, materialized as PSR-7 and checked by openapi-contract before they reach a transport. The idea behind Schemathesis, for PHP.
Hand-written API tests cover the examples someone thought of. The OpenAPI document already says what a valid request is, so it can also produce the valid ones, and the invalid ones by category, and show whether the handler and the contract agree.
ContractSuite drives a PSR-15 handler in process through Psr15Transport.Contract::accepts() before they are used.OperationProperty runs unchanged under Testo and PHPUnit.OperationCoverage reports which selected operations actually ran a trial.UnsupportedGeneration.openapi-contract is usable on its own. It validates PSR-7 requests and responses against OpenAPI 3.0 and 3.1.
validateRequest, validateResponse and validateExchange return violation lists with stable codes.instancePath and the failed schema keyword.ContractMiddleware for PSR-15: observe-only, strict (400 problem+json) or a custom closure.bin/openapi-contract, validates a directory of JSON fixtures with CI-friendly exit codes.fromFile resolves relative $refs but rejects path traversal, URI schemes and symlink escapes.multipleOf is judged exactly on the spelled decimal, with or without ext-bcmath.$result = $contract->validateExchange($request, $response);$result->assertValid();throws ContractViolation when violations exist
More examples
A PSR-15 middleware in two modes: observe-only logs violations, strict refuses the request.
$contract = Contract::fromFile(__DIR__ . '/openapi/pets.yaml'); $observing = new ContractMiddleware( $contract, static function (array $violations, ServerRequestInterface $request) use ($formatter): ?ResponseInterface { echo 'observed on ', $request->getMethod(), ' ', $request->getUri(), ":\n", $formatter->format(new ValidationResult($violations)), "\n\n"; return null; },);$strict = ContractMiddleware::strict($contract, new Psr17Factory());
A CLI runner validates a directory of JSON fixtures against one contract and returns a CI-friendly exit code.
vendor/bin/openapi-contract openapi.yaml tests/api-fixturesSize budgets are caller policy: an oversized body is refused by default, raised on request.
$result = Contract::fromArray($document)->validateExchange($request, $big);printf("default budget -> %s\n", $result->violations[0]->code); $raised = Contract::fromArray($document, new Limits(messageBodyBytes: 8 * 1024 * 1024));printf("messageBodyBytes 8M -> %s\n", $raised->validateExchange($request, $big)->isValid() ? 'valid' : 'invalid'); try { Contract::fromArray($document, new Limits(documentNodes: 5));} catch (InvalidContract $exception) { printf("documentNodes 5 -> %s\n", $exception->getMessage());}
A contract suite sends generated valid requests through a PSR-15 handler and checks invalid ones never cause a 5xx.
$suite = ContractSuite::fromContract($contract, $factory, $factory) ->operations(['pets.get']) ->transport(new Psr15Transport($handler, $factory)); foreach ([1, 2, 3] as $seed) { $suite->checkValid('pets.get', $suite->validCases('pets.get')->generate(new Random($seed))->value);} $negative = $suite->negativeCases('pets.get')->generate(new Random(5))->value;$suite->checkNegative('pets.get', $negative);
A coverage report shows which operations the suite exercised and fails when some were left untested.
$coverage = new OperationCoverage(); $suite = ContractSuite::fromContract($contract, $factory, $factory) ->allSafeOperations() ->coverage($coverage) ->transport(new CallableTransport(static fn(): Response => new Response(204))); $report = $suite->coverageReport();echo $report->toJson() . PHP_EOL; try { $report->assertComplete();} catch (CoverageIncomplete $incomplete) { echo $incomplete->getMessage() . PHP_EOL;}
A stricter oracle: invalid input must be answered with 4XX, with a per-operation exception.
use Rasuvaeff\PropertyTesting\OpenApi\RejectionPolicy; $suite = $suite->rejectionPolicy( RejectionPolicy::rejectWith('4XX')->forOperation('legacy.get', 200),);
| Package | Role |
|---|---|
| openapi-contract(3) | The validator |
| property-testing-core(3) | The engine: generators, shrinking, corpus |
| property-testing-testo(3) | Testo adapter |
| property-testing-phpunit(3) | PHPUnit adapter |
The default operation selection is empty. Unsafe-method operations need explicit listing plus allowUnsafeOperations(), otherwise SuiteConfigurationError. openapi-contract does not enforce declared security: a request missing its API key validates clean, only the exchange shape is checked. Both packages are pre-1.0.
requires: openapi-contract(3), property-testing-core(3)
First released as v0.1.0 on 2026-08-29; 27 releases in all.
| v0.19.2 | 2026-11-04 |
| v0.19.1 | 2026-11-04 |
| v0.19.0 | 2026-10-11 |
| v0.18.0 | 2026-09-29 |
| v0.17.0 | 2026-09-20 |
| v0.16.0 | 2026-09-19 |
| v0.15.2 | 2026-09-19 |
| v0.15.1 | 2026-09-19 |
| v0.15.0 | 2026-09-19 |
| v0.14.1 | 2026-09-17 |
… and 17 earlier. All releases
/ search · n N next, previous · g G top, bottom · q back to the index