A handshake

Run a process with multiple actors and actions.

In the previous tutorial, we created and tested our first scenario. In that scenario, we didn't define any actors. In this tutorial, we explicitly define multiple actors to participate in the process.

Defining actors

Each actor plays a specific role in the scenario. We'll tie the actor to a particular user (or team) when creating the process. We define two actors for the handshake 'initiator' and 'recipient' and give each actor a title.

Create file handshake.yaml (or handshake.json) in the scenarios directory.

YAML

handshake.yaml

actors:
  initiator:
    title: Initiator
  recipient:
    title: Recipient

states:
  initial:
    on: complete
    goto: (success)

JSON

handshake.json

{
    "actors": {
        "initiator": {
            "title": "Initiator"
        },
        "recipient": {
            "title": "Recipient"
        }
    },
    "states": {
        "initial": {
            "on": "complete",
            "goto": "(success)"
        }
    }
}

Greeting each other

We want the two actors to interact in the form of a simple greeting:

Initiator: Hi, how are you? Recipient: Fine. How about you? Initiator: Fine

The initiator will still complete the process, but from the initial state, it will first do a greeting, expecting a reply. We'll add these 2 states where these can be performed. First, the initiator waits on the recipient and then visa versa.

We use the by property to specify which actor can perform the action in that state.

Scenario

YAML

handshake.yaml

actors:
  initiator:
    title: Initiator
  recipient:
    title: Recipient

states:
  initial:
    on: greet
    by: initiator
    goto: wait_on_recipient
  wait_on_recipient:
    on: reply
    by: recipient
    goto: wait_on_initiator
  wait_on_initiator:
    on: complete
    goto: (success)

JSON

{
    "schema": "https://specs.letsflow.io/v0.3.0/scenario",
    "title": "Basic user",
    "actors": {
        "initiator": {
            "title": "Initiator"
        },
        "recipient": {
            "title": "Recipient"
        }
    },
    "actions": {
        "greet": {
            "title": "Greet the recipient",
            "actor": "initiator"
        },
        "reply": {
            "title": "Reply to the greeting",
            "actor": "recipient"
        },
        "complete": {
            "title": "Finish the conversation",
            "actor": "initiator"
        }
    },
    "states": {
        "initial": {
            "on": "greet",
            "goto": "wait_on_recipient"
        },
        "wait_on_recipient": {
            "on": "reply",
            "goto": "wait_on_initiator"
        },
        "wait_on_initiator": {
            "on": "complete",
            "goto": "(success)"
        }
    }
}

We see that we transition from the "initial" state to "wait_on_recipient", then wait on "initiator" and finally to successful completion of the process.

Test case

Create file handshake.feature in the features directory.

handshake.feature

Feature: Two actors greet each other

  Background:
    Given the process is created from the "handshake" scenario
    And "Bob" is the "initiator" actor
    And "Eve" is the "recipient" actor

  Scenario:
    When "Bob" does "greet"
    Then the process is in "wait_on_recipient"
    When "Eve" does "reply"
    Then the process is in "wait_on_initiator"
    When "Bob" does "complete"
    Then the process ended

Choose to ignore

Let's give the recipient a choice to either reply or ignore the greeting. If he chooses to ignore the greeting the process will have failed.

Scenario

For the "wait_on_recipient" state we define two transitions. Both can only be performed by the "recipient" actor.

YAML

handshake.yaml

actors:
  initiator:
    title: Initiator
  recipient:
    title: Recipient

states:
  initial:
    on: greet
    by: initiator
    goto: wait_on_recipient
  wait_on_recipient:
    transitions:
      - on: reply
        by: recipient
        goto: wait_on_initiator
      - on: ignore
        by: recipient
        goto: (failed)
  wait_on_initiator:
    on: complete
    by: initiator
    goto: (success)

JSON

handshake.json

{
    "actors": {
        "initiator": {
            "title": "Initiator"
        },
        "recipient": {
            "title": "Recipient"
        }
    },
    "states": {
        "initial": {
            "on": "greet",
            "by": "initiator",
            "goto": "wait_on_recipient"
        },
        "wait_on_recipient": {
            "transitions": [
                {
                    "on": "reply",
                    "by": "recipient",
                    "goto": "wait_on_initiator"
                },
                {
                    "on": "ignore",
                    "by": "recipient",
                    "goto": "(cancelled)"
                }
            ]
        },
        "wait_on_initiator": {
            "on": "complete",
            "by": "recipient",
            "goto": "(success)"
        }
    }
}

Test case

We can add a new Scenario section in our test file to test the path in the process where the recipient "Jane" ignores the greeting.

handshake.feature

Feature: Two actors greet each other

  Background:
    Given the process is created from the "handshake" scenario
    And "Bob" is the "initiator" actor
    And "Eve" is the "recipient" actor

  Scenario:
    When "Bob" does "greet"
    Then the process is in "wait_on_recipient"
    When "Eve" does "reply"
    Then the process is in "wait_on_initiator"
    When "Bob" does "complete"
    Then the process ended in "success"

  Scenario:
    When "Bob" does "greet"
    Then the process is in "wait_on_recipient"
    When "Eve" does "ignore"
    Then the process ended in "failed"

You can have multiple Scenario sections. The Background is run before each Scenario.