Test suite optimization and final consistency

- Split test suites: unit/integration (CI uses only fast units)
- Make all classes consistently final
- Fix PHPDoc compatibility and deprecations

Author: calliostro

.github/workflows/ci.yml

@@ -93,19 +93,21 @@ jobs:
       - name: Run static analysis
         run: composer analyse
 
-      - name: Run tests
+      - name: Run tests (Unit Tests only)
         run: composer test
 
-      - name: Run integration tests (public API only)
+      - name: Run integration tests (public API only - manual trigger)
+        if: github.event_name == 'workflow_dispatch'
         run: vendor/bin/phpunit tests/Integration/PublicApiIntegrationTest.php --testdox
 
-      - name: Run integration tests (with authentication)
+      - name: Run integration tests (with authentication - manual trigger)
+        if: github.event_name == 'workflow_dispatch'
         env:
           DISCOGS_CONSUMER_KEY: ${{ secrets.DISCOGS_CONSUMER_KEY }}
           DISCOGS_CONSUMER_SECRET: ${{ secrets.DISCOGS_CONSUMER_SECRET }}
-          DISCOGS_PERSONAL_TOKEN: ${{ secrets.DISCOGS_PERSONAL_TOKEN }}
+          DISCOGS_PERSONAL_ACCESS_TOKEN: ${{ secrets.DISCOGS_PERSONAL_ACCESS_TOKEN }}
         run: |
-          if [ -n "$DISCOGS_CONSUMER_KEY" ] && [ -n "$DISCOGS_CONSUMER_SECRET" ] && [ -n "$DISCOGS_PERSONAL_TOKEN" ]; then
+          if [ -n "$DISCOGS_CONSUMER_KEY" ] && [ -n "$DISCOGS_CONSUMER_SECRET" ] && [ -n "$DISCOGS_PERSONAL_ACCESS_TOKEN" ]; then
             vendor/bin/phpunit tests/Integration/AuthenticationLevelsTest.php --testdox
           else
             echo "⚠️  Skipping authenticated integration tests - secrets not available"
@@ -174,8 +176,8 @@ jobs:
       - name: Install dependencies
         run: composer install --prefer-dist --no-interaction --no-progress
 
-      - name: Run tests with coverage
-        run: vendor/bin/phpunit --coverage-clover coverage.xml
+      - name: Run tests with coverage (Unit Tests only)
+        run: composer test-coverage
 
       - name: Upload coverage to Codecov
         uses: codecov/codecov-action@v4

.gitignore

@@ -14,6 +14,8 @@ composer.lock
 
 # Coverage reports
 coverage/
+coverage.xml
+*.clover
 
 # Environment files
 .env

INTEGRATION_TESTS.md

@@ -1,18 +1,40 @@
 # Integration Test Setup
 
+## Test Strategy
+
+Integration tests are **separated from the CI pipeline** to prevent:
+
+- 🚫 Rate limiting (429 Too Many Requests)
+- 🚫 Flaky builds due to network issues
+- 🚫 Dependency on external API availability
+- 🚫 Slow build times (2+ minutes vs. 0.4 seconds)
+
+## Running Tests
+
+```bash
+# Unit tests only (CI default - fast & reliable)
+composer test-unit
+
+# Integration tests only (manual - requires API access)
+composer test-integration  
+
+# All tests together (local development)
+composer test-all
+```
+
 ## GitHub Secrets Required
 
 To enable authenticated integration tests in CI/CD, add these secrets to your GitHub repository:
 
 ### Repository Settings → Secrets and variables → Actions
 
