further tests implemented, updated documentation, Machine::runOnce() added

Author: coff

CHANGELOG.md

@@ -0,0 +1,27 @@
+# CHANGELOG
+
+## dev-master
+
+- `MachineTest`: more detailed tests implemented 
+- added installation procedure to README.md  
+- added `MachineInterface::runOnce()` and `Machine::runOnce()` to allow just one pass over possible transitions
+- started actual CHANGELOG.md
+- small fix for example used in documentation (missing `$machine->init()` call)
+- implemented tests for assertion classes
+- updated and extended documentation (README.md)
+
+## v0.3
+
+- README.md updated
+- created CODE_OF_CONDUCT.md
+- created CONTRIBUTING.md
+
+## v0.2
+
+- defined php version requirements
+- fixed `Machine::setMachineState()` behavior with exactly same state given in param
+- implemented basic tests
+
+## v0.1
+
+- basic functionality and architecture implementation, first working version

README.md

@@ -7,6 +7,23 @@ dynamically and launch. You can define state transition conditions you want base
 anonymous functions or class methods. Fire events on each state transition with your favorite
 event dispatcher.
 
+## Installation
+
+Easiest way is to use composer:
+
+```bash
+$ composer require coff/state-machine-framework
+```
+
+Alternatively just clone repository:
+```bash
+$ git clone https://github.com/coff/php-state-machine-framework.git
+```
+
+and then checkout specific tag:
+```bash
+$ git checkout tags/v0.3
+```
 
 ## Usage example
 

src/Machine.php

@@ -214,30 +214,42 @@ public function assertTransition(Transition $transition): bool
      */
     public function run()
     {
-
         do {
-            $result = false;
+            $result = $this->runOnce();
+
+        } while (true == $result);
+
+        return $this->machineState;
+    }
+
+    /**
+     * Makes one pass through transitions available in current state
+     *
+     * @return boolean
+     * @throws TransitionException
+     */
+    public function runOnce(): bool
+    {
+        $result = false;
 
-            $allowedTrans = $this->getAllowedTransitions();
+        $allowedTrans = $this->getAllowedTransitions();
 
-            /**
-             * @var StateEnum $nextState
-             * @var Transition $transition
-             */
-            foreach ($allowedTrans as $nextState => $transition) {
+        /**
+         * @var StateEnum $nextState
+         * @var Transition $transition
+         */
+        foreach ($allowedTrans as $nextState => $transition) {
 
-                $result = $transition->assert();
+            $result = $transition->assert();
 
-                if (true === $result) {
-                    $this->machineState = $transition->getToState();
+            if (true === $result) {
+                $this->machineState = $transition->getToState();
 
-                    $this->onTransition($transition);
-                }
+                $this->onTransition($transition);
             }
+        }
 
-        } while (true == $result);
-
-        return $this->machineState;
+        return $result;
     }
 
     /**

src/MachineInterface.php

@@ -2,6 +2,7 @@
 
 namespace Coff\SMF;
 
+use Coff\SMF\Exception\TransitionException;
 use Coff\SMF\Transition\Transition;
 
 interface MachineInterface
@@ -48,8 +49,15 @@ public function onTransition(Transition $transition);
 
     /**
      * Runs state machine. Performs assertions for all transitions defined for current state.
-     * @return mixed
      */
     public function run();
 
+    /**
+     * Makes one pass through transitions available in current state, makes assertions and eventually changes state
+     *
+     * @return boolean
+     * @throws TransitionException
+     */
+    public function runOnce(): bool;
+
 }

tests/MachineTest.php

@@ -168,14 +168,29 @@ public function test_isTransitionAllowed_same()
      * @depends test_setInitState
      * @depends test_allowTransition
      * @throws TransitionException
+     * @throws MachineException
      */
     public function test_run_automatic_transition_through_n_states_succ()
     {
+        $this->machine = $this->createPartialMock(SampleMachine::class, ['onTransition']);
+
         $this->machine->setInitState($this->x);
 
         $this->machine->allowTransition($this->x, $this->y, new AlwaysTrueAssertion());
         $this->machine->allowTransition($this->y, $this->z, new AlwaysTrueAssertion());
 
+
+        $transition1 = $this->machine->getTransition($this->x, $this->y);
+        $transition2 = $this->machine->getTransition($this->y, $this->z);
+
+        $this->machine->expects($this->at(0))
+            ->method('onTransition')
+            ->with($this->equalTo($transition1));
+
+        $this->machine->expects($this->at(1))
+            ->method('onTransition')
+            ->with($this->equalTo($transition2));
+
         $this->machine->run();
 
         $this->assertTrue($this->machine->isMachineState($this->z));
@@ -186,14 +201,51 @@ public function test_run_automatic_transition_through_n_states_succ()
      * @depends test_setInitState
      * @depends test_allowTransition
      * @throws TransitionException
+     * @throws MachineException
+     */
+    public function test_runOnce_automatic_transition_through_1_state_succ()
+    {
+        $this->machine = $this->createPartialMock(SampleMachine::class, ['onTransition']);
+
+        $this->machine->setInitState($this->x);
+
+        $this->machine->allowTransition($this->x, $this->y, new AlwaysTrueAssertion());
+        $this->machine->allowTransition($this->y, $this->z, new AlwaysTrueAssertion());
+
+        $transition = $this->machine->getTransition($this->x, $this->y);
+
+        $this->machine->expects($this->once())
+            ->method('onTransition')
+            ->with($this->equalTo($transition));
+
+
+        $this->machine->runOnce();
+
+        $this->assertTrue($this->machine->isMachineState($this->y));
+
+    }
+
+    /**
+     * @depends test_setInitState
+     * @depends test_allowTransition
+     * @throws TransitionException
+     * @throws MachineException
      */
     public function test_run_automatic_transition_through_n_states_stops()
     {
+        $this->machine = $this->createPartialMock(SampleMachine::class, ['onTransition']);
+
         $this->machine->setInitState($this->x);
 
         $this->machine->allowTransition($this->x, $this->y, new AlwaysTrueAssertion());
         $this->machine->allowTransition($this->y, $this->z, new AlwaysFalseAssertion());
 
+        $transition1 = $this->machine->getTransition($this->x, $this->y);
+
+        $this->machine->expects($this->once())
+            ->method('onTransition')
+            ->with($this->equalTo($transition1));
+
         $this->machine->run();
 
         $this->assertFalse($this->machine->isMachineState($this->z));