Update docs to explain how WP_Mock TestCase is preferable to extend t…

…han PhpUnit's (#239)

<!--
Filling out the required portions of this template is mandatory. 
Any PR that does not include enough information to be reviewed may be
closed at a maintainers' discretion.
All new code requires associated documentation and unit tests.
-->

# Summary <!-- Required -->

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 <!-- Required -->

<!--- Go over all the following points, and put an `x` in all the boxes
that apply. -->
<!--- If you are unsure about any of these, please ask for
clarification. We are here to help! -->

- [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 <!-- Required -->

<!-- The following checklist is for the reviewer: add any steps that may
be relevant while reviewing this pull request -->

- [ ] 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 <[email protected]>
Co-authored-by: Ryan Neudorf <[email protected]>
Co-authored-by: Drew Jaynes <[email protected]>

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   
+}
+
 ```

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.
+You will also need to [configure WP_Mock with a bootstrap file](configuration.md) to use it in your tests.

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
     {

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`.