TypeDBClient roadmap

[mkschulze]

Assessment for Grakn client implementation

Summary of Gherkins features

credits for this sum up go to @tk3369

The following Gherkins keywords are found at the official Cucumber site. Features supported by ExecutableSpecifications.jl are checked accordingly.

Issue references

• Lenient parser: Allow linebreaks between steps #41 Lenient parser: Allow linebreaks between steps
• Parser test for GraknClient #42 Paerser test for GraknClient
• Gherkin: Implement Background sections in Features #43 Gherkin: Implement Background sections in Features
• Gherkin: handle comments #45 Gherkin: handle comments
• Gherkin: support Data Tables #46 Gherkins: support Data Tables
• Gherkin: support out of order and interleaving steps #47 Gherkin: support out of order and interleaving steps
• Gherkin: support Rule keyword #48 Gherkin: support Rule keyword
• Gherkin: support And, But, and * step keywords #49 Gherkin: support And, But, and * step keywords
• Read feature files recursively from any directory #50 Read feature files recursively from any directory
• Support the use of variables in step definition #51 Support the use of variables in step definition
• Scenarios/Outlines/Backgrounds can also have free form descriptions #52 Scenarios/Outlines/Backgrounds can also have free form descriptions
• Scenario Outlines assume all placeholders are in the step strings #53 Scenario Outlines assume all placeholders are in the step strings
• Add support for beforeall and afterall #54 Add support for beforeall and afterall
• Read feature files recursively from any directory (implementation) #55 Include line number in parse results
• Doc strings should allow empty lines #57 Doc strings should allow empty lines
• Scenario descriptions with @ characters are treated as tags #58 Scenario descriptions with @ characters are treated as tags
• Lenient parser: Optionally allow mid-line comments #59 Lenient parser: Optionally allow mid-line comments
• Select features and scenarios using tags #70 Select features and scenarios using tags
• Terse presentation #71 Terse presentation

Primary keywords

• Feature
• Rule (as of Gherkin 6)
• Example (or Scenario)
• Given, When, Then
• And, But for steps (or *)
• Background
• Scenario Outline (or Scenario Template)
• Examples (or Scenarios)

Secondary keywords

• """ (Doc Strings)
• | (Data Tables)*
• @ (Tags)
• #\ (Comments)

Notes:
(*) Data tables is partially supported in the Examples section of scenario outline.
Features required for implementing Grakn client

Background keyword

The Background feature is used extensively. It is used to run multiple Given
statements before executing each scenario.
Doc strings

Not to be confused with Julia doc strings. It is a multi-line string that is passed to the step's context in the text attribute. See behave's documentation.

Example:

  Scenario: write data in a schema session throws
    When connection create database: grakn
    Given connection open schema session for database: grakn
    When session opens transaction of type: write
    Then graql define
      """
      define person sub entity;
      """
    Then graql insert; throws exception containing "session type does not allow"
      """
      insert $x isa person;
      """

Data tables

Data tables are used extensively. It appears that implementation differs in language bindings. For example, the Java implementation maps to a number of data structures. In Python, the behave package simply returns an object that implements some kind of Table API.

Example:

  Scenario: for many databases, open many sessions
    When connection create databases:
      | alice   |
      | bob     |
      | charlie |
      | dylan   |
      | eve     |
      | frank   |

    When connection open sessions for databases:
      | alice   |
      | bob     |
      | charlie |
      | dylan   |
      | eve     |
      | frank   |

    Then sessions are null: false
    Then sessions are open: true
    Then sessions have databases:
      | alice   |
      | bob     |
      | charlie |
      | dylan   |
      | eve     |
      | frank   |

Comments

Comments exists throughout the Grakn feature files for documentation purpose.

# Given all answers are correct in reasoned database
# There are 3^4 possible choices for the set {$x, $y, $z1, $z2}, for a total of 81
# Given answer size in reasoned database is: 81

Out of order steps

Sometimes When is provided before Given. It seems to be backward and not a good practice to provide the trigger prior to listing the pre-conditions? Perhaps we should talk to the Grakn team to fix it on their side.

Example:

  Scenario: an abstract entity type can be defined
    When graql define
      """
      define animal sub entity, abstract;
      """
    Then transaction commits
    Then the integrity is validated
    Given session opens transaction of type: read
    When get answers of graql match
      """
      match $x type animal; $x abstract;
      """
    Then uniquely identify answer concepts
      | x            |
      | label:animal |

Interleaving When and Then's

Grakn's features definitions are long and often embedding multiple, interleaving When's and Then's. It seems to be a bad practice. However, asking them to fix is probably going to be a huge undertaking. We should probably support that regardless.

  Scenario: Relation with role players can be created and role players can be retrieved
    When $m = relation(marriage) create new instance with key(license): m
    Then relation $m is null: false
    Then relation $m has type: marriage
    Then relation(marriage) get instances contain: $m
    When $a = entity(person) create new instance with key(username): alice
    When $b = entity(person) create new instance with key(username): bob
    When relation $m add player for role(wife): $a
    When relation $m add player for role(husband): $b
    Then relation $m is null: false
    Then relation $m has type: marriage

Blank lines

Sometimes there are additional blank lines between When's and Then's in the same scenario. The python behave parser seems to be more relaxed than ExecutableSpecifications.jl at the moment.

Reference: Humans-of-Julia/GraknClient.jl#22