update tests

Author: HPWebdeveloper

tests/Feature/ApiResources/HasStatesResourceMethodsTest.php

@@ -12,6 +12,11 @@
 
 describe('HasStates resource methods', function () {
     describe('getStateResource', function () {
+        /**
+         * Scenario: Model returns its current state as a resource array
+         * Setup: Create post in draft state
+         * Assertions: Resource contains all state metadata keys and correct values
+         */
         it('returns state as resource array', function () {
             $post = Post::create(['title' => 'Test', 'state' => 'draft']);
 
@@ -33,6 +38,11 @@
             expect($resource['is_current'])->toBeTrue();
         });
 
+        /**
+         * Scenario: State resource respects user context for permission checks
+         * Setup: Create admin user and draft post
+         * Assertions: Resource generated successfully with user context
+         */
         it('accepts user context', function () {
             $user = new User(['id' => 1, 'role' => 'admin']);
             $post = Post::create(['title' => 'Test', 'state' => 'draft']);
@@ -42,6 +52,11 @@
             expect($resource['name'])->toBe('draft');
         });
 
+        /**
+         * Scenario: Resource handles models with null state gracefully
+         * Setup: Create post and manually set state to null
+         * Assertions: Resource returns with name key present
+         */
         it('handles null state', function () {
             // Create post without triggering the creating hook
             $post = new Post(['id' => 999, 'title' => 'No State']);
@@ -58,6 +73,11 @@
     });
 
     describe('getStateForUI', function () {
+        /**
+         * Scenario: Model returns simplified state data for UI rendering
+         * Setup: Create post in draft state
+         * Assertions: UI data contains name, title, color, icon keys with correct values
+         */
         it('returns state for UI display', function () {
             $post = Post::create(['title' => 'Test', 'state' => 'draft']);
 
@@ -69,6 +89,11 @@
             expect($ui['color'])->toBe('primary');
         });
 
+        /**
+         * Scenario: UI method returns null when model has no state
+         * Setup: Create post and clear its state attribute
+         * Assertions: getStateForUI returns null
+         */
         it('returns null for no state', function () {
             $post = Post::create(['title' => 'Test', 'state' => 'draft']);
             $post->setAttribute('state', null);
@@ -80,6 +105,11 @@
     });
 
     describe('getNextStatesForUI', function () {
+        /**
+         * Scenario: Model returns available transitions formatted for UI
+         * Setup: Create post in draft state (has transitions)
+         * Assertions: Array of next states with UI metadata (name, title, color, icon)
+         */
         it('returns next states for UI display', function () {
             $post = Post::create(['title' => 'Test', 'state' => 'draft']);
 
@@ -92,6 +122,11 @@
             expect($nextState)->toHaveKeys(['name', 'title', 'color', 'icon']);
         });
 
+        /**
+         * Scenario: Next states are filtered by user permissions
+         * Setup: Create admin user and draft post
+         * Assertions: Next states array respects user context
+         */
         it('accepts user context', function () {
             $user = new User(['id' => 1, 'role' => 'admin']);
             $post = Post::create(['title' => 'Test', 'state' => 'draft']);
@@ -101,6 +136,11 @@
             expect($nextStates)->toBeArray();
         });
 
+        /**
+         * Scenario: Terminal states return no available transitions
+         * Setup: Create post in published state (terminal state with no outgoing transitions)
+         * Assertions: Empty array returned
+         */
         it('returns empty array when no transitions available', function () {
             // Published has no outgoing transitions
             $post = Post::create(['title' => 'Test', 'state' => 'published']);

tests/Feature/ApiResources/StateCollectionResourceTest.php

@@ -15,6 +15,11 @@
 });
 
 describe('StateCollectionResource', function () {
+    /**
+     * Scenario: Generate collection resource for all states of a model
+     * Setup: Use Post model class with configured states
+     * Assertions: Returns non-empty array of state resources
+     */
     it('creates collection for model class', function () {
         $request = Request::create('/');
         $resource = StateCollectionResource::forModel(Post::class);
@@ -25,6 +30,11 @@
         expect($array)->not->toBeEmpty();
     });
 
+    /**
+     * Scenario: Non-stateful models return empty collection
+     * Setup: Use User model which doesn't have state management
+     * Assertions: Returns empty array
+     */
     it('creates empty collection for non-stateable model', function () {
         $request = Request::create('/');
         $resource = StateCollectionResource::forModel(User::class);
@@ -35,6 +45,11 @@
         expect($array)->toBeEmpty();
     });
 
+    /**
+     * Scenario: Generate collection of available next states for a model instance
+     * Setup: Create draft post with configured transitions
+     * Assertions: Returns array with at least one next state
+     */
     it('creates collection for next states', function () {
         $post = Post::create(['title' => 'Test', 'state' => 'draft']);
         $request = Request::create('/');
@@ -46,6 +61,11 @@
         expect(count($array))->toBeGreaterThan(0);
     });
 
+    /**
+     * Scenario: Filter next states based on user permissions
+     * Setup: Create admin user and draft post
+     * Assertions: Collection respects user's permission context
+     */
     it('creates collection with user context', function () {
         $user = new User(['id' => 1, 'role' => 'admin']);
         $post = Post::create(['title' => 'Test', 'state' => 'draft']);
@@ -57,6 +77,11 @@
         expect($array)->toBeArray();
     });
 
+    /**
+     * Scenario: Return only essential state data to reduce API payload size
+     * Setup: Create draft post, request next states in minimal format
+     * Assertions: Array items contain only name and title, no color or metadata
+     */
     it('supports minimal format', function () {
         $post = Post::create(['title' => 'Test', 'state' => 'draft']);
         $request = Request::create('/');
@@ -70,6 +95,11 @@
         }
     });
 
+    /**
+     * Scenario: Return UI-optimized state data with visual metadata but without transition flags
+     * Setup: Create draft post, request next states in UI format
+     * Assertions: Items include name, title, color, icon, description but exclude is_current/can_transition_to
+     */
     it('supports ui format', function () {
         $post = Post::create(['title' => 'Test', 'state' => 'draft']);
         $request = Request::create('/');
@@ -83,6 +113,11 @@
         }
     });
 
+    /**
+     * Scenario: Return complete state data including all metadata and transition capabilities
+     * Setup: Create draft post, request next states in full format
+     * Assertions: Items contain all fields including is_default, is_current, can_transition_to
+     */
     it('supports full format', function () {
         $post = Post::create(['title' => 'Test', 'state' => 'draft']);
         $request = Request::create('/');
@@ -102,6 +137,11 @@
         }
     });
 
+    /**
+     * Scenario: Provide model context to collection so it can mark the current state correctly
+     * Setup: Create post in draft state, build collection with Draft and Review states
+     * Assertions: Draft state is marked as is_current=true since post is in draft
+     */
     it('sets model context with withModel', function () {
         $post = Post::create(['title' => 'Test', 'state' => 'draft']);
         $request = Request::create('/');
@@ -116,6 +156,11 @@
         expect($draftItem['is_current'])->toBeTrue();
     });
 
+    /**
+     * Scenario: Pass user context to enable permission-based filtering of available states
+     * Setup: Create admin user and draft post, build Review state collection with user context
+     * Assertions: Collection is successfully built with user permission context applied
+     */
     it('sets user context with withUser', function () {
         $user = new User(['id' => 1, 'role' => 'admin']);
         $post = Post::create(['title' => 'Test', 'state' => 'draft']);
@@ -130,6 +175,11 @@
         expect($array)->toBeArray();
     });
 
+    /**
+     * Scenario: Get complete list of all possible states for a given model type
+     * Setup: Use Post model class which has draft, review, published, rejected states
+     * Assertions: Returned array contains all configured state names for Post model
+     */
     it('returns states for model from all states', function () {
         $request = Request::create('/');
         $resource = StateCollectionResource::forModel(Post::class);

tests/Feature/ApiResources/StateResourceTest.php

@@ -20,6 +20,11 @@
 // -----------------------------------------------------------------------------
 
 describe('StateResourceData', function () {
+    /**
+     * Scenario: Create a data transfer object from a state class to prepare for serialization
+     * Setup: Use Draft state class which has name, title, color, and is marked as default
+     * Assertions: DTO properties match state class metadata including default state flag
+     */
     it('creates from state class with basic properties', function () {
         $data = StateResourceData::fromStateClass(Draft::class);
 
@@ -29,6 +34,11 @@
         expect($data->isDefault)->toBeTrue();
     });
 
+    /**
+     * Scenario: Serialize DTO to complete array structure for full API responses
+     * Setup: Create DTO from Draft state
+     * Assertions: Array includes all 9 keys: identification, visual metadata, state flags, and additional data
+     */
     it('converts to full array', function () {
         $data = StateResourceData::fromStateClass(Draft::class);
         $array = $data->toArray();
@@ -49,6 +59,11 @@
         expect($array['is_default'])->toBeTrue();
     });
 
+    /**
+     * Scenario: Serialize to minimal format containing only identifier and human-readable name
+     * Setup: Create DTO from Draft state
+     * Assertions: Only name and title present; no visual or flag metadata to minimize payload
+     */
     it('converts to minimal array', function () {
         $data = StateResourceData::fromStateClass(Draft::class);
         $array = $data->toMinimal();
@@ -58,6 +73,11 @@
         expect($array)->not->toHaveKey('is_default');
     });
 
+    /**
+     * Scenario: Serialize to UI format with visual metadata for rendering but without business logic flags
+     * Setup: Create DTO from Draft state
+     * Assertions: Includes UI elements (color, icon, description) but excludes is_default and is_current
+     */
     it('converts to UI array', function () {
         $data = StateResourceData::fromStateClass(Draft::class);
         $array = $data->toUI();
@@ -77,6 +97,11 @@
         expect($reviewData->isCurrent)->toBeFalse();
     });
 
+    /**
+     * Scenario: Check if a state is reachable from model's current state via allowed transitions
+     * Setup: Create draft post, generate DTOs for Draft (current) and Review (next) states
+     * Assertions: Can't transition to current state (Draft), can transition to allowed next state (Review)
+     */
     it('detects can transition to with model context', function () {
         $post = Post::create(['title' => 'Test', 'state' => 'draft']);