Skip to content

acuminous/twiki-gherkish-feature-parser

Repository files navigation

twiki-gherkish-feature-parser

Node.js CI Maintainability Test Coverage Tested with zUnit

A Gherkin like feature parser

TL;DR

import { FeatureParser } from "@twiki-bdd/gherkish-feature-parser";
import * as fs from "node:fs";

const featureFilePath = "./buck-rogers-season-one.feature";
const featureFile = fs.readFileSync(featureFilePath, "utf-8");
const parser = new FeatureParser();
const metadata = {
  source: {
    uri: featureFilePath,
  },
};
const feature = parser.parse(featureFile, metadata);

Installation

npm install @twiki-bdd/gherkish-feature-parser

Feature Parser Options

Option Notes
language A language from the Languages module
import { FeatureParser, Languages } from "@twiki-bdd/gherkish-feature-parser";
const parser = new FeatureParser({ language: Languages.中国人 });

Supported Languages

  • Chinese / 中国人
  • Dutch / Nederlands
  • English
  • French / Français
  • German / Deutsch
  • Norweigian / Norsk
  • Polish / Polski
  • Portugeuse / Polski
  • Russian / Русский
  • Spanish / Español
  • Ukrainian / Yкраїнська

Gherkin Compatability

Syntax Supported
Language directive No - use the parser "language" option instead
Feature Yes
Feature descriptions Yes
Feature tags/annotations Yes
Feature backgrounds Yes
Background tags/annotations Yes
Rules Yes
Scenario Outlines Yes - use "Where:", "Examples:", etc
Scenarios Yes
Scenario descriptions Yes
Scenario tags/annotations Yes
Steps Yes
Step tags/annotations Yes
Given / When / Then keywords No - twiki does not special case step keywords
Docstring Yes - use """ or ---

Development

git clone [email protected]:acuminous/twiki-gherkish-feature-parser.git
cd twiki-gherkish-feature-parser
npm install
npm test

State Machine

The parser uses a state machine which transitions between states (e.g. InitialState, DeclareFeatureState) in response to specific events (e.g. Annotation, Feature, etc). When encoutering an event, the state may do one or more of the following...

  • Use the event data to build an internal representation of the feature
  • Ask the state machine to checkpoint the current state
  • Ask the state machine to alias the a specific future state, so it can be transitioned to by a shared/common state
  • Ask the state machine to transition to a new state
  • Ask the state machine to unwind to a previously checkpointed state
  • Ask the state machine to dispatch the event again (after transitioning or unwinding)
  • Ask the state machine to interpret the original line of text again (after transitioning or unwinding)
  • Ignore the event, i.e. do nothing
  • Report an unexpected event
  • Report a missing event handler

For example, the state machine starts off in InitialState. If the first line of text in the feature specifciation is @skip then this will be translated into an AnnotationEvent. The AnnotationEvent will parse the text, resulting in the following event data: { name: "skip", value: true }. The event and data will be dispatched to the InitialState, which will ask the state machine to checkpoint the current state, transition to the CaptureAnnotationState and redispatch the event. The CaptureAnnotationState will stash the event data using until such time as a feature is created. While the state machine continues to receive annoations, the events will continue to be dispatched to and stashed by the CaptureAnnotationState. However, if the 'Feature:' keyword is encountered, a FeatureEvent will be dispatched causing the CaptureAnnotationState to unwind to the previously checkpointed InitialState. The FeatureEvent will be redispatched, and handled by the InitialState.

Events

Name Data Examples
AnnotationEvent name, value @skip
@timeout=1000
BackgroundEvent title? Background:
Background: Introduction
BlankLineEvent
BlockCommentDelimiterEvent ###
DocstringTextEvent text This is a line in a docstring
EndEvent \u0000 (automatically appended by the feature parser)
ExampleTableEvent Where:
ExampleTableHeaderRow headings | height | width |
ExampleTableSeparatorRow |--------|---------|
ExampleTableDataRow values |  10cm  |  20cm  |
ExplicitDocstringStartEvent ---
"""
ExplicitDocstringStopEvent ---
"""
FeatureEvent title? Feature:
Feature: Buck Rogers - Season One
ImplicitDocstringStartEvent    This is the start of an indented docstring
ImplicitDocstringStopEvent This is the start of an indented docstring
RuleEvent title? Rule:
Rule: Buck Rogers always wins
ScenarioEvent title? Scenario:
Scenario: Awakening
SingleLineCommentEvent # This is a comment
StepEvent text This is a step
TextEvent text This is some text

State Transitions

Legend

┌───────────────────────────────────────────┐
│                                           │
│               InitialState                │
│                                           │
│              [valid events]               │
│                                           │
└───────────────────────────────────────────┘

╔═══════════════════════════════════════════╗
║                                           ║
║            A substate machine             ║
║                                           ║
╚═══════════════════════════════════════════╝
Notation Example Meaning
A solid line ─────── A state transition
A dashed line ─ ─ ─ ─ Unwind to the previous checkpoint
A solid diamond Checkpoint the current state before tranistioning
A solid arrow head Redispatch the event
A hollow arrow head Do not redispatch the event
A solid circle Reinterpret the source text

Capture Feature

                        ┌───────────────────────────────────────────┐
                        │                  Initial                  │
                        │                                           │
                        │  [annotation, blank line, block comment   │
                        │ delimiter, feature, single line comment]  │
                        │                                           │
                        └───────────────────────────────────────────┘
                                              │[feature]
                                              │
                                              │
                                              ▽
┌───────────────────────────────────────────────────────────────────────────────────────────┐
│                                      Declare Feature                                      │
│                                                                                           │
│ [annotation, background, blank line, block comment delimiter, rule, scenario, single line │
│                                      comment, text]                                       │
│                                                                                           │
└───────────────────────────────────────────────────────────────────────────────────────────┘
           │[background]                      │[rule]                             │[scenario]
           │                                  │                                   │
           │                                  │                                   │
           ▽                                  ▽                                   ▽
╔════════════════════╗             ╔════════════════════╗              ╔════════════════════╗
║                    ║             ║                    ║[scenario]    ║                    ║
║      Capture       ║ [rule]      ║      Capture       ║─────────────▷║      Capture       ║
║ Feature Background ║────────────▷║        Rule        ║              ║      Scenario      ║
║                    ║             ║                    ║        [rule]║                    ║
║                    ║             ║                    ║◁─────────────║                    ║
╚════════════════════╝             ╚════════════════════╝              ╚════════════════════╝
       [scenario]                                                           △     │[end]
           │                                                                │     │
           └────────────────────────────────────────────────────────────────┘     │
                                                                                  │
                                                                                  ▽
                                                                        ┌───────────────────┐
                                                                        │                   │
                                                                        │       Final       │
                                                                        │                   │
                                                                        └───────────────────┘

Capture Feature Background

                           │[background]
                           │
                           │
                           │
                           ▽
     ┌───────────────────────────────────────────┐
     │        Declare Feature Background         │
     │                                           │
     │  [annotation, blank line, block comment   │
     │   delimiter, single line comment, step]   │
     │                                           │
     └───────────────────────────────────────────┘
                           │[step]
                           │
                           │
                           ▼
     ┌───────────────────────────────────────────┐
     │      Capture Feature Background Step      │[rule]
     │                                           │─────────────────────▷
     │  [annotation, blank line, block comment   │
┌ ─ ▶│   delimiter, explicit docstring start,    │
     │   implicit docstring start, single line   │[scenario]
│    │      comment, rule, scenario, step]       │─────────────────────▷
     │                                           │
│    └───────────────────────────────────────────┘
         ◈[explicit docstring start]         ◈[implicit docstring start]
│        │                                   │
         │                                   │
│        ▽                                   ●
     ╔═══════════════════════════════════════════╗
│    ║                                           ║
     ║             Capture Docstring             ║
│    ║                                           ║
     ╚═══════════════════════════════════════════╝
│        │[explicit docstring end]           │[implicit docstring end]
         │                                   │
│        │                                   │
         ▽                                   ●
│    ┌───────────────────────────────────────────┐
     │     End Feature Background Docstring      │
│    │                                           │
     │  [annotation, blank line, block comment,  │
│    │rule, scenario, single line comment, step] │
     │                                           │
│    └───────────────────────────────────────────┘
                           │[annotation, blank line, block
│                           comment delimiter, single line
                           │comment, rule, scenario, step]
└ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─

Capture Rule

                           │[rule]
                           │
                           │
                           │
                           ▽
     ┌───────────────────────────────────────────┐
     │               Declare Rule                │
     │                                           │
     │[annotation, background, blank line, block │[scenario]
     │ comment delimiter, scenario, single line  │─────────────────────▷
     │              comment, text]               │
     │                                           │
     └───────────────────────────────────────────┘
                           │[background]
                           │
                           │
                           ▼
     ┌───────────────────────────────────────────┐
     │          Declare Rule Background          │
     │                                           │
     │  [annotation, blank line, block comment   │
     │   delimiter, single line comment, step]   │
     │                                           │
     └───────────────────────────────────────────┘
                           │[step]
                           │
                           │
                           ▼
     ┌───────────────────────────────────────────┐
     │       Capture Rule Background Step        │
     │                                           │
     │  [annotation, blank line, block comment   │[scenario]
 ─ ─▶│   delimiter, explicit docstring start,    │─────────────────────▷
│    │   implicit docstring start, single line   │
     │         comment, scenario, step]          │
│    │                                           │
     └───────────────────────────────────────────┘
│        ◈[explicit docstring start]         ◈[implicit docstring start]
         │                                   │
│        │                                   │
         │                                   │
│        ▼                                   ▼
     ╔═══════════════════════════════════════════╗
│    ║                                           ║
     ║             Capture Docstring             ║
│    ║                                           ║
     ╚═══════════════════════════════════════════╝
│        │[explicit docstring end]           │[implicit docstring end]
         │                                   │
│        │                                   │
         ▽                                   ●
│    ┌───────────────────────────────────────────┐
     │       End Rule Background Docstring       │
│    │                                           │
     │  [annotation, blank line, block comment,  │
│    │   scenario, single line comment, step]    │
     │                                           │
│    └───────────────────────────────────────────┘
                           │[annotation, blank line, block
│                           comment delimiter, single line
                           │comment, scenario, step]
└ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─

Capture Scenario

                                            │ [scenario]
                                            │
                                            │
                                            │
                                            ▽
                      ┌───────────────────────────────────────────┐
                      │             Declare Scenario              │
                      │                                           │
                      │  [annotation, blank line, block comment   │
                      │   delimiter, single line comment, step]   │
                      │                                           │
                      └───────────────────────────────────────────┘
                                            │[step]
                                            │
                                            │
                                            ▼
     ┌────────────────────────────────────────────────────────────────────────────┐
     │                                                                            │[rule, scenario, end]
     │                           Capture Scenario Step                            │─────────────────────▷
     │                                                                            │
     │   [annotation, blank line, block comment delimiter, end, example table,    │
 ─ ─▶│  explicit docstring start, implicit docstring start, single line comment,  │◀ ─ ─ ─ ─ ─ ─ ┐
│    │                           rule, scenario, step]                            │
     │                                                                            │              │
│    │                                                                            │
     └────────────────────────────────────────────────────────────────────────────┘              │
│          ◈[explicit             ◈[implicit                    ◈[example table]
           │docstring             │docstring                    │                                │
│          │start]                │start]                       │
           │                      │                             │                                │
│          ▼                      ▼                             ▽
     ╔═══════════════════════════════════╗    ╔═══════════════════════════════════╗              │
│    ║                                   ║    ║                                   ║
     ║         Capture Docstring         ║    ║       Capture Example Table       ║              │
│    ║                                   ║    ║                                   ║
     ╚═══════════════════════════════════╝    ╚═══════════════════════════════════╝              │
│          │[explicit             │[implicit                    │[annotation, blank line, block
           │docstring             │docstring                     comment delimiter, end, rule,   │
│          │end]                  │end]                         │scenario, single line comment]
           ▽                      ●                              ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘
│    ┌───────────────────────────────────┐
     │      End Scenario Docstring       │
│    │                                   │
     │  [annotation, blank line, block   │
│    │  comment, rule, scenario, single  │
     │        line comment, step]        │
│    └───────────────────────────────────┘
                       │[annotation, blank line, block
│                       comment, rule, scenario, single
                       │line comment, step]
└ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─

Capture Docstring

                      ◈                                                  ◈
                      │[explicit docstring start]                        │[implicit docstring start]
                      │                                                  │
                      │                                                  │
                      ▽                                                  │
┌───────────────────────────────────────────┐                            │
│                                           │                            │
│         Begin Explicit Docstring          │                            │
│                                           │                            │
│                  [text]                   │                            │
│                                           │                            │
└───────────────────────────────────────────┘                            │
                      │[text]                                            │
                      │                                                  │
                      │                                                  │
                      ▼                                                  ●
┌───────────────────────────────────────────┐      ┌───────────────────────────────────────────┐
│        Capture Explicit Docstring         │      │        Capture Implicit Docstring         │
│                                           │      │                                           │
│  [annotation, blank line, block comment   │      │  [annotation, blank line, block comment   │
│   delimiter, single line comment, rule,   │      │   delimiter, single line comment, rule,   │
│              scenario, step]              │      │              scenario, step]              │
│                                           │      │                                           │
└───────────────────────────────────────────┘      └───────────────────────────────────────────┘
                      │[explicit docstring end]                          │[implicit docstring end]
                      │                                                  │
                      │                                                  │
                      ▽                                                  ●

Capture Example Table

▲                         ◈
                          │[example table]
│                         │
                          │
│                         ▽
    ┌───────────────────────────────────────────┐
│   │                                           │
    │           Declare Example Table           │
│   │                                           │
    │        [example table header row]         │
│   │                                           │
    └───────────────────────────────────────────┘
│                         │[example table header row]
                          │
│                         │
                          ▽
│   ┌───────────────────────────────────────────┐
    │                                           │
│   │       Capture Example Table Header        │
    │                                           │
│   │       [example table separator row]       │
    │                                           │
│   └───────────────────────────────────────────┘
                          │[explicit table separator row]
│                         │
                          │
│                         ▽
    ┌───────────────────────────────────────────┐
│   │                                           │
    │    Consume Example Table Separator Row    │
│   │                                           │
    │         [example table data row]          │
│   │                                           │
    └───────────────────────────────────────────┘
│                         │[example table data row]
                          │
│                         │
                          ▽
│   ┌───────────────────────────────────────────┐
    │        Capture Example Table Data         │
│   │                                           │
    │  [annotation, blank line, block comment   │
│   │  delimiter, example table data row, end,  │
    │   rule, scenario, single line comment]    │
│   │                                           │
    └───────────────────────────────────────────┘
│                         │[annotation, blank line, block
                           comment delimiter, end, rule,
│                         │scenario, single line comment]
 ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─