Feature Guide

A quick orientation block that answers the essential questions: what this feature does, how it works, why it matters, and the key concepts behind it.

What this does

Automated contract testing for payloads — #[TestablePayload] marks a payload for strategy-based validation.

How it works

The testing framework discovers testable payloads, applies strategy profiles (Standard, Strict, Paranoid), and runs security, type enforcement, and monkey testing strategies against each endpoint.

Why it matters

Contract tests verify that payloads reject bad input and accept good input without writing individual test cases. Strategy profiles let teams choose their risk tolerance.

Key concepts

#[TestablePayload]: Marks a payload for automated contract testing with configurable strategies.
MonkeyTestingStrategy: Sends random/malformed input to test endpoint robustness.

Contract Testing

One scaffolded suite can exercise every testable payload

Instead of hand-writing the same validation and bad-input cases for every endpoint, Semitexa lets payloads declare their testing strategies and runs the composed suite through a shared transport.

Scaffold once. test:init creates the universal ProjectPayloadsContractTest that auto-discovers payloads marked with #[TestablePayload].

Choose a profile. Strict and Paranoid profiles expand into concrete strategies like method checks, type mutation, security assertions, and monkey input.

Run through real transport. The contract tester sends actual requests and reports which strategy or generated case failed instead of hiding everything in custom helpers.

Command	Purpose	Why it matters
`bin/semitexa test:init`	Scaffold the universal payload contract test into tests/Payload.	Gives the project one canonical entrypoint for payload boundary verification.
`bin/semitexa test:run -- --filter ProjectPayloadsContractTest`	Run only the generated contract suite inside the dev Docker stack.	Keeps feedback focused while expanding coverage across all marked payloads.
`bin/semitexa test:run -- --testdox`	Forward normal PHPUnit flags through the Semitexa wrapper.	Developers keep PHPUnit ergonomics while preserving the project container setup.

Mark a payload as contract-testable

#[AsPublicPayload(path: '/api/payments', methods: ['POST'])]
#[TestablePayload(
    strategies: [StrictProfileStrategy::class, ParanoidProfileStrategy::class],
    context: ['fail_fast' => false],
)]
final class PaymentPayload {}

Scaffold and run the suite

bin/semitexa test:init
bin/semitexa test:run -- --filter ProjectPayloadsContractTest

What Paranoid profile expands to

ParanoidProfileStrategy::class => [
    SecurityStrategy::class,
    HttpMethodStrategy::class,
    TypeEnforcementStrategy::class,
    MonkeyTestingStrategy::class,
]

test:run StrictProfileStrategy

Verified against Semitexa Ultimate 2026.09.19.1020

Payload Contract Testing

Automated contract testing for payloads -- #[TestablePayload] marks a payload for strategy-based validation.

How it works

The testing framework discovers testable payloads, applies strategy profiles (Standard, Strict, Paranoid), and runs security, type enforcement, and monkey testing strategies against each endpoint. The semitexa-testing package ships its own ProjectPayloadsContractTest integration test, and the canonical runner bin/semitexa test:run appends that suite automatically from vendor/semitexa/testing/tests/Integration/ProjectPayloadsContractTest.php in consuming projects. That keeps payload-contract coverage enabled without scaffolding a root-level tests/ bucket, but it also means direct vendor/bin/phpunit runs are not the supported entry point.

Why this matters

Contract tests verify that payloads reject bad input and accept good input without writing individual test cases. Strategy profiles let teams choose their risk tolerance -- Strict catches common boundary mistakes, while Paranoid adds monkey input and deeper type mutation coverage.

