Merge pull request #675 from code16/new-testing-api

New testing API

Author: aguingand

docs/.vitepress/sidebar.ts

@@ -101,7 +101,8 @@ export function sidebar(): DefaultTheme.SidebarItem[] {
                 { text: 'Sharp Context', link: '/guide/context.md' },
                 { text: 'Sharp built-in solution for uploads', link: '/guide/sharp-uploads.md' },
                 { text: 'Data localization in Form and Show Page', link: '/guide/data-localization.md' },
-                { text: 'Testing with Sharp', link: '/guide/testing-with-sharp.md' },
+                { text: 'Testing', link: '/guide/testing.md' },
+                { text: 'Testing (legacy API)', link: '/guide/testing-legacy.md' },
                 { text: 'Artisan Generators', link: '/guide/artisan-generators.md' },
                 { text: 'Style & Visual Theme', link: '/guide/style-visual-theme.md' }
             ]

docs/guide/testing-with-sharp.md docs/guide/testing-legacy.mddocs/guide/testing-with-sharp.md renamed to docs/guide/testing-legacy.md

@@ -1,4 +1,8 @@
-# Testing with Sharp
+# Testing with Sharp (legacy API)
+
+::: warning
+This page documents the old Testing API, we recommend using the new [Testing API](/guide/testing).
+:::
 
 Sharp provides a few assertions and helpers to help you test your Sharp code.
 

docs/guide/testing.md

