From 1bcc9a4ae6f31aa984931a223f7e3013d0531b88 Mon Sep 17 00:00:00 2001 From: Fulvio Notarstefano Date: Fri, 12 Jan 2024 15:15:37 +0900 Subject: [PATCH] Update docs to explain how WP_Mock TestCase is preferable to extend than PhpUnit's (#239) # Summary Updates docs to make it clear that implementations should use WP_Mock own `TestCase`, ideally, or at least provide teardown overrides. ### Closes: #238 ## Contributor checklist - [x] I agree to follow this project's [**Code of Conduct**](https://github.com/10up/.github/blob/trunk/CODE_OF_CONDUCT.md). - [x] I have updated the documentation accordingly - [x] I have added tests to cover changes introduced by this pull request - [x] All new and existing tests pass ### Reviewer checklist - [ ] Code changes review - [ ] Documentation changes review - [ ] Doc examples should always reference WP_Mock own `TestCase` - [ ] Unit tests pass - [ ] Static analysis passes --------- Co-authored-by: Ryan Neudorf Co-authored-by: Ryan Neudorf <109976277+rneudorf-godaddy@users.noreply.github.com> Co-authored-by: Drew Jaynes <113622064+ajaynes-godaddy@users.noreply.github.com> --- docs/general/configuration.md | 46 ++++++++++++++++++++++++++++++-- docs/general/installation.md | 2 +- docs/usage/mocking-wp-objects.md | 3 +-- docs/usage/using-wp-mock.md | 13 +++++++-- 4 files changed, 57 insertions(+), 7 deletions(-) diff --git a/docs/general/configuration.md b/docs/general/configuration.md index c4204f4..61e6b32 100644 --- a/docs/general/configuration.md +++ b/docs/general/configuration.md @@ -42,7 +42,7 @@ A more convenient way though would be to add the following to the phpunit.xml co bootstrap="/path/to/bootstrap.php" ``` -## Patchwork +## Enable Patchwork [Patchwork](https://github.com/antecedent/patchwork) is a library that enables temporarily overwriting user-defined functions and static methods. This means you can better isolate your system under test by mocking your plugin's functions that are tested elsewhere. If Patchwork is turned on, WP_Mock will transparently use it behind the scenes. For most use cases, you won't need to worry about using it directly. @@ -53,7 +53,7 @@ WP_Mock::setUsePatchwork(true); WP_Mock::bootstrap(); ``` -## Strict Mode +## Enable Strict Mode WP_Mock has a strict mode that developers may optionally enable. By default, it is disabled. If enabled, strict mode will cause tests to fail if they use previously mocked functions without first explicitly declaring an expectation for how that function will be used. This provides an easy way to enforce an extra layer of specificity in unit tests. @@ -62,4 +62,46 @@ Like using patchwork, strict mode has to be enabled before the WP_Mock framework ```php WP_Mock::activateStrictMode(); WP_Mock::bootstrap(); +``` + +## Extend WP_Mock Test Case + +Once you have followed the configuration steps as outlined above, you'll want to update your test classes to extend the `WP_Mock\Tools\TestCase` class for the best results when using WP_Mock. This class extends PHPUnit's own `TestCase` class, with some helper and other methods that help WP_Mock to function properly. + +```php + +use WP_Mock\Tools\TestCase; + +class MyClassTest extends TestCase +{ + // your test methods +} + +``` + +If you **do not** wish to extend WP_Mock own test case, then you should make sure to call `WP_Mock::setUp()` and `WP_Mock::tearDown()` in your test case's `setUp()` and `tearDown()` methods respectively. This is not recommended though. + +```php + +use PHPUnit\Framework\TestCase; + +class MyClassTest extends TestCase +{ + public function setUp() : void + { + parent::setUp() + + WP_Mock::setUp(); + } + + public function tearDown() : void + { + parent::tearDown(); + + WP_Mock::tearDown(); + } + + // your test methods +} + ``` \ No newline at end of file diff --git a/docs/general/installation.md b/docs/general/installation.md index dfefcf5..071fbdc 100644 --- a/docs/general/installation.md +++ b/docs/general/installation.md @@ -25,4 +25,4 @@ They will be installed for you by Composer. Next, you will need to configure PHPUnit first before enabling WP_Mock. [Consult PHPUnit documentation](https://phpunit.de/documentation.html) for this step. -You will also need to configure WP_Mock with a bootstrap file to use it in your tests. \ No newline at end of file +You will also need to [configure WP_Mock with a bootstrap file](configuration.md) to use it in your tests. \ No newline at end of file diff --git a/docs/usage/mocking-wp-objects.md b/docs/usage/mocking-wp-objects.md index 070efc4..a9723ba 100644 --- a/docs/usage/mocking-wp-objects.md +++ b/docs/usage/mocking-wp-objects.md @@ -24,9 +24,8 @@ When we mock the `$wpdb` object, we're not performing an actual database call, o ```php use Mockery; use MyPlugin\MyClass; -use PHPUnit\Framework\TestCase; -final class MyClassTest extends TestCase +final class MyClassTest extends \WP_Mock\Tools\TestCase { public function testCanGetSomePostIds() : void { diff --git a/docs/usage/using-wp-mock.md b/docs/usage/using-wp-mock.md index 1062aa1..304a031 100644 --- a/docs/usage/using-wp-mock.md +++ b/docs/usage/using-wp-mock.md @@ -26,11 +26,10 @@ You can use `WP_Mock::userFunction()` to mock the `get_post()` function and retu ```php use MyPlugin\MyClass; -use PHPUnit\Framework\TestCase; use stdClass use WP_Mock; -final class MyClassTest extends TestCase +final class MyClassTest extends WP_Mock\Tools\TestCase { public function testMyFunction() : void { @@ -55,6 +54,16 @@ Calling `WP_Mock::userFunction()` will dynamically define the function for you i return \WP_Mock\Functions\Handler::handleFunction(__FUNCTION__, func_get_args()); ``` + +{% hint style="warning" %} + +**Important!** + +You should typically extend `WP_Mock\Tools\TestCase` instead of `PHPUnit\Framework\TestCase` when using WP_Mock. +See [WP_Mock Test Case Documentation](../tools/wp-mock-test-case.md) and [how to configure WP_Mock](../general/configuration.md) for more information. + +{% endhint %} + ## Using Mockery expectations The `WP_Mock::userFunction()` class will return a complete `Mockery\Expectation` object with any expectations added to match the arguments passed to the function. This enables using [Mockery methods](http://docs.mockery.io/en/latest/reference/expectations.html) to add expectations in addition to, or instead of using the arguments array passed to `userFunction`.