Documentation version: nextdevelopment documentation
Skip to content

Prepare for Gesso 3.0 ​

Gesso 3.0 removes the configuration keys, CLI spellings, and APIs that v2 deprecated. Upgrade to the latest v2.x first: every removal emits a [Gesso deprecation] notice there, so a clean run on it is a clean v3 upgrade. The per-surface ledger lives in UPGRADING.md. The PHP renames and removals below can be rewritten with the Rector set GessoSetList::V3.

Then require 3.0, which ships that Rector set. While it is in beta, the constraint needs the @beta flag:

bash
composer require --dev "studio-design/gesso:^3.0@beta"

Configuration ​

Since 3.0, gesso.php at the application root is the only configuration entry point.

  1. Generate it with vendor/bin/gesso config:migrate --write. The command reads the PHPUnit extension's <parameter> elements and a published v2 config/gesso.php and writes the equivalent gesso.php. It also lists every other edit with its file and line: the parameters to delete, and the removed CLI flags and v2 environment variables in composer.json scripts, .github/workflows/*.yml, and Makefile. In a Laravel application whose config/gesso.php calls base_path() or another helper, run php artisan gesso:config-migrate --write instead. See config:migrate.
  2. Delete the extension's <parameter> elements (keep only config, and only for a non-default location). The full mapping table is in UPGRADING.md. To start from scratch instead, run vendor/bin/gesso doctor --spec=openapi/front.json --emit-config > gesso.php or php artisan vendor:publish --tag=gesso.
  3. Delete config/gesso.php, rename config('gesso.auto_assert')-style lookups and overrides in tests to the new paths (config('gesso.laravel.auto_assert')), and run php artisan config:clear.
  4. Add vendor/bin/gesso config:migrate --check to CI until it exits 0. An env() call in config/gesso.php is written as its current value, with a warning. Re-wrap such values by hand, for example as getenv('X') ?: 'default'.

A leftover parameter or flat key fails the run naming its replacement, so an incomplete migration cannot pass silently. See Configuration for every key.

CLI flags and exit codes ​

Each removed spelling is now a usage error (exit 2) whose message names the replacement, for example Unknown argument(s): --specs (removed in Gesso 3.0; use --spec-name).

CommandRemoved in 3.0Use instead
coverage:merge--specs=<a,b>--spec-name=<name> (repeatable, comma-accepting)
coverage:merge--strip-prefixes=<a,b>--strip-prefix=<prefix> (repeatable, comma-accepting)
coverage:merge--json-output=<path>--report=json:<path>
coverage:merge--junit-output=<path>--report=junit:<path>
coverage:merge--html-output=<path>--report=html:<path>
coverage:merge--console-output=<mode>--console-report=<mode>
coverage:merge--min-endpoint-coverage=<pct>--min-coverage="endpoint=<pct>"
coverage:merge--min-response-coverage=<pct>--min-coverage="response=<pct>"
coverage:merge--min-sdk-exercise-coverage=<pct>--min-coverage="sdk_exercise=<pct>"
coverage:merge--min-coverage-strict--min-coverage="strict"
coverage:merge--baseline-file=<path>--baseline="violations=<path>"
coverage:merge--coverage-baseline-file=<path>--baseline="coverage=<path>"
coverage:merge--coverage-baseline-stale=<mode>--baseline-stale="coverage=<mode>"
coverage:merge--strict-required=<mode>--strict-required="run=<mode>"
coverage:merge--strict-additional-properties=<mode>--strict-additional-properties="run=<mode>"
stubs, gesso:stubs--output=<dir>--output-dir=<dir>
coverage:mergeexit 1 when a sidecar, report, or baseline file cannot be read or writtenexit 2; a check for any non-zero exit needs no change
coverage:mergean unknown argument ignored with a [Gesso] WARNINGrejected with exit 2, as doctor, coverage:gate, and stubs already did

A merge with several sink or threshold flags folds into one grouped flag: --min-endpoint-coverage=80 --min-coverage-strict becomes --min-coverage="endpoint=80,strict". See the CLI reference.

CLI JSON documents ​

Every JSON document Gesso emits names its version schema_version, as the validation, coverage, and Laravel route-parity documents already did. The --format=json output of doctor, coverage:gate, and stubs (and gesso:stubs) renamed schemaVersion to schema_version and moved to version 2. Their other fields are unchanged. The new explain and config:migrate documents start at schema_version: 1.

To migrate, read schema_version instead of schemaVersion in scripts and CI steps that parse these documents, and accept 2 where they check the value, for example jq -e '.schema_version == 2'. See the CLI reference.

