update docs

Author: rodber

packages/workflow.md

@@ -54,7 +54,7 @@ To create a Workflow define its named Jobs.
 
 A [Job](#creating-job) is created by passing an [Action](https://chevere.org/packages/action) and its *expected* run arguments which can be raw values,  [Variables](#variable) and/or [Responses](#response) to another job's output.
 
-The syntax for writing Workflow jobs require `name` for job's name, `sync/async` depending on job run method, and named `parameter` bding for each Action run parameter.
+The syntax for writing Workflow jobs require `name` for job's name, `sync/async` depending on job run method, and named `parameter` binding for each `Action::main` parameter.
 
 ```plain
 <name>: <sync|async>(
@@ -77,7 +77,7 @@ class MyAction extends Action
 }
 ```
 
-You would be able to write Workflows like this:
+You will be able to write a Workflow like this:
 
 ```php
 use function Chevere\Workflow\sync;
@@ -127,12 +127,18 @@ workflow(
 ```
 
 * `variable('payload')` and `variable('file')` declares a [Variable](#variable).
-* `response('meta', 'name')` and `reference('user')` declares a [Response](#response) reference.
+* `response('meta', 'name')` and `response('user')` declares a [Response](#response) reference.
 
 The graph for this Workflow says that all jobs run one after each other as all jobs are defined using `sync`.
 
+```mermaid
+graph TD;
+    user-->validate-->meta-->store;
+```
+
 ```php
-//$workflow->jobs()->graph()->toArray();
+$workflow->jobs()->graph()->toArray();
+// contains
 [
     ['user'],
     ['validate'],
@@ -155,7 +161,7 @@ run(
 
 ### With asynchronous jobs
 
-Use function `async` to create an asynchronous job, which runs in parallel non-blocking.
+Use function `async` to create an asynchronous job, which runs non-blocking.
 
 In the example below a Workflow describes an image creation procedure for multiple image sizes.
 
@@ -190,10 +196,18 @@ workflow(
 * `variable('image')` declares a [Variable](#variable).
 * `response('thumb', 'filename')` and `response('medium', 'filename')` declares a [Response](#response) reference.
 
-The graph for this Workflow says that `thumb` and `medium` run non-blocking. Job `store` runs blocking (another node).
+The graph for this Workflow says that `thumb`, `medium` and `poster` run non-blocking in parallel. Job `store` runs blocking (another node).
+
+```mermaid
+graph TD;
+    thumb-->store;
+    medium-->store;
+    poster-->store;
+```
 
 ```php
-//$workflow->jobs()->graph()->toArray();
+$workflow->jobs()->graph()->toArray();
+// contains
 [
     ['thumb', 'medium', 'poster'],
     ['store']
@@ -282,7 +296,7 @@ sync(
 );
 ```
 
-For the code above, argument `context` will be passed "as-is" (`public`) to `SomeAction`, arguments `role` and `userId` will be dynamic provided. When running the Workflow these arguments will be matched against the Parameters defined at the [run](https://chevere.org/packages/action#run) method for `SomeAction`.
+For the code above, argument `context` will be passed "as-is" (`public`) to `SomeAction`, arguments `role` and `userId` will be dynamic provided. When running the Workflow these arguments will be matched against the Parameters defined at the [main method](https://chevere.org/packages/action#mai-method) for `SomeAction`.
 
 ### Conditional running
 
@@ -295,7 +309,7 @@ sync(
 )
     ->withRunIf(
         variable('compressImage'),
-        reference('SomeAction', 'doImageCompress')
+        response('SomeAction', 'doImageCompress')
     )
 ```
 
@@ -326,144 +340,55 @@ Use `getResponse` to retrieve a job response as a `CastArgument` object which ca
 $string = $run->getResponse('myJob')->string();
 ```
 
-## Code Examples
+## Demo
 
-### Hello, world
+See the [demo](https://github.com/chevere/workflow/tree/1.0/demo) directory for a set of examples.
 
-Run live example: `php demo/hello-world.php Rodolfo` - [view source](https://github.com/chevere/workflow/blob/0.9/demo/hello-world.php)
+## Debugging
 
-The basic example Workflow defines a greet for a given username. The job `greet` is a named argument and it takes the `GreetAction` plus its run [arguments](https://chevere.org/packages/action#run).
+When working with this package you may want to debug the Workflow to ensure that the jobs are declared as expected.
 
-```php
-use Chevere\Demo\Actions\Greet;
-use function Chevere\Workflow\run;
-use function Chevere\Workflow\sync;
-use function Chevere\Workflow\variable;
-use function Chevere\Workflow\workflow;
-
-$workflow = workflow(
-    greet: sync(
-        new Greet(),
-        username: variable('username'),
-    ),
-);
-```
-
-Use function `run` to run the Workflow, variables are passed as named arguments.
+To debug a Workflow inspect the Jobs graph. It will show the job names and their dependencies for each execution level.
 
 ```php
-$run = run(
-    $workflow,
-    username: 'MyUsername'
-);
+$workflow->jobs()->graph()->toArray();
+[
+    ['job1', 'job2'], // 1st level
+    ['job3', 'job4'], // 2nd level
+    ['job5'],         // 3rd level
+];
 ```
 
-### Async example
-
-Run live example: `php demo/image-resize.php` - [view source](https://github.com/chevere/workflow/blob/0.9/demo/image-resize.php)
+For each level jobs will run in parallel, but the next level will run after the previous level gets resolved.
 
-For this example Workflow defines an image resize procedure in two sizes. All jobs are defined as async, but as there are dependencies between jobs (see `variable` and `response`) the system resolves a suitable run strategy.
+> [!NOTE]
+> For runtime debugging is strongly recommended to use a non-blocking debugger like [xrDebug](https://xrdebug.com).
 
-```php
-use Chevere\Demo\Actions\ImageResize;
-use Chevere\Demo\Actions\StoreFile;
-use function Chevere\Workflow\async;
-use function Chevere\Workflow\response;
-use function Chevere\Workflow\run;
-use function Chevere\Workflow\variable;
-use function Chevere\Workflow\workflow;
+## Testing
 
-$workflow = workflow(
-    thumb: async(
-        new ImageResize(),
-        file: variable('image'),
-        fit: 'thumbnail',
-    ),
-    poster: async(
-        new ImageResize(),
-        file: variable('image'),
-        fit: 'poster',
-    ),
-    storeThumb: async(
-        new StoreFile(),
-        file: response('thumb'),
-        path: variable('savePath'),
-    ),
-    storePoster: async(
-        new StoreFile(),
-        file: response('poster'),
-        path: variable('savePath'),
-    )
-);
-```
+Workflow checks on variables, references and any other configuration so you don't have to worry about that.
 
-The graph for the Workflow above shows that `thumb` and `poster` run async, just like `storeThumb` and `storePoster` but the storage jobs run after the first dependency level gets resolved.
+Testing the Workflow itself is not necessary as it's just a configuration. What you need to test is the Workflow definition and their Jobs (Actions).
 
-```mermaid
-graph TD;
-    thumb-->storeThumb;
-    poster-->storePoster;
-```
+### Testing Workflow
 
-Use function `run` to run the Workflow, variables are passed as named arguments.
+For testing a Workflow what you need to assert is the expected Workflow graph (execution order).
 
 ```php
-use function Chevere\Workflow\run;
-
-$run = run(
-    $workflow,
-    image: '/path/to/image-to-upload.png',
-    savePath: '/path/to/storage/'
+assertSame(
+    $expectedGraph,
+    $workflow->jobs()->graph()->toArray()
 );
-
-// Alternative syntax
-$variables = [
-    'image' => '/path/to/image-to-upload.png',
-    'savePath' => '/path/to/storage/'
-];
-$run = run($workflow, ...$variables);
 ```
 
-Use `getReturn` to retrieve a job response as a `CastArgument` object which can be used to get a typed response.
-
-```php
-$thumbFile = $run->getReturn('thumb')->string();
-```
+### Testing Job
 
-### Conditional jobs
-
-Run live example: `php demo/run-if.php` - [view source](https://github.com/chevere/workflow/blob/0.9/demo/run-if.php)
-
-For this example Workflow defines a greet for a given username, but only if a `sayHello` variable is set to `true`.
+For testing a Job what you need to test is the Action that defines that given Job against the response from the Action `main` method.
 
 ```php
-use Chevere\Demo\Actions\Greet;
-use function Chevere\Workflow\run;
-use function Chevere\Workflow\sync;
-use function Chevere\Workflow\variable;
-use function Chevere\Workflow\workflow;
-
-/*
-php demo/run-if.php Rodolfo
-php demo/run-if.php
-*/
-
-$workflow = workflow(
-    greet: sync(
-        new Greet(),
-        username: variable('username'),
-    )->withRunIf(
-        variable('sayHello')
-    ),
+$action = new MyAction();
+assertSame(
+    $expected,
+    $action->main(...$arguments)
 );
 ```
-
-Method `withRunIf` accepts one or more `variable` and `response` references. All conditions must be true at the same time for the job to run.
-
-## Debugging Workflow
-
-To debug a Workflow inspect the Jobs graph. It will show the job names and their dependencies for each execution level.
-
-```php
-$workflow->jobs()->graph()->toArray();
-```