6.0.0: Merge pull request #84 from byjg/6.0

Changelog - Version 6.0

Release Overview

Version 6.0 represents a major update to the PHP Swagger Test library with significant improvements to the API, enhanced XML support, better error messages, comprehensive documentation, and modernized PHP requirements.

---

New Features

XML Request and Response Support

• Added full support for XML content type in both request bodies and response validation
• Automatic conversion of SimpleXMLElement to arrays for schema matching
• Enhanced response parsing with support for JSON, XML, and plain text content types
• Improved content-type detection and header parsing for XML responses

New Fluent API with ApiRequester

• Introduced ApiRequester class with fluent interface for building API requests
• New convenience expectation methods:
  • expectStatus() - Verify response status code
  • expectBodyContains() - Check if response body contains specific content
  • expectHeaderContains() - Validate response headers
  • expectJsonContains() - Check JSON response for specific values
  • expectJsonPath() - Validate JSON structure using JSON path expressions
• Better code readability and maintainability compared to legacy parameter-based approach

OpenApiValidation Trait

• New OpenApiValidation trait for flexible validation without requiring base class inheritance
• Allows integration of OpenAPI validation into existing test suites
• Provides same validation capabilities as ApiTestCase with more flexibility

Enhanced Schema Factory Methods

• Added three new factory methods for creating schema instances:
  • Schema::fromFile() - Create schema directly from file path
  • Schema::fromJson() - Create schema from JSON string
  • Schema::fromArray() - Create schema from array
• More intuitive and self-documenting than the legacy getInstance() method
• Better error messages specific to input type

Improved Parameter Validation

• Enhanced validation for query parameters in URL and query strings
• Better validation for required parameters
• More accurate parameter type checking and coercion

Better Error Messages

• Renamed GenericSwaggerException to GenericApiException for clarity
• Enhanced error messages with more context about validation failures
• Improved error reporting for mismatched content types and bodies
• Clearer messages when request/response validation fails

Comprehensive Documentation

• Complete documentation restructure for Docusaurus
• New documentation sections:
  • Functional test cases guide
  • Contract test cases guide
  • Runtime parameters validator guide
  • Mocking requests guide
  • Schema classes guide
  • Trait usage guide
  • Advanced usage guide
  • Exception handling guide
  • Migration guide with detailed examples
  • Troubleshooting guide
• All documentation follows DRY principles and is well-organized

Development Improvements

• Added Docker setup for easier local development
• Updated VSCode run configurations and debug settings
• Improved GitHub workflow configuration
• Added composer scripts for common tasks (test and psalm)

---

Bug Fixes

• Fixed response header parsing and content-type detection
• Fixed parameter required validation logic
• Corrected XML and JSON validation logic for body content handling
• Fixed method type hints in AbstractRequester
• Resolved issues with query parameter handling
• Fixed PSR-7 request generation in AbstractRequester

---

Breaking Changes

Before	After	Description
PHP 8.1+	PHP 8.3+	Minimum PHP version increased from 8.1 to 8.3. Added support for PHP 8.4 and 8.5.
byjg/webrequest ^5.0	byjg/webrequest ^6.0	Upgraded to version 6.0 of webrequest dependency
byjg/restserver ^5.0	byjg/restserver ^6.0	Upgraded to version 6.0 of restserver dependency (dev)
phpunit/phpunit ^9.6	phpunit/phpunit ^10.5|^11.5	Updated PHPUnit to versions 10.5 or 11.5
vimeo/psalm ^5.9	vimeo/psalm ^5.9|^6.13	Added support for Psalm 6.13
Test class names with "Test" suffix	Test class names without "Test" suffix	Renamed test helper classes: AbstractRequesterTest → AbstractRequester, OpenApiTest → OpenApi, SwaggerTest → Swagger
GenericSwaggerException	GenericApiException	Exception class renamed to better reflect its purpose for general API testing
#[Override] not required	#[Override] attributes added	Added #[Override] attributes to applicable methods for better IDE support and type safety
No strict types	Strict type declarations	Added declare(strict_types=1) to all classes and test methods

---

Deprecations

The following methods are deprecated in version 6.0 and will be removed in version 7.0:

Deprecated Method	Replacement	Reason
Schema::getInstance()	Schema::fromFile(), Schema::fromJson(), or Schema::fromArray()	Method name implies singleton pattern but creates new instances (factory pattern). New methods are clearer and more specific.
assertRequest()	sendRequest()	Method name is misleading as it returns a value and validation happens via exceptions. sendRequest() is more accurate.
makeRequest()	ApiRequester fluent interface	Six-parameter method is verbose and error-prone. Fluent interface is more readable and extensible.
assertResponseCode()	expectStatus()	Renamed for semantic clarity - sets expectations validated later, doesn't assert immediately
assertStatus()	expectStatus()	Renamed for semantic clarity - sets expectations validated later, doesn't assert immediately
assertBodyContains()	expectBodyContains()	Renamed for semantic clarity - sets expectations validated later, doesn't assert immediately
assertHeaderContains()	expectHeaderContains()	Renamed for semantic clarity - sets expectations validated later, doesn't assert immediately
assertJsonContains()	expectJsonContains()	Renamed for semantic clarity - sets expectations validated later, doesn't assert immediately
assertJsonPath()	expectJsonPath()	Renamed for semantic clarity - sets expectations validated later, doesn't assert immediately

