✅ test: Add comprehensive test suite for RegionBuilder functionality.

Author: Biont

docs/README.md

@@ -50,12 +50,16 @@ This trivial example shows how a product may move through various states during
 
 require 'vendor/autoload.php';
 
+use Noem\State\Feature\Transitions\AddTransition;
+use Noem\State\Feature\Transitions\TransitionsFeature;
 use Noem\State\RegionBuilder;
 
 $orderId = 12345;
 
 // Define the state machine
 $region = (new RegionBuilder())
+    // Enable the transitions feature
+    ->enableFeatures(new TransitionsFeature())
     // State configuration
     ->setStates('Checkout', 'Pending', 'Processing', 'Shipped', 'Delivered')
     ->markInitial('Checkout')
@@ -66,10 +70,10 @@ $region = (new RegionBuilder())
 
     // Transitions
     // In a real application, these inspect the $trigger and allow/deny the transition based on it
-    ->pushTransition(from: 'Checkout', to: 'Pending', guard: fn(object $trigger): bool => true)
-    ->pushTransition(from: 'Pending', to: 'Processing', guard: fn(object $trigger): bool => true)
-    ->pushTransition(from: 'Processing', to: 'Shipped', guard: fn(object $trigger): bool => true)
-    ->pushTransition(from: 'Shipped', to: 'Delivered', guard: fn(object $trigger): bool => true)
+    ->addBuildStep(new AddTransition(from: 'Checkout', to: 'Pending', guard: fn(object $trigger): bool => true))
+    ->addBuildStep(new AddTransition(from: 'Pending', to: 'Processing', guard: fn(object $trigger): bool => true))
+    ->addBuildStep(new AddTransition(from: 'Processing', to: 'Shipped', guard: fn(object $trigger): bool => true))
+    ->addBuildStep(new AddTransition(from: 'Shipped', to: 'Delivered', guard: fn(object $trigger): bool => true))
 
     // Entry events
     ->onEnter(state: 'Pending', callback: function (object $trigger) {
@@ -108,9 +112,13 @@ within a state machine, making it convenient for implementing stateful behavior
 
 declare(strict_types=1);
 
+use Noem\State\Feature\Transitions\AddTransition;
+use Noem\State\Feature\Transitions\TransitionsFeature;
 use Noem\State\RegionBuilder;
 
 $r = (new RegionBuilder())
+        // Enable the transitions feature
+        ->enableFeatures(new TransitionsFeature())
         // Define all possible states
         ->setStates('off', 'starting', 'on', 'error')
         // if not called, will default to the first entry
@@ -119,13 +127,13 @@ $r = (new RegionBuilder())
         ->markFinal('error')
         // Define a transition from one state to another
         // <FROM> <TO> <PREDICATE>
-        ->pushTransition('off', 'starting', fn(object $trigger):bool => true)
+        ->addBuildStep(new AddTransition('off', 'starting', fn(object $trigger):bool => true))
         // no predicate means always true 
-        ->pushTransition('starting', 'on') 
-        ->pushTransition('on', 'error', function(\Throwable $exception){
+        ->addBuildStep(new AddTransition('starting', 'on'))
+        ->addBuildStep(new AddTransition('on', 'error', function(\Throwable $exception){
             echo 'Error: '. $exception->getMessage();
             return true;
-        })
+        }))
         // Add a callback that runs whenever the specified state is entered
         ->onEnter('starting', function(object $trigger){
             echo 'Starting application';
@@ -161,11 +169,12 @@ This means you can -for example- only allow a transition when an Exception occur
 
 ```php
 $r = new RegionBuilder();
-$r->setStates('on', 'running', 'error')
-    ->pushTransition('on', 'error', function(\Throwable $exception){
+$r->enableFeatures(new TransitionsFeature())
+    ->setStates('on', 'running', 'error')
+    ->addBuildStep(new AddTransition('on', 'error', function(\Throwable $exception){
         echo 'Error: '. $exception->getMessage();
         return true;
-    })
+    }))
 ;
 ```
 
@@ -174,8 +183,9 @@ and greatly helps serializing application state. The syntax is a little more com
 
 ```php
 $r = new RegionBuilder();
-$r->setStates('one', 'two', 'three')
-    ->pushTransition('one', 'two', fn(#[Name('hello-world')] Event $event): bool => true)
+$r->enableFeatures(new TransitionsFeature())
+    ->setStates('one', 'two', 'three')
+    ->addBuildStep(new AddTransition('one', 'two', fn(#[Name('hello-world')] Event $event): bool => true))
 ;
 ```
 Here, the `Name` attribute works in tandem with the internal `Event` interface that mandates a name.
@@ -261,8 +271,9 @@ $middleware = function (RegionBuilder $builder, \Closure $next) use (&$logs) {
 };
 
 $region = (new RegionBuilder())
+    ->enableFeatures(new TransitionsFeature())
     ->setStates('foo', 'bar')
-    ->pushTransition('foo', 'bar')
+    ->addBuildStep(new AddTransition('foo', 'bar'))
     ->pushMiddleware($middleware)
     ->build();
 ```

tests/PHPUnit/Integration/Feature/AsyncFeature/AsyncFeatureTest.php

@@ -10,6 +10,8 @@
 use Noem\State\Feature\ExtendedState\ExtendedState;
 use Noem\State\Feature\Template\Compiler\TemplateFactory;
 use Noem\State\Feature\Template\Helpers;
+use Noem\State\Feature\Transitions\AddTransition;
+use Noem\State\Feature\Transitions\TransitionsFeature;
 use Noem\State\Test\Integration\RegionBuilderTestCase;
 use PHPUnit\Framework\Attributes\Test;
 use PHPUnit\Framework\Attributes\TestDox;
@@ -21,7 +23,8 @@ public function setUp(): void
     {
         parent::setUp();
         $this->builder->enableFeatures(
-            new AsyncFeature()
+            new AsyncFeature(),
+            new TransitionsFeature()
         );
     }
 
@@ -192,9 +195,9 @@ public function resolver()
                 new ExtendedState()
             )
             ->setStates('one', 'two')
-            ->pushTransition('one', 'two', function (object $t): bool {
+            ->addBuildStep(new AddTransition('one', 'two', function (object $t): bool {
                 return $this->get('context') !== null;
-            })
+            }))
             ->onEnter('two', function (object $t) {
                 $t->out .= $this->get('context');
             })
@@ -243,10 +246,10 @@ public function resolveWithNestedContext()
                 new ExtendedState()
             )
             ->setStates('off', 'one', 'two')
-            ->pushTransition('off', 'one')
-            ->pushTransition('one', 'two', function (object $t): bool {
+            ->addBuildStep(new AddTransition('off', 'one'))
+            ->addBuildStep(new AddTransition('one', 'two', function (object $t): bool {
                 return $this->get('context') !== null;
-            })
+            }))
             ->onEnter('one', function (object $t) {
                 $this->set('dependency', 'waiting');
             })
@@ -368,9 +371,9 @@ public function testFetch()
                 $t->out .= '|END';
                 yield;
             })
-            ->pushTransition('one', 'two', function (object $t): bool {
+            ->addBuildStep(new AddTransition('one', 'two', function (object $t): bool {
                 return str_ends_with($t->out, 'END');
-            })
+            }))
             ->build();
 
         $payload = new \stdClass();

tests/PHPUnit/Integration/Feature/EventHooks/EventHooksTest.php

@@ -9,6 +9,7 @@
 use Noem\State\Feature\EventHooks\Hook\Before;
 use Noem\State\Feature\ExtendedState\ExtendedState;
 use Noem\State\Feature\NamedEvents\Event;
+use Noem\State\Feature\Transitions\AddTransition;
 use Noem\State\Test\Integration\RegionBuilderTestCase;
 use PHPUnit\Framework\Attributes\Test;
 use PHPUnit\Framework\Attributes\TestDox;
@@ -98,7 +99,7 @@ public function hooksCanCauseTransitions()
             /**
              * We register a transition caused by an After event hook
              */
-            ->pushTransition('one', 'two', #[After] fn(Event $t): bool => $guardSpy())
+            ->addBuildStep(new AddTransition('one', 'two', #[After] fn(Event $t): bool => $guardSpy()))
             ->onAction('two', #[After] function (Event $t) use (&$actual) {
                 $actual .= '/after';
             })

tests/PHPUnit/Integration/Feature/Loader/LoaderTest.php

@@ -13,6 +13,8 @@
 use Noem\State\Feature\Loader\RegionLoader;
 use Noem\State\Feature\Loader\RegionSpawnRegistry;
 use Noem\State\Feature\OrthogonalRegions\OrthogonalRegions;
+use Noem\State\Feature\Transitions\AddTransition;
+use Noem\State\Feature\Transitions\TransitionsFeature;
 use Noem\State\Middleware\ChainException;
 use Noem\State\Test\Integration\RegionBuilderTestCase;
 use PHPUnit\Framework\Attributes\Test;
@@ -31,7 +33,8 @@ public function setUp(): void
             new ExtendedState(),
             new OrthogonalRegions(),
             new AsyncFeature(),
-            new JsonSchemaFeature()
+            new JsonSchemaFeature(),
+            new TransitionsFeature()
         );
     }
 
@@ -63,13 +66,13 @@ public function spawnSubMachine()
                         ->builder
                         ->newInstance()
                         ->setStates('checking', 'check_complete')
-                        ->pushTransition(
+                        ->addBuildStep(new AddTransition(
                             'checking',
                             'check_complete',
                             function (object $t): bool {
                                 return $t->count >= 4;
                             }
-                        )
+                        ))
                         ->onEnter('check_complete', function (object $t) {
                             $this->get('foo');
                         })
@@ -82,7 +85,7 @@ function (object $t): bool {
         $region = $this
             ->builder
             ->setStates('off', 'on')
-            ->pushTransition('off', 'on')
+            ->addBuildStep(new AddTransition('off', 'on'))
             ->build();
         $this->assertRegionContext($region, 'html', null);
         $counter = 0;
@@ -111,16 +114,16 @@ public function spawnMultipleSubMachines()
                     ->builder
                     ->newInstance()
                     ->setStates('off', 'checking', 'check_complete')
-                    ->pushTransition('off', 'checking')
-                    ->pushTransition(
+                    ->addBuildStep(new AddTransition('off', 'checking'))
+                    ->addBuildStep(new AddTransition(
                         'checking',
                         'check_complete',
                         function (object $t): bool {
                             $count = $this->get('count');
 
                             return $count >= 10;
                         }
-                    )
+                    ))
                     ->onEnter('checking', function (object $t) {
                         $count = (int)$this->get('count');
 
@@ -137,7 +140,7 @@ function (object $t): bool {
         $region = $this
             ->builder
             ->setStates('off', 'on')
-            ->pushTransition('off', 'on')
+            ->addBuildStep(new AddTransition('off', 'on'))
             ->build();
         $this->assertRegionContext($region, 'html', null);
         $counter = 0;

tests/PHPUnit/Unit/Core/RegionBuilder/AddBuildStepTest.php

@@ -0,0 +1,92 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Noem\State\Test\Unit\Core\RegionBuilder;
+
+use Noem\State\BuildStep;
+use Noem\State\Region;
+use Noem\State\RegionBuilder;
+use PHPUnit\Framework\Attributes\Group;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * Acceptance Criterion: A builder can add custom build steps using addBuildStep with BuildStep interface
+ */
+#[Group('region-builder')]
+#[Group('build-steps')]
+class AddBuildStepTest extends TestCase
+{
+    public function testAddBuildStepAcceptsBuildStepInterface(): void
+    {
+        $builder = new RegionBuilder();
+        $builder->setStates('idle');
+        
+        $buildStep = new class implements BuildStep {
+            public function callback(RegionBuilder $builder, callable $next, callable $first): Region
+            {
+                return $next($builder);
+            }
+        };
+        
+        $result = $builder->addBuildStep($buildStep);
+        
+        $this->assertSame($builder, $result, 'addBuildStep should return builder for chaining');
+        
+        $region = $builder->build();
+        $this->assertInstanceOf(Region::class, $region);
+    }
+    
+    public function testAddBuildStepCanBeCalledMultipleTimes(): void
+    {
+        $builder = new RegionBuilder();
+        $builder->setStates('idle');
+        
+        $stepOne = new class implements BuildStep {
+            public function callback(RegionBuilder $builder, callable $next, callable $first): Region
+            {
+                return $next($builder);
+            }
+        };
+        
+        $stepTwo = new class implements BuildStep {
+            public function callback(RegionBuilder $builder, callable $next, callable $first): Region
+            {
+                return $next($builder);
+            }
+        };
+        
+        $builder->addBuildStep($stepOne)
+                ->addBuildStep($stepTwo);
+        
+        $region = $builder->build();
+        $this->assertInstanceOf(Region::class, $region);
+    }
+    
+    public function testBuildStepIsInvokedDuringBuild(): void
+    {
+        $builder = new RegionBuilder();
+        $builder->setStates('idle');
+        
+        $stepInvoked = false;
+        
+        $buildStep = new class($stepInvoked) implements BuildStep {
+            public function __construct(private bool &$invoked) {}
+            
+            public function callback(RegionBuilder $builder, callable $next, callable $first): Region
+            {
+                $this->invoked = true;
+                return $next($builder);
+            }
+        };
+        
+        $builder->addBuildStep($buildStep);
+        
+        $this->assertFalse($stepInvoked, 'Build step should not be invoked before build()');
+        
+        $region = $builder->build();
+        
+        $this->assertTrue($stepInvoked, 'Build step should be invoked during build()');
+        $this->assertInstanceOf(Region::class, $region);
+    }
+}

tests/PHPUnit/Unit/Core/RegionBuilder/AddStateTest.php

@@ -0,0 +1,55 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Noem\State\Test\Unit\Core\RegionBuilder;
+
+use Noem\State\RegionBuilder;
+use PHPUnit\Framework\Attributes\Group;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * Acceptance Criterion: A builder can add individual states using addState
+ */
+#[Group('region-builder')]
+#[Group('state-configuration')]
+class AddStateTest extends TestCase
+{
+    public function testAddStateSingleState(): void
+    {
+        $builder = new RegionBuilder();
+        
+        $result = $builder->addState('initial');
+        
+        $this->assertSame($builder, $result, 'addState should return builder for chaining');
+        
+        $region = $builder->build();
+        
+        $this->assertTrue($region->isInState('initial'));
+    }
+    
+    public function testAddStateMultipleTimes(): void
+    {
+        $builder = new RegionBuilder();
+        
+        $builder->addState('first')
+                ->addState('second')
+                ->addState('third');
+        
+        $region = $builder->build();
+        
+        $this->assertTrue($region->isInState('first'), 'Region should start in first added state');
+    }
+    
+    public function testAddStateCanBeMixedWithSetStates(): void
+    {
+        $builder = new RegionBuilder();
+        
+        $builder->setStates('one', 'two')
+                ->addState('three');
+        
+        $region = $builder->build();
+        
+        $this->assertTrue($region->isInState('one'));
+    }
+}