@@ -0,0 +1,281 @@
+# Testing
+
+::: tip INFO
+This page documents the new Testing API. If you use the legacy one, please refer to [Testing (legacy)](../legacy/testing.md).
+:::
+
+Sharp provides a fluent testing API to help you test your Sharp code. These assertions and helpers are designed to be used in Feature tests.
+
+## The `SharpAssertions` trait
+
+To use Sharp's testing helpers, include the `Code16\Sharp\Utils\Testing\SharpAssertions` trait in your TestCase class:
+
+```php
+use Code16\Sharp\Utils\Testing\SharpAssertions;
+
+abstract class TestCase extends BaseTestCase
+{
+    use SharpAssertions;
+    
+    // ...
+}
+```
+
+or in `Pest.php`:
+
+```php
+use Code16\Sharp\Utils\Testing\SharpAssertions;
+
+pest()
+    ->extend(\Tests\TestCase::class)
+    ->use(SharpAssertions::class);
+```
+
+## Authentication
+
+### `loginAsSharpUser($user)`
+
+Sharp provides a helper to log in a user. By default, it will use the `SharpAssertions` internal logic to ensure the user is authorized to access Sharp.
+
+```php
+it('allows the user to access the list', function () {
+    $user = User::factory()->create();
+
+    $this
+        ->loginAsSharpUser($user)
+        ->sharpList(Post::class)
+        ->get()
+        ->assertOk();
+});
+```
+
+## Testing Entity Lists
+
+Use `sharpList()` to test your Entity Lists.
+
+### `sharpList(string $entityKey)`
+
+Starts a fluent interaction with an Entity List.
+
+```php
+$this->sharpList(Post::class)
+    ->get()
+    ->assertOk()
+    ->assertListData(fn (AssertableJson $data) => $data
+        ->count(3)
+        ->has('0.title', 'My first post')
+        ->etc()
+    );
+```
+
+### Filtering the list
+
+You can use `withFilter()` to apply filters to the list before calling `get()` or a command.
+
+```php
+$this->sharpList(Post::class)
+    ->withFilter(CategoryFilter::class, 1)
+    ->get()
+    ->assertOk();
+```
+
+### Entity Commands
+
+You can call an Entity Command directly from the list:
+
+```php
+$this->sharpList(Post::class)
+    ->entityCommand(ExportPosts::class)
+    ->post()
+    ->assertOk()
+    ->assertReturnsDownload('posts.csv');
+```
+
+If the command has a form, you can test it:
+    
+```php
+$this->sharpList(Post::class)
+    ->entityCommand(ExportPosts::class)
+    ->getForm()
+    ->assertFormData(fn (AssertableJson $data) => $data
+        ->where('format', 'xls')
+        ->etc()
+    )
+    ->post(['format' => 'csv'])
+    ->assertOk();
+```
+
+### Instance Commands
+
+Similarly, you can call an Instance Command:
+
+```php
+$this->sharpList(Post::class)
+    ->instanceCommand(PublishPost::class, 1)
+    ->post()
+    ->assertOk()
+    ->assertReturnsReload();
+```
+
+### Multi-step Commands (Wizards)
+
+For commands that have multiple steps, you can use `getNextStepForm()`:
+
+```php
+$this->sharpList(Post::class)
+    ->entityCommand(MyWizardCommand::class)
+    ->getForm()
+    ->post(['step1_data' => 'value'])
+    ->assertReturnsStep('step2')
+    ->getNextStepForm()
+    ->assertFormData(fn (AssertableJson $data) => $data
+        ->where('step2_field', 'default')
+        ->etc()
+    )
+    ->post(['step2_data' => 'value'])
+    ->assertOk();
+```
+
+## Testing Show Pages
+
+Use `sharpShow()` to test your Show Pages.
+
+### `sharpShow(string $entityKey, $instanceId)`
+
+Starts a fluent interaction with a Show Page.
+
+```php
+$this->sharpShow(Post::class, 1)
+    ->get()
+    ->assertOk()
+    ->assertShowData(fn (AssertableJson $data) => $data
+        ->where('title', 'My first post')
+        ->where('author', 'John Doe')
+        ->etc()
+    );
+```
+
+### Instance Commands from Show
+
+```php
+$this->sharpShow(Post::class, 1)
+    ->instanceCommand(PublishPost::class)
+    ->post()
+    ->assertOk();
+```
+
+### List & dashboard fields
+
+Show Pages can contain embedded Entity Lists or Dashboards. You can test them using `sharpListField()` and `sharpDashboardField()`.
+
+#### `sharpListField(string $entityKey)`
+
+```php
+$this->sharpShow(Post::class, 1)
+    ->sharpListField(Comment::class)
+    ->get()
+    ->assertOk()
+    ->assertListData(fn (AssertableJson $data) => $data
+        ->count(5)
+    );
+```
+
+#### `sharpDashboardField(string $entityKey)`
+
+```php
+$this->sharpShow(User::class, 1)
+    ->sharpDashboardField(UserStatsDashboard::class)
+    ->get()
+    ->assertOk();
+```
+
+### Nested shows
+
+There are some cases where you have nested shows by navigating through Show List fields. You can chain `sharpShow()` calls to simulate the correct breadcrumb :
+
+```php
+$this->sharpList(Post::class)
+    ->sharpShow(Post::class, 1)
+    ->sharpListField(Comment::class)
+    ->sharpShow(Comment::class, 1)
+    ->assertOk();
+```
+
+## Testing Forms
+
+Use `sharpForm()` to test your Forms.
+
+### `sharpForm(string $entityKey, $instanceId = null)`
+
+Starts a fluent interaction with a Form. If `$instanceId` is provided, it targets an edit form; otherwise, it targets a creation form.
+
+### Creating and Updating
+
+```php
+// Create
+$this->sharpForm(Post::class)
+    ->store(['title' => 'New Post'])
+    ->assertValid()
+    ->assertRedirect();
+
+// Update
+$this->sharpForm(Post::class, 1)
+    ->update(['title' => 'Updated Post'])
+    ->assertValid()
+    ->assertRedirect();
+```
+
+### Testing the "Creation" or "Edit" request itself
+
+If you want to test that the form displays correctly:
+
+```php
+$this->sharpForm(Post::class, 1)
+    ->edit()
+    ->assertOk()
+    ->assertFormData(fn (AssertableJson $data) => $data
+        ->where('title', 'Existing Post')
+        ->etc()
+    );
+```
+
+From an `AssertableForm` (the result of `edit()` or `create()`), you can also call `update()` or `store()`:
+
+```php
+$this->sharpForm(Post::class, 1)
+    ->edit()
+    ->update(['title' => 'New title'])
+    ->assertValid();
+```
+
+## Testing Dashboards
+
+Use `sharpDashboard()` to test your Dashboards.
+
+### `sharpDashboard(string $entityKey)`
+
+Starts a fluent interaction with a Dashboard.
+
+```php
+$this->sharpDashboard(MyDashboard::class)
+    ->get()
+    ->assertOk();
+```
+
+### Filtering the dashboard
+
+```php
+$this->sharpDashboard(MyDashboard::class)
+    ->withFilter(PeriodFilter::class, ['start' => '2023-01-01', 'end' => '2023-01-31'])
+    ->get()
+    ->assertOk();
+```
+
+### Dashboard Commands
+
+```php
+$this->sharpDashboard(MyDashboard::class)
+    ->dashboardCommand(RefreshStats::class)
+    ->post()
+    ->assertOk();
+```