1<?php23declare(strict_types=1);45namespace Semitexa\Testing\Attributes;67use Attribute;89/**10 * Declares testing strategies for a PayloadDTO class.11 *12 * Intentionally separate from #[AsPayload] to avoid loading test classes13 * during production bootstrap (SRP — routing ≠ testing).14 *15 * Example:16 * ```php17 * #[AsProtectedPayload(path: '/api/payments', methods: ['POST'])]18 * #[TestablePayload(19 *     strategies: [ParanoidProfileStrategy::class],20 *     context: [21 *         'auth_header'    => 'Authorization',22 *         'auth_scheme'    => 'Bearer',23 *         'token_provider' => TestTokenProvider::class,24 *     ]25 * )]26 * class PaymentPayload implements PayloadInterface { }27 * ```28 *29 * The `context` map is passed as-is to each strategy via PayloadMetadata::$context.30 * Each strategy reads only the keys it cares about; unknown keys are ignored.31 */32#[Attribute(Attribute::TARGET_CLASS)]33final class TestablePayload34{35    /**36     * @param list<class-string<\Semitexa\Testing\Contract\TestingStrategyInterface>> $strategies37     * @param array<string, mixed> $context  Per-strategy configuration (auth tokens, flags, etc.)38     */39    public function __construct(40        public readonly array $strategies = [],41        public readonly array $context = [],42    ) {}43}44

<?php

declare(strict_types=1);

namespace Semitexa\Testing\Attributes;

use Attribute;

/**
 * Declares testing strategies for a PayloadDTO class.
 *
 * Intentionally separate from #[AsPayload] to avoid loading test classes
 * during production bootstrap (SRP — routing ≠ testing).
 *
 * Example:
 * ```php
 * #[AsProtectedPayload(path: '/api/payments', methods: ['POST'])]
 * #[TestablePayload(
 *     strategies: [ParanoidProfileStrategy::class],
 *     context: [
 *         'auth_header'    => 'Authorization',
 *         'auth_scheme'    => 'Bearer',
 *         'token_provider' => TestTokenProvider::class,
 *     ]
 * )]
 * class PaymentPayload implements PayloadInterface { }
 * ```
 *
 * The `context` map is passed as-is to each strategy via PayloadMetadata::$context.
 * Each strategy reads only the keys it cares about; unknown keys are ignored.
 */
#[Attribute(Attribute::TARGET_CLASS)]
final class TestablePayload
{
    /**
     * @param list<class-string<\Semitexa\Testing\Contract\TestingStrategyInterface>> $strategies
     * @param array<string, mixed> $context  Per-strategy configuration (auth tokens, flags, etc.)
     */
    public function __construct(
        public readonly array $strategies = [],
        public readonly array $context = [],
    ) {}
}

