From b24256101b99961ef5eaf0a41e10e4cd1a8759d5 Mon Sep 17 00:00:00 2001 From: Fulvio Notarstefano Date: Tue, 9 Jan 2024 15:53:47 +0900 Subject: [PATCH 1/5] Update docs to explain how WP_Mock TestCase is preferable to extend thatn PhpUnit's --- docs/usage/mocking-wp-objects.md | 3 +-- docs/usage/using-wp-mock.md | 7 +++++-- 2 files changed, 6 insertions(+), 4 deletions(-) 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..7f9f7e8 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,10 @@ Calling `WP_Mock::userFunction()` will dynamically define the function for you i return \WP_Mock\Functions\Handler::handleFunction(__FUNCTION__, func_get_args()); ``` +**Important!** + +Note how in the above test class `WP_Mock\Tools\TestCase` was extended instead of `PHPUnit\Framework\TestCase`. This is because WP_Mock provides a custom test case class that extends PHPUnit's test case class and adds additional functionality to it. Ideally, you should always extend `WP_Mock\Tools\TestCase` instead of `PHPUnit\Framework\TestCase` when using WP_Mock. _If you do not wish to extend WP_Mock own test case class_ you should make sure to call `WP_Mock::setUp()` and `WP_Mock::tearDown()` in your test case's `setUp()` and `tearDown()` methods respectively. + ## 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`. From 1b0aa27183c0b029e2d304fc7eda5955da632530 Mon Sep 17 00:00:00 2001 From: Ryan Neudorf Date: Wed, 10 Jan 2024 13:39:23 -0600 Subject: [PATCH 2/5] Added GitBook hint style and link to full WP_MockTestCase documentation. --- docs/usage/using-wp-mock.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/usage/using-wp-mock.md b/docs/usage/using-wp-mock.md index 7f9f7e8..4235490 100644 --- a/docs/usage/using-wp-mock.md +++ b/docs/usage/using-wp-mock.md @@ -54,10 +54,17 @@ 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!** Note how in the above test class `WP_Mock\Tools\TestCase` was extended instead of `PHPUnit\Framework\TestCase`. This is because WP_Mock provides a custom test case class that extends PHPUnit's test case class and adds additional functionality to it. Ideally, you should always extend `WP_Mock\Tools\TestCase` instead of `PHPUnit\Framework\TestCase` when using WP_Mock. _If you do not wish to extend WP_Mock own test case class_ you should make sure to call `WP_Mock::setUp()` and `WP_Mock::tearDown()` in your test case's `setUp()` and `tearDown()` methods respectively. +See [WP_Mock Test Case Documentation](../tools/wp-mock-test-case.md) + +{% 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`. From 48c99e88476a1d92b4fb2cca333cc40dc729f6ea Mon Sep 17 00:00:00 2001 From: Fulvio Notarstefano Date: Thu, 11 Jan 2024 11:43:28 +0900 Subject: [PATCH 3/5] Update configuration to explain that extending TestCase is required --- docs/general/configuration.md | 46 +++++++++++++++++++++++++++++++++-- docs/general/installation.md | 2 +- docs/usage/using-wp-mock.md | 4 +-- 3 files changed, 47 insertions(+), 5 deletions(-) diff --git a/docs/general/configuration.md b/docs/general/configuration.md index c4204f4..ab98c22 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 set up WP_Mock as outlined above, you should use the `WP_Mock\Tools\TestCase` class as your base test case class in your PHPUnit tests. This class extends PHPUnit's own `TestCase` class, with some helper methods but also methods that help WP_Mock to function properly. You should always extend `WP_Mock\Tools\TestCase` instead of `PHPUnit\Framework\TestCase` when using WP_Mock. + +```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/using-wp-mock.md b/docs/usage/using-wp-mock.md index 4235490..e234db0 100644 --- a/docs/usage/using-wp-mock.md +++ b/docs/usage/using-wp-mock.md @@ -59,9 +59,9 @@ return \WP_Mock\Functions\Handler::handleFunction(__FUNCTION__, func_get_args()) **Important!** -Note how in the above test class `WP_Mock\Tools\TestCase` was extended instead of `PHPUnit\Framework\TestCase`. This is because WP_Mock provides a custom test case class that extends PHPUnit's test case class and adds additional functionality to it. Ideally, you should always extend `WP_Mock\Tools\TestCase` instead of `PHPUnit\Framework\TestCase` when using WP_Mock. _If you do not wish to extend WP_Mock own test case class_ you should make sure to call `WP_Mock::setUp()` and `WP_Mock::tearDown()` in your test case's `setUp()` and `tearDown()` methods respectively. +Note how in the above test class `WP_Mock\Tools\TestCase` was extended instead of `PHPUnit\Framework\TestCase`. This is because WP_Mock provides a custom test case class that extends PHPUnit's test case class to run properly, as well as while adding additional utility and test methods. You should always 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) +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 %} From 1a675a82d516c43687f018305e822b7b3b320912 Mon Sep 17 00:00:00 2001 From: Fulvio Notarstefano Date: Fri, 12 Jan 2024 11:54:23 +0900 Subject: [PATCH 4/5] Update docs/usage/using-wp-mock.md Co-authored-by: Ryan Neudorf <109976277+rneudorf-godaddy@users.noreply.github.com> --- docs/usage/using-wp-mock.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/usage/using-wp-mock.md b/docs/usage/using-wp-mock.md index e234db0..304a031 100644 --- a/docs/usage/using-wp-mock.md +++ b/docs/usage/using-wp-mock.md @@ -59,8 +59,7 @@ return \WP_Mock\Functions\Handler::handleFunction(__FUNCTION__, func_get_args()) **Important!** -Note how in the above test class `WP_Mock\Tools\TestCase` was extended instead of `PHPUnit\Framework\TestCase`. This is because WP_Mock provides a custom test case class that extends PHPUnit's test case class to run properly, as well as while adding additional utility and test methods. You should always extend `WP_Mock\Tools\TestCase` instead of `PHPUnit\Framework\TestCase` when using WP_Mock. - +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 %} From 1517e83ca7af935914314002206840573fc21f26 Mon Sep 17 00:00:00 2001 From: Fulvio Notarstefano Date: Fri, 12 Jan 2024 15:12:37 +0900 Subject: [PATCH 5/5] Update docs/general/configuration.md Co-authored-by: Drew Jaynes <113622064+ajaynes-godaddy@users.noreply.github.com> --- docs/general/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/general/configuration.md b/docs/general/configuration.md index ab98c22..61e6b32 100644 --- a/docs/general/configuration.md +++ b/docs/general/configuration.md @@ -66,7 +66,7 @@ WP_Mock::bootstrap(); ## Extend WP_Mock Test Case -Once you have set up WP_Mock as outlined above, you should use the `WP_Mock\Tools\TestCase` class as your base test case class in your PHPUnit tests. This class extends PHPUnit's own `TestCase` class, with some helper methods but also methods that help WP_Mock to function properly. You should always extend `WP_Mock\Tools\TestCase` instead of `PHPUnit\Framework\TestCase` when using WP_Mock. +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