docs/guide/upgrading/9.0.md

@@ -404,7 +404,7 @@ All assertions, like for instance `assertSharpHasAuthorization`, were removed be
 
 This means you also need to remove all `$this->initSharpAssertions()` calls from your tests.
 
-Of course, the test helpers remain available, see the dedicated [testing documentation](../testing-with-sharp.md).
+Of course, the test helpers remain available, see the dedicated [testing documentation](../testing.md).
 
 Also take note that the `withSharpCurrentBreadcrumb()` method is now deprecated, in favor of the new `withSharpBreadcrumb()` method also documented in the section linked above.
 

ide.json

@@ -14,6 +14,17 @@
                     "parameters": [
                         1
                     ]
+                },
+                {
+                    "classFqn": [
+                        "Code16\\Sharp\\Utils\\Testing\\Commands\\AssertableCommand"
+                    ],
+                    "methodNames": [
+                        "assertReturnsView"
+                    ],
+                    "parameters": [
+                        1
+                    ]
                 }
             ]
         },

src/Data/Commands/CommandFormData.php

@@ -23,6 +23,7 @@ public function __construct(
         /** @var array<string> */
         public ?array $locales = null,
         public ?PageAlertData $pageAlert = null,
+        public ?array $_rawData = null,
     ) {}
 
     public static function from(array $form): self
@@ -36,6 +37,7 @@ public static function from(array $form): self
             layout: FormLayoutData::optional($form['layout'] ?? null),
             locales: $form['locales'] ?? null,
             pageAlert: PageAlertData::optional($form['pageAlert']),
+            _rawData: $form['_rawData'] ?? null,
         );
     }
 }

src/Http/Controllers/Api/Commands/HandlesCommandForm.php

@@ -33,6 +33,9 @@ protected function getCommandForm(InstanceCommand|EntityCommand|DashboardCommand
             'locales' => $commandHandler->hasDataLocalizations()
                 ? $commandHandler->getDataLocalizations()
                 : null,
+            ...app()->environment('testing') ? [
+                '_rawData' => $formData,
+            ] : [],
         ];
     }
 }

src/Http/Controllers/FormController.php

@@ -37,6 +37,10 @@ public function create(string $globalFilter, string $parentUri, EntityKey $entit
         $form->buildFormConfig();
         $formData = $form->newInstance();
 
+        if (app()->environment('testing')) {
+            Inertia::share('_rawData', $formData);
+        }
+
         return Inertia::render('Form/Form', [
             'form' => FormData::from([
                 ...$this->buildFormData($form, $formData, $entityKey),
@@ -90,6 +94,10 @@ public function edit(string $globalFilter, string $parentUri, EntityKey $entityK
             ->breadcrumb()
             ->getParentShowCachedBreadcrumbLabel() ?: $entity->getLabelOrFail($entityKey->multiformKey());
 
+        if (app()->environment('testing')) {
+            Inertia::share('_rawData', $formData);
+        }
+
         return Inertia::render('Form/Form', [
             'form' => FormData::from([
                 ...$this->buildFormData($form, $formData, $entityKey, $instanceId),

src/Http/Controllers/ShowController.php

@@ -57,6 +57,10 @@ public function show(string $globalFilter, string $parentUri, EntityKey $entityK
 
         $this->addPreloadHeadersForShowEntityLists($payload);
 
+        if (app()->environment('testing')) {
+            Inertia::share('_rawData', $showData);
+        }
+
         return Inertia::render('Show/Show', [
             'show' => $payload,
             'breadcrumb' => BreadcrumbData::from([

src/Http/Controllers/SingleShowController.php

@@ -53,6 +53,10 @@ public function show(string $globalFilter, EntityKey $entityKey)
 
         $this->addPreloadHeadersForShowEntityLists($payload);
 
+        if (app()->environment('testing')) {
+            Inertia::share('_rawData', $showData);
+        }
+
         return Inertia::render('Show/Show', [
             'show' => $payload,
             'breadcrumb' => BreadcrumbData::from([