Generators: add initial set of tests #671
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
rodrigoprimo
approved these changes
Nov 13, 2024
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.
|
After #663, I'm going to add the I'll also rebase the PR (without changes other than the one mentioned above), as the CI setup has undergone some changes and some new required builds are missing. Once the build has passed, I'll get this merged. |
jrfnl
force-pushed
the
feature/generators-add-tests
branch
from
e7fa943
to
c883660
Compare
jrfnl
added a commit
that referenced
this pull request
Nov 13, 2024
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.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
These new tests safeguard the output generated by the
Text,MarkdownandHTMLdoc generators and the logic in the abstractGeneratorclass.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
MarkdownandHTMLgenerators 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 theprintFooter()methods and replace 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
MarkdownTestandHTMLTestclasses.Finally, as things were, the tests for
MarkdownandHTMLwould 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.Suggested changelog entry
--generator=...feature will respect the expected EOL, based on the OS on which PHPCS is run, in more places.Related issues/external references
This PR is part of a series of PRs which will add a complete set of tests for the Generator feature.
Related to #146
Types of changes