Feature File AST Structure

Gáspár Nagy edited this page Apr 9, 2014 · 6 revisions

This abstract description contains the structure of the abstract syntax tree (AST) that the gherkin3 parser builds up.

General guidelines

  • The AST should be separated from logic, logic should be rather in visitors.
  • The AST should not have circular references (e.g. no back reference from Scenario to Feature). The links should go down but not up.
  • No mutable state on the AST. The AST nodes should be immutable values.

Notes

  • In this pseudo code we used ruby naming convention, but this can be adapted to the concrete programming language.
  • AST is a tree of objects. For better clarity we defined explicitly named sub-collections (e.g. steps or decnario_definitions). In addition to that, the language implementations can provide generalized sub-item accessors (e.g. 'children' property or implementing enumerable interfaces) to be able to write visitors more easily.
  • The sub-item collections should be exposed as public members, but keep immutability in mind (e.g. #freeze! in ruby, unmodifiableList() in Java).
  • The Gherkin parser is not responsible for opening/reading files, but the client implementations should pass in the necessary IO/reader objects. Hence the Location does not hold a file path.
  • We have not defined the interfaces / mixins that help processing the AST. These can be defined depending on the language specifics, if needed. We thought of:
    • HasHeader - the ones that has keyword, title and description (Feature, Background, Scenario, Scenario Outline, Examples)
    • HasTags - the ones with tags attached (Feature, Scenario, Scenario Outline, Examples)
    • HasLocation - the ones with source location information (nearly all)
    • HasSteps - the ones with steps inside (Background, Scenario, Scenario Outline)
    • HasRows - the ones with table rows inside (Examples, DataTable)

Feature

  • location : Location
  • language : string
  • tags : list of Tag
  • keyword : string
  • title : string
  • description: string
  • background : Background
  • scenario_definitions : list of (Scenario or Scenario Outline - ScenarioDefinition)
  • comments : list of Comment

Background

  • location : Location
  • keyword : string
  • title : string
  • description: string
  • steps : list of Step

ScenarioDefinition (abstract)

  • location : Location
  • tags : list of Tag
  • keyword : string
  • title : string
  • description: string
  • steps : list of Step

Scenario : ScenarioDefinition

ScenarioOutline : ScenarioDefinition

  • examples : list of Examples

Examples

  • location : Location
  • tags : list of Tag
  • keyword : string
  • title : string
  • description: string
  • header : TableRow
  • rows : list of TableRow

Step

  • location : Location
  • keyword : string
  • text : string
  • step_arg : (DataTable, DocString or EmptyStepArg - StepArg)

StepArg (abstract)

DocString : StepArg

  • location : Location
  • content_type : string // hint for syntax highlighting, like in like in GFM
  • content : string

DataTable : StepArg

  • rows : list of TableRow

EmptyStepArg : StepArg

TableRow

  • location : Location //location of the first '|' character
  • cells : list of TableCell

TableCell

  • location : Location //location of the first non-whitespace character, or the location of the character after the left '|' if empty
  • value : string //trimmed

Tag

  • location : Location
  • name : string //including leading '@'

Comment

  • location : Location
  • value : string //the entire original line, so including '#' and whitespaces before/after

Location

  • line : int // 1-based index
  • column : int // 1-based index