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 dependenc...

Release 5.0.0

What's Changed

• Defining PHP 8.1 as base version by @byjg in #79

This pull request includes several updates to modernize the codebase, improve type safety, and enhance testing. Key changes involve updating PHP versions, adding Psalm for static analysis, renaming and adding new run configurations, and refactoring code to use stricter type declarations.

Updates to Testing and CI:

• .github/workflows/phpunit.yml: Added PHP 8.3 to the test matrix and removed older versions (7.4, 8.0). Also added Psalm static analysis to the CI pipeline. [1] [2]
• .travis.yml: Removed the Travis CI configuration in favor of GitHub Actions.

Configuration and Dependency Updates:

• composer.json: Updated PHP requirement to >=8.1, updated dependencies to their latest versions, and added vimeo/psalm for static analysis. [1] [2]
• psalm.xml: Added a new configuration file for Psalm static analysis.

Code Refactoring for Type Safety:

• src/AbstractRequester.php: Refactored methods to use stricter type declarations and updated exception handling. [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13]
• src/ApiRequester.php: Updated to use stricter type declarations and improved exception handling. [1] [2] [3]

Documentation and Configuration:

• .idea/runConfigurations/Main.xml: Renamed from Test_Project.xml and updated configuration.
• .idea/runConfigurations/Psalm.xml: Added a new run configuration for Psalm.

These changes collectively enhance the project's compatibility with modern PHP versions, improve code quality through static analysis, and ensure better type safety across the codebase.

Full Changelog: 4.9.2...5.0.0

Release 4.9.2

What's Changed

• Minor Bug Fixes by @byjg in #80

Full Changelog: 4.9.1...4.9.2

Release 4.9.1

What's Changed

• Remove deprecated var usage by @vitormattos in #77
• Fetch schema from content by @Fantom409 in #78
• README.md and minor adjustments by @byjg in #75

New Contributors

• @Fantom409 made their first contribution in #78

Full Changelog: 4.9.0...4.9.1

Release 4.9.0

What's Changed

• Fixed some broken english by @byjg in #70
• Make compatible with php8 by @vitormattos in #65
• Fix mach string type by @vitormattos in #66
• Bump Major Components Changes by @byjg in #74

Full Changelog: 3.1.4...4.9.0

Release 3.1.4

Follow the OpenAPI specification and allow regex without an initial and final slash (/).

PR #71

Release 3.1.3

Use Webrequest component compatible with PHP 5.6 --> 8.0

Release 3.1.2

Enable allOf work with references PR #63

Release 3.1.1

Added the following specifications:

• additionalProperties
• allOf
• oneOf
• pattern matching

Release 3.1.0

Some Refactory in the code:

• Using PSR-7 implementation in the ApiRequester
• Remove URI (dependency from WebRequest)
• Code clean up.
• Change the HttpClient to support Mock HTTP
• Mock example.
• ApiRequester now supports any PSR7 RequestInterface implementation by using the method withPsr7Request()
• Support to parameter in formData (for upload files)