chore: tests documentation classes (#7855)

dev-tools/doc.php

@@ -19,8 +19,9 @@ require __DIR__.'/../vendor/autoload.php';
 
 use PhpCsFixer\Console\Command\DocumentationCommand;
 use Symfony\Component\Console\Application;
+use Symfony\Component\Filesystem\Filesystem;
 
-$command = new DocumentationCommand();
+$command = new DocumentationCommand(new Filesystem());
 
 $application = new Application();
 $application->add($command);

src/Console/Command/DocumentationCommand.php

@@ -36,6 +36,14 @@ final class DocumentationCommand extends Command
     /** @var string */
     protected static $defaultName = 'documentation';
 
+    private Filesystem $filesystem;
+
+    public function __construct(Filesystem $filesystem)
+    {
+        parent::__construct();
+        $this->filesystem = $filesystem;
+    }
+
     protected function configure(): void
     {
         $this
@@ -46,7 +54,6 @@ final class DocumentationCommand extends Command
 
     protected function execute(InputInterface $input, OutputInterface $output): int
     {
-        $filesystem = new Filesystem();
         $locator = new DocumentationLocator();
 
         $fixerFactory = new FixerFactory();
@@ -66,7 +73,7 @@ final class DocumentationCommand extends Command
 
         foreach ($fixers as $fixer) {
             $docForFixerRelativePaths[] = $locator->getFixerDocumentationFileRelativePath($fixer);
-            $filesystem->dumpFile(
+            $this->filesystem->dumpFile(
                 $locator->getFixerDocumentationFilePath($fixer),
                 $fixerDocumentGenerator->generateFixerDocumentation($fixer)
             );
@@ -78,12 +85,12 @@ final class DocumentationCommand extends Command
                 ->in($locator->getFixersDocumentationDirectoryPath())
                 ->notPath($docForFixerRelativePaths) as $file
         ) {
-            $filesystem->remove($file->getPathname());
+            $this->filesystem->remove($file->getPathname());
         }
 
         // Fixer doc. index
 
-        $filesystem->dumpFile(
+        $this->filesystem->dumpFile(
             $locator->getFixersDocumentationIndexFilePath(),
             $fixerDocumentGenerator->generateFixersDocumentationIndex($fixers)
         );
@@ -92,7 +99,7 @@ final class DocumentationCommand extends Command
 
         /** @var SplFileInfo $file */
         foreach ((new Finder())->files()->in($locator->getRuleSetsDocumentationDirectoryPath()) as $file) {
-            $filesystem->remove($file->getPathname());
+            $this->filesystem->remove($file->getPathname());
         }
 
         $paths = [];
@@ -100,12 +107,12 @@ final class DocumentationCommand extends Command
         foreach ($setDefinitions as $name => $definition) {
             $path = $locator->getRuleSetsDocumentationFilePath($name);
             $paths[$path] = $definition;
-            $filesystem->dumpFile($path, $ruleSetDocumentationGenerator->generateRuleSetsDocumentation($definition, $fixers));
+            $this->filesystem->dumpFile($path, $ruleSetDocumentationGenerator->generateRuleSetsDocumentation($definition, $fixers));
         }
 
         // RuleSet doc. index
 
-        $filesystem->dumpFile(
+        $this->filesystem->dumpFile(
             $locator->getRuleSetsDocumentationIndexFilePath(),
             $ruleSetDocumentationGenerator->generateRuleSetsDocumentationIndex($paths)
         );

src/Documentation/DocumentationLocator.php

@@ -73,11 +73,6 @@ final class DocumentationLocator
         return $this->getRuleSetsDocumentationDirectoryPath().'/'.str_replace(':risky', 'Risky', ucfirst(substr($name, 1))).'.rst';
     }
 
-    public function getListingFilePath(): string
-    {
-        return $this->path.'/list.rst';
-    }
-
     public function getUsageFilePath(): string
     {
         return $this->path.'/usage.rst';

tests/AutoReview/ProjectCodeTest.php

@@ -17,14 +17,9 @@ namespace PhpCsFixer\Tests\AutoReview;
 use PhpCsFixer\AbstractFixer;
 use PhpCsFixer\AbstractPhpdocTypesFixer;
 use PhpCsFixer\AbstractProxyFixer;
-use PhpCsFixer\Console\Command\DocumentationCommand;
 use PhpCsFixer\Console\Command\FixCommand;
 use PhpCsFixer\DocBlock\Annotation;
 use PhpCsFixer\DocBlock\DocBlock;
-use PhpCsFixer\Documentation\DocumentationLocator;
-use PhpCsFixer\Documentation\FixerDocumentGenerator;
-use PhpCsFixer\Documentation\RstUtils;
-use PhpCsFixer\Documentation\RuleSetDocumentationGenerator;
 use PhpCsFixer\Fixer\AbstractPhpUnitFixer;
 use PhpCsFixer\Fixer\PhpUnit\PhpUnitNamespacedFixer;
 use PhpCsFixer\FixerFactory;
@@ -65,21 +60,6 @@ final class ProjectCodeTest extends TestCase
      */
     private static array $tokensCache = [];
 
-    /**
-     * This structure contains older classes that are not yet covered by tests.
-     *
-     * It may only shrink, never add anything to it.
-     *
-     * @var string[]
-     */
-    private static $classesWithoutTests = [
-        DocumentationCommand::class,
-        DocumentationLocator::class,
-        FixerDocumentGenerator::class,
-        RstUtils::class,
-        RuleSetDocumentationGenerator::class,
-    ];
-
     public static function tearDownAfterClass(): void
     {
         self::$srcClassCases = null;
@@ -87,16 +67,6 @@ final class ProjectCodeTest extends TestCase
         self::$tokensCache = [];
     }
 
-    public function testThatClassesWithoutTestsVarIsProper(): void
-    {
-        $unknownClasses = array_filter(
-            self::$classesWithoutTests,
-            static fn (string $class): bool => !class_exists($class) && !trait_exists($class),
-        );
-
-        self::assertSame([], $unknownClasses);
-    }
-
     /**
      * @dataProvider provideThatSrcClassHaveTestClassCases
      */
@@ -104,11 +74,6 @@ final class ProjectCodeTest extends TestCase
     {
         $testClassName = 'PhpCsFixer\\Tests'.substr($className, 10).'Test';
 
-        if (\in_array($className, self::$classesWithoutTests, true)) {
-            self::assertFalse(class_exists($testClassName), sprintf('Class "%s" already has tests, so it should be removed from "%s::$classesWithoutTests".', $className, self::class));
-            self::markTestIncomplete(sprintf('Class "%s" has no tests yet, please help and add it.', $className));
-        }
-
         self::assertTrue(class_exists($testClassName), sprintf('Expected test class "%s" for "%s" not found.', $testClassName, $className));
     }
 

tests/Console/Command/DocumentationCommandTest.php

@@ -0,0 +1,67 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of PHP CS Fixer.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *     Dariusz Rumiński <dariusz.ruminski@gmail.com>
+ *
+ * This source file is subject to the MIT license that is bundled
+ * with this source code in the file LICENSE.
+ */
+
+namespace PhpCsFixer\Tests\Console\Command;
+
+use PhpCsFixer\Console\Application;
+use PhpCsFixer\Console\Command\DocumentationCommand;
+use PhpCsFixer\Tests\TestCase;
+use Symfony\Component\Console\Output\OutputInterface;
+use Symfony\Component\Console\Tester\CommandTester;
+use Symfony\Component\Filesystem\Filesystem;
+
+/**
+ * @internal
+ *
+ * @covers \PhpCsFixer\Console\Command\DocumentationCommand
+ */
+final class DocumentationCommandTest extends TestCase
+{
+    public function testGeneratingDocumentation(): void
+    {
+        $filesystem = $this->createFilesystemDouble();
+
+        $application = new Application();
+        $application->add(new DocumentationCommand($filesystem));
+
+        $command = $application->find('documentation');
+        $commandTester = new CommandTester($command);
+
+        $commandTester->execute(
+            [
+                'command' => $command->getName(),
+            ],
+            [
+                'interactive' => false,
+                'decorated' => false,
+                'verbosity' => OutputInterface::VERBOSITY_DEBUG,
+            ],
+        );
+
+        self::assertStringContainsString(
+            'Docs updated.',
+            $commandTester->getDisplay(),
+        );
+    }
+
+    private function createFilesystemDouble(): Filesystem
+    {
+        return new class() extends Filesystem {
+            public function dumpFile(string $filename, $content): void {}
+
+            /** @phpstan-ignore-next-line */
+            public function remove($files): void {}
+        };
+    }
+}

tests/Documentation/DocumentationLocatorTest.php

@@ -0,0 +1,91 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of PHP CS Fixer.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *     Dariusz Rumiński <dariusz.ruminski@gmail.com>
+ *
+ * This source file is subject to the MIT license that is bundled
+ * with this source code in the file LICENSE.
+ */
+
+namespace PhpCsFixer\Tests\Documentation;
+
+use PhpCsFixer\Documentation\DocumentationLocator;
+use PhpCsFixer\Fixer\Casing\ConstantCaseFixer;
+use PhpCsFixer\Tests\TestCase;
+
+/**
+ * @internal
+ *
+ * @covers \PhpCsFixer\Documentation\DocumentationLocator
+ */
+final class DocumentationLocatorTest extends TestCase
+{
+    public function testFixersDocumentationDirectoryPath(): void
+    {
+        self::assertSame(
+            realpath(__DIR__.'/../..').'/doc/rules',
+            (new DocumentationLocator())->getFixersDocumentationDirectoryPath()
+        );
+    }
+
+    public function testFixersDocumentationIndexFilePath(): void
+    {
+        self::assertSame(
+            realpath(__DIR__.'/../..').'/doc/rules/index.rst',
+            (new DocumentationLocator())->getFixersDocumentationIndexFilePath()
+        );
+    }
+
+    public function testFixerDocumentationFilePath(): void
+    {
+        self::assertSame(
+            realpath(__DIR__.'/../..').'/doc/rules/casing/constant_case.rst',
+            (new DocumentationLocator())->getFixerDocumentationFilePath(new ConstantCaseFixer())
+        );
+    }
+
+    public function testFixerDocumentationFileRelativePath(): void
+    {
+        self::assertSame(
+            'casing/constant_case.rst',
+            (new DocumentationLocator())->getFixerDocumentationFileRelativePath(new ConstantCaseFixer())
+        );
+    }
+
+    public function testRuleSetsDocumentationDirectoryPath(): void
+    {
+        self::assertSame(
+            realpath(__DIR__.'/../..').'/doc/ruleSets',
+            (new DocumentationLocator())->getRuleSetsDocumentationDirectoryPath()
+        );
+    }
+
+    public function testRuleSetsDocumentationIndexFilePath(): void
+    {
+        self::assertSame(
+            realpath(__DIR__.'/../..').'/doc/ruleSets/index.rst',
+            (new DocumentationLocator())->getRuleSetsDocumentationIndexFilePath()
+        );
+    }
+
+    public function testRuleSetsDocumentationFilePath(): void
+    {
+        self::assertSame(
+            realpath(__DIR__.'/../..').'/doc/ruleSets/PhpCsFixerRisky.rst',
+            (new DocumentationLocator())->getRuleSetsDocumentationFilePath('@PhpCsFixer:risky')
+        );
+    }
+
+    public function testUsageFilePath(): void
+    {
+        self::assertSame(
+            realpath(__DIR__.'/../..').'/doc/usage.rst',
+            (new DocumentationLocator())->getUsageFilePath()
+        );
+    }
+}

tests/Documentation/FixerDocumentGeneratorTest.php

@@ -0,0 +1,79 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of PHP CS Fixer.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *     Dariusz Rumiński <dariusz.ruminski@gmail.com>
+ *
+ * This source file is subject to the MIT license that is bundled
+ * with this source code in the file LICENSE.
+ */
+
+namespace PhpCsFixer\Tests\Documentation;
+
+use PhpCsFixer\Documentation\DocumentationLocator;
+use PhpCsFixer\Documentation\FixerDocumentGenerator;
+use PhpCsFixer\Fixer\Basic\BracesFixer;
+use PhpCsFixer\Fixer\ClassNotation\VisibilityRequiredFixer;
+use PhpCsFixer\Fixer\Comment\HeaderCommentFixer;
+use PhpCsFixer\Fixer\FixerInterface;
+use PhpCsFixer\Fixer\LanguageConstruct\ClassKeywordFixer;
+use PhpCsFixer\Fixer\Strict\StrictParamFixer;
+use PhpCsFixer\FixerFactory;
+use PhpCsFixer\Tests\TestCase;
+
+/**
+ * @internal
+ *
+ * @covers \PhpCsFixer\Documentation\FixerDocumentGenerator
+ */
+final class FixerDocumentGeneratorTest extends TestCase
+{
+    /**
+     * @dataProvider provideGenerateRuleSetsDocumentationCases
+     */
+    public function testGenerateRuleSetsDocumentation(FixerInterface $fixer): void
+    {
+        $locator = new DocumentationLocator();
+        $generator = new FixerDocumentGenerator($locator);
+
+        self::assertSame(
+            file_get_contents($locator->getFixerDocumentationFilePath($fixer)),
+            $generator->generateFixerDocumentation($fixer),
+        );
+    }
+
+    /**
+     * @return iterable<array{FixerInterface}>
+     */
+    public static function provideGenerateRuleSetsDocumentationCases(): iterable
+    {
+        yield [new BracesFixer()];
+
+        yield [new ClassKeywordFixer()];
+
+        yield [new HeaderCommentFixer()];
+
+        yield [new StrictParamFixer()];
+
+        yield [new VisibilityRequiredFixer()];
+    }
+
+    public function testGenerateFixersDocumentationIndex(): void
+    {
+        $locator = new DocumentationLocator();
+        $generator = new FixerDocumentGenerator($locator);
+
+        $fixerFactory = new FixerFactory();
+        $fixerFactory->registerBuiltInFixers();
+        $fixers = $fixerFactory->getFixers();
+
+        self::assertSame(
+            file_get_contents($locator->getFixersDocumentationIndexFilePath()),
+            $generator->generateFixersDocumentationIndex($fixers),
+        );
+    }
+}

tests/Documentation/RstUtilsTest.php

@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of PHP CS Fixer.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *     Dariusz Rumiński <dariusz.ruminski@gmail.com>
+ *
+ * This source file is subject to the MIT license that is bundled
+ * with this source code in the file LICENSE.
+ */
+
+namespace PhpCsFixer\Tests\Documentation;
+
+use PhpCsFixer\Documentation\RstUtils;
+use PhpCsFixer\Tests\TestCase;
+
+/**
+ * @internal
+ *
+ * @covers \PhpCsFixer\Documentation\RstUtils
+ */
+final class RstUtilsTest extends TestCase
+{
+    public function testToRst(): void
+    {
+        self::assertSame(
+            <<<'TEXT'
+                Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
+                    tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
+                    quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
+                    consequat.
+                TEXT,
+            RstUtils::toRst(
+                'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.',
+                4,
+            ),
+        );
+    }
+}

tests/Documentation/RuleSetDocumentationGeneratorTest.php

@@ -0,0 +1,80 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of PHP CS Fixer.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *     Dariusz Rumiński <dariusz.ruminski@gmail.com>
+ *
+ * This source file is subject to the MIT license that is bundled
+ * with this source code in the file LICENSE.
+ */
+
+namespace PhpCsFixer\Tests\Documentation;
+
+use PhpCsFixer\Documentation\DocumentationLocator;
+use PhpCsFixer\Documentation\RuleSetDocumentationGenerator;
+use PhpCsFixer\FixerFactory;
+use PhpCsFixer\RuleSet\RuleSets;
+use PhpCsFixer\RuleSet\Sets\PERSet;
+use PhpCsFixer\RuleSet\Sets\SymfonySet;
+use PhpCsFixer\Tests\TestCase;
+
+/**
+ * @internal
+ *
+ * @covers \PhpCsFixer\Documentation\RuleSetDocumentationGenerator
+ */
+final class RuleSetDocumentationGeneratorTest extends TestCase
+{
+    /**
+     * @dataProvider provideGenerateRuleSetsDocumentationCases
+     */
+    public function testGenerateRuleSetsDocumentation(string $ruleSetName): void
+    {
+        $locator = new DocumentationLocator();
+        $generator = new RuleSetDocumentationGenerator($locator);
+
+        $fixerFactory = new FixerFactory();
+        $fixerFactory->registerBuiltInFixers();
+        $fixers = $fixerFactory->getFixers();
+
+        self::assertSame(
+            file_get_contents($locator->getRuleSetsDocumentationFilePath($ruleSetName)),
+            $generator->generateRuleSetsDocumentation(RuleSets::getSetDefinition($ruleSetName), $fixers),
+        );
+    }
+
+    /**
+     * @return iterable<array{string}>
+     */
+    public static function provideGenerateRuleSetsDocumentationCases(): iterable
+    {
+        yield ['@PER'];
+
+        yield ['@PhpCsFixer:risky'];
+    }
+
+    public function testGenerateRuleSetsDocumentationIndex(): void
+    {
+        $locator = new DocumentationLocator();
+        $generator = new RuleSetDocumentationGenerator($locator);
+
+        self::assertSame(
+            <<<'RST'
+                ===========================
+                List of Available Rule sets
+                ===========================
+                - `@PER <./PER.rst>`_ *(deprecated)*
+                - `@Symfony <./Symfony.rst>`_
+
+                RST,
+            $generator->generateRuleSetsDocumentationIndex([
+                $locator->getRuleSetsDocumentationFilePath('@PER') => new PERSet(),
+                $locator->getRuleSetsDocumentationFilePath('@Symfony') => new SymfonySet(),
+            ]),
+        );
+    }
+}