PHPCS 3.6.2 added a sniff for a PSR-12 rule which was previously not strictly checked: "No blank line after the opening brace of a class".
This fixes the newly flagged issues.
The `TestCase::checkChanges()` method is a way of exposing what properties in the `PHPMailer` class have a changed value compared to their default value in a particular test situation. The method is used for debugging tests.
As things were, the `TestCase::checkChanges()` method would check against a limited set of hard-coded values to determine whether the default value of a property has been updated.
This is unstable as:
1. Default values may change in the `PHPMailer` class and the values within this method would need to be updated to match, which is easily forgotten.
2. New properties may be introduced in the `PHPMailer` class and be relevant to this debug changelog.
Again, it would require manually adding these new properties to this method to start tracking them.
3. Property values may be changed in the `set_up()` method, which would be a "known change" for a certain test.
In part such "expected" changes were taken into account in this method based on the previously hard-coded setting changes in `set_up()`.
With the logic for the property setting from the `set_up()` method now being more flexible, the pre-setting of properties having been reduced to the bare minimum, but also allowing individual test clases to set their own additional changes, keeping track of what is a "known" change by checking against hard-coded values is no longer stable.
With this in mind, I propose to make the `TestCase::checkChanges()` method dynamic.
To that end, this commit:
* Retrieves the default values of all properties of the `PHPMailer` class via the PHP native `get_class_vars()` function.
* Will automatically check for changes in *all* properties, with only a limited set of _exclusions_, effectively changing the changelog from an "inclusion list" to an "exclusion list".
A select list of properties is excluded from being listed in the changelog via the `TestCase::$changelogExclude` property.
See the inline documentation in the property for the reasoning behind excluding certain properties from the changelog.
* The value of static properties will always be compared to their default value as registered in the `TestCase::$PHPMailerStaticProps` method and will be listed when different.
_Note: as documented, this list has to be hard-coded due to Reflection (as well as `get_class_vars()`) not handling default values for static properties correctly._
* The value of non-static properties will be compared to both the known changes made in the `set_up()` method and if the property was not changed in `set_up()`, to their default value. The property will be listed in the changelog when the value is different from the "expected" value, i.e. not a known change from `set_up()` and not the default value.
In addition to this, the representation of the properties will now be created via `var_export()`, which allows for listing `null` and boolean values as well.
This commit makes the property setting in the `TestCase::set_up()` more flexible by combining an overloadable property `$propertyChanges` and a `foreach` loop to set the actual property values.
Concrete test classes can either overload the `$propertyChanges` property with their own version or can add to the default setup using the following pattern:
```php
protected function set_up()
{
$this->propertyChanges['additional_key'] = 'value';
// Add more properties...
parent::set_up();
}
```
The `TestCase::set_up()` was setting quite a number of properties in the `PHPMailer` class.
This makes testing more difficult for the following reasons:
1. The tests can no longer presume the properties in the `PHPMailer` class will have their default values
This means that tests are not "transparent" (clearly show what is being tested), nor isolated (only target what is specifically being tested).
2. Any changes to the values set in the `set_up()` method may have a ripple effect and create a need for individual test expectations to be adjusted.
3. As the `set_up()` is changing a number of the properties using methods in the `PHPMailer()` class and methods called during the `set_up()` are included in code coverage visualizations, code coverage cannot fully be trusted and it is more difficult to verify that each piece of code has tests covering that code path.
With this in mind, I'm proposing splitting the `TestCase` into three distinct abstract `TestCase`s:
* A basic `TestCase` containing the utility methods and a minimal `set_up()` and `tear_down()`.
* A `PreSendTestCase` for use with tests using the `preSend()` method which requires a few properties to be set.
* A `SendTestCase` for use with tests actually testing the sending of mail using the `send()` method, which needs yet more properties and uses the `testbootstrap.php` file to retrieve the values of those variables.
This commit executes the initial split. Follow-on commits will streamline this further.
Includes adjusting the `TestCase` being extended for select existing unit test classes.
The `PHPMailer::preSend()` method may alter the value of the _`protect static`_ `PHPMailer::$LE` property.
a9978d2079/src/PHPMailer.php (L1494-L1504)
This means that tests which rely on the value of the property being the default, may start to fail unexpectedly depending on the _order_ in which tests are being run.
I.e. if the test relying on the default value is run first, all will be fine, however, if that same test is run _after_ a test which calls `preSend()` on a non-Windows box with PHP < 8.0 and with `$this->Mailer` set to `mail`, the test may fail unexpectedly.
This commit fixes that by expanding the previously introduced "resetting of static properties" logic.
This commit:
* Expands the list of static properties in the `TestCase` class to include the `PHPMailer::$LE` property.
* Introduces two new methods to the `TestCase` class:
- `resetStaticProperties()` to reset all static properties listed in the `TestCase::$PHPMailerStaticProps` property to their default values.
- `updateStaticProperty()` to change the value of one individual static property in a class.
* The `updateStaticProperty()` method was made `public static` to allow for tests which do not need an instantiated PHPMailer object and thus extend the `Yoast\PHPUnitPolyfills\TestCases\TestCase` directly to be able to use the method as well.
If any such tests would use the method, that particular test will be responsible for resetting the value back to the default after the test.
* The resetting of the static properties has also been moved from the `set_up()` to the `tear_down()` method.
As mentioned above, these static properties may be used by both tests extending this `TestCase` as well as test extending the `Yoast\PHPUnitPolyfills\TestCases\TestCase`. With that in mind, resetting _after_ each test will be more stable, as long as tests which extend the `Yoast\PHPUnitPolyfills\TestCases\TestCase` and would change static properties clean up after themselves.
**Note**: I'm not including the `PHPMailer::$IcalMethods` property in this change as AFAICS, this property is not being changed anywhere in the package code and as the property is `protected`, it cannot easily be changed from within a test either (and if it would be changed by a test, that test would be responsible for resetting it).
Also note: due to limitations in the `Reflection` extension, a hard-coded list of the default values of the static properties will need to be maintained in the `TestCase`. This cannot be helped as the `Reflection` extension does not have a way to accurately retrieve the default value of static properties in a PHP cross-version compatible manner.
The `PHPMailer::__construct()` method has an optional `$exceptions` property to throw exceptions on errors.
Up to now, the `PHPMailer` instance created by the `set_up()` would not pass any parameters, effectively instantiating `PHPMailer` without turning on exceptions.
In a test situation it may be useful for tests to test the behaviour of a method _with_ and _without_ the exceptions option and to test that certain exceptions are thrown and throw the correct message.
With that in mind, I'm introducing a `USE_EXCEPTIONS` class constant to the `TestCase` which can be overloaded in individual test classes and will be used by the `set_up()` method to determine whether it will be instantiated with exceptions or not.
Includes introducing an overload of the class constant in one of the test class for which it would seem appropriate at this time.
Note: this does mean that the `testDKIMSigningMail()` test will show as errored instead of failed if no SMTP connection could be made, but that IMO is the more correct status anyhow.
This allows for using the `setAddress()` method in a more consistent manner (where appropriate).
Includes introducing the use of the `setAddress()` function in a few select places.
Note: I do wonder whether this method should ever be used outside of `set_up()` and `tear_down()`, but that is for further discussion and outside the scope of this commit.
Public static properties changed by individual tests were not being reset to their default value prior to the next test being run.
This could influence the test results of subsequent tests as static properties are not automatically reset when a new instance of a class is instantiated. See: https://3v4l.org/8s1RB
Luckily this didn't aversely affect the tests so far, but should be safeguarded for the future.
There are only three static properties in the `PHPMailer` class, with only one of these being `public`.
This commit introduces a code snippet which will reset any static properties as listed in the `$PHPMailerStaticProps` property of the `TestCase` to the default value, as also set in the `$PHPMailerStaticProps` property, at the start of the `set_up()` which is run before each test using the `TestCase`.
For now, this is only relevant for the `ValidateAddressCustomValidatorTest` test and only when the `testSetDefaultValidatorToCustom()` test would fail before resetting the property. All the same, having the reset in place by default will ensure that future tests which change this property won't introduce side-effects to other tests.
* Tests/reorganize: move POP before SMTP tests to own file
This also removed the `$pids` property and handling from the PHPMailer base `TestCase` and moves this to the POP test class.
As this test now does not actually need an instantiated PHPMailer object, this class extends the `Yoast\PHPUnitPolyfills\TestCases\TestCase` instead of the `PHPMailer\Test\TestCase`.
* PopBeforeSmtpTest: move `@group` tags
... to the class level and remove them from the individual test functions.
* PopBeforeSmtpTest: various test tweaks
Minor test tweaks:
* Add `@covers` tag at class level.
* Inline comment punctuation.
* Minor code readability tweaks.
Co-authored-by: jrfnl <jrfnl@users.noreply.github.com>
* Tests/reorganize: add an abstract base testcase
As a first step towards reorganizing the tests, this commit:
* Creates an abstract base `TestCase` class which can be extended by concrete child test classes and holds the generic properties and helper methods for use throughout the tests.
Based on their use, the visibility of properties and methods have been adjusted for the new setup.
* Removes the generic property and helper method declarations from the concrete test class.
* Moves the `require` statement for the `validators.php` file to a `set_up_before_class()` method in the base `TestCase`.
* Tests/reorganize: define base directory in set_up_before_class
The `$this->INCLUDE_DIR` property which points to the project root directory does not change at any time during the test run, but was being redefined for every test in the `set_up()` method.
As this is in effect a _constant_ value, let's define it as a constant in the TestCase `set_up_before_class()` method instead.
Notes:
Both actions executed in the `set_up_before_class()` method are typically things for a test bootstrap file.
However, to allow for PHPUnit to be able to run from both a Composer install as well as a Phar file, without having to create custom autoloaders, it is simpler to have the `vendor/autoload.php` file as the bootstrap file as, in that case, PHPUnit will handle the loading order and prevent loading conflicting PHPUnit files from a Composer install when running via the Phar.
With this in mind, putting these actions in a `set_up_before_class()` method is a valid compromise.
* Tests/reorganize: move actual test files to subdirectories
... leaving the test root directory to only contain test utility files.
Note: I've added a second entry for the test generated files to the `.gitignore`. Adding this entry instead of replacing the entry allows for any existing generated files in contributor clones to continue to be ignored.
At a later point in time, it could be elected to remove the original entry, once all active contributors have updated their installs and removed any stray generated files from their `test` root directories.
Co-authored-by: jrfnl <jrfnl@users.noreply.github.com>
SirLouen
Marcus Bointon
jrfnl
Juliette