Generators: add initial set of tests

These new tests safeguard the output generated by the `Text`, `Markdown` and `HTML` doc generators and the logic in the abstract `Generator` class. **Notes about the setup for these tests**: These tests use a set of test fixtures specially crafted for these tests. The use of fixtures means that the tests don't use _real_ documentation as included with the various standards, which is subject to change and would make the tests unstable. As the test fixtures are set up as an external standard, these tests will not only safeguard that doc generation works as expected, but also that it continues to work with external standards. This should help prevent issues as previously fixed in a10bea6 and e5bdaad. The footer output for the `Markdown` and `HTML` generators contains a date and a PHPCS version nr, which, again, would make the tests unstable. To mitigate this, test double classes are included for these classes, which overload the `printFooter()` methods and replaces the date and PHPCS version number with placeholders for the generic documentation tests. The _real_ footer is still tested, but via a regex pattern in a separate test in the `MarkdownTest` and `HTMLTest` classes. Finally, as things were, the tests for `Markdown` and `HTML` would fail on Windows due to the generated output containing mixed line endings in the HTML `<style>` tag and in the code samples for both. Commit 85b4a90 previously changed the EOL char used for output to screen to `PHP_EOL`, but these two places were overlooked. That is now fixed via this commit.
PHPCSStandards · Nov 12, 2024 · 3dcbb7f · 3dcbb7f
1 parent d228eb4
commit 3dcbb7f
Show file tree

Hide file tree

Showing 44 changed files with 1,630 additions and 3 deletions.
diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml
@@ -19,6 +19,7 @@ showFound: true
 ignores:
   - "node_modules/"
   - "vendor/"
+  - "tests/Core/Generators/Expectations/"
 
 # Disable inline config comments.
 noInlineConfig: true

diff --git a/src/Generators/HTML.php b/src/Generators/HTML.php
@@ -7,7 +7,9 @@
  * to each sniff.
  *
  * @author    Greg Sherwood <gsherwood@squiz.net>
+ * @author    Juliette Reinders Folmer <phpcs_nospam@adviesenzo.nl>
  * @copyright 2006-2015 Squiz Pty Ltd (ABN 77 084 670 600)
+ * @copyright 2024 PHPCSStandards and contributors
  * @license   https://github.com/PHPCSStandards/PHP_CodeSniffer/blob/master/licence.txt BSD Licence
  */
 
@@ -133,7 +135,7 @@ protected function printHeader()
         echo '<html>'.PHP_EOL;
         echo ' <head>'.PHP_EOL;
         echo "  <title>$standard Coding Standards</title>".PHP_EOL;
-        echo '  '.self::STYLESHEET.PHP_EOL;
+        echo '  '.str_replace("\n", PHP_EOL, self::STYLESHEET).PHP_EOL;
         echo ' </head>'.PHP_EOL;
         echo ' <body>'.PHP_EOL;
         echo "  <h1>$standard Coding Standards</h1>".PHP_EOL;
@@ -226,6 +228,9 @@ protected function printTextBlock(DOMNode $node)
         $content = trim($node->nodeValue);
         $content = htmlspecialchars($content);
 
+        // Use the correct line endings based on the OS.
+        $content = str_replace("\n", PHP_EOL, $content);
+
         // Allow em tags only.
         $content = str_replace('&lt;em&gt;', '<em>', $content);
         $content = str_replace('&lt;/em&gt;', '</em>', $content);

diff --git a/src/Generators/Markdown.php b/src/Generators/Markdown.php
@@ -3,7 +3,9 @@
  * A doc generator that outputs documentation in Markdown format.
  *
  * @author    Stefano Kowalke <blueduck@gmx.net>
+ * @author    Juliette Reinders Folmer <phpcs_nospam@adviesenzo.nl>
  * @copyright 2014 Arroba IT
+ * @copyright 2024 PHPCSStandards and contributors
  * @license   https://github.com/PHPCSStandards/PHP_CodeSniffer/blob/master/licence.txt BSD Licence
  */
 
@@ -111,6 +113,9 @@ protected function printTextBlock(DOMNode $node)
         $content = trim($node->nodeValue);
         $content = htmlspecialchars($content);
 
+        // Use the correct line endings based on the OS.
+        $content = str_replace("\n", PHP_EOL, $content);
+
         $content = str_replace('&lt;em&gt;', '*', $content);
         $content = str_replace('&lt;/em&gt;', '*', $content);
 
@@ -132,13 +137,13 @@ protected function printCodeComparisonBlock(DOMNode $node)
 
         $firstTitle = $codeBlocks->item(0)->getAttribute('title');
         $first      = trim($codeBlocks->item(0)->nodeValue);
-        $first      = str_replace("\n", "\n    ", $first);
+        $first      = str_replace("\n", PHP_EOL.'    ', $first);
         $first      = str_replace('<em>', '', $first);
         $first      = str_replace('</em>', '', $first);
 
         $secondTitle = $codeBlocks->item(1)->getAttribute('title');
         $second      = trim($codeBlocks->item(1)->nodeValue);
-        $second      = str_replace("\n", "\n    ", $second);
+        $second      = str_replace("\n", PHP_EOL.'    ', $second);
         $second      = str_replace('<em>', '', $second);
         $second      = str_replace('</em>', '', $second);
 

diff --git a/tests/Core/Generators/Expectations/ExpectedOutputEmpty.txt b/tests/Core/Generators/Expectations/ExpectedOutputEmpty.txt
diff --git a/tests/Core/Generators/Expectations/ExpectedOutputNoDocs.html b/tests/Core/Generators/Expectations/ExpectedOutputNoDocs.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>
+  <h2>Table of Contents</h2>
+  <ul class="toc">
+  </ul>
+  <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/ExpectedOutputNoDocs.md b/tests/Core/Generators/Expectations/ExpectedOutputNoDocs.md
@@ -0,0 +1,2 @@
+# GeneratorTest Coding Standard
+Documentation generated on *REDACTED* by [PHP_CodeSniffer *VERSION*](https://github.com/PHPCSStandards/PHP_CodeSniffer)
diff --git a/tests/Core/Generators/Expectations/ExpectedOutputOneDoc.html b/tests/Core/Generators/Expectations/ExpectedOutputOneDoc.html
@@ -0,0 +1,82 @@
+<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>
+  <h2>Table of Contents</h2>
+  <ul class="toc">
+   <li><a href="#One-Standard-Block,-No-Code">One Standard Block, No Code</a></li>
+  </ul>
+  <a name="One-Standard-Block,-No-Code" />
+  <h2>One Standard Block, No Code</h2>
+  <p class="text">Documentation contains one standard block and no code comparison.</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/ExpectedOutputOneDoc.md b/tests/Core/Generators/Expectations/ExpectedOutputOneDoc.md
@@ -0,0 +1,5 @@
+# GeneratorTest Coding Standard
+
+## One Standard Block, No Code
+Documentation contains one standard block and no code comparison.
+Documentation generated on *REDACTED* by [PHP_CodeSniffer *VERSION*](https://github.com/PHPCSStandards/PHP_CodeSniffer)
diff --git a/tests/Core/Generators/Expectations/ExpectedOutputOneDoc.txt b/tests/Core/Generators/Expectations/ExpectedOutputOneDoc.txt
@@ -0,0 +1,7 @@
+
+--------------------------------------------------------------
+| GENERATORTEST CODING STANDARD: ONE STANDARD BLOCK, NO CODE |
+--------------------------------------------------------------
+
+Documentation contains one standard block and no code comparison.
+