[8.x] Add Fluent JSON Assertions

src/Illuminate/Testing/Fluent/Assert.php

@@ -0,0 +1,126 @@
+<?php
+
+namespace Illuminate\Testing\Fluent;
+
+use Closure;
+use Illuminate\Contracts\Support\Arrayable;
+use Illuminate\Support\Arr;
+use Illuminate\Support\Traits\Macroable;
+use Illuminate\Support\Traits\Tappable;
+use Illuminate\Testing\AssertableJsonString;
+use PHPUnit\Framework\Assert as PHPUnit;
+
+class Assert implements Arrayable
+{
+    use Concerns\Has,
+        Concerns\Matching,
+        Concerns\Debugging,
+        Concerns\Interaction,
+        Macroable,
+        Tappable;
+
+    /**
+     * The properties in the current scope.
+     *
+     * @var array
+     */
+    private $props;
+
+    /**
+     * The "dot" path to the current scope.
+     *
+     * @var string|null
+     */
+    private $path;
+
+    /**
+     * Create a new Assert instance.
+     *
+     * @param  array  $props
+     * @param  string|null  $path
+     */
+    protected function __construct(array $props, string $path = null)
+    {
+        $this->path = $path;
+        $this->props = $props;
+    }
+
+    /**
+     * Compose the absolute "dot" path to the given key.
+     *
+     * @param  string  $key
+     * @return string
+     */
+    protected function dotPath(string $key): string
+    {
+        if (is_null($this->path)) {
+            return $key;
+        }
+
+        return implode('.', [$this->path, $key]);
+    }
+
+    /**
+     * Retrieve a prop within the current scope using "dot" notation.
+     *
+     * @param  string|null  $key
+     * @return mixed
+     */
+    protected function prop(string $key = null)
+    {
+        return Arr::get($this->props, $key);
+    }
+
+    /**
+     * Instantiate a new "scope" at the path of the given key.
+     *
+     * @param  string  $key
+     * @param  Closure  $callback
+     * @return $this
+     */
+    protected function scope(string $key, Closure $callback): self
+    {
+        $props = $this->prop($key);
+        $path = $this->dotPath($key);
+
+        PHPUnit::assertIsArray($props, sprintf('Property [%s] is not scopeable.', $path));
+
+        $scope = new self($props, $path);
+        $callback($scope);
+        $scope->interacted();
+
+        return $this;
+    }
+
+    /**
+     * Create a new instance from an array.
+     *
+     * @param  array  $data
+     * @return static
+     */
+    public static function fromArray(array $data): self
+    {
+        return new self($data);
+    }
+
+    /**
+     * Create a new instance from a AssertableJsonString.
+     *
+     * @param  AssertableJsonString  $json
+     * @return static
+     */
+    public static function fromAssertableJsonString(AssertableJsonString $json): self
+    {
+        return self::fromArray($json->json());
+    }
+
+    /**
+     * Get the instance as an array.
+     *
+     * @return array
+     */
+    public function toArray()
+    {
+        return $this->props;
+    }
+}

src/Illuminate/Testing/Fluent/Concerns/Debugging.php

@@ -0,0 +1,38 @@
+<?php
+
+namespace Illuminate\Testing\Fluent\Concerns;
+
+trait Debugging
+{
+    /**
+     * Dumps the given props.
+     *
+     * @param  string|null  $prop
+     * @return $this
+     */
+    public function dump(string $prop = null): self
+    {
+        dump($this->prop($prop));
+
+        return $this;
+    }
+
+    /**
+     * Dumps the given props and exits.
+     *
+     * @param  string|null  $prop
+     * @return void
+     */
+    public function dd(string $prop = null): void
+    {
+        dd($this->prop($prop));
+    }
+
+    /**
+     * Retrieve a prop within the current scope using "dot" notation.
+     *
+     * @param  string|null  $key
+     * @return mixed
+     */
+    abstract protected function prop(string $key = null);
+}

src/Illuminate/Testing/Fluent/Concerns/Has.php

