[Feature] Add non-JSON API request test helper methods

The test builder now more easily supports testing non-JSON API
requests for which a JSON API response is expected.

Closes #545

Author: lindyhopchris

CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to this project will be documented in this file. This projec
 
 ## Unreleased
 
+### Added
+- [#545](https://github.com/cloudcreativity/laravel-json-api/issues/545)
+The request test builder now supports testing requests that do not have JSON API request content,
+but expect a JSON API response. For example, a file upload that results in a JSON API resource
+in the response body can be tested using:
+`$this->jsonApi()->asMultiPartFormData()->withPayload($data)->post('/api/v1/avatars');`.
+
 ### Changed
 - [#497](https://github.com/cloudcreativity/laravel-json-api/issues/497) and
 [#529](https://github.com/cloudcreativity/laravel-json-api/pull/529)

src/Testing/TestBuilder.php

@@ -9,7 +9,6 @@
 use PHPUnit\Framework\TestCase;
 use function array_walk_recursive;
 use function collect;
-use function http_build_query;
 use function implode;
 use function is_bool;
 use function is_null;
@@ -46,7 +45,17 @@ final class TestBuilder
     /**
      * @var Collection
      */
-    private $document;
+    private $headers;
+
+    /**
+     * @var Collection|null
+     */
+    private $json;
+
+    /**
+     * @var Collection|null
+     */
+    private $payload;
 
     /**
      * TestBuilder constructor.
@@ -58,7 +67,7 @@ public function __construct($test)
         $this->test = $test;
         $this->accept = $this->contentType = 'application/vnd.api+json';
         $this->query = collect();
-        $this->document = collect();
+        $this->headers = collect();
     }
 
     /**
@@ -100,6 +109,28 @@ public function contentType(?string $mediaType): self
         return $this;
     }
 
+    /**
+     * Set the request content type to 'application/x-www-form-urlencoded'.
+     *
+     * @return $this
+     */
+    public function asFormUrlEncoded(): self
+    {
+        return $this->contentType('application/x-www-form-urlencoded');
+    }
+
+    /**
+     * Set the request content type to multipart form data.
+     *
+     * @return $this
+     */
+    public function asMultiPartFormData(): self
+    {
+        return $this->contentType(
+            'multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW'
+        );
+    }
+
     /**
      * Add query parameters to the request.
      *
@@ -127,7 +158,7 @@ public function includePaths(string ...$paths): self
     }
 
     /**
-     * Set the sparse fieldsets for a resource type.
+     * Set the sparse field sets for a resource type.
      *
      * @param string $resourceType
      * @param string|string[] $fieldNames
@@ -183,17 +214,40 @@ public function page(iterable $page): self
     /**
      * Set the data member of the request JSON API document.
      *
-     * @param mixed|null $data
+     * @param iterable|null $data
      * @return $this
+     * @deprecated 4.0 use `withData`.
      */
     public function data($data): self
+    {
+        return $this->withData($data);
+    }
+
+    /**
+     * Set the data member of the request JSON API document.
+     *
+     * @param iterable|null $data
+     * @return $this
+     */
+    public function withData($data): self
     {
         if (is_null($data)) {
-            $this->document->put('data', null);
-        } else {
-            $this->document->put('data', collect($data));
+            return $this->withJson(['data' => null]);
         }
 
+        return $this->withJson(['data' => collect($data)]);
+    }
+
+    /**
+     * Set the JSON request document.
+     *
+     * @param $json
+     * @return $this
+     */
+    public function withJson($json): self
+    {
+        $this->json = collect($json);
+
         return $this;
     }
 
@@ -203,10 +257,11 @@ public function data($data): self
      * @param mixed $document
      * @param string|null $contentType
      * @return $this
+     * @deprecated 4.0
      */
     public function content($document, string $contentType = null): self
     {
-        $this->document = collect($document);
+        $this->json = collect($document);
 
         if ($contentType) {
             $this->contentType($contentType);
@@ -215,6 +270,44 @@ public function content($document, string $contentType = null): self
         return $this;
     }
 
+    /**
+     * Set the request payload for a non-JSON API request.
+     *
+     * @param $parameters
+     * @return $this
+     */
+    public function withPayload($parameters): self
+    {
+        $this->payload = collect($parameters);
+        // we need a content length as it is used by the JSON API implementation to determine if there is body.
+        $this->headers['CONTENT_LENGTH'] = '1';
+
+        return $this;
+    }
+
+    /**
+     * @param iterable $headers
+     * @return $this
+     */
+    public function withHeaders(iterable $headers): self
+    {
+        $this->headers = $this->headers->merge($headers);
+
+        return $this;
+    }
+
+    /**
+     * @param string $name
+     * @param string $value
+     * @return $this
+     */
+    public function withHeader(string $name, string $value): self
+    {
+        $this->headers->put($name, $value);
+
+        return $this;
+    }
+
     /**
      * Visit the given URI with a GET request, expecting JSON API content.
      *
@@ -251,6 +344,16 @@ public function patch(string $uri, iterable $headers = []): TestResponse
         return $this->call('PATCH', $uri, $headers);
     }
 
+    /**
+     * @param string $uri
+     * @param array|iterable $headers
+     * @return TestResponse
+     */
+    public function put(string $uri, iterable $headers = []): TestResponse
+    {
+        return $this->call('PUT', $uri, $headers);
+    }
+
     /**
      * Visit the given URI with a DELETE request, expecting JSON API content.
      *
@@ -275,17 +378,24 @@ public function call(string $method, string $uri, iterable $headers = []): TestR
             $uri .= '?' . $this->buildQuery();
         }
 
-        $headers = collect([
-            'Accept' => $this->accept,
-            'CONTENT_TYPE' => $this->contentType,
-        ])->filter()->merge($headers);
+        $headers = $this->buildHeaders($headers);
 
-        $response = TestResponse::cast($this->test->json(
-            $method,
-            $uri,
-            $this->document->toArray(),
-            $headers->toArray()
-        ));
+        if ($this->payload) {
+            $response = $this->test->{strtolower($method)}(
+                $uri,
+                $this->payload->toArray(),
+                $headers
+            );
+        } else {
+            $response = $this->test->json(
+                $method,
+                $uri,
+                $this->json ? $this->json->toArray() : [],
+                $headers
+            );
+        }
+
+        $response = TestResponse::cast($response);
 
         if ($this->expectedResourceType) {
             $response->willSeeResourceType($this->expectedResourceType);
@@ -315,6 +425,19 @@ private function buildQuery(): string
             }
         });
 
-        return http_build_query($query);
+        return Arr::query($query);
+    }
+
+    /**
+     * @param iterable $headers
+     * @return array
+     */
+    private function buildHeaders(iterable $headers): array
+    {
+        return collect(['Accept' => $this->accept, 'CONTENT_TYPE' => $this->contentType])
+            ->filter()
+            ->merge($this->headers)
+            ->merge($headers)
+            ->toArray();
     }
 }

tests/dummy/tests/Feature/Avatars/CreateTest.php

@@ -47,9 +47,10 @@ public function test(string $contentType): void
 
         $response = $this
             ->jsonApi()
+            ->includePaths('user')
             ->contentType($contentType)
-            ->content(['avatar' => $file])
-            ->post('/api/v1/avatars?include=user');
+            ->withPayload(['avatar' => $file])
+            ->post('/api/v1/avatars');
 
         $id = $response
             ->assertCreatedWithServerId(url('/api/v1/avatars'), $expected)