feat: Improve the FileSystemTestCase (#57)

Simplify the usage by no longer requiring to implement an abstract
method.

A significant (internal, but observable) change is that we no longer use
a namespaced directory. Indeed, instead of having:

```
/path/to/system/default-tmp/
  TestCaseThreadSafeNamespace/
    tmpDir1
    tmpDir2
    ...
```

We now have:

```
/path/to/system/default-tmp/
  tmpDir1
  tmpDir2
  ...
```

Indeed, the creation of the temporary directory is already thread safe,
so there is no need for the user to implement an abstract method. And
because of it, we can remove the usage of a namespace which is not that
useful and if anything may mess up the thread safety.

Author: theofidry

README.md

@@ -123,7 +123,7 @@ An example of a PHPUnit test:
 
 <?php declare(strict_types=1);
 
-namespace App;
+namespace App\Tests;
 
 use Fidry\FileSystem\FS;
 use Fidry\FileSystem\Test\FileSystemTestCase;
@@ -134,25 +134,12 @@ use function is_string;
 
 final class MyAppFileSystemTest extends FileSystemTestCase
 {
-    // This method needs to be implemented by your test or base filesystem test class.
-    public static function getTmpDirNamespace(): string
-    {
-        // This is to make it thread safe with Infection. If you are not using
-        // infection or do not need thread safety, this can return a constant
-        // string, e.g. your project/library name.
-        $threadId = getenv('TEST_TOKEN');
-
-        if (!is_string($threadId)) {
-            $threadId = '';
-        }
-
-        return 'MyApp'.$threadId;
-    }
-
     public function test_it_works(): void
     {
+        // The temporary directory can be changed by overriding `::getTmpDirPrefix()`.
+    
         // This file is dumped into a temporary directory. Here,
-        // something like '/private/var/folders/p3/lkw0cgjj2fq0656q_9rd0mk80000gn/T/MyApp/MyAppFileSystemTest10000'
+        // something like '/private/var/folders/p3/lkw0cgjj2fq0656q_9rd0mk80000gn/T/AppTestsMyAppFileSystemTest10000'
         // on OSX.
         FS::dumpFile('file1', '');
 
@@ -162,6 +149,17 @@ final class MyAppFileSystemTest extends FileSystemTestCase
 
         self::assertSame(['file1'], $this->normalizePaths($files));
     }
+    
+    // Utility methods available:
+    /**
+     * @param iterable<string|Stringable> $paths
+     *
+     * @return list<string> File real paths relative to the current temporary directory
+     */
+    function normalizePaths(iterable $paths): array;
+    
+    static function safeChdir(string $directory): void;
+    static function safeGetCurrentWorkingDirectory(): string;
 }
 
 ```

UPGRADE.md

@@ -2,6 +2,13 @@
 
 - The class `FileSystem` was renamed `NativeFileSystem`. `FileSystem` is now an
   interface.
+- Made explicit the dependency on `ext-mbstring`. If you do not have this dependency
+  met use [symfony/polyfill-mbstring](https://packagist.org/packages/symfony/polyfill-mbstring).
 - Deprecated the `::getFileContents()` method in favour of `::readFile()`.
 - Deprecated the `::isAbsolutePath()` method in favour of `Path::isAbsolute()`.
 - Deprecated the `::isRelativePath()` method in favour of `Path::isRelative()`.
+- Deprecated the `::makeTmpDir()` method in favour of `::tmpDir()`.
+- Deprecated the `::getNamespacedTmpDir()` method in favour of `::tmpDir()`.
+- Deprecated the `FileSystemTestCase::getTmpDirNamespace()` has been removed. This was requiring too 
+  much boilerplate. Instead, the temporary directory is now already thread safe although it no longer
+  creates one unique directory.

infection.json.dist

@@ -40,5 +40,11 @@
         "FunctionCallRemoval": false,
         "MethodCallRemoval": false,
         "PublicVisibility": false,
+        "ProtectedVisibility": false,
+        "UnwrapStrReplace": {
+            "ignore": [
+                "Fidry\\FileSystem\\Test\\FileSystemTestCase::getTmpDirPrefix"
+            ]
+        }
     }
 }

src/Test/FileSystemTestCase.php

@@ -43,7 +43,6 @@
 use function array_map;
 use function array_values;
 use function chdir;
-use function dirname;
 use function getcwd;
 use function is_array;
 use function iterator_to_array;
@@ -55,34 +54,18 @@
 
 abstract class FileSystemTestCase extends TestCase
 {
-    protected static ?string $lastKnownTmpNamespace = null;
-
     protected string $cwd = '';
     protected string $tmp = '';
 
-    /**
-     * To make it thread safe you cna make the namespace different on a thread basis,
-     * e.g. based on an environment variable which indicates the thread "ID".
-     */
-    abstract public static function getTmpDirNamespace(): string;
-
-    public static function tearDownAfterClass(): void
-    {
-        // Cleans up whatever was there before. Indeed, upon failure PHPUnit may fail to trigger the
-        // `tearDown()` method and as a result some temporary files may still remain.
-        if (null !== static::$lastKnownTmpNamespace) {
-            FS::remove(static::$lastKnownTmpNamespace);
-        }
-    }
-
     protected function setUp(): void
     {
+        $tmpDirPrefix = $this->getTmpDirPrefix();
+
         $this->cwd = self::safeGetCurrentWorkingDirectory();
-        $this->tmp = FS::makeTmpDir(
-            static::getTmpDirNamespace(),
-            static::class,
-        );
-        static::$lastKnownTmpNamespace = dirname($this->tmp);
+        // We use the real path here as, for example, in OSX, the path returned
+        // is otherwise a link.
+        $this->tmp = FS::realPath(FS::tmpDir($tmpDirPrefix));
+
         self::safeChdir($this->tmp);
     }
 
@@ -94,6 +77,9 @@ protected function tearDown(): void
             self::safeChdir($this->cwd);
             FS::remove($this->tmp);
         }
+
+        $this->cwd = '';
+        $this->tmp = '';
     }
 
     /**
@@ -118,7 +104,7 @@ final protected function normalizePaths(iterable $paths): array
         return array_values($normalizedPaths);
     }
 
-    private static function safeChdir(string $directory): void
+    final protected static function safeChdir(string $directory): void
     {
         $chdirResult = chdir($directory);
 
@@ -132,7 +118,7 @@ private static function safeChdir(string $directory): void
         }
     }
 
-    private static function safeGetCurrentWorkingDirectory(): string
+    final protected static function safeGetCurrentWorkingDirectory(): string
     {
         $result = getcwd();
 
@@ -142,4 +128,14 @@ private static function safeGetCurrentWorkingDirectory(): string
 
         return $result;
     }
+
+    /**
+     * If the test case is `App\Tests\MyFilesystemServiceTestCase`, the default prefix will be "App\Tests\MyFilesystemServiceTestCase".
+     *
+     * @return string
+     */
+    protected function getTmpDirPrefix(): string
+    {
+        return str_replace('\\', '', static::class);
+    }
 }

tests/Test/FilesystemTestCaseTest.php

@@ -41,8 +41,7 @@
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\Attributes\Small;
 use Symfony\Component\Finder\Finder;
-use function getenv;
-use function is_string;
+use function getcwd;
 
 /**
  * @internal
@@ -51,22 +50,40 @@
 #[Small]
 final class FilesystemTestCaseTest extends FileSystemTestCase
 {
-    public static function getTmpDirNamespace(): string
+    private string $cwdBeforeSetUp = '';
+
+    protected function setUp(): void
+    {
+        $this->cwdBeforeSetUp = getcwd();
+
+        parent::setUp();
+    }
+
+    protected function tearDown(): void
     {
-        $threadId = getenv('TEST_TOKEN');
+        $tmpBeforeCleanup = $this->tmp;
+
+        parent::tearDown();
 
-        if (!is_string($threadId)) {
-            $threadId = '';
-        }
+        $cwdAfterTearDown = getcwd();
 
-        return 'FidryFilesystem'.$threadId;
+        // It is not very elegant to test in a teardown, but it's easier that
+        // way...
+
+        self::assertSame('', $this->cwd, 'Expected the current working directory to have been reset.');
+        self::assertSame('', $this->tmp, 'Expected the current temporary directory to have been reset.');
+        self::assertSame($this->cwdBeforeSetUp, $cwdAfterTearDown, 'Expected the current working directory to have been restored.');
+        self::assertDirectoryDoesNotExist($tmpBeforeCleanup, 'Expected the temporary directory to have been removed.');
     }
 
-    public function test_it_works(): void
+    public function test_it_creates_a_temporary_directory_to_which_we_switch_to(): void
     {
-        self::assertNotNull($this->cwd);
-        self::assertNotNull($this->tmp);
-        self::assertNotNull(self::$lastKnownTmpNamespace);
+        $cwd = getcwd();
+
+        self::assertNotSame('', $this->cwd, 'Expected the current working directory to be set.');
+        self::assertNotSame('', $this->tmp, 'Expected the current temporary directory to be set.');
+        self::assertSame($this->cwdBeforeSetUp, $this->cwd, 'Expected the current working directory before setup to have been stored.');
+        self::assertSame($this->tmp, $cwd, 'Expected the current working directory to be the temporary directory.');
     }
 
     public function test_it_can_provide_the_relative_paths(): void