@@ -0,0 +1,158 @@
+<?php
+
+namespace Illuminate\Testing\Fluent\Concerns;
+
+use Closure;
+use Illuminate\Support\Arr;
+use PHPUnit\Framework\Assert as PHPUnit;
+
+trait Has
+{
+    /**
+     * Assert that the prop is of the expected size.
+     *
+     * @param  string  $key
+     * @param  int  $length
+     * @return $this
+     */
+    protected function count(string $key, int $length): self
+    {
+        PHPUnit::assertCount(
+            $length,
+            $this->prop($key),
+            sprintf('Property [%s] does not have the expected size.', $this->dotPath($key))
+        );
+
+        return $this;
+    }
+
+    /**
+     * Ensure that the given prop exists.
+     *
+     * @param  string  $key
+     * @param  null  $value
+     * @param  Closure|null  $scope
+     * @return $this
+     */
+    public function has(string $key, $value = null, Closure $scope = null): self
+    {
+        $prop = $this->prop();
+
+        PHPUnit::assertTrue(
+            Arr::has($prop, $key),
+            sprintf('Property [%s] does not exist.', $this->dotPath($key))
+        );
+
+        $this->interactsWith($key);
+
+        // When all three arguments are provided, this indicates a short-hand
+        // expression that combines both a `count`-assertion, followed by
+        // directly creating a `scope` on the first element.
+        if (is_int($value) && ! is_null($scope)) {
+            $prop = $this->prop($key);
+            $path = $this->dotPath($key);
+
+            PHPUnit::assertTrue($value > 0, sprintf('Cannot scope directly onto the first entry of property [%s] when asserting that it has a size of 0.', $path));
+            PHPUnit::assertIsArray($prop, sprintf('Direct scoping is unsupported for non-array like properties such as [%s].', $path));
+
+            $this->count($key, $value);
+
+            return $this->scope($key.'.'.array_keys($prop)[0], $scope);
+        }
+
+        if (is_callable($value)) {
+            $this->scope($key, $value);
+        } elseif (! is_null($value)) {
+            $this->count($key, $value);
+        }
+
+        return $this;
+    }
+
+    /**
+     * Assert that all of the given props exist.
+     *
+     * @param  array|string $key
+     * @return $this
+     */
+    public function hasAll($key): self
+    {
+        $keys = is_array($key) ? $key : func_get_args();
+
+        foreach ($keys as $prop => $count) {
+            if (is_int($prop)) {
+                $this->has($count);
+            } else {
+                $this->has($prop, $count);
+            }
+        }
+
+        return $this;
+    }
+
+    /**
+     * Assert that none of the given props exist.
+     *
+     * @param  array|string $key
+     * @return $this
+     */
+    public function missingAll($key): self
+    {
+        $keys = is_array($key) ? $key : func_get_args();
+
+        foreach ($keys as $prop) {
+            $this->missing($prop);
+        }
+
+        return $this;
+    }
+
+    /**
+     * Assert that the given prop does not exist.
+     *
+     * @param  string  $key
+     * @return $this
+     */
+    public function missing(string $key): self
+    {
+        PHPUnit::assertNotTrue(
+            Arr::has($this->prop(), $key),
+            sprintf('Property [%s] was found while it was expected to be missing.', $this->dotPath($key))
+        );
+
+        return $this;
+    }
+
+    /**
+     * Compose the absolute "dot" path to the given key.
+     *
+     * @param  string  $key
+     * @return string
+     */
+    abstract protected function dotPath(string $key): string;
+
+    /**
+     * Marks the property as interacted.
+     *
+     * @param  string  $key
+     * @return void
+     */
+    abstract protected function interactsWith(string $key): void;
+
+    /**
+     * Retrieve a prop within the current scope using "dot" notation.
+     *
+     * @param  string|null  $key
+     * @return mixed
+     */
+    abstract protected function prop(string $key = null);
+
+    /**
+     * Instantiate a new "scope" at the path of the given key.
+     *
+     * @param  string  $key
+     * @param  Closure  $callback
+     * @return $this
+     */
+    abstract protected function scope(string $key, Closure $callback);
+}

src/Illuminate/Testing/Fluent/Concerns/Interaction.php

@@ -0,0 +1,67 @@
+<?php
+
+namespace Illuminate\Testing\Fluent\Concerns;
+
+use Illuminate\Support\Str;
+use PHPUnit\Framework\Assert as PHPUnit;
+
+trait Interaction
+{
+    /**
+     * The list of interacted properties.
+     *
+     * @var array
+     */
+    protected $interacted = [];
+
+    /**
+     * Marks the property as interacted.
+     *
+     * @param  string  $key
+     * @return void
+     */
+    protected function interactsWith(string $key): void
+    {
+        $prop = Str::before($key, '.');
+
+        if (! in_array($prop, $this->interacted, true)) {
+            $this->interacted[] = $prop;
+        }
+    }
+
+    /**
+     * Asserts that all properties have been interacted with.
+     *
+     * @return void
+     */
+    public function interacted(): void
+    {
+        PHPUnit::assertSame(
+            [],
+            array_diff(array_keys($this->prop()), $this->interacted),
+            $this->path
+                ? sprintf('Unexpected properties were found in scope [%s].', $this->path)
+                : 'Unexpected properties were found on the root level.'
+        );
+    }
+
+    /**
+     * Disables the interaction check.
+     *
+     * @return $this
+     */
+    public function etc(): self
+    {
+        $this->interacted = array_keys($this->prop());
+
+        return $this;
+    }
+
+    /**
+     * Retrieve a prop within the current scope using "dot" notation.
+     *
+     * @param  string|null  $key
+     * @return mixed
+     */
+    abstract protected function prop(string $key = null);
+}