wip

leeovery · leeovery · commit e22e114a344a · 2023-01-27T10:07:21.000Z
diff --git a/config/laravel-playwright.php b/config/laravel-playwright.php
@@ -59,19 +59,25 @@
         'user' => 'App\\Models\\User',
 
         /**
-         * When passing state values to the factory, you can include a class or class alias (see
-         * below) along with a value and column. This is handy for when the state method on the
-         * factory expects an object as the parameter(s). These config values will be used as the
-         * separators to split the class/alias from the id and column.
+         * When passing state values to the factory, you can include a FQCN or class alias (see
+         * below) along with a value and column, or params (if param_alias). This is handy for
+         * when the state method on the factory expects an object as the parameter(s). The
+         * separator config values defined below will be used as the detectors and
+         * separators to split the class/alias from the passed options/params.
+         *
+         * When passing a model or model alias, you should prefix the model definition with
+         * 'model.' (can be changed as desired below) so that we can differentiate it from
+         * a param alias.
+         *
+         * ** To fetch a model and pass to the state method: **
          *
-         * eg:
          * This will trigger the "first" eloquent method to execute with a "where" clause for
-         * the user with an id of 100. This User will then be passed to the "createdBy"
-         * method on the factory.
+         * the user with an `id` of 100. This fetched and hydrated `User` will then be passed
+         * to your "createdBy" method on the defined factory.
          *
          * $state = [
          *     'createdBy' => [
-         *         ['user@100:id'],
+         *         ['model.user:100,id'],
          *     ],
          * ]
          *
@@ -80,47 +86,61 @@
          *
          * $state = [
          *     'createdBy' => [
-         *         ['\\App\\Models\\User@100'],
+         *         ['model.\\App\\Models\\User:100'],
          *     ],
          * ]
          *
-         * eg:
-         * This will use the `param_alias` commented out below to resolve the param for the endsAt
+         * ** To construct an object with params to be passed to the state method: **
+         *
+         * This will use a `param_alias` (defined below) to resolve the param for the `endsAt`
          * state method on the factory as a Carbon instance with the value to the right of the
          * separator. You can also pass multiple parameters to the state method that resolve using
-         * aliases as defined below. Parameters for the param_alias should be wrapped in square
-         * brackets as shown below.
+         * aliases as defined below. Parameters for the param_alias should be wrapped in
+         * parentheses as shown below.
          *
+         * This example will use the `carbon` alias (defined below - commented out) to make a
+         * `Carbon` instance with the value `2023-12-25 23:59:59`, and will be passed to the
+         * `endsAt` method on the factory:
          * $state = [
          *     'endsAt' => [
-         *         ['carbon@[2023-12-25 23:59:59]'],
+         *         ['carbon(2023-12-25 23:59:59)'],
          *     ],
+         * ]
+         *
+         * This example will use the carbon alias to make 2 instances, each with the date values
+         * as shown, and both instances will then be passed, in the order they are defined, to the `liveBetween` method on the factory class:
+         * $state = [
          *     'liveBetween' => [
-         *         ['carbon@[2023-01-01 00:00:00]', 'carbon@[2023-12-25 23:59:59]'],
+         *         ['carbon(2023-01-01 00:00:00)', 'carbon(2023-12-25 23:59:59)'],
          *     ],
+         * ]
+         *
+         * This example will use the collect alias to make a Collection with 2 items as defined.
+         * The Collection instance will then be passed to the comments method on the factory:
+         * $state = [
          *     'comments' => [
-         *         ['collect@[hello,goodbye]'],
+         *         ['collect(hello,goodbye)'],
          *     ],
          * ]
          */
 
         /**
-         * Used to separate the alias from any other passed options. Should be used first.
+         * Used to separate the model from any other passed options.
          */
-        'alias_separator' => '@',
-
-        /**
-         * If passing multiple params to be passed into an aliases callable, you can separate
-         * them using this option.
-         */
-        'param_separator' => ',',
+        'model_separator' => ':',
 
         /**
          * If you wish to resolve a model from the DB, you can optionally pass the column to compare
          * the value to in a where clause. The default column used is `id`. Use this separator to
          * separate the desired column from the rest of the passed options.
          */
