Flysystem Adapter Test Utilities Laravel Package

Getting Started

Minimal Steps

1. Installation Add the package via Composer:

   composer require --dev league/flysystem-adapter-test-utilities
   

2. Basic Usage Import the League\Flysystem\Adapter\TestUtil\TestAdapter class and use it to mock a filesystem adapter for testing:

   use League\Flysystem\Adapter\TestUtil\TestAdapter;
   
   $testAdapter = new TestAdapter();
   $filesystem = new League\Flysystem\Filesystem($testAdapter);
   

3. First Use Case Test file operations (e.g., upload, read, delete) without hitting a real storage system:

   $filesystem->write('test.txt', 'Hello, Laravel!');
   $contents = $filesystem->read('test.txt');
   $this->assertEquals('Hello, Laravel!', $contents);
   

Where to Look First

• Documentation: League/Flysystem Adapter Test Utilities
• Source Code: Focus on TestAdapter and TestFilesystem classes in the package.
• Laravel Integration: Check how Laravel’s Storage facade can use custom adapters (e.g., Filesystem::adapter()).

Implementation Patterns

Workflows

1. Unit Testing Adapters Mock a filesystem adapter for isolated tests:

   public function testFileUpload()
   {
       $adapter = new TestAdapter();
       $filesystem = new Filesystem($adapter);
   
       $filesystem->write('file.txt', 'content');
       $this->assertTrue($adapter->has('file.txt'));
   }
   

2. Integration with Laravel Storage Replace Laravel’s default adapter with TestAdapter in tests:

   use Illuminate\Support\Facades\Storage;
   
   public function testCustomAdapter()
   {
       Storage::extend('test', function () {
           return new Filesystem(new TestAdapter());
       });
   
       Storage::disk('test')->put('file.txt', 'content');
       $this->assertTrue(Storage::disk('test')->exists('file.txt'));
   }
   

3. Customizing Test Data Pre-populate the adapter with test files:

   $adapter = new TestAdapter();
   $adapter->addFile('existing.txt', 'pre-existing content');
   

Integration Tips

• Laravel Testing: Use Storage::fake() for Laravel’s built-in fake storage, but TestAdapter is useful for custom adapters.
• Custom Adapters: Extend TestAdapter to simulate edge cases (e.g., read-only mode):

  class ReadOnlyTestAdapter extends TestAdapter
  {
      public function write($path, $contents, Config $config)
      {
          throw new RuntimeException('Read-only mode');
      }
  }
  

• Assertions: Combine with PHPUnit assertions or Laravel’s assertDatabaseHas equivalents for filesystem checks.

Gotchas and Tips

Pitfalls

1. State Management TestAdapter retains state between tests. Reset it or use a fresh instance per test:

   $adapter = new TestAdapter(); // Fresh instance per test
   

2. Laravel’s Fake Storage Avoid mixing Storage::fake() with TestAdapter—they serve different purposes. Use one or the other.

3. Visibility of Test Files Files added via addFile() are not visible to Laravel’s Storage facade unless explicitly configured.

Debugging

• Inspect Contents: Use $adapter->listContents() to debug file structure.
• Clear State: Call $adapter->clear() to wipe all test data between tests.

Extension Points

1. Custom Adapters Extend TestAdapter to simulate specific behaviors (e.g., slow responses, quota limits):

   class SlowTestAdapter extends TestAdapter
   {
       public function read($path, Config $config)
       {
           sleep(2); // Simulate latency
           return parent::read($path, $config);
       }
   }
   

2. Mocking Exceptions Override methods to throw exceptions for error-case testing:

   public function delete($path)
   {
       throw new RuntimeException('Permission denied');
   }
   

3. Laravel Service Providers Dynamically swap adapters in tests using Laravel’s Storage::extend():

   Storage::extend('test', function () {
       return new Filesystem(new TestAdapter());
   });
   

Config Quirks

• Config Objects: Methods like write() accept a Config object (e.g., visibility, timestamp). Pass null for defaults:

  $adapter->write('file.txt', 'content', null);