@twiki-bdd/gherkish-feature-parser
v0.3.0
Published
Twiki Gherkish feature parser
Downloads
9
Maintainers
Readme
twiki-gherkish-feature-parser
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
| 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 |