-        'column_separator' => ':',
+        'column_separator' => ',',
+
+        /**
+         * If passing multiple params to be passed into an alias' callable, you can separate
+         * them using this option.
+         */
+        'param_separator' => ',',
 
         /**
          * You can optionally register aliases for models or other objects, rather than having
@@ -136,7 +156,7 @@
 
         'param_aliases' => [
             // 'carbon' => fn($date) => \Carbon\Carbon::create($date),
-            // 'collect' => fn($items) => \Illuminate\Support\Collection::make($items),
+            // 'collect' => fn($items) => \Illuminate\Support\Collection::make(...$items),
         ],
 
     ],
diff --git a/src/Exceptions/LaravelPlaywrightException.php b/src/Exceptions/LaravelPlaywrightException.php
@@ -0,0 +1,18 @@
+<?php
+
+namespace Leeovery\LaravelPlaywright\Exceptions;
+
+use Exception;
+
+class LaravelPlaywrightException extends Exception
+{
+    public static function resolvedModelDoesNotExist($model): LaravelPlaywrightException
+    {
+        return new self("Passed model does not exist ({$model}).", 404);
+    }
+
+    public static function resolvedParamAliasDoesNotExist($alias): LaravelPlaywrightException
+    {
+        return new self("Passed param alias does not exist ({$alias}).", 404);
+    }
+}
diff --git a/src/Http/Controllers/LaravelPlaywrightController.php b/src/Http/Controllers/LaravelPlaywrightController.php
@@ -2,14 +2,16 @@
 
 namespace Leeovery\LaravelPlaywright\Http\Controllers;
 
-use Illuminate\Support\Arr;
-use Illuminate\Support\Str;
+use Illuminate\Database\Eloquent\Factories\Factory;
 use Illuminate\Http\Request;
+use Illuminate\Routing\Route as RoutingRoute;
+use Illuminate\Support\Arr;
+use Illuminate\Support\Facades\Artisan;
 use Illuminate\Support\Facades\DB;
 use Illuminate\Support\Facades\Route;
-use Illuminate\Support\Facades\Artisan;
-use Illuminate\Routing\Route as RoutingRoute;
-use Illuminate\Database\Eloquent\Factories\Factory;
+use Illuminate\Support\Str;
+use Leeovery\LaravelPlaywright\Exceptions\LaravelPlaywrightException;
+use Throwable;
 
 class LaravelPlaywrightController
 {
@@ -119,11 +121,11 @@ public function tearDownEnv()
     public function routes()
     {
         return collect(Route::getRoutes()->getRoutes())
-            ->reject(fn(RoutingRoute $route) => Str::of($route->getName())
+            ->reject(fn (RoutingRoute $route) => Str::of($route->getName())
                 ->contains(config('laravel-playwright.route.ignore_names'))
             )
-            ->reject(fn(RoutingRoute $route) => is_null($route->getName()))
-            ->mapWithKeys(fn(RoutingRoute $route) => [
+            ->reject(fn (RoutingRoute $route) => is_null($route->getName()))
+            ->mapWithKeys(fn (RoutingRoute $route) => [
                 $route->getName() => [
                     'name' => $route->getName(),
                     'uri' => $route->uri(),
@@ -150,7 +152,7 @@ public function login(Request $request)
                 ->first();
         }
 
-        if (!$user) {
+        if (! $user) {
             $user = DB::transaction(function () use ($request) {
                 return $this
                     ->factoryBuilder($this->userClassName($request), $request->input('state', []))
@@ -176,19 +178,31 @@ protected function userClassName(Request $request)
         return config('laravel-playwright.factory.user');
     }
 
+    /**
+     * @throws Throwable
+     */
     protected function resolveModelAlias(string $alias)
     {
-        return data_get(config('laravel-playwright.factory.model_aliases'), $alias, $alias);
+        $model = data_get(config('laravel-playwright.factory.model_aliases'), $alias, $alias);
+
+        throw_unless(class_exists($model),
+            LaravelPlaywrightException::resolvedModelDoesNotExist($model)
+        );
+
+        return $model;
     }
 