Coverage sidecars ​

Gesso 3.0 merges only sidecars with envelopeVersion: 10, the envelope every worker has written since 2.7 (#505). The 2.x merge also read the legacy envelopes 2–9 (written by Gesso 1.9–2.6) and the bare coverage state with no envelopeVersion, with a [Gesso deprecation] notice since 2.9.0. The 3.0 merge rejects them, exiting 1 with a message that names the writing release and the fix:

text
[OpenAPI Coverage] FATAL: invalid sidecar payload: Sidecar envelope version 6
was written by a Gesso 1.9-2.6 worker; Gesso 3 reads envelopeVersion 10 only. …

To migrate, install the same Gesso version in the worker and merge steps, delete any sidecar directory a v2 run left behind (for example, artifacts restored from an earlier CI run), and re-run the parallel suite. Old sidecars cannot be converted. See versioned sidecar compatibility.

Enum binding ​

Enums bind to the spec by component name only (#508). A backed enum matches the components.schemas entry named after its class (an Enum suffix on either side is ignored) in the configured specs. Keep #[BoundToOpenApiEnum] only for enums whose component has another name. These surfaces are gone:

  • the file-path binding #[BoundToOpenApiEnum('path/to/file.json')] and the attribute's $specPath property (deprecated in 2.8.0). The attribute now takes one required argument, the component name; its parameter is still called component.
  • OpenApiSpecLoader::configure(enumBasePath:) and getEnumBasePath() (deprecated in 2.8.0).
  • EnumBindingException::forBinding() (deprecated in 2.7.0).
  • the EnumBindingReason cases that only file-path bindings raised (deprecated in 2.9.0): BasePathNotConfigured, EnumBasePathNotFound, EnumSpecBasePathOrphaned, SpecFileNotFound, MalformedJson, MalformedYaml, YamlLibraryMissing, NonMappingRoot, and EnumKeyMissing. These raised no notice, so search your code for the names, for example an arm of a match over EnumBindingReason.
php
// Before (v2)
#[BoundToOpenApiEnum('_shared/components/schemas/enums/IdpAuthorizeErrorCode.json')]
enum IdpErrorEnum: string { /* ... */ }
OpenApiSpecLoader::configure('openapi/bundled', enumBasePath: 'openapi');
EnumBindingException::forBinding($reason, $message, $enumFqcn);
// After (v3)
#[BoundToOpenApiEnum('IdpAuthorizeErrorCode')] // or no attribute when the names match
enum IdpErrorEnum: string { /* ... */ }
OpenApiSpecLoader::configure('openapi/bundled');
new EnumBindingException($reason, $message, $enumFqcn);

Enum values are now read only from the documents OpenApiSpecLoader::load() returns. To keep per-enum source files, $ref them from components.schemas. A file path left in the attribute is read as a component name and fails as ComponentNotFound. The attribute with no argument fails as AttributeInvalid. See enum drift detection.

Assertion methods ​

The assertion methods of the Laravel, Symfony, and PSR-7 traits share three names: assertOpenApiResponse(), assertOpenApiRequest(), and assertOpenApiExchange() (deprecated in 2.10.0, which already has the new names). The response comes first; the request is optional.

v2v3
Laravel assertResponseMatchesOpenApiSchema($response, ...)assertOpenApiResponse($response, ...), now public
Symfony assertResponseMatchesOpenApiSchema($request, $response, ...)assertOpenApiResponse($response, $request, ...)
Symfony assertRequestMatchesOpenApiSchema($request, ...)assertOpenApiRequest($request, ...)
Symfony assertClientMatchesOpenApiSchema($client, ...)assertOpenApiExchange($client, ...)
PSR-7 assertPsr7RequestMatchesOpenApiSchema($request, ...)assertOpenApiRequest($request, ...)
PSR-7 assertPsr7ResponseMatchesOpenApiSchema($request, $response)assertOpenApiResponse($response, $request)
PSR-7 assertPsr7ResponseForOperationMatchesOpenApiSchema($method, $path, $response)assertOpenApiResponse($response, method: $method, path: $path)
PSR-7 assertPsr7ExchangeMatchesOpenApiSchema($request, $response)assertOpenApiExchange($request, $response)

The Symfony assertOpenApiResponse() also takes method: and path: instead of a request.

php
// Before (v2)
$this->assertResponseMatchesOpenApiSchema($request, $response);
// After (v3)
$this->assertOpenApiResponse($response, $request);

Server base paths ​

A request path now matches the base paths the spec's servers declare (ADR 0008). A request to /api/pets against servers: [{ url: "/api" }] and a /pets path matched nothing in v2 and validates in v3. The path as written is tried first, and a non-empty spec.strip_prefixes turns server base paths off, so a suite that already configures the prefix behaves as before. A test that expected the path-not-found failure must set spec.strip_prefixes or call a path the spec does not document.

Unquoted YAML dates ​

An unquoted date or date-time in a YAML spec is now a string, as it is in a JSON spec (#695). v2 handed validation the Unix timestamp symfony/yaml decodes it to, so enum: [2026-06-15] under format: date rejected the real value and doctor reported GSO314 for example: 2026-06-15.

The string is canonical, not the source text: 2026-06-15, or 2026-06-15T22:30:00 with the fraction and zone as written. A space separator becomes T, single-digit fields are padded, a date-time at midnight with no zone reads as a date, and an impossible day rolls over (2026-02-30 reads as 2026-03-02). Quote a value whose exact spelling matters. A test that relied on the integer must expect the string.

Mapping keys are not covered. A flow mapping with an unquoted date key ({2026-06-15: …}) no longer loads, and a block mapping key (2026-06-15:) is still the timestamp; quote the key in both.

405 responses need an Allow header ​

The unsupported_method contract check now fails a 405 that has no Allow header, as RFC 9110 requires, when the dispatcher returns a response object. A dispatcher that returns only the status code is checked as before. Laravel and Symfony set the header on their own 405 responses.

Contract-check aliases ​

The Studio\Gesso\Fuzz\ aliases of the named contract checks are gone (#503; deprecated in 2.7.0). ContractCheck, ContractCheckPlan, ContractCheckFailure, ContractCheckSkip, ContractCheckSummary, OpenApiContractChecks, and the @internal ContractCheckProbe resolve only under Studio\Gesso\Contract\. Generator types (ExploredCase, OpenApiSpecExplorer, ...) stay in Studio\Gesso\Fuzz\.

php
// Before (v2)
use Studio\Gesso\Fuzz\OpenApiContractChecks;
// After (v3)
use Studio\Gesso\Contract\OpenApiContractChecks;

The v2 notice did not fire for an old name referenced after the class was already loaded, so search for Gesso\Fuzz\ContractCheck and Gesso\Fuzz\OpenApiContractChecks rather than relying on a silent v2.9 run.

PHPUnit dependency ​

phpunit/phpunit moved from Gesso's require to require-dev (#506; announced in 2.9.0), so installing Gesso no longer installs a test runner. Declare PHPUnit 12 or 13 in your own require-dev — a current 12.5+ or 13.x release. Gesso's ^12.0 || ^13.0 range is unchanged: PHPUnit 11 and Pest 3 stay unsupported, and a Composer conflict keeps them from being installed alongside Gesso.

bash
composer require --dev "phpunit/phpunit:^12.5 || ^13.0"

A Laravel 12 application still on PHPUnit 11 or Pest 3 must upgrade the runner first (for Pest, move to Pest 4):

bash
composer require --dev "phpunit/phpunit:^12.5" --with-all-dependencies

Gesso now declares ext-dom (JUnit coverage report) and ext-filter, which it used directly but had received through PHPUnit. Calling a Gesso assertion without PHPUnit installed throws a RuntimeException naming the composer require command instead of a "Class not found" fatal.

The private helpers composed into the assertion traits, deprecated in 2.9.0, are gone: failOpenApi() and assertOpenApi() (ValidatesOpenApiSchema, Symfony and PSR-7 OpenApiAssertions), failPsr7() and assertPsr7() (PSR-7 OpenApiAssertions), and failExplore() (ExploresOpenApiEndpoint).

php
// Before (v2)
$this->failOpenApi('message');
$this->assertOpenApi($condition, 'message');
// After (v3)
$this->fail('message');
$this->assertTrue($condition, 'message');

Deprecated helper methods ​

OpenApiCoverageTracker::hasAnyCoverage() and the SkipOpenApiResolver trait's private shouldSkipOpenApi() (composed into ValidatesOpenApiSchema) are gone; both were deprecated in 2.7.0.

php
// Before (v2)
OpenApiCoverageTracker::hasAnyCoverage('front');
$this->shouldSkipOpenApi();
// After (v3)
OpenApiCoverageTracker::current()->hasAnyCoverageOn('front');
$this->findSkipOpenApiAttribute() !== null;

ValidatesOpenApiSchema::resetValidatorCache() (@internal) and the trait's seven private static $cached* properties are gone too. They have done nothing since 2.7.0 moved the validator cache onto the test-case instance. Delete any self::resetValidatorCache() call from setUp() / tearDown().