---

Path to Upgrade from 5.x to 6.x

Step 1: Update PHP Version

Ensure you're running PHP 8.3 or higher:

php -v

If you're on PHP 8.1 or 8.2, you'll need to upgrade to PHP 8.3+ before proceeding.

Step 2: Update Composer Dependencies

Update your composer.json:

{
  "require": {
    "php": ">=8.3",
    "byjg/swagger-test": "^6.0"
  }
}

Then run:

composer update byjg/swagger-test

This will also update the required dependencies:

• byjg/webrequest to ^6.0
• PHPUnit to ^10.5 or ^11.5 (if in dev dependencies)

Step 3: Update Test Helper Class Names (if applicable)

If you extend any of the test helper classes in the tests/ directory, update the class names:

// Before
class MyTest extends Tests\AbstractRequesterTest { }
class MyTest extends Tests\OpenApiTest { }
class MyTest extends Tests\SwaggerTest { }

// After
class MyTest extends Tests\AbstractRequester { }
class MyTest extends Tests\OpenApi { }
class MyTest extends Tests\Swagger { }

Step 4: Replace Deprecated Exception Class

Update any catch blocks or type hints:

// Before
use ByJG\ApiTools\Exception\GenericSwaggerException;

try {
    // code
} catch (GenericSwaggerException $e) {
    // handle
}

// After
use ByJG\ApiTools\Exception\GenericApiException;

try {
    // code
} catch (GenericApiException $e) {
    // handle
}

Note: GenericSwaggerException is now an alias that extends GenericApiException, so existing code will continue to work during the transition period.

Step 5: Migrate from makeRequest() to ApiRequester (Recommended)

While makeRequest() still works in 6.0, we strongly recommend migrating to the new ApiRequester fluent interface:

// Before
$this->makeRequest('GET', '/pet/1', 200, null, null, []);

// After
$request = new \ByJG\ApiTools\ApiRequester();
$request
    ->withMethod('GET')
    ->withPath('/pet/1');

$this->sendRequest($request);

For more migration examples, see the Migration Guide.

Step 6: Update Schema Initialization (Recommended)

Replace Schema::getInstance() with the appropriate factory method:

// Before
$schema = Schema::getInstance(file_get_contents('/path/to/spec.json'));

// After - Recommended
$schema = Schema::fromFile('/path/to/spec.json');

// Or if you already have JSON string
$schema = Schema::fromJson($jsonString);

// Or if you have an array
$schema = Schema::fromArray($arrayData);

Step 7: Update Assertion Methods to Expectation Methods (Recommended)

Replace assertion-style methods with expectation-style methods:

// Before
$request
    ->assertResponseCode(200)
    ->assertBodyContains('test')
    ->assertHeaderContains('Content-Type', 'json');

// After
$request
    ->expectStatus(200)
    ->expectBodyContains('test')
    ->expectHeaderContains('Content-Type', 'json');

Step 8: Run Tests

After making these changes, run your test suite to ensure everything works correctly:

vendor/bin/phpunit

Step 9: Review New Features

Consider taking advantage of new features:

1. XML Support: If your API uses XML, you can now test XML requests and responses
2. OpenApiValidation Trait: For more flexibility in existing test suites
3. Enhanced Error Messages: Better debugging with improved error context
4. New Documentation: Comprehensive guides for all features

Compatibility Notes

• All deprecated methods in 6.0 will continue to work with deprecation notices
• Deprecated methods will be removed in version 7.0
• The upgrade can be done gradually - you don't need to change everything at once
• Existing tests should continue to work after the dependency update

Getting Help

If you encounter issues during the upgrade:

1. Check the Migration Guide for detailed examples
2. Review the Troubleshooting Guide for common issues
3. Consult the documentation for feature-specific guidance
4. Open an issue on GitHub

---

Contributors

Thanks to all contributors who made this release possible:

• @leonardomunsa - XML support implementation
• @cdenadai - text/html body validation improvements
• @byjg - Core development and maintenance

---

Timeline

• Version 6.0 (Current): New features, deprecations announced
• Version 7.0 (Future): All deprecated methods will be removed

---

For detailed migration instructions and examples, see the Migration Guide.