Add JSON payload contract assertions

[SoftCreatR]

This adds optional integration with softcreatr/json-payload-contract for validating and normalizing REST responses.

Two new actions are available:

$I->seeResponseMatchesJsonPayloadContract($contract);

$data = $I->grabDataFromResponseByJsonPayloadContract($contract);

The assertion reports all contract violations, including the affected output field, stable violation code, message, and selector where available.

Motivation

JSON Schema verifies the structure of a response, while JSONPath extracts individual values. JSON Payload Contract complements both by allowing tests to:

• extract a stable application-facing shape from changing API responses;
• support old and new response paths through ordered fallbacks;
• validate types, cardinality, and constraints;
• normalize values before reusing them in subsequent test steps;
• report all independent contract violations in one assertion.

Compatibility

The integration is optional and does not change the module’s PHP 8.2 requirement.

softcreatr/json-payload-contract requires PHP 8.3 or newer, so it is listed under Composer suggestions and installed in CI only for PHP 8.3–8.5. Existing users and PHP 8.2 installations are unaffected.

Installation:

composer require --dev softcreatr/json-payload-contract:^1.0

Example

use SoftCreatR\JsonPayloadContract\Contract;
use SoftCreatR\JsonPayloadContract\Field;

$contract = Contract::define([
    'id' => Field::required('$.data.user.id')
        ->fallback('$.user.id')
        ->integer(),
    'email' => Field::required('$.data.user.email')
        ->fallback('$.user.email')
        ->string()
        ->email(),
]);

$I->seeResponseMatchesJsonPayloadContract($contract);

$user = $I->grabDataFromResponseByJsonPayloadContract($contract);

Verification

• PHP 8.2 with normal and lowest dependencies: existing suite passes; optional integration tests are skipped.
• PHP 8.3 with normal and lowest dependencies: all 136 tests pass.
• PHP 8.5: all 136 tests and 359 assertions pass.
• Composer validation and PHP syntax checks pass