[Refactor] Use the laravel-json-api/testing dependency

Author: lindyhopchris

CHANGELOG.md

@@ -17,6 +17,16 @@ All notable changes to this project will be documented in this file. This projec
 - Package now depends on our fork of the Neomerx JSON:API package - `laravel-json-api/neomerx-json-api`. This is a
   non-breaking change.
 
+### Removed
+
+- **BREAKING** Removed the following classes from the `CloudCreativity\LaravelJsonApi\Testing` namespace. You must 
+  use classes (with the same names) from the `LaravelJsonApi\Testing` namespace, after installing the 
+  `laravel-json-api/testing` package as a dev dependency. Refer to the upgrade guide for details. Classes/traits removed
+  are:
+    - `MakesJsonApiRequests`
+    - `TestBuilder`
+    - `TestResponse`
+
 ## Unreleased
 
 ### Changed

composer.json

@@ -34,6 +34,7 @@
         "ext-sqlite3": "*",
         "cloudcreativity/json-api-testing": "^4.0",
         "guzzlehttp/guzzle": "^7.0",
+        "laravel-json-api/testing": "^1.1",
         "laravel/legacy-factories": "^1.0.4",
         "laravel/ui": "^3.0",
         "mockery/mockery": "^1.1",

docs/upgrade.md

@@ -2,12 +2,160 @@
 
 ## 3.x to 4.0
 
+To upgrade, run the following Composer commands:
+
+```bash
+composer remove cloudcreativity/json-api-testing --dev
+composer require cloudcreativity/laravel-json-api:^4.0 --no-update
+composer require laravel-json-api/testing:^1.1 --no-update
+composer up cloudcreativity/* laravel-json-api/*
+```
+
 ### PHP 8.1
 
-To remove deprecation messages from PHP 8.1, we've added return types of `#[\ReturnTypeWillChange]` annotations to
+To remove deprecation messages from PHP 8.1, we've added return types or `#[\ReturnTypeWillChange]` annotations to
 methods for internal interfaces. This is unlikely to break your application, unless you have extended one of our classes
 and overridden an internal method.
 
+### Testing
+
+We are switching to using the `laravel-json-api/testing` package. This will help in the future with upgrading to the
+new `laravel-json-api/laravel` package, because it will mean when you upgrade your tests should continue to work
+without modifications. I.e. having a great test suite for your JSON:API functionality will help you safely upgrade in
+the future.
+
+The `laravel-json-api/testing` dependency uses the `cloudcreativity/json-api-testing` package, which is what you have 
+been using up until now. It's just a more recent version, so there are a few changes to implement when upgrading.
+
+The new testing package is fully 
+[documented on the Laravel JSON:API site](https://laraveljsonapi.io/docs/1.0/testing/) so we recommend you take a look
+at that if you get stuck when upgrading.
+
+#### Test Case
+
+In the test case where you're importing `MakesJsonApiRequests`, change the `use` statement from this:
+
+```php
+use CloudCreativity\LaravelJsonApi\Testing\MakesJsonApiRequests;
+```
+
+to this:
+
+```php
+use LaravelJsonApi\Testing\MakesJsonApiRequests;
+```
+
+#### Test Response
+
+If anywhere in your application you have type-hinted our specific `TestResponse` you will need to change the `use`
+statement. (Note that most applications won't have type-hinted the `TestResponse` anywhere.)
+
+Previously:
+
+```php
+use CloudCreativity\LaravelJsonApi\Testing\TestResponse;
+```
+
+It now needs to be:
+
+```php
+use LaravelJsonApi\Testing\TestResponse;
+```
+
+#### Test Actions
+
+The following test actions have been deprecated for some time and have now been removed. This is because these helper
+methods used the JSON:API implementation internally, which was potentially risky as the JSON:API implementation itself
+is the subject of the tests. These are the methods:
+
+- `doSearch()`
+- `doSearchById()`
+- `doCreate()`
+- `doRead()`
+- `doUpdate()`
+- `doDelete()`
+- `doReadRelated()`
+- `doReadRelationship()`
+- `doReplaceRelationship()`
+- `doAddToRelationship()`
+- `doRemoveFromRelationship()`
+
+Here are example replacements:
+
+```php
+// doSearch()
+$response = $this->jsonApi('posts')->get('/api/v1/posts');
+
+// doSearchById()
+$response = $this
+    ->jsonApi('posts')
+    ->filter(['id' => $posts])
+    ->get('/api/v1/posts');
+
+// doCreate()
+$response = $this
+    ->jsonApi('posts')
+    ->withData($data)
+    ->post('/api/v1/posts');
+
+// doRead()
+$response = $this
+    ->jsonApi('posts')
+    ->get(url('/api/v1/posts', $post));
+
+// doUpdate()
+$response = $this
+    ->jsonApi('posts')
+    ->withData($data)
+    ->patch(url('/api/v1/posts', $post));
+
+// doDelete()
+$response = $this
+    ->jsonApi('posts')
+    ->delete(url('/api/v1/posts', $post));
+
+// doReadRelated()
+$response = $this
+    ->jsonApi('comments')
+    ->get(url('/api/v1/posts', [$post, 'comments']));
+
+// doReadRelationship()
+$response = $this
+    ->jsonApi('comments')
+    ->get(url('/api/v1/posts', [$post, 'relationships', 'comments']));
+
+// doReplaceRelationship()
+$response = $this
+    ->jsonApi('comments')
+    ->withData($data)
+    ->patch(url('/api/v1/posts', [$post, 'relationships', 'comments']));
+
+// doAddToRelationship()
+$response = $this
+    ->jsonApi('comments')
+    ->withData($data)
+    ->post(url('/api/v1/posts', [$post, 'relationships', 'comments']));
+
+// doRemoveFromRelationship()
+$response = $this
+    ->jsonApi('comments')
+    ->withData($data)
+    ->delete(url('/api/v1/posts', [$post, 'relationships', 'comments']));
+```
+
+> Note in all the above we use `withData()` to set the data for the request. Previously there was a `data` method, which
+> has been removed.
+
+Also, the following HTTP verb JSON:API methods have been removed:
+
+- `getJsonApi` - use `$this->jsonApi('posts')->get($url)`
+- `postJsonApi` - use `$this->jsonApi('posts')->withData($data)->post($url)`
+- `patchJsonApi` - use `$this->jsonApi('posts')->withData($data)->patch($url)`
+- `deleteJsonApi` - use `$this->jsonApi('posts')->withData($data)->delete($url)`
+
+> For info, everything has been moved to the test builder that's returned by the `jsonApi()` method, so that we can 
+> avoid collisions with any methods that Laravel might.
+
 ## 2.x to 3.0
 
 ### Validators