Add PHPUnit test suite

- Add PHPUnit 11.0 as dev dependency
- Add phpunit.xml configuration
- Add DTO tests (LicenseInfo, LicenseStatus, ActivationResult)
- Add Exception tests (factory method, all exception types)
- Add LicenseClient tests with mocked HTTP responses
- Update README with testing instructions
- Update CHANGELOG

32 tests, 93 assertions

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

.gitignore

@@ -1,4 +1,5 @@
 /vendor/
+.phpunit.cache/
 .phpunit.result.cache
 .php-cs-fixer.cache
 *.log

CHANGELOG.md

@@ -18,6 +18,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - PSR-3 logging support (optional)
 - PSR-6 caching support (optional)
 - PSR dependencies (`psr/log`, `psr/cache`, `psr/http-client`)
+- PHPUnit test suite with 32 tests covering DTOs, exceptions, and client
 
 ### Changed
 

README.md

@@ -105,6 +105,14 @@ try {
 }
 ```
 
+## Testing
+
+Run the test suite with PHPUnit:
+
+```bash
+./vendor/bin/phpunit
+```
+
 ## API Endpoints
 
 This client interacts with the following WooCommerce Licensed Product API endpoints:

composer.json

@@ -22,6 +22,9 @@
         "psr/log": "^3.0",
         "symfony/http-client": "^7.0"
     },
+    "require-dev": {
+        "phpunit/phpunit": "^11.0"
+    },
     "autoload": {
         "psr-4": {
             "Magdev\\WcLicensedProductClient\\": "src/"

phpunit.xml

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
+         bootstrap="vendor/autoload.php"
+         colors="true"
+         cacheDirectory=".phpunit.cache"
+         executionOrder="depends,defects"
+         beStrictAboutOutputDuringTests="true"
+         failOnRisky="true"
+         failOnWarning="true">
+    <testsuites>
+        <testsuite name="default">
+            <directory>tests</directory>
+        </testsuite>
+    </testsuites>
+
+    <source>
+        <include>
+            <directory>src</directory>
+        </include>
+    </source>
+</phpunit>

tests/Dto/ActivationResultTest.php

@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Magdev\WcLicensedProductClient\Tests\Dto;
+
+use Magdev\WcLicensedProductClient\Dto\ActivationResult;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(ActivationResult::class)]
+final class ActivationResultTest extends TestCase
+{
+    #[Test]
+    public function itCanBeCreatedFromArrayWithSuccess(): void
+    {
+        $data = [
+            'success' => true,
+            'message' => 'License activated successfully.',
+        ];
+
+        $result = ActivationResult::fromArray($data);
+
+        self::assertTrue($result->success);
+        self::assertSame('License activated successfully.', $result->message);
+    }
+
+    #[Test]
+    public function itCanBeCreatedFromArrayWithAlreadyActivated(): void
+    {
+        $data = [
+            'success' => true,
+            'message' => 'License is already activated for this domain.',
+        ];
+
+        $result = ActivationResult::fromArray($data);
+
+        self::assertTrue($result->success);
+        self::assertSame('License is already activated for this domain.', $result->message);
+    }
+}

tests/Dto/LicenseInfoTest.php

@@ -0,0 +1,71 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Magdev\WcLicensedProductClient\Tests\Dto;
+
+use Magdev\WcLicensedProductClient\Dto\LicenseInfo;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(LicenseInfo::class)]
+final class LicenseInfoTest extends TestCase
+{
+    #[Test]
+    public function itCanBeCreatedFromArray(): void
+    {
+        $data = [
+            'product_id' => 123,
+            'expires_at' => '2027-01-21',
+            'version_id' => 5,
+        ];
+
+        $licenseInfo = LicenseInfo::fromArray($data);
+
+        self::assertSame(123, $licenseInfo->productId);
+        self::assertInstanceOf(\DateTimeImmutable::class, $licenseInfo->expiresAt);
+        self::assertSame('2027-01-21', $licenseInfo->expiresAt->format('Y-m-d'));
+        self::assertSame(5, $licenseInfo->versionId);
+    }
+
+    #[Test]
+    public function itCanBeCreatedWithNullExpiresAt(): void
+    {
+        $data = [
+            'product_id' => 456,
+            'expires_at' => null,
+            'version_id' => null,
+        ];
+
+        $licenseInfo = LicenseInfo::fromArray($data);
+
+        self::assertSame(456, $licenseInfo->productId);
+        self::assertNull($licenseInfo->expiresAt);
+        self::assertNull($licenseInfo->versionId);
+    }
+
+    #[Test]
+    public function itCanBeCreatedWithoutOptionalFields(): void
+    {
+        $data = [
+            'product_id' => 789,
+        ];
+
+        $licenseInfo = LicenseInfo::fromArray($data);
+
+        self::assertSame(789, $licenseInfo->productId);
+        self::assertNull($licenseInfo->expiresAt);
+        self::assertNull($licenseInfo->versionId);
+    }
+
+    #[Test]
+    public function itIdentifiesLifetimeLicense(): void
+    {
+        $lifetime = LicenseInfo::fromArray(['product_id' => 1, 'expires_at' => null]);
+        $expiring = LicenseInfo::fromArray(['product_id' => 2, 'expires_at' => '2027-12-31']);
+
+        self::assertTrue($lifetime->isLifetime());
+        self::assertFalse($expiring->isLifetime());
+    }
+}

tests/Dto/LicenseStatusTest.php

@@ -0,0 +1,118 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Magdev\WcLicensedProductClient\Tests\Dto;
+
+use Magdev\WcLicensedProductClient\Dto\LicenseState;
+use Magdev\WcLicensedProductClient\Dto\LicenseStatus;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(LicenseStatus::class)]
+#[CoversClass(LicenseState::class)]
+final class LicenseStatusTest extends TestCase
+{
+    #[Test]
+    public function itCanBeCreatedFromArray(): void
+    {
+        $data = [
+            'valid' => true,
+            'status' => 'active',
+            'domain' => 'example.com',
+            'expires_at' => '2027-01-21',
+            'activations_count' => 1,
+            'max_activations' => 3,
+        ];
+
+        $status = LicenseStatus::fromArray($data);
+
+        self::assertTrue($status->valid);
+        self::assertSame(LicenseState::Active, $status->status);
+        self::assertSame('example.com', $status->domain);
+        self::assertInstanceOf(\DateTimeImmutable::class, $status->expiresAt);
+        self::assertSame('2027-01-21', $status->expiresAt->format('Y-m-d'));
+        self::assertSame(1, $status->activationsCount);
+        self::assertSame(3, $status->maxActivations);
+    }
+
+    #[Test]
+    #[DataProvider('licenseStateProvider')]
+    public function itParsesAllLicenseStates(string $stateString, string $expectedStateValue): void
+    {
+        $data = [
+            'valid' => false,
+            'status' => $stateString,
+            'domain' => 'test.com',
+            'expires_at' => null,
+            'activations_count' => 0,
+            'max_activations' => 1,
+        ];
+
+        $status = LicenseStatus::fromArray($data);
+
+        self::assertSame($expectedStateValue, $status->status->value);
+    }
+
+    public static function licenseStateProvider(): array
+    {
+        return [
+            'active' => ['active', 'active'],
+            'inactive' => ['inactive', 'inactive'],
+            'expired' => ['expired', 'expired'],
+            'revoked' => ['revoked', 'revoked'],
+        ];
+    }
+
+    #[Test]
+    public function itIdentifiesLifetimeLicense(): void
+    {
+        $lifetime = LicenseStatus::fromArray([
+            'valid' => true,
+            'status' => 'active',
+            'domain' => 'test.com',
+            'expires_at' => null,
+            'activations_count' => 1,
+            'max_activations' => 1,
+        ]);
+
+        $expiring = LicenseStatus::fromArray([
+            'valid' => true,
+            'status' => 'active',
+            'domain' => 'test.com',
+            'expires_at' => '2027-12-31',
+            'activations_count' => 1,
+            'max_activations' => 1,
+        ]);
+
+        self::assertTrue($lifetime->isLifetime());
+        self::assertFalse($expiring->isLifetime());
+    }
+
+    #[Test]
+    public function itChecksAvailableActivations(): void
+    {
+        $hasAvailable = LicenseStatus::fromArray([
+            'valid' => true,
+            'status' => 'active',
+            'domain' => 'test.com',
+            'expires_at' => null,
+            'activations_count' => 1,
+            'max_activations' => 3,
+        ]);
+
+        $noAvailable = LicenseStatus::fromArray([
+            'valid' => true,
+            'status' => 'active',
+            'domain' => 'test.com',
+            'expires_at' => null,
+            'activations_count' => 3,
+            'max_activations' => 3,
+        ]);
+
+        self::assertTrue($hasAvailable->hasAvailableActivations());
+        self::assertFalse($noAvailable->hasAvailableActivations());
+    }
+}

tests/Exception/LicenseExceptionTest.php

@@ -0,0 +1,121 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Magdev\WcLicensedProductClient\Tests\Exception;
+
+use Magdev\WcLicensedProductClient\Exception\ActivationFailedException;
+use Magdev\WcLicensedProductClient\Exception\DomainMismatchException;
+use Magdev\WcLicensedProductClient\Exception\LicenseException;
+use Magdev\WcLicensedProductClient\Exception\LicenseExpiredException;
+use Magdev\WcLicensedProductClient\Exception\LicenseInactiveException;
+use Magdev\WcLicensedProductClient\Exception\LicenseInvalidException;
+use Magdev\WcLicensedProductClient\Exception\LicenseNotFoundException;
+use Magdev\WcLicensedProductClient\Exception\LicenseRevokedException;
+use Magdev\WcLicensedProductClient\Exception\MaxActivationsReachedException;
+use Magdev\WcLicensedProductClient\Exception\RateLimitExceededException;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(LicenseException::class)]
+#[CoversClass(LicenseNotFoundException::class)]
+#[CoversClass(LicenseExpiredException::class)]
+#[CoversClass(LicenseRevokedException::class)]
+#[CoversClass(LicenseInactiveException::class)]
+#[CoversClass(LicenseInvalidException::class)]
+#[CoversClass(DomainMismatchException::class)]
+#[CoversClass(MaxActivationsReachedException::class)]
+#[CoversClass(ActivationFailedException::class)]
+#[CoversClass(RateLimitExceededException::class)]
+final class LicenseExceptionTest extends TestCase
+{
+    #[Test]
+    #[DataProvider('exceptionMappingProvider')]
+    public function itCreatesCorrectExceptionFromApiResponse(
+        string $errorCode,
+        string $expectedClass,
+    ): void {
+        $data = [
+            'error' => $errorCode,
+            'message' => 'Test message for ' . $errorCode,
+        ];
+
+        $exception = LicenseException::fromApiResponse($data, 403);
+
+        self::assertInstanceOf($expectedClass, $exception);
+        self::assertSame('Test message for ' . $errorCode, $exception->getMessage());
+        self::assertSame($errorCode, $exception->errorCode);
+        self::assertSame(403, $exception->getCode());
+    }
+
+    public static function exceptionMappingProvider(): array
+    {
+        return [
+            'license_not_found' => ['license_not_found', LicenseNotFoundException::class],
+            'license_expired' => ['license_expired', LicenseExpiredException::class],
+            'license_revoked' => ['license_revoked', LicenseRevokedException::class],
+            'license_inactive' => ['license_inactive', LicenseInactiveException::class],
+            'license_invalid' => ['license_invalid', LicenseInvalidException::class],
+            'domain_mismatch' => ['domain_mismatch', DomainMismatchException::class],
+            'max_activations_reached' => ['max_activations_reached', MaxActivationsReachedException::class],
+            'activation_failed' => ['activation_failed', ActivationFailedException::class],
+        ];
+    }
+
+    #[Test]
+    public function itCreatesRateLimitExceptionWithRetryAfter(): void
+    {
+        $data = [
+            'error' => 'rate_limit_exceeded',
+            'message' => 'Too many requests.',
+            'retry_after' => 45,
+        ];
+
+        $exception = LicenseException::fromApiResponse($data, 429);
+
+        self::assertInstanceOf(RateLimitExceededException::class, $exception);
+        self::assertSame(45, $exception->retryAfter);
+    }
+
+    #[Test]
+    public function itCreatesGenericExceptionForUnknownErrorCode(): void
+    {
+        $data = [
+            'error' => 'unknown_error',
+            'message' => 'Something went wrong.',
+        ];
+
+        $exception = LicenseException::fromApiResponse($data, 500);
+
+        self::assertInstanceOf(LicenseException::class, $exception);
+        self::assertNotInstanceOf(LicenseNotFoundException::class, $exception);
+        self::assertSame('unknown_error', $exception->errorCode);
+    }
+
+    #[Test]
+    public function itHandlesMissingMessageInApiResponse(): void
+    {
+        $data = [
+            'error' => 'license_not_found',
+        ];
+
+        $exception = LicenseException::fromApiResponse($data, 404);
+
+        self::assertSame('Unknown license error', $exception->getMessage());
+    }
+
+    #[Test]
+    public function itHandlesMissingErrorCodeInApiResponse(): void
+    {
+        $data = [
+            'message' => 'Some error occurred.',
+        ];
+
+        $exception = LicenseException::fromApiResponse($data, 500);
+
+        self::assertInstanceOf(LicenseException::class, $exception);
+        self::assertNull($exception->errorCode);
+    }
+}

tests/LicenseClientTest.php

@@ -0,0 +1,177 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Magdev\WcLicensedProductClient\Tests;
+
+use Magdev\WcLicensedProductClient\Dto\ActivationResult;
+use Magdev\WcLicensedProductClient\Dto\LicenseInfo;
+use Magdev\WcLicensedProductClient\Dto\LicenseState;
+use Magdev\WcLicensedProductClient\Dto\LicenseStatus;
+use Magdev\WcLicensedProductClient\Exception\LicenseException;
+use Magdev\WcLicensedProductClient\Exception\LicenseNotFoundException;
+use Magdev\WcLicensedProductClient\LicenseClient;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+use Psr\Log\LoggerInterface;
+use Symfony\Component\HttpClient\MockHttpClient;
+use Symfony\Component\HttpClient\Response\MockResponse;
+
+#[CoversClass(LicenseClient::class)]
+final class LicenseClientTest extends TestCase
+{
+    private const BASE_URL = 'https://example.com';
+    private const LICENSE_KEY = 'ABCD-1234-EFGH-5678';
+    private const DOMAIN = 'test.example.com';
+
+    #[Test]
+    public function itValidatesLicenseSuccessfully(): void
+    {
+        $responseData = [
+            'valid' => true,
+            'license' => [
+                'product_id' => 123,
+                'expires_at' => '2027-01-21',
+                'version_id' => 5,
+            ],
+        ];
+
+        $client = $this->createClientWithResponse($responseData);
+
+        $result = $client->validate(self::LICENSE_KEY, self::DOMAIN);
+
+        self::assertInstanceOf(LicenseInfo::class, $result);
+        self::assertSame(123, $result->productId);
+        self::assertSame('2027-01-21', $result->expiresAt->format('Y-m-d'));
+        self::assertSame(5, $result->versionId);
+    }
+
+    #[Test]
+    public function itThrowsExceptionOnValidationFailure(): void
+    {
+        $responseData = [
+            'valid' => false,
+            'error' => 'license_not_found',
+            'message' => 'License key not found.',
+        ];
+
+        $client = $this->createClientWithResponse($responseData, 403);
+
+        $this->expectException(LicenseNotFoundException::class);
+        $this->expectExceptionMessage('License key not found.');
+
+        $client->validate(self::LICENSE_KEY, self::DOMAIN);
+    }
+
+    #[Test]
+    public function itRetrievesLicenseStatusSuccessfully(): void
+    {
+        $responseData = [
+            'valid' => true,
+            'status' => 'active',
+            'domain' => 'example.com',
+            'expires_at' => '2027-01-21',
+            'activations_count' => 1,
+            'max_activations' => 3,
+        ];
+
+        $client = $this->createClientWithResponse($responseData);
+
+        $result = $client->status(self::LICENSE_KEY);
+
+        self::assertInstanceOf(LicenseStatus::class, $result);
+        self::assertTrue($result->valid);
+        self::assertSame(LicenseState::Active, $result->status);
+        self::assertSame('example.com', $result->domain);
+        self::assertSame(1, $result->activationsCount);
+        self::assertSame(3, $result->maxActivations);
+    }
+
+    #[Test]
+    public function itActivatesLicenseSuccessfully(): void
+    {
+        $responseData = [
+            'success' => true,
+            'message' => 'License activated successfully.',
+        ];
+
+        $client = $this->createClientWithResponse($responseData);
+
+        $result = $client->activate(self::LICENSE_KEY, self::DOMAIN);
+
+        self::assertInstanceOf(ActivationResult::class, $result);
+        self::assertTrue($result->success);
+        self::assertSame('License activated successfully.', $result->message);
+    }
+
+    #[Test]
+    public function itLogsValidationRequests(): void
+    {
+        $responseData = [
+            'valid' => true,
+            'license' => [
+                'product_id' => 123,
+                'expires_at' => null,
+                'version_id' => null,
+            ],
+        ];
+
+        $logger = $this->createMock(LoggerInterface::class);
+        $logger->expects(self::atLeastOnce())
+            ->method('info')
+            ->with(self::stringContains('License'));
+
+        $client = $this->createClientWithResponse($responseData, 200, $logger);
+
+        $client->validate(self::LICENSE_KEY, self::DOMAIN);
+    }
+
+    #[Test]
+    public function itThrowsExceptionOnHttpError(): void
+    {
+        $httpClient = new MockHttpClient([
+            new MockResponse('', ['http_code' => 500, 'error' => 'Server error']),
+        ]);
+
+        $client = new LicenseClient($httpClient, self::BASE_URL);
+
+        $this->expectException(LicenseException::class);
+
+        $client->validate(self::LICENSE_KEY, self::DOMAIN);
+    }
+
+    #[Test]
+    public function itSendsRequestToCorrectEndpoint(): void
+    {
+        $requestHistory = [];
+
+        $httpClient = new MockHttpClient(function ($method, $url) use (&$requestHistory) {
+            $requestHistory[] = ['method' => $method, 'url' => $url];
+
+            return new MockResponse(json_encode([
+                'valid' => true,
+                'license' => ['product_id' => 1, 'expires_at' => null, 'version_id' => null],
+            ]));
+        });
+
+        $client = new LicenseClient($httpClient, self::BASE_URL);
+        $client->validate(self::LICENSE_KEY, self::DOMAIN);
+
+        self::assertCount(1, $requestHistory);
+        self::assertSame('POST', $requestHistory[0]['method']);
+        self::assertStringContainsString('/wp-json/wc-licensed-product/v1/validate', $requestHistory[0]['url']);
+    }
+
+    private function createClientWithResponse(
+        array $responseData,
+        int $statusCode = 200,
+        ?LoggerInterface $logger = null,
+    ): LicenseClient {
+        $httpClient = new MockHttpClient([
+            new MockResponse(json_encode($responseData), ['http_code' => $statusCode]),
+        ]);
+
+        return new LicenseClient($httpClient, self::BASE_URL, $logger);
+    }
+}