+    /**
+     * @throws Throwable
+     */
     protected function factoryBuilder($model, $states = []): Factory
     {
         $factory = $this->resolveModelAlias($model)::factory();
 
         foreach (Arr::wrap($states) as $state) {
             $attributes = [];
             if (is_array($state)) {
-                $attributes = $this->buildUpStateAttributes($state);
+                $attributes = $this->resolveStateAttributes($state);
                 $state = array_key_first($state);
             }
             $factory = $factory->{$state}(...$attributes);
@@ -234,54 +248,71 @@ public function factory(Request $request)
                 )
                 ->count($request->integer('count', 1))
                 ->create($request->input('attributes'))
-                ->each(fn($model) => $model->setHidden([])->setVisible([]))
+                ->each(fn ($model) => $model->setHidden([])->setVisible([]))
                 ->load($request->input('load') ?? [])
-                ->pipe(fn($collection) => $collection->count() > 1
+                ->pipe(fn ($collection) => $collection->count() > 1
                     ? $collection
                     : $collection->first());
         });
     }
 
-    protected function buildUpStateAttributes($state): array
+    protected function resolveStateAttributes($state): array
     {
-        if (!is_array($state)) {
+        if (! is_array($state)) {
             return [];
         }
 
-        $aliasSeparator = config('laravel-playwright.factory.alias_separator');
-        $paramSeparator = config('laravel-playwright.factory.param_separator');
+        $modelDesignator = config('laravel-playwright.factory.model_designator');
+        $modelSeparator = config('laravel-playwright.factory.model_separator');
         $columnSeparator = config('laravel-playwright.factory.column_separator');
+        $paramSeparator = config('laravel-playwright.factory.param_separator');
 
         return collect(...array_values($state))->map(function ($attribute) use (
+            $modelDesignator,
+            $modelSeparator,
             $columnSeparator,
             $paramSeparator,
-            $aliasSeparator
         ) {
-            if (!is_string($attribute) || !str_contains($attribute, $aliasSeparator)) {
+            if (
+                ! is_string($attribute)
+                || ! str_contains($attribute, $modelDesignator)
+                || (! str_contains($attribute, '(') && ! str_contains($attribute, ')'))
+            ) {
                 return $attribute;
             }
 
-            if (str_contains($attribute, '[') && str_contains($attribute, ']')) {
-                [$alias, $options] = explode($aliasSeparator, $attribute);
-                $options = str($options)
-                    ->remove('[')
-                    ->remove(']')
+            if (str_contains($attribute, '(') && str_contains($attribute, ')')) {
+                $paramAlias = Str::before($attribute, '(');
+                $params = str($attribute)
+                    ->between('(', ')')
                     ->explode($paramSeparator)
-                    ->map(fn($option) => trim($option));
-                return value($this->resolveParamAlias($alias), ...$options);
+                    ->map(fn ($option) => trim($option));
+
+                return value($this->resolveParamAlias($paramAlias), ...$params);
             }
 
-            [$modelAlias, $options] = explode($aliasSeparator, $attribute);
+            $attribute = Str::after($attribute, $modelDesignator);
+
+            [$model, $options] = explode($modelSeparator, $attribute);
             [$value, $column] = array_pad(explode($columnSeparator, $options), 2, null);
             $column ??= 'id';
 
-            return $this->resolveModelAlias($modelAlias)::where($column, $value)->first();
+            return $this->resolveModelAlias($model)::where($column, $value)->first();
         })->filter()->all();
     }
 
+    /**
+     * @throws Throwable
+     */
     protected function resolveParamAlias(string $alias): callable
     {
-        return data_get(config('laravel-playwright.factory.param_aliases'), $alias, $alias);
+        $paramAlias = data_get(config('laravel-playwright.factory.param_aliases'), $alias);
+
+        throw_if(is_null($paramAlias),
+            LaravelPlaywrightException::resolvedParamAliasDoesNotExist($alias)
+        );
+
+        return $paramAlias;
     }
 
     public function logout()