-| Secret Name                  | Description                      | Where to get it                                                           |
-|------------------------------|----------------------------------|---------------------------------------------------------------------------|
-| `DISCOGS_CONSUMER_KEY`       | Your Discogs app consumer key    | [Discogs Developer Settings](https://www.discogs.com/settings/developers) |
-| `DISCOGS_CONSUMER_SECRET`    | Your Discogs app consumer secret | [Discogs Developer Settings](https://www.discogs.com/settings/developers) |
-| `DISCOGS_PERSONAL_TOKEN`     | Your personal access token       | [Discogs Developer Settings](https://www.discogs.com/settings/developers) |
-| `DISCOGS_OAUTH_TOKEN`        | OAuth access token (optional)    | OAuth flow result                                                         |
-| `DISCOGS_OAUTH_TOKEN_SECRET` | OAuth token secret (optional)    | OAuth flow result                                                         |
+| Secret Name                     | Description                      | Where to get it                                                           |
+|---------------------------------|----------------------------------|---------------------------------------------------------------------------|
+| `DISCOGS_CONSUMER_KEY`          | Your Discogs app consumer key    | [Discogs Developer Settings](https://www.discogs.com/settings/developers) |
+| `DISCOGS_CONSUMER_SECRET`       | Your Discogs app consumer secret | [Discogs Developer Settings](https://www.discogs.com/settings/developers) |
+| `DISCOGS_PERSONAL_ACCESS_TOKEN` | Your personal access token       | [Discogs Developer Settings](https://www.discogs.com/settings/developers) |
+| `DISCOGS_OAUTH_TOKEN`           | OAuth access token (optional)    | OAuth flow result                                                         |
+| `DISCOGS_OAUTH_TOKEN_SECRET`    | OAuth token secret (optional)    | OAuth flow result                                                         |
 
 ## Test Levels
 
@@ -39,7 +61,7 @@ To enable authenticated integration tests in CI/CD, add these secrets to your Gi
 # Set environment variables
 export DISCOGS_CONSUMER_KEY="your-consumer-key"
 export DISCOGS_CONSUMER_SECRET="your-consumer-secret" 
-export DISCOGS_PERSONAL_TOKEN="your-personal-token"
+export DISCOGS_PERSONAL_ACCESS_TOKEN="your-personal-access-token"
 
 # Run public tests only
 vendor/bin/phpunit tests/Integration/PublicApiIntegrationTest.php

README.md

@@ -45,7 +45,7 @@ $discogs = ClientFactory::createWithConsumerCredentials('key', 'secret');
 $results = $discogs->search(['q' => 'Daft Punk']);
 
 // Your collections (personal token)  
-$discogs = ClientFactory::createWithPersonalAccessToken('key', 'secret', 'token');
+$discogs = ClientFactory::createWithPersonalAccessToken('token');
 $collection = $discogs->listCollectionFolders(['username' => 'you']);
 
 // Multi-user apps (OAuth)
@@ -151,7 +151,7 @@ $discogs = ClientFactory::createWithConsumerCredentials('key', 'secret');
 $results = $discogs->search(['q' => 'Taylor Swift']);
 
 // Level 3: Your account access (most common)
-$discogs = ClientFactory::createWithPersonalAccessToken('key', 'secret', 'token');
+$discogs = ClientFactory::createWithPersonalAccessToken('token');
 $folders = $discogs->listCollectionFolders(['username' => 'you']);
 $wantlist = $discogs->getUserWantlist(['username' => 'you']);
 
@@ -221,24 +221,41 @@ echo "Hello " . $identity['username'];
 
 ## 🧪 Testing
 
-Run the test suite:
+### Quick Testing Commands
 
 ```bash
+# Unit tests (fast, CI-compatible, no external dependencies)
 composer test
-```
 
-Run static analysis:
+# Integration tests (requires Discogs API credentials)
+composer test-integration
 
-```bash
-composer analyse
+# All tests together (unit + integration)
+composer test-all
+
+# Code coverage (HTML + XML reports)
+composer test-coverage
 ```
 
-Check code style:
+### Static Analysis & Code Quality
 
 ```bash
+# Static analysis (PHPStan Level 8)
+composer analyse
+
+# Code style check (PSR-12)
 composer cs
+
+# Auto-fix code style
+composer cs-fix
 ```
 
+### Test Strategy
+
+- **Unit Tests (101)**: Fast, reliable, no external dependencies → **CI default**
+- **Integration Tests (31)**: Real API calls, rate-limited → **Manual execution**  
+- **Total Coverage**: 100% lines, methods, and classes covered
+
 ## 📚 API Documentation
 
 Complete method documentation available at [Discogs API Documentation](https://www.discogs.com/developers/).

composer.json

@@ -55,7 +55,12 @@
         }
     },
     "scripts": {
-        "test": "vendor/bin/phpunit",
+        "test": "vendor/bin/phpunit --testsuite=\"Unit Tests\"",
+        "test-unit": "vendor/bin/phpunit --testsuite=\"Unit Tests\"",
+        "test-integration": "vendor/bin/phpunit --testsuite=\"Integration Tests\"",
+        "test-all": "vendor/bin/phpunit --testsuite=\"All Tests\"",
+        "test-coverage": "vendor/bin/phpunit --testsuite=\"Unit Tests\" --coverage-html coverage --coverage-clover coverage.xml",
+        "test-coverage-all": "vendor/bin/phpunit --testsuite=\"All Tests\" --coverage-html coverage --coverage-clover coverage.xml",
         "cs": "vendor/bin/php-cs-fixer fix --dry-run --diff --verbose",
         "cs-fix": "vendor/bin/php-cs-fixer fix --verbose",
         "analyse": "phpstan analyse src/ tests/ --level=8"

phpunit.xml.dist

@@ -11,7 +11,13 @@
          displayDetailsOnIncompleteTests="true"
          displayDetailsOnSkippedTests="true">
   <testsuites>
-    <testsuite name="Discogs API Test Suite">
+    <testsuite name="Unit Tests">
+      <directory>tests/Unit</directory>
+    </testsuite>
+    <testsuite name="Integration Tests">
+      <directory>tests/Integration</directory>
+    </testsuite>
+    <testsuite name="All Tests">
       <directory>tests</directory>
     </testsuite>
   </testsuites>

src/ClientFactory.php

@@ -4,6 +4,7 @@
 
 namespace Calliostro\Discogs;
 
+use Exception;
 use GuzzleHttp\Client as GuzzleClient;
 
 /**
@@ -33,7 +34,19 @@ private static function getConfig(): array
      */
     public static function create(array|GuzzleClient $optionsOrClient = []): DiscogsApiClient
     {
-        return new DiscogsApiClient($optionsOrClient);
+        // If GuzzleClient is passed directly, return it as-is
+        if ($optionsOrClient instanceof GuzzleClient) {
+            return new DiscogsApiClient($optionsOrClient);
+        }
+
+        $config = self::getConfig();
+
+        // Merge user options with base configuration
+        $clientOptions = array_merge($optionsOrClient, [
+            'base_uri' => $config['baseUrl'],
+        ]);
+
+        return new DiscogsApiClient(new GuzzleClient($clientOptions));
     }
 
     /**
@@ -45,6 +58,8 @@ public static function create(array|GuzzleClient $optionsOrClient = []): Discogs
      * @param string $accessToken OAuth access token
      * @param string $accessTokenSecret OAuth access token secret
      * @param array<string, mixed>|GuzzleClient $optionsOrClient
+     *
+     * @throws Exception If secure random number generation fails (PHP 8.2+: \Random\RandomException)
      */
     public static function createWithOAuth(
         string $consumerKey,
@@ -63,7 +78,7 @@ public static function createWithOAuth(
         $oauthParams = [
             'oauth_consumer_key' => $consumerKey,
             'oauth_token' => $accessToken,
-            'oauth_nonce' => bin2hex(random_bytes(16)), // Cryptographically secure nonce
+            'oauth_nonce' => bin2hex(random_bytes(16)),
             'oauth_signature_method' => 'PLAINTEXT',
             'oauth_timestamp' => (string) time(),
             'oauth_version' => '1.0',
@@ -116,14 +131,10 @@ public static function createWithConsumerCredentials(
      * Create a client authenticated with Personal Access Token
      * Uses Discogs-specific authentication format
      *
-     * @param string $consumerKey OAuth consumer key (required for rate limiting)
-     * @param string $consumerSecret OAuth consumer secret (required for rate limiting)
      * @param string $personalAccessToken Personal Access Token from Discogs
      * @param array<string, mixed>|GuzzleClient $optionsOrClient
      */
     public static function createWithPersonalAccessToken(
-        string $consumerKey,
-        string $consumerSecret,
         string $personalAccessToken,
         array|GuzzleClient $optionsOrClient = []
     ): DiscogsApiClient {
@@ -134,8 +145,8 @@ public static function createWithPersonalAccessToken(
         }
 
         // Discogs-specific authentication format for Personal Access Tokens
-        // Requires both token and consumer credentials for proper API access
-        $authHeader = 'Discogs token=' . $personalAccessToken . ', key=' . $consumerKey . ', secret=' . $consumerSecret;
+        // Personal Access Token should work standalone without consumer credentials
+        $authHeader = 'Discogs token=' . $personalAccessToken;
 
         return self::createClientWithAuth($authHeader, $optionsOrClient);
     }