Tests Laravel Package

Getting Started

Minimal Steps

1. Install Dependencies:

   composer require --dev php-ds/php-ds phpunit/phpunit ^11
   

   Ensure your composer.json targets PHP 8.2+.

2. Clone the Test Suite:

   git clone https://github.com/php-ds/tests.git
   

   Or include it as a dev dependency:

   composer require --dev php-ds/tests
   

3. First Use Case: Run a basic test for Map operations to validate correctness:

   vendor/bin/phpunit --filter testMapOperations
   

   Focus on MapTest, SeqTest, or HeapTest based on your needs.

4. Key Files to Review:

   • tests/MapTest.php (for key-value operations)
   • tests/SeqTest.php (for sequence/iterator behavior)
   • tests/HeapTest.php (for priority queue logic)

Implementation Patterns

Usage Patterns

1. Trait-Based Testing: Use traits like MapTrait or SeqTrait to modularize test logic. Example:

   use php\ds\tests\MapTrait;
   
   class CustomMapTest extends TestCase
   {
       use MapTrait;
   
       public function testCustomMapBehavior()
       {
           $this->testMapOperations();
           // Add Laravel-specific assertions
       }
   }
   

2. Integration with Laravel Services: Wrap php-ds structures in Laravel service classes and test interactions:

   namespace App\Services;
   
   use php\ds\Map;
   
   class CacheService
   {
       public function __construct(private Map $cache) {}
   
       public function get(string $key): mixed
       {
           return $this->cache->get($key);
       }
   }
   

   Test the service with Laravel’s testing helpers:

   use App\Services\CacheService;
   use php\ds\Map;
   
   class CacheServiceTest extends TestCase
   {
       public function testCacheService()
       {
           $cache = new Map();
           $service = new CacheService($cache);
           $cache->put('test', 'value');
           $this->assertEquals('value', $service->get('test'));
       }
   }
   

3. Benchmarking: Compare php-ds performance against Laravel’s Collection:

   use php\ds\Map;
   use Illuminate\Support\Collection;
   
   class PerformanceTest extends TestCase
   {
       public function testMapVsCollection()
       {
           $map = new Map();
           $collection = collect();
   
           // Benchmark insertion
           $this->benchmark(fn() => $map->put('key', 'value'), 'php-ds Map');
           $this->benchmark(fn() => $collection->put('key', 'value'), 'Laravel Collection');
       }
   }
   

4. Edge Case Validation: Leverage existing tests for edge cases (e.g., 0.0/-0.0 keys):

   use php\ds\tests\MapTrait;
   
   class EdgeCaseTest extends TestCase
   {
       use MapTrait;
   
       public function testZeroKeys()
       {
           $this->testMapWithKeys([0.0, -0.0, 'normal_key']);
       }
   }
   

Workflows

1. Adopt php-ds for High-Performance Features:

   • Replace SplQueue with php-ds\Deque in job processing.
   • Use php-ds\Heap for priority-based scheduling.

2. Leverage Tests for Custom Structures:

   • Extend SeqTest traits to validate custom sequence logic in Laravel packages.

3. Isolate php-ds from Laravel Core:

   • Keep php-ds usage confined to services or standalone libraries to avoid dependency conflicts.

Integration Tips

• PHPUnit Configuration: Add a separate test suite for php-ds in phpunit.xml:

  <configurations>
      <configuration default="true" name="laravel">
          <!-- Laravel tests -->
      </configuration>
      <configuration name="php-ds">
          <php>
              <ini name="memory_limit" value="-1"/>
          </php>
          <extensions>
              <extension class="PHPUnit\Extensions\PhpDSTestCase"/>
          </extensions>
      </configuration>
  </configurations>
  

• Type Safety: Use php-ds’s generic types (e.g., Vector<int>) in Laravel services to enforce stricter typing:

  use php\ds\Vector;
  
  class IdGenerator
  {
      private Vector<int> $ids;
  
      public function __construct()
      {
          $this->ids = new Vector();
      }
  
      public function generate(): int
      {
          return $this->ids->push(1); // Type-safe
      }
  }
  

• Testing in CI: Add a CI job to validate php-ds tests:

  jobs:
    php-ds-tests:
      runs-on: ubuntu-latest
      steps:
        - uses: actions/checkout@v4
        - uses: shivammathur/setup-php@v2
          with:
            php-version: '8.2'
            extensions: xdebug
        - run: composer require php-ds/php-ds phpunit/phpunit ^11 --dev
        - run: vendor/bin/phpunit --testsuite php-ds
  

Gotchas and Tips

Pitfalls

1. PHPUnit Version Mismatch:

   • Issue: Laravel 9/10 uses PHPUnit 9/10, but php-ds/tests requires PHPUnit 11.
   • Fix: Use a separate test suite or upgrade Laravel to v10+ with PHP 8.2+.

2. Laravel Helper Conflicts:

   • Issue: Tests assume PHPUnit’s global functions (e.g., assertEquals), which may conflict with Laravel’s testing helpers.
   • Fix: Use PHPUnit\Framework\TestCase as the base class for php-ds tests.

3. Missing Laravel-Specific Tests:

   • Issue: No tests for Laravel integrations (e.g., Eloquent, Queues).
   • Fix: Write custom tests for php-ds-backed Laravel services.

4. Deprecated Structures:

   • Issue: VectorTest, DequeTest, etc., were removed in v2.0.0.
   • Fix: Use SeqTest for sequence-like behavior or adapt existing traits.

5. Key Interface Changes:

   • Issue: HashableObject → KeyObject in v2.0.0 may break custom implementations.
   • Fix: Update custom key objects to implement Ds\Key.

Debugging

1. Test Failures:

   • Run tests with -v for verbose output:

     vendor/bin/phpunit --filter testMapOperations -v
     

   • Check for Key interface compliance if tests fail on custom objects.

2. Performance Bottlenecks:

   • Use Xdebug to profile php-ds operations:

     XDEBUG_MODE=debug vendor/bin/phpunit --filter testHeapOperations
     

3. Type Errors:

   • Enable strict types in php.ini:

     declare(strict_types=1);
     

   • Ensure php-ds structures are typed correctly (e.g., Vector<string>).

Config Quirks

1. PHP 8.2+ Features:

   • Enable php-ds’s modern features (e.g., Key interface) by ensuring:

     php_version = "8.2"
     

2. Memory Limits:

   • Increase memory for large test suites:

     <php>
         <ini name="memory_limit" value="1G"/>
     </php>
     

3. Autoloading:

   • Ensure php-ds is autoloaded in composer.json:

     "autoload": {
         "psr-4": {
             "php\\ds\\": "vendor/php-ds/php-ds/src"
         }
     }
     

Extension Points

1. Custom Traits:

   • Extend existing traits (e.g., MapTrait) for Laravel-specific logic:

     trait LaravelMapTrait
     {
         use \php\ds\tests\MapTrait;
     
         public function testMapWithEloquent()
         {
             $model = Model::factory()->create();
             $map = new Map();
             $map->put($model->id, $model);
             $this->assertInstanceOf(Model::class, $map->get($model->id));
         }
     }
     

2. Benchmarking Helpers:

   • Create a custom test case for performance comparisons:

     abstract class BenchmarkTestCase extends TestCase
     {
         protected function benchmark(callable $callback, string $name): void
         {
             $start = microtime(true);
             $callback();
             $time = microtime(true) - $start;
             $this->output()->writeln(sprintf("Benchmark: