Skip to content
PROPERTY-TESTING-OPENAPI(3)Руководство по PHP-библиотекам rasuvaeffPROPERTY-TESTING-OPENAPI(3)

ИМЯ ​

property-testing-openapi — генерация валидных и невалидных запросов OpenAPI по контракту и проверка их в процессе. Работает вместе с 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();

ОПИСАНИЕ ​

Запросы, сгенерированные из документа OpenAPI, материализованные как PSR-7 и проверенные openapi-contract до того, как попадут в транспорт. Идея Schemathesis, для PHP.

Ручные тесты API покрывают только те примеры, о которых кто-то подумал. Документ OpenAPI уже описывает, что такое валидный запрос, поэтому он может породить и валидные запросы, и невалидные по категориям, и показать, согласны ли обработчик и контракт.

  • Генерирует валидные скалярные значения, массивы и объекты из описанного подмножества JSON Schema.
  • Материализует стили параметров OpenAPI 3 и тела JSON, form-urlencoded и multipart.
  • ContractSuite прогоняет PSR-15 обработчик в процессе через Psr15Transport.
  • Негативные кейсы по категориям: missing-required, type, enum, const, boundary, length, format, pattern.
  • Свидетели значений проверяются через Contract::accepts() до использования.
  • Учётные данные безопасности применяются только при материализации и никогда не хранятся в кейсах или корпусе.
  • OperationProperty работает без изменений под Testo и PHPUnit.
  • OperationCoverage показывает, какие из выбранных операций реально выполнили прогон.
  • Неподдерживаемые конструкции отказывают закрыто, как UnsupportedGeneration.

OPENAPI-CONTRACT ​

openapi-contract можно использовать отдельно. Он проверяет PSR-7 запросы и ответы по OpenAPI 3.0 и 3.1.

  • validateRequest, validateResponse и validateExchange возвращают списки нарушений со стабильными кодами.
  • Нарушения тела содержат instancePath и сработавшее ключевое слово схемы.
  • ContractMiddleware для PSR-15: только наблюдение, строгий режим (400 problem+json) или собственное замыкание.
  • CLI bin/openapi-contract проверяет каталог JSON-фикстур с кодами возврата, удобными для CI.
  • Бюджеты ограничивают размер документа, число узлов, число разрешённых узлов и размер тела сообщения.
  • fromFile разрешает относительные $ref, но отвергает выход за пределы пути, URI-схемы и побеги через симлинки.
  • multipleOf проверяется точно по записанному десятичному числу, с ext-bcmath и без него.
$result = $contract->validateExchange($request, $response);$result->assertValid();throws ContractViolation when violations exist

Ещё примеры

PSR-15 middleware в двух режимах: наблюдающий только фиксирует нарушения, строгий отклоняет запрос.

$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());

CLI проверяет каталог JSON-фикстур по одному контракту и возвращает код выхода для CI.

bash
vendor/bin/openapi-contract openapi.yaml tests/api-fixtures

Лимиты размера задаёт вызывающий код: слишком большое тело по умолчанию отклоняется, лимит можно поднять.

$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());}

ПРИМЕРЫ ​

Набор по контракту прогоняет валидные запросы через PSR-15 обработчик и проверяет, что невалидные не дают 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);

Отчёт покрытия показывает, какие операции затронул набор, и падает, если часть осталась без проверки.

$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;}

Более строгий оракул: невалидный вход должен получать 4XX, для отдельной операции можно задать исключение.

use Rasuvaeff\PropertyTesting\OpenApi\RejectionPolicy; $suite = $suite->rejectionPolicy(    RejectionPolicy::rejectWith('4XX')->forOperation('legacy.get', 200),);

СМОТРИТЕ ТАКЖЕ ​

PackageRole
openapi-contract(3)Валидатор
property-testing-core(3)Движок: генераторы, shrinking, корпус
property-testing-testo(3)Адаптер для Testo
property-testing-phpunit(3)Адаптер для PHPUnit

ОШИБКИ ​

Выбор операций по умолчанию пуст. Операции с небезопасными методами нужно перечислить явно и вызвать allowUnsafeOperations(), иначе будет SuiteConfigurationError. openapi-contract не проверяет объявленную безопасность: запрос без API-ключа проходит валидацию чисто, проверяется только форма обмена. Оба пакета до 1.0.

ЗАВИСИМОСТИ

требует: openapi-contract(3), property-testing-core(3)

ИСТОРИЯ

Первый релиз v0.1.0 — 2026-08-29, всего релизов: 27.

v0.19.22026-11-04
v0.19.12026-11-04
v0.19.02026-10-11
v0.18.02026-09-29
v0.17.02026-09-20
v0.16.02026-09-19
v0.15.22026-09-19
v0.15.12026-09-19
v0.15.02026-09-19
v0.14.12026-09-17

… и ещё 17 раньше. Все релизы

rasuvaeff/property-testing-openapi 0.19.2мутационный порог 91%PROPERTY-TESTING-OPENAPI(3)

/ поиск · n N следующее, предыдущее · g G начало, конец · q к индексу