1<?php23declare(strict_types=1);45namespace Semitexa\Testing;67use Semitexa\Testing\Contract\TestingProfileInterface;8use Semitexa\Testing\Contract\TestingStrategyInterface;9use Semitexa\Testing\Contract\TransportInterface;10use Semitexa\Testing\Data\ContractTestResult;11use Semitexa\Testing\Data\PayloadMetadata;12use Semitexa\Testing\Data\StrategyResult;1314/**15 * Orchestrates the execution of all declared strategies against a PayloadDTO.16 *17 * Execution model:18 *   - Sequential strategy execution (predictable output order).19 *   - Fail-safe by default: all strategies run even if one fails.20 *   - Fail-fast: configurable via context['fail_fast'] = true.21 *   - Profiles are expanded into sub-strategies before execution (recursive, deduplicated).22 *   - Skipped strategies (canRun() = false) are reported as SKIPPED, not FAILED.23 */24final class PayloadContractTester25{26    public function __construct(27        private readonly TransportInterface $transport,28        private readonly FailureReporter $reporter,29    ) {}3031    public function run(PayloadMetadata $metadata): ContractTestResult32    {33        $failFast = (bool) ($metadata->context['fail_fast'] ?? false);34        $strategies = $this->resolveStrategies($metadata->strategies);35        $results = [];3637        foreach ($strategies as $strategyClass) {38            $strategy = new $strategyClass();3940            if (!$strategy->canRun($metadata)) {41                $results[] = StrategyResult::skipped($strategyClass, $strategy->skipReason($metadata));42                continue;43            }4445            foreach ($strategy->generateCases($metadata) as $case) {46                $response = $this->transport->send($case);4748                try {49                    $strategy->assertResponse($case, $response);50                    $results[] = StrategyResult::passed($strategyClass, $case);51                } catch (\PHPUnit\Framework\AssertionFailedError $e) {52                    $this->reporter->report($metadata, $strategy, $case, $response, $e);53                    $results[] = StrategyResult::failed($strategyClass, $case, $e->getMessage());5455                    if ($failFast) {56                        return new ContractTestResult($results);57                    }58                }59            }60        }6162        return new ContractTestResult($results);63    }6465    /**66     * Expand profiles into their constituent strategies recursively.67     * Deduplicates: each strategy class runs at most once.68     *69     * @param list<class-string<TestingStrategyInterface>> $strategyClasses70     * @return list<class-string<TestingStrategyInterface>>71     */72    private function resolveStrategies(array $strategyClasses): array73    {74        $resolved = [];75        $seen = [];7677        $expand = function(array $classes) use (&$expand, &$resolved, &$seen): void {78            foreach ($classes as $class) {79                if (isset($seen[$class])) {80                    continue;81                }82                $seen[$class] = true;8384                if (!class_exists($class)) {85                    continue;86                }8788                $instance = new $class();89                if ($instance instanceof TestingProfileInterface) {90                    // Expand profile into sub-strategies (recursive)91                    $expand($instance->getStrategyClasses());92                } else {93                    $resolved[] = $class;94                }95            }96        };9798        $expand($strategyClasses);99        return $resolved;100    }101}102

<?php

declare(strict_types=1);

namespace Semitexa\Testing;

use Semitexa\Testing\Contract\TestingProfileInterface;
use Semitexa\Testing\Contract\TestingStrategyInterface;
use Semitexa\Testing\Contract\TransportInterface;
use Semitexa\Testing\Data\ContractTestResult;
use Semitexa\Testing\Data\PayloadMetadata;
use Semitexa\Testing\Data\StrategyResult;

/**
 * Orchestrates the execution of all declared strategies against a PayloadDTO.
 *
 * Execution model:
 *   - Sequential strategy execution (predictable output order).
 *   - Fail-safe by default: all strategies run even if one fails.
 *   - Fail-fast: configurable via context['fail_fast'] = true.
 *   - Profiles are expanded into sub-strategies before execution (recursive, deduplicated).
 *   - Skipped strategies (canRun() = false) are reported as SKIPPED, not FAILED.
 */
final class PayloadContractTester
{
    public function __construct(
        private readonly TransportInterface $transport,
        private readonly FailureReporter $reporter,
    ) {}

    public function run(PayloadMetadata $metadata): ContractTestResult
    {
        $failFast = (bool) ($metadata->context['fail_fast'] ?? false);
        $strategies = $this->resolveStrategies($metadata->strategies);
        $results = [];

        foreach ($strategies as $strategyClass) {
            $strategy = new $strategyClass();

            if (!$strategy->canRun($metadata)) {
                $results[] = StrategyResult::skipped($strategyClass, $strategy->skipReason($metadata));
                continue;
            }

            foreach ($strategy->generateCases($metadata) as $case) {
                $response = $this->transport->send($case);

                try {
                    $strategy->assertResponse($case, $response);
                    $results[] = StrategyResult::passed($strategyClass, $case);
                } catch (\PHPUnit\Framework\AssertionFailedError $e) {
                    $this->reporter->report($metadata, $strategy, $case, $response, $e);
                    $results[] = StrategyResult::failed($strategyClass, $case, $e->getMessage());

                    if ($failFast) {
                        return new ContractTestResult($results);
                    }
                }
            }
        }

        return new ContractTestResult($results);
    }

    /**
     * Expand profiles into their constituent strategies recursively.
     * Deduplicates: each strategy class runs at most once.
     *
     * @param list<class-string<TestingStrategyInterface>> $strategyClasses
     * @return list<class-string<TestingStrategyInterface>>
     */
    private function resolveStrategies(array $strategyClasses): array
    {
        $resolved = [];
        $seen = [];

        $expand = function(array $classes) use (&$expand, &$resolved, &$seen): void {
            foreach ($classes as $class) {
                if (isset($seen[$class])) {
                    continue;
                }
                $seen[$class] = true;

                if (!class_exists($class)) {
                    continue;
                }

                $instance = new $class();
                if ($instance instanceof TestingProfileInterface) {
                    // Expand profile into sub-strategies (recursive)
                    $expand($instance->getStrategyClasses());
                } else {
                    $resolved[] = $class;
                }
            }
        };

        $expand($strategyClasses);
        return $resolved;
    }
}

1<?php23declare(strict_types=1);45namespace Semitexa\Testing\Strategy\Profile;67use Semitexa\Testing\Contract\TestingProfileInterface;8use Semitexa\Testing\Data\PayloadMetadata;9use Semitexa\Testing\Data\ResponseResult;10use Semitexa\Testing\Data\TestCaseDescriptor;11use Semitexa\Testing\Strategy\HttpMethodStrategy;12use Semitexa\Testing\Strategy\SecurityStrategy;13use Semitexa\Testing\Strategy\TypeEnforcementStrategy;1415/**16 * Strict profile: Standard + aggressive type mutation testing.17 *18 * Forces type_mutation to true even if context overrides it to false.19 * Inject context override via PayloadContractTester before expansion.20 */21final class StrictProfileStrategy implements TestingProfileInterface22{23    public function getStrategyClasses(): array24    {25        return [26            SecurityStrategy::class,27            HttpMethodStrategy::class,28            TypeEnforcementStrategy::class, // type_mutation defaults to true29        ];30    }3132    public function canRun(PayloadMetadata $metadata): bool33    {34        return false;35    }3637    public function skipReason(PayloadMetadata $metadata): string38    {39        return 'StrictProfileStrategy is a profile — it is always expanded into sub-strategies.';40    }4142    public function generateCases(PayloadMetadata $metadata): iterable43    {44        return [];45    }4647    public function assertResponse(TestCaseDescriptor $case, ResponseResult $response): void {}48}49

<?php

declare(strict_types=1);

namespace Semitexa\Testing\Strategy\Profile;

use Semitexa\Testing\Contract\TestingProfileInterface;
use Semitexa\Testing\Data\PayloadMetadata;
use Semitexa\Testing\Data\ResponseResult;
use Semitexa\Testing\Data\TestCaseDescriptor;
use Semitexa\Testing\Strategy\HttpMethodStrategy;
use Semitexa\Testing\Strategy\SecurityStrategy;
use Semitexa\Testing\Strategy\TypeEnforcementStrategy;

/**
 * Strict profile: Standard + aggressive type mutation testing.
 *
 * Forces type_mutation to true even if context overrides it to false.
 * Inject context override via PayloadContractTester before expansion.
 */
final class StrictProfileStrategy implements TestingProfileInterface
{
    public function getStrategyClasses(): array
    {
        return [
            SecurityStrategy::class,
            HttpMethodStrategy::class,
            TypeEnforcementStrategy::class, // type_mutation defaults to true
        ];
    }

    public function canRun(PayloadMetadata $metadata): bool
    {
        return false;
    }

    public function skipReason(PayloadMetadata $metadata): string
    {
        return 'StrictProfileStrategy is a profile — it is always expanded into sub-strategies.';
    }

    public function generateCases(PayloadMetadata $metadata): iterable
    {
        return [];
    }

    public function assertResponse(TestCaseDescriptor $case, ResponseResult $response): void {}
}

1<?php23declare(strict_types=1);45namespace Semitexa\Testing\Strategy\Profile;67use Semitexa\Testing\Contract\TestingProfileInterface;8use Semitexa\Testing\Data\PayloadMetadata;9use Semitexa\Testing\Data\ResponseResult;10use Semitexa\Testing\Data\TestCaseDescriptor;11use Semitexa\Testing\Strategy\HttpMethodStrategy;12use Semitexa\Testing\Strategy\MonkeyTestingStrategy;13use Semitexa\Testing\Strategy\SecurityStrategy;14use Semitexa\Testing\Strategy\TypeEnforcementStrategy;1516/**17 * Paranoid profile: everything — Standard + type mutations + MonkeyTesting.18 * Maximum coverage. Use for critical endpoints (auth, payments, data mutation).19 */20final class ParanoidProfileStrategy implements TestingProfileInterface21{22    public function getStrategyClasses(): array23    {24        return [25            SecurityStrategy::class,26            HttpMethodStrategy::class,27            TypeEnforcementStrategy::class,28            MonkeyTestingStrategy::class,29        ];30    }3132    public function canRun(PayloadMetadata $metadata): bool33    {34        return false;35    }3637    public function skipReason(PayloadMetadata $metadata): string38    {39        return 'ParanoidProfileStrategy is a profile — it is always expanded into sub-strategies.';40    }4142    public function generateCases(PayloadMetadata $metadata): iterable43    {44        return [];45    }4647    public function assertResponse(TestCaseDescriptor $case, ResponseResult $response): void {}48}49

<?php

declare(strict_types=1);

namespace Semitexa\Testing\Strategy\Profile;

use Semitexa\Testing\Contract\TestingProfileInterface;
use Semitexa\Testing\Data\PayloadMetadata;
use Semitexa\Testing\Data\ResponseResult;
use Semitexa\Testing\Data\TestCaseDescriptor;
use Semitexa\Testing\Strategy\HttpMethodStrategy;
use Semitexa\Testing\Strategy\MonkeyTestingStrategy;
use Semitexa\Testing\Strategy\SecurityStrategy;
use Semitexa\Testing\Strategy\TypeEnforcementStrategy;

/**
 * Paranoid profile: everything — Standard + type mutations + MonkeyTesting.
 * Maximum coverage. Use for critical endpoints (auth, payments, data mutation).
 */
final class ParanoidProfileStrategy implements TestingProfileInterface
{
    public function getStrategyClasses(): array
    {
        return [
            SecurityStrategy::class,
            HttpMethodStrategy::class,
            TypeEnforcementStrategy::class,
            MonkeyTestingStrategy::class,
        ];
    }

    public function canRun(PayloadMetadata $metadata): bool
    {
        return false;
    }

    public function skipReason(PayloadMetadata $metadata): string
    {
        return 'ParanoidProfileStrategy is a profile — it is always expanded into sub-strategies.';
    }

    public function generateCases(PayloadMetadata $metadata): iterable
    {
        return [];
    }

    public function assertResponse(TestCaseDescriptor $case, ResponseResult $response): void {}
}

1<?php23declare(strict_types=1);45namespace Semitexa\Testing\Strategy;67use PHPUnit\Framework\Assert;8use Semitexa\Testing\Contract\TestingStrategyInterface;9use Semitexa\Testing\Data\PayloadMetadata;10use Semitexa\Testing\Data\ResponseResult;11use Semitexa\Core\Http\HttpStatus;12use Semitexa\Testing\Data\TestCaseDescriptor;1314/**15 * Sends chaotic / garbage requests and verifies the system returns a safe 4xx,16 * never a 5xx (500, 502, 503, 504).17 *18 * Configurable via context:19 *   monkey_reject_statuses: list<int>  — statuses considered failures (default: 5xx range)20 *   monkey_accept_statuses: list<int>  — statuses considered safe (default: 4xx range)21 *   If neither is set, any non-5xx is considered safe.22 */23final class MonkeyTestingStrategy implements TestingStrategyInterface24{25    private const DEFAULT_REJECT = [HttpStatus::InternalServerError->value, HttpStatus::BadGateway->value, HttpStatus::ServiceUnavailable->value, HttpStatus::GatewayTimeout->value];2627    public function canRun(PayloadMetadata $metadata): bool28    {29        return true;30    }3132    public function skipReason(PayloadMetadata $metadata): string33    {34        return '';35    }3637    public function generateCases(PayloadMetadata $metadata): iterable38    {39        $method = $this->pickWriteMethod($metadata->methods);40        $path = $metadata->path;4142        yield new TestCaseDescriptor(43            description: 'Huge JSON body (~1 MB) → safe rejection',44            method: $method,45            path: $path,46            headers: ['Content-Type' => 'application/json'],47            body: str_repeat('{"a":"' . str_repeat('x', 100) . '",', 10_000) . '"z":"end"}',48            expectedStatus: $this->safeStatusRange($metadata),49        );5051        yield new TestCaseDescriptor(52            description: 'Deeply nested array (depth 500) → safe rejection',53            method: $method,54            path: $path,55            headers: [],56            body: $this->buildDeeplyNested(500),57            expectedStatus: $this->safeStatusRange($metadata),58        );5960        yield new TestCaseDescriptor(61            description: 'Malformed JSON → safe rejection',62            method: $method,63            path: $path,64            headers: ['Content-Type' => 'application/json'],65            body: '{not valid json at all ][[]',66            expectedStatus: $this->safeStatusRange($metadata),67        );6869        yield new TestCaseDescriptor(70            description: 'SQLi-like string in all fields → safe rejection',71            method: $method,72            path: $path,73            headers: [],74            body: $this->buildSqliPayload($metadata),75            expectedStatus: $this->safeStatusRange($metadata),76        );7778        yield new TestCaseDescriptor(79            description: 'Null bytes and control characters → safe rejection',80            method: $method,81            path: $path,82            headers: [],83            body: $this->buildNullBytePayload($metadata),84            expectedStatus: $this->safeStatusRange($metadata),85        );8687        yield new TestCaseDescriptor(88            description: 'Extreme Unicode (emoji, RTL, surrogates) → safe rejection',89            method: $method,90            path: $path,91            headers: [],92            body: $this->buildUnicodePayload($metadata),93            expectedStatus: $this->safeStatusRange($metadata),94        );95    }9697    public function assertResponse(TestCaseDescriptor $case, ResponseResult $response): void98    {99        $rejectStatuses = $case->expectedStatus;100        if (is_array($rejectStatuses)) {101            // expectedStatus here is the SAFE set102            Assert::assertContains(103                $response->statusCode,104                $rejectStatuses,105                "[MonkeyTestingStrategy] {$case->description}: got unsafe status {$response->statusCode}."106            );107        } else {108            Assert::assertNotSame(109                $case->expectedStatus,110                $response->statusCode,111                "[MonkeyTestingStrategy] {$case->description}: got status {$response->statusCode}."112            );113        }114    }115116    /** @return list<int> Safe (accepted) status codes */117    private function safeStatusRange(PayloadMetadata $metadata): array118    {119        if (isset($metadata->context['monkey_accept_statuses'])) {120            return $metadata->context['monkey_accept_statuses'];121        }122        $reject = $metadata->context['monkey_reject_statuses'] ?? self::DEFAULT_REJECT;123        return array_values(array_diff(range(100, 599), $reject));124    }125126    private function buildDeeplyNested(int $depth): array127    {128        $nested = ['leaf' => true];129        for ($i = 0; $i < $depth; $i++) {130            $nested = ['child' => $nested];131        }132        return $nested;133    }134135    private function buildSqliPayload(PayloadMetadata $metadata): array136    {137        $sqli = "'; DROP TABLE users; --";138        $body = [];139        foreach ($metadata->properties as $prop) {140            $body[$prop->name] = $sqli;141        }142        return $body ?: ['q' => $sqli];143    }144145    private function buildNullBytePayload(PayloadMetadata $metadata): array146    {147        $evil = "normal\x00null\x01\x02\x03byte";148        $body = [];149        foreach ($metadata->properties as $prop) {150            $body[$prop->name] = $evil;151        }152        return $body ?: ['q' => $evil];153    }154155    private function buildUnicodePayload(PayloadMetadata $metadata): array156    {157        $unicode = "\u{1F4A9}\u{202E}reversed\u{FEFF}bom\u{D800}";158        $body = [];159        foreach ($metadata->properties as $prop) {160            $body[$prop->name] = $unicode;161        }162        return $body ?: ['q' => $unicode];163    }164165    private function pickWriteMethod(array $methods): string166    {167        $methods = array_map('strtoupper', $methods);168        foreach (['POST', 'PUT', 'PATCH', 'GET'] as $preferred) {169            if (in_array($preferred, $methods, true)) {170                return $preferred;171            }172        }173        return $methods[0] ?? 'POST';174    }175}176

<?php

declare(strict_types=1);

namespace Semitexa\Testing\Strategy;

use PHPUnit\Framework\Assert;
use Semitexa\Testing\Contract\TestingStrategyInterface;
use Semitexa\Testing\Data\PayloadMetadata;
use Semitexa\Testing\Data\ResponseResult;
use Semitexa\Core\Http\HttpStatus;
use Semitexa\Testing\Data\TestCaseDescriptor;

/**
 * Sends chaotic / garbage requests and verifies the system returns a safe 4xx,
 * never a 5xx (500, 502, 503, 504).
 *
 * Configurable via context:
 *   monkey_reject_statuses: list<int>  — statuses considered failures (default: 5xx range)
 *   monkey_accept_statuses: list<int>  — statuses considered safe (default: 4xx range)
 *   If neither is set, any non-5xx is considered safe.
 */
final class MonkeyTestingStrategy implements TestingStrategyInterface
{
    private const DEFAULT_REJECT = [HttpStatus::InternalServerError->value, HttpStatus::BadGateway->value, HttpStatus::ServiceUnavailable->value, HttpStatus::GatewayTimeout->value];

    public function canRun(PayloadMetadata $metadata): bool
    {
        return true;
    }

    public function skipReason(PayloadMetadata $metadata): string
    {
        return '';
    }

    public function generateCases(PayloadMetadata $metadata): iterable
    {
        $method = $this->pickWriteMethod($metadata->methods);
        $path = $metadata->path;

        yield new TestCaseDescriptor(
            description: 'Huge JSON body (~1 MB) → safe rejection',
            method: $method,
            path: $path,
            headers: ['Content-Type' => 'application/json'],
            body: str_repeat('{"a":"' . str_repeat('x', 100) . '",', 10_000) . '"z":"end"}',
            expectedStatus: $this->safeStatusRange($metadata),
        );

        yield new TestCaseDescriptor(
            description: 'Deeply nested array (depth 500) → safe rejection',
            method: $method,
            path: $path,
            headers: [],
            body: $this->buildDeeplyNested(500),
            expectedStatus: $this->safeStatusRange($metadata),
        );

        yield new TestCaseDescriptor(
            description: 'Malformed JSON → safe rejection',
            method: $method,
            path: $path,
            headers: ['Content-Type' => 'application/json'],
            body: '{not valid json at all ][[]',
            expectedStatus: $this->safeStatusRange($metadata),
        );

        yield new TestCaseDescriptor(
            description: 'SQLi-like string in all fields → safe rejection',
            method: $method,
            path: $path,
            headers: [],
            body: $this->buildSqliPayload($metadata),
            expectedStatus: $this->safeStatusRange($metadata),
        );

        yield new TestCaseDescriptor(
            description: 'Null bytes and control characters → safe rejection',
            method: $method,
            path: $path,
            headers: [],
            body: $this->buildNullBytePayload($metadata),
            expectedStatus: $this->safeStatusRange($metadata),
        );

        yield new TestCaseDescriptor(
            description: 'Extreme Unicode (emoji, RTL, surrogates) → safe rejection',
            method: $method,
            path: $path,
            headers: [],
            body: $this->buildUnicodePayload($metadata),
            expectedStatus: $this->safeStatusRange($metadata),
        );
    }

    public function assertResponse(TestCaseDescriptor $case, ResponseResult $response): void
    {
        $rejectStatuses = $case->expectedStatus;
        if (is_array($rejectStatuses)) {
            // expectedStatus here is the SAFE set
            Assert::assertContains(
                $response->statusCode,
                $rejectStatuses,
                "[MonkeyTestingStrategy] {$case->description}: got unsafe status {$response->statusCode}."
            );
        } else {
            Assert::assertNotSame(
                $case->expectedStatus,
                $response->statusCode,
                "[MonkeyTestingStrategy] {$case->description}: got status {$response->statusCode}."
            );
        }
    }

    /** @return list<int> Safe (accepted) status codes */
    private function safeStatusRange(PayloadMetadata $metadata): array
    {
        if (isset($metadata->context['monkey_accept_statuses'])) {
            return $metadata->context['monkey_accept_statuses'];
        }
        $reject = $metadata->context['monkey_reject_statuses'] ?? self::DEFAULT_REJECT;
        return array_values(array_diff(range(100, 599), $reject));
    }

    private function buildDeeplyNested(int $depth): array
    {
        $nested = ['leaf' => true];
        for ($i = 0; $i < $depth; $i++) {
            $nested = ['child' => $nested];
        }
        return $nested;
    }

    private function buildSqliPayload(PayloadMetadata $metadata): array
    {
        $sqli = "'; DROP TABLE users; --";
        $body = [];
        foreach ($metadata->properties as $prop) {
            $body[$prop->name] = $sqli;
        }
        return $body ?: ['q' => $sqli];
    }

    private function buildNullBytePayload(PayloadMetadata $metadata): array
    {
        $evil = "normal\x00null\x01\x02\x03byte";
        $body = [];
        foreach ($metadata->properties as $prop) {
            $body[$prop->name] = $evil;
        }
        return $body ?: ['q' => $evil];
    }

    private function buildUnicodePayload(PayloadMetadata $metadata): array
    {
        $unicode = "\u{1F4A9}\u{202E}reversed\u{FEFF}bom\u{D800}";
        $body = [];
        foreach ($metadata->properties as $prop) {
            $body[$prop->name] = $unicode;
        }
        return $body ?: ['q' => $unicode];
    }

    private function pickWriteMethod(array $methods): string
    {
        $methods = array_map('strtoupper', $methods);
        foreach (['POST', 'PUT', 'PATCH', 'GET'] as $preferred) {
            if (in_array($preferred, $methods, true)) {
                return $preferred;
            }
        }
        return $methods[0] ?? 'POST';
    }
}

Testing Posture

When this pays off the most

Contract testing is strongest when the payload really is the transport boundary and the team wants broad negative coverage without a pile of custom boilerplate.

Use Strict or Paranoid profiles on auth, money, or mutation endpoints where malformed input should never leak into handler logic.

Keep the payload as the real boundary object; contract testing loses value if the handler still parses raw arrays or globals.

Prefer one generated suite plus strategy profiles over dozens of repetitive “422 when field is missing” tests.

Let the contract suite complement domain tests, not replace them; payload robustness and business behavior are different concerns.

How it works

The testing framework discovers testable payloads, applies strategy profiles (Standard, Strict, Paranoid), and runs security, type enforcement, and monkey testing strategies against each endpoint.

Why it matters

Contract tests verify that payloads reject bad input and accept good input without writing individual test cases. Strategy profiles let teams choose their risk tolerance.

Key concepts

#[TestablePayload]: Marks a payload for automated contract testing with configurable strategies.
MonkeyTestingStrategy: Sends random/malformed input to test endpoint robustness.