Skip to content

Commit f9c5f18

Browse files
jrfnljrfnl
authored
Generators: add initial set of tests (#671)
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.
1 parent 7d33bcd commit f9c5f18

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

44 files changed

+1634
-3
lines changed

‎.markdownlint-cli2.yaml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ showFound: true
1919
ignores:
2020
- "node_modules/"
2121
- "vendor/"
22+
- "tests/Core/Generators/Expectations/"
2223

2324
# Disable inline config comments.
2425
noInlineConfig: true

‎src/Generators/HTML.php

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,9 @@
77
* to each sniff.
88
*
99
* @author Greg Sherwood <[email protected]>
10+
* @author Juliette Reinders Folmer <[email protected]>
1011
* @copyright 2006-2015 Squiz Pty Ltd (ABN 77 084 670 600)
12+
* @copyright 2024 PHPCSStandards and contributors
1113
* @license https://github.com/PHPCSStandards/PHP_CodeSniffer/blob/master/licence.txt BSD Licence
1214
*/
1315

@@ -133,7 +135,7 @@ protected function printHeader()
133135
echo '<html>'.PHP_EOL;
134136
echo ' <head>'.PHP_EOL;
135137
echo " <title>$standard Coding Standards</title>".PHP_EOL;
136-
echo ' '.self::STYLESHEET.PHP_EOL;
138+
echo ' '.str_replace("\n", PHP_EOL, self::STYLESHEET).PHP_EOL;
137139
echo ' </head>'.PHP_EOL;
138140
echo ' <body>'.PHP_EOL;
139141
echo " <h1>$standard Coding Standards</h1>".PHP_EOL;
@@ -226,6 +228,9 @@ protected function printTextBlock(DOMNode $node)
226228
$content = trim($node->nodeValue);
227229
$content = htmlspecialchars($content);
228230

231+
// Use the correct line endings based on the OS.
232+
$content = str_replace("\n", PHP_EOL, $content);
233+
229234
// Allow em tags only.
230235
$content = str_replace('&lt;em&gt;', '<em>', $content);
231236
$content = str_replace('&lt;/em&gt;', '</em>', $content);

‎src/Generators/Markdown.php

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,9 @@
33
* A doc generator that outputs documentation in Markdown format.
44
*
55
* @author Stefano Kowalke <[email protected]>
6+
* @author Juliette Reinders Folmer <[email protected]>
67
* @copyright 2014 Arroba IT
8+
* @copyright 2024 PHPCSStandards and contributors
79
* @license https://github.com/PHPCSStandards/PHP_CodeSniffer/blob/master/licence.txt BSD Licence
810
*/
911

@@ -111,6 +113,9 @@ protected function printTextBlock(DOMNode $node)
111113
$content = trim($node->nodeValue);
112114
$content = htmlspecialchars($content);
113115

116+
// Use the correct line endings based on the OS.
117+
$content = str_replace("\n", PHP_EOL, $content);
118+
114119
$content = str_replace('&lt;em&gt;', '*', $content);
115120
$content = str_replace('&lt;/em&gt;', '*', $content);
116121

@@ -132,13 +137,13 @@ protected function printCodeComparisonBlock(DOMNode $node)
132137

133138
$firstTitle = $codeBlocks->item(0)->getAttribute('title');
134139
$first = trim($codeBlocks->item(0)->nodeValue);
135-
$first = str_replace("\n", "\n ", $first);
140+
$first = str_replace("\n", PHP_EOL.' ', $first);
136141
$first = str_replace('<em>', '', $first);
137142
$first = str_replace('</em>', '', $first);
138143

139144
$secondTitle = $codeBlocks->item(1)->getAttribute('title');
140145
$second = trim($codeBlocks->item(1)->nodeValue);
141-
$second = str_replace("\n", "\n ", $second);
146+
$second = str_replace("\n", PHP_EOL.' ', $second);
142147
$second = str_replace('<em>', '', $second);
143148
$second = str_replace('</em>', '', $second);
144149

‎tests/Core/Generators/Expectations/ExpectedOutputEmpty.txt

Whitespace-only changes.

‎tests/Core/Generators/Expectations/ExpectedOutputNoDocs.html

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
<html>
2+
<head>
3+
<title>GeneratorTest Coding Standards</title>
4+
<style>
5+
body {
6+
background-color: #FFFFFF;
7+
font-size: 14px;
8+
font-family: Arial, Helvetica, sans-serif;
9+
color: #000000;
10+
}
11+
12+
h1 {
13+
color: #666666;
14+
font-size: 20px;
15+
font-weight: bold;
16+
margin-top: 0px;
17+
background-color: #E6E7E8;
18+
padding: 20px;
19+
border: 1px solid #BBBBBB;
20+
}
21+
22+
h2 {
23+
color: #00A5E3;
24+
font-size: 16px;
25+
font-weight: normal;
26+
margin-top: 50px;
27+
}
28+
29+
.code-comparison {
30+
width: 100%;
31+
}
32+
33+
.code-comparison td {
34+
border: 1px solid #CCCCCC;
35+
}
36+
37+
.code-comparison-title, .code-comparison-code {
38+
font-family: Arial, Helvetica, sans-serif;
39+
font-size: 12px;
40+
color: #000000;
41+
vertical-align: top;
42+
padding: 4px;
43+
width: 50%;
44+
background-color: #F1F1F1;
45+
line-height: 15px;
46+
}
47+
48+
.code-comparison-code {
49+
font-family: Courier;
50+
background-color: #F9F9F9;
51+
}
52+
53+
.code-comparison-highlight {
54+
background-color: #DDF1F7;
55+
border: 1px solid #00A5E3;
56+
line-height: 15px;
57+
}
58+
59+
.tag-line {
60+
text-align: center;
61+
width: 100%;
62+
margin-top: 30px;
63+
font-size: 12px;
64+
}
65+
66+
.tag-line a {
67+
color: #000000;
68+
}
69+
</style>
70+
</head>
71+
<body>
72+
<h1>GeneratorTest Coding Standards</h1>
73+
<h2>Table of Contents</h2>
74+
<ul class="toc">
75+
</ul>
76+
<div class="tag-line">Documentation generated on #REDACTED# by <a href="https://github.com/PHPCSStandards/PHP_CodeSniffer">PHP_CodeSniffer #VERSION#</a></div>
77+
</body>
78+
</html>

‎tests/Core/Generators/Expectations/ExpectedOutputNoDocs.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
# GeneratorTest Coding Standard
2+
Documentation generated on *REDACTED* by [PHP_CodeSniffer *VERSION*](https://github.com/PHPCSStandards/PHP_CodeSniffer)

‎tests/Core/Generators/Expectations/ExpectedOutputOneDoc.html

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
<html>
2+
<head>
3+
<title>GeneratorTest Coding Standards</title>
4+
<style>
5+
body {
6+
background-color: #FFFFFF;
7+
font-size: 14px;
8+
font-family: Arial, Helvetica, sans-serif;
9+
color: #000000;
10+
}
11+
12+
h1 {
13+
color: #666666;
14+
font-size: 20px;
15+
font-weight: bold;
16+
margin-top: 0px;
17+
background-color: #E6E7E8;
18+
padding: 20px;
19+
border: 1px solid #BBBBBB;
20+
}
21+
22+
h2 {
23+
color: #00A5E3;
24+
font-size: 16px;
25+
font-weight: normal;
26+
margin-top: 50px;
27+
}
28+
29+
.code-comparison {
30+
width: 100%;
31+
}
32+
33+
.code-comparison td {
34+
border: 1px solid #CCCCCC;
35+
}
36+
37+
.code-comparison-title, .code-comparison-code {
38+
font-family: Arial, Helvetica, sans-serif;
39+
font-size: 12px;
40+
color: #000000;
41+
vertical-align: top;
42+
padding: 4px;
43+
width: 50%;
44+
background-color: #F1F1F1;
45+
line-height: 15px;
46+
}
47+
48+
.code-comparison-code {
49+
font-family: Courier;
50+
background-color: #F9F9F9;
51+
}
52+
53+
.code-comparison-highlight {
54+
background-color: #DDF1F7;
55+
border: 1px solid #00A5E3;
56+
line-height: 15px;
57+
}
58+
59+
.tag-line {
60+
text-align: center;
61+
width: 100%;
62+
margin-top: 30px;
63+
font-size: 12px;
64+
}
65+
66+
.tag-line a {
67+
color: #000000;
68+
}
69+
</style>
70+
</head>
71+
<body>
72+
<h1>GeneratorTest Coding Standards</h1>
73+
<h2>Table of Contents</h2>
74+
<ul class="toc">
75+
<li><a href="#One-Standard-Block,-No-Code">One Standard Block, No Code</a></li>
76+
</ul>
77+
<a name="One-Standard-Block,-No-Code" />
78+
<h2>One Standard Block, No Code</h2>
79+
<p class="text">Documentation contains one standard block and no code comparison.</p>
80+
<div class="tag-line">Documentation generated on #REDACTED# by <a href="https://github.com/PHPCSStandards/PHP_CodeSniffer">PHP_CodeSniffer #VERSION#</a></div>
81+
</body>
82+
</html>

‎tests/Core/Generators/Expectations/ExpectedOutputOneDoc.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# GeneratorTest Coding Standard
2+
3+
## One Standard Block, No Code
4+
Documentation contains one standard block and no code comparison.
5+
Documentation generated on *REDACTED* by [PHP_CodeSniffer *VERSION*](https://github.com/PHPCSStandards/PHP_CodeSniffer)

‎tests/Core/Generators/Expectations/ExpectedOutputOneDoc.txt

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
2+
--------------------------------------------------------------
3+
| GENERATORTEST CODING STANDARD: ONE STANDARD BLOCK, NO CODE |
4+
--------------------------------------------------------------
5+
6+
Documentation contains one standard block and no code comparison.
7+

0 commit comments

Comments
 (0)