Different spec that supports full GivenWhenThen syntax

[stefanooldeman]

The current structure in which a scenario can be written has some limitations
See examples/scenarios/v2.yaml.

In more detail:

1. Only one simulate and validate schema object per scenario.
2. Both simulate/validate schema are linked to one adapter: broker/kafka or requests/http. As a result of this, we cannot validate against data from two different systems within the same resultset (one scenario should be atomic and result in a pass or fail).
3. A side effect: the reporter cannot print errors with descriptive texts. Only the failed assertions for a simulate or validate object.

Also in discussion with Wouter:
The default verbosity should still be descriptive enough to pinpoint issues to a misbehaving component, or otherwise said; a requirement on the architecture under test.

The aim is to add schema properties under simulate and validate. And preferably to allow a scenario to be written with BDD vocabulary taken from Given-When-Then.

Given-When-Then is a style of representing tests - or as its advocates would say - specifying a system's behavior using SpecificationByExample. see Martin Fowler blog

Let's look at an example that should be possible within pyrandall:

Feature: catalog change events leads to manipulating the nr of items in stock
 Scenario:  A product sale event decrements the stock by one
    Given: product {xyz} has 5 items in stock 
      And: product {foo} has 10 items in stock
    When: a sale event with id {xyz} is processed
    Then: the stock of product {xyz} is 4
      And: the stock of product {foo} is 10

Based on this I wrote two examples that we could implement:

Example 1:

version: example-1/v1
feature: catalog change events leads to manipulating the nr of items in stock
scenarios:
  - scenario: "A product sale event decrements the stock by one"
    given-state:
      # the given property can describe the initial state for an application
      # dummy date should be populated as a result of it)
      - description: "product {xyz} has 5 items in stock"
          properties: {}
    when-simulate:  # previously _simulate_ holds one object, now a list
      - that: "a sale event with id {xyz}"
          adapter: broker/kafka
    then-validate: # previously _validate_ also becomes a list
      - that: "the stock of product {xyz} is 4
         adapter: requests/http

Example 2:

version: example-1/v1
feature: catalog change events leads to manipulating the nr of items in stock
scenarios:
  - scenario: "A product sale event decrements the stock by one"
    given:
      # the given property can describe the initial state for an application
      # dummy date should be populated as a result of it)
      - description: "product {xyz} has 5 items in stock"
        properties: {}
    when:  # previously _simulate_ holds one object, now a list
      - simulate: "a sale event with id {xyz}"
        adapter: broker/kafka
      - simulate: "a sale event with id {xyz}"
        adapter: requests/http
    then: # previously _validate_ also beomes a list
      - validate: "the stock of product {xyz} is 4"
        adapter: requests/http
      - validate: "the stock of product {xyz} is 4"
        adapter: requests/http

It would be good for the project to become stable and keep compatibility with schema scenario/v2. Therefore, pyrandall can introduce a new schema and parse this.

Constraint: a new parser implementation can be based on pyrandall/spec.py and should provide the same interface to pyrandall/commander.py. This does not exclude refactoring to the existing classes to refine the interface.

Related to this is how ScalaTest supports different ways of writing tests.
Based on this I suggest introducing a new version: "featurespec/v1" instead of version: scenario/v3.

Please leave a comment to vote on example 1 or 2 and suggest a name for the new schema.