Generators: add tests for handling documentation titles

This adds dedicated tests for specific issues which can be encountered with the `title` attribute for `<documentation>` elements. This initial set of tests for this documents the current behaviour. This behaviour may not always be the desired behaviour, in which case, this will be fixed in follow-up commits.
PHPCSStandards · Nov 23, 2024 · 8b8aa2e · 8b8aa2e
1 parent fa96dd3
commit 8b8aa2e
Show file tree

Hide file tree

Showing 14 changed files with 413 additions and 0 deletions.
diff --git a/tests/Core/Generators/AllValidDocsTest.xml b/tests/Core/Generators/AllValidDocsTest.xml
@@ -0,0 +1,10 @@
+<?xml version="1.0"?>
+<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="GeneratorTest" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/PHPCSStandards/PHP_CodeSniffer/master/phpcs.xsd">
+
+    <config name="installed_paths" value="./tests/Core/Generators/Fixtures/"/>
+
+    <rule ref="StandardWithDocs">
+        <exclude name="StandardWithDocs.Structure.NoDocumentationElement"/>
+    </rule>
+
+</ruleset>
diff --git a/tests/Core/Generators/Expectations/ExpectedOutputDocumentationTitleCase.html b/tests/Core/Generators/Expectations/ExpectedOutputDocumentationTitleCase.html
@@ -0,0 +1,78 @@
+<html>
+ <head>
+  <title>GeneratorTest Coding Standards</title>
+  <style>
+        body {
+            background-color: #FFFFFF;
+            font-size: 14px;
+            font-family: Arial, Helvetica, sans-serif;
+            color: #000000;
+        }
+
+        h1 {
+            color: #666666;
+            font-size: 20px;
+            font-weight: bold;
+            margin-top: 0px;
+            background-color: #E6E7E8;
+            padding: 20px;
+            border: 1px solid #BBBBBB;
+        }
+
+        h2 {
+            color: #00A5E3;
+            font-size: 16px;
+            font-weight: normal;
+            margin-top: 50px;
+        }
+
+        .code-comparison {
+            width: 100%;
+        }
+
+        .code-comparison td {
+            border: 1px solid #CCCCCC;
+        }
+
+        .code-comparison-title, .code-comparison-code {
+            font-family: Arial, Helvetica, sans-serif;
+            font-size: 12px;
+            color: #000000;
+            vertical-align: top;
+            padding: 4px;
+            width: 50%;
+            background-color: #F1F1F1;
+            line-height: 15px;
+        }
+
+        .code-comparison-code {
+            font-family: Courier;
+            background-color: #F9F9F9;
+        }
+
+        .code-comparison-highlight {
+            background-color: #DDF1F7;
+            border: 1px solid #00A5E3;
+            line-height: 15px;
+        }
+
+        .tag-line {
+            text-align: center;
+            width: 100%;
+            margin-top: 30px;
+            font-size: 12px;
+        }
+
+        .tag-line a {
+            color: #000000;
+        }
+    </style>
+ </head>
+ <body>
+  <h1>GeneratorTest Coding Standards</h1>
+  <a name="lowercase-title" />
+  <h2>lowercase title</h2>
+  <p class="text">This is a standard block.</p>
+  <div class="tag-line">Documentation generated on #REDACTED# by <a href="https://github.com/PHPCSStandards/PHP_CodeSniffer">PHP_CodeSniffer #VERSION#</a></div>
+ </body>
+</html>
diff --git a/tests/Core/Generators/Expectations/ExpectedOutputDocumentationTitleCase.md b/tests/Core/Generators/Expectations/ExpectedOutputDocumentationTitleCase.md
@@ -0,0 +1,6 @@
+# GeneratorTest Coding Standard
+
+## lowercase title
+This is a standard block.
+
+Documentation generated on *REDACTED* by [PHP_CodeSniffer *VERSION*](https://github.com/PHPCSStandards/PHP_CodeSniffer)
diff --git a/tests/Core/Generators/Expectations/ExpectedOutputDocumentationTitleCase.txt b/tests/Core/Generators/Expectations/ExpectedOutputDocumentationTitleCase.txt
@@ -0,0 +1,7 @@
+
+--------------------------------------------------
+| GENERATORTEST CODING STANDARD: LOWERCASE TITLE |
+--------------------------------------------------
+
+This is a standard block.
+
diff --git a/tests/Core/Generators/Expectations/ExpectedOutputDocumentationTitleLength.html b/tests/Core/Generators/Expectations/ExpectedOutputDocumentationTitleLength.html
@@ -0,0 +1,78 @@
+<html>
+ <head>
+  <title>GeneratorTest Coding Standards</title>
+  <style>
+        body {
+            background-color: #FFFFFF;
+            font-size: 14px;
+            font-family: Arial, Helvetica, sans-serif;
+            color: #000000;
+        }
+
+        h1 {
+            color: #666666;
+            font-size: 20px;
+            font-weight: bold;
+            margin-top: 0px;
+            background-color: #E6E7E8;
+            padding: 20px;
+            border: 1px solid #BBBBBB;
+        }
+
+        h2 {
+            color: #00A5E3;
+            font-size: 16px;
+            font-weight: normal;
+            margin-top: 50px;
+        }
+
+        .code-comparison {
+            width: 100%;
+        }
+
+        .code-comparison td {
+            border: 1px solid #CCCCCC;
+        }
+
+        .code-comparison-title, .code-comparison-code {
+            font-family: Arial, Helvetica, sans-serif;
+            font-size: 12px;
+            color: #000000;
+            vertical-align: top;
+            padding: 4px;
+            width: 50%;
+            background-color: #F1F1F1;
+            line-height: 15px;
+        }
+
+        .code-comparison-code {
+            font-family: Courier;
+            background-color: #F9F9F9;
+        }
+
+        .code-comparison-highlight {
+            background-color: #DDF1F7;
+            border: 1px solid #00A5E3;
+            line-height: 15px;
+        }
+
+        .tag-line {
+            text-align: center;
+            width: 100%;
+            margin-top: 30px;
+            font-size: 12px;
+        }
+
+        .tag-line a {
+            color: #000000;
+        }
+    </style>
+ </head>
+ <body>
+  <h1>GeneratorTest Coding Standards</h1>
+  <a name="This-is-a-very-very-very-very-very-very-very-very-very-very-very-long-title" />
+  <h2>This is a very very very very very very very very very very very long title</h2>
+  <p class="text">This is a standard block.</p>
+  <div class="tag-line">Documentation generated on #REDACTED# by <a href="https://github.com/PHPCSStandards/PHP_CodeSniffer">PHP_CodeSniffer #VERSION#</a></div>
+ </body>
+</html>
diff --git a/tests/Core/Generators/Expectations/ExpectedOutputDocumentationTitleLength.md b/tests/Core/Generators/Expectations/ExpectedOutputDocumentationTitleLength.md
@@ -0,0 +1,6 @@
+# GeneratorTest Coding Standard
+
+## This is a very very very very very very very very very very very long title
+This is a standard block.
+
+Documentation generated on *REDACTED* by [PHP_CodeSniffer *VERSION*](https://github.com/PHPCSStandards/PHP_CodeSniffer)
diff --git a/tests/Core/Generators/Expectations/ExpectedOutputDocumentationTitleLength.txt b/tests/Core/Generators/Expectations/ExpectedOutputDocumentationTitleLength.txt
@@ -0,0 +1,7 @@
+
+--------------------------------------------------------------------------------------------------------------
+| GENERATORTEST CODING STANDARD: THIS IS A VERY VERY VERY VERY VERY VERY VERY VERY VERY VERY VERY LONG TITLE |
+--------------------------------------------------------------------------------------------------------------
+
+This is a standard block.
+
diff --git a/...Core/Generators/Fixtures/StandardWithDocs/Docs/Content/DocumentationTitleCaseStandard.xml b/...Core/Generators/Fixtures/StandardWithDocs/Docs/Content/DocumentationTitleCaseStandard.xml
@@ -0,0 +1,7 @@
+<documentation title="lowercase title">
+    <standard>
+    <![CDATA[
+    This is a standard block.
+    ]]>
+    </standard>
+</documentation>
diff --git a/...re/Generators/Fixtures/StandardWithDocs/Docs/Content/DocumentationTitleLengthStandard.xml b/...re/Generators/Fixtures/StandardWithDocs/Docs/Content/DocumentationTitleLengthStandard.xml
@@ -0,0 +1,7 @@
+<documentation title="This is a very very very very very very very very very very very long title">
+    <standard>
+    <![CDATA[
+    This is a standard block.
+    ]]>
+    </standard>
+</documentation>
diff --git a/.../Core/Generators/Fixtures/StandardWithDocs/Sniffs/Content/DocumentationTitleCaseSniff.php b/.../Core/Generators/Fixtures/StandardWithDocs/Sniffs/Content/DocumentationTitleCaseSniff.php
@@ -0,0 +1,12 @@
+<?php
+/**
+ * Test fixture.
+ *
+ * @see \PHP_CodeSniffer\Tests\Core\Generators\GeneratorTest
+ */
+
+namespace Fixtures\StandardWithDocs\Sniffs\Content;
+
+use Fixtures\StandardWithDocs\Sniffs\DummySniff;
+
+final class DocumentationTitleCaseSniff extends DummySniff {}
diff --git a/...ore/Generators/Fixtures/StandardWithDocs/Sniffs/Content/DocumentationTitleLengthSniff.php b/...ore/Generators/Fixtures/StandardWithDocs/Sniffs/Content/DocumentationTitleLengthSniff.php
@@ -0,0 +1,12 @@
+<?php
+/**
+ * Test fixture.
+ *
+ * @see \PHP_CodeSniffer\Tests\Core\Generators\GeneratorTest
+ */
+
+namespace Fixtures\StandardWithDocs\Sniffs\Content;
+
+use Fixtures\StandardWithDocs\Sniffs\DummySniff;
+
+final class DocumentationTitleLengthSniff extends DummySniff {}
diff --git a/tests/Core/Generators/HTMLTest.php b/tests/Core/Generators/HTMLTest.php
@@ -77,6 +77,67 @@ public static function dataDocs()
     }//end dataDocs()
 
 
+    /**
+     * Test the generated docs for the handling of specific parts of the documentation.
+     *
+     * @param string $sniffs         The specific fixture sniffs to verify the docs for.
+     * @param string $pathToExpected Path to a file containing the expected function output.
+     *
+     * @dataProvider dataDocSpecifics
+     *
+     * @return void
+     */
+    public function testDocSpecifics($sniffs, $pathToExpected)
+    {
+        // Set up the ruleset.
+        $standard = __DIR__.'/AllValidDocsTest.xml';
+        $config   = new ConfigDouble(["--standard=$standard", "--sniffs=$sniffs"]);
+        $ruleset  = new Ruleset($config);
+
+        // In tests, the `--sniffs` setting doesn't work out of the box.
+        $sniffParts = explode('.', $sniffs);
+        $sniffFile  = __DIR__.DIRECTORY_SEPARATOR.'Fixtures'.DIRECTORY_SEPARATOR.$sniffParts[0].DIRECTORY_SEPARATOR;
+        $sniffFile .= 'Sniffs'.DIRECTORY_SEPARATOR.$sniffParts[1].DIRECTORY_SEPARATOR.$sniffParts[2].'Sniff.php';
+
+        $sniffParts   = array_map('strtolower', $sniffParts);
+        $sniffName    = $sniffParts[0].'\sniffs\\'.$sniffParts[1].'\\'.$sniffParts[2].'sniff';
+        $restrictions = [$sniffName => true];
+        $ruleset->registerSniffs([$sniffFile], $restrictions, []);
+
+        $expected = file_get_contents($pathToExpected);
+        $this->assertNotFalse($expected, 'Output expectation file could not be found');
+
+        // Make the test OS independent.
+        $expected = str_replace("\n", PHP_EOL, $expected);
+        $this->expectOutputString($expected);
+
+        $generator = new HTMLDouble($ruleset);
+        $generator->generate();
+
+    }//end testDocSpecifics()
+
+
+    /**
+     * Data provider.
+     *
+     * @return array<string, array<string, string>>
+     */
+    public static function dataDocSpecifics()
+    {
+        return [
+            'Documentation title: case'   => [
+                'sniffs'         => 'StandardWithDocs.Content.DocumentationTitleCase',
+                'pathToExpected' => __DIR__.'/Expectations/ExpectedOutputDocumentationTitleCase.html',
+            ],
+            'Documentation title: length' => [
+                'sniffs'         => 'StandardWithDocs.Content.DocumentationTitleLength',
+                'pathToExpected' => __DIR__.'/Expectations/ExpectedOutputDocumentationTitleLength.html',
+            ],
+        ];
+
+    }//end dataDocSpecifics()
+
+
     /**
      * Test the generated footer.
      *

diff --git a/tests/Core/Generators/MarkdownTest.php b/tests/Core/Generators/MarkdownTest.php
@@ -77,6 +77,67 @@ public static function dataDocs()
     }//end dataDocs()
 
 
+    /**
+     * Test the generated docs for the handling of specific parts of the documentation.
+     *
+     * @param string $sniffs         The specific fixture sniffs to verify the docs for.
+     * @param string $pathToExpected Path to a file containing the expected function output.
+     *
+     * @dataProvider dataDocSpecifics
+     *
+     * @return void
+     */
+    public function testDocSpecifics($sniffs, $pathToExpected)
+    {
+        // Set up the ruleset.
+        $standard = __DIR__.'/AllValidDocsTest.xml';
+        $config   = new ConfigDouble(["--standard=$standard", "--sniffs=$sniffs"]);
+        $ruleset  = new Ruleset($config);
+
+        // In tests, the `--sniffs` setting doesn't work out of the box.
+        $sniffParts = explode('.', $sniffs);
+        $sniffFile  = __DIR__.DIRECTORY_SEPARATOR.'Fixtures'.DIRECTORY_SEPARATOR.$sniffParts[0].DIRECTORY_SEPARATOR;
+        $sniffFile .= 'Sniffs'.DIRECTORY_SEPARATOR.$sniffParts[1].DIRECTORY_SEPARATOR.$sniffParts[2].'Sniff.php';
+
+        $sniffParts   = array_map('strtolower', $sniffParts);
+        $sniffName    = $sniffParts[0].'\sniffs\\'.$sniffParts[1].'\\'.$sniffParts[2].'sniff';
+        $restrictions = [$sniffName => true];
+        $ruleset->registerSniffs([$sniffFile], $restrictions, []);
+
+        $expected = file_get_contents($pathToExpected);
+        $this->assertNotFalse($expected, 'Output expectation file could not be found');
+
+        // Make the test OS independent.
+        $expected = str_replace("\n", PHP_EOL, $expected);
+        $this->expectOutputString($expected);
+
+        $generator = new MarkdownDouble($ruleset);
+        $generator->generate();
+
+    }//end testDocSpecifics()
+
+
+    /**
+     * Data provider.
+     *
+     * @return array<string, array<string, string>>
+     */
+    public static function dataDocSpecifics()
+    {
+        return [
+            'Documentation title: case'   => [
+                'sniffs'         => 'StandardWithDocs.Content.DocumentationTitleCase',
+                'pathToExpected' => __DIR__.'/Expectations/ExpectedOutputDocumentationTitleCase.md',
+            ],
+            'Documentation title: length' => [
+                'sniffs'         => 'StandardWithDocs.Content.DocumentationTitleLength',
+                'pathToExpected' => __DIR__.'/Expectations/ExpectedOutputDocumentationTitleLength.md',
+            ],
+        ];
+
+    }//end dataDocSpecifics()
+
+
     /**
      * Test the generated footer.
      *