Gherkin::Grammar Raku package

This repository has the Raku package for Gherkin grammar and interpretations.

Gherkin is the language of the Cucumber framework, [Wk1] that is used to Behavior-Driven Development (BDD), [Wk2].

The Raku package "Cucumis Sextus, [RL1], aims to provide a "full-blown" specification-and-execution framework in Raku like the typical Cucumber functionalities in other languages. (Ruby, Java, etc.)

This package, "Gherkin::Grammar", aims to provide:

• Grammar (and roles) for parsing Gherkin specifications

• Test file template generation

Having a "standalone" Gherkin grammar (or role) facilitates the creation and execution of general or specialized frameworks for Raku support of BDD.

The package provides the functions:

• gherkin-parse

• gherkin-subparse

• gherkin-interpret

The Raku outputs of gherkin-interpret are test file templates that after filling-in would provide tests correspond to the input specifications (given in Gherkin.)

Remark: A good introduction to the Cucumber / Gherkin approach and workflows is the README of [RLp1].

Remark: The grammar in this package was programmed following the specifications and explanations in Gherkin Reference.

Installation

From Zef ecosystem:

zef install Gherkin::Grammar

From GitHub:

zef install https://github.com/antononcube/Raku-Gherkin-Grammar

Workflow

The package follows the general Cucumber workflow, but some elements are less automated. Here is flow chart

Here is corresponding narration:

1. Write tests using Gherkin specs

2. Generate test code

   • Using the package "Gherkin::Grammar".

3. Fill-in the code of step functions

4. Execute tests

5. Revisit (refine) steps 1 and/or 4 as needed

6. Integrate resulting test file

Usage examples

Here is a basic (and short) Gherkin spec parsing example:

use Gherkin::Grammar;

my $text0 = q:to/END/;
Feature: Calculation
    Example: One plus one
    When 1 + 1
    Then 2
END

gherkin-interpret($text0);

# use v6.d;
#
# #============================================================
#
# proto Background(@cmdFuncPairs) {*}
# proto ScenarioOutline(@cmdFuncPairs) {*}
# proto Example($descr) {*}
# proto Given(Str:D $cmd, |) {*}
# proto When(Str:D $cmd, |) {*}
# proto Then(Str:D $cmd, |) {*}
#
# #============================================================
#
# use Test;
# plan *;
#
# #============================================================
# # Example : One plus one
# #------------------------------------------------------------
#
# multi sub When( '1 + 1' ) {}
#
# multi sub Then( '2' ) {}
#
# multi sub Example('One plus one') {
# 	When( '1 + 1' );
# 	Then( '2' );
# }
#
# is Example('One plus one'), True, 'One plus one';
#
# done-testing;

Internationalization

The package provides provides internationalization using different languages. The (initial) internationalization keyword-regexes were taken from [RLp1]. (See the file "I18n.rakumod".)

Here is an example with Russian:

my $ru-text = q:to/END/;
Функционал: Вычисление
    Пример: одно плюс одно
    Когда 1 + 1
    Тогда 2
END

gherkin-interpret($ru-text, lang => 'Russian');

# use v6.d;
#
# #============================================================
#
# proto Background(@cmdFuncPairs) {*}
# proto ScenarioOutline(@cmdFuncPairs) {*}
# proto Example($descr) {*}
# proto Given(Str:D $cmd, |) {*}
# proto When(Str:D $cmd, |) {*}
# proto Then(Str:D $cmd, |) {*}
#
# #============================================================
#
# use Test;
# plan *;
#
# #============================================================
# # Example : одно плюс одно
# #------------------------------------------------------------
#
# multi sub When( '1 + 1' ) {}
#
# multi sub Then( '2' ) {}
#
# multi sub Example('одно плюс одно') {
# 	When( '1 + 1' );
# 	Then( '2' );
# }
#
# is Example('одно плюс одно'), True, 'одно плюс одно';
#
# done-testing;

Arguments

The package takes both doc-strings and tables as step arguments.

The tables are parsed with the package "Markdown::Grammar", [AAp1].

TBD...

Complete example

The files "Calculator.feature" and "Calculator.rakutest" provide a fully worked example of how this package can be used to implement Cucumber framework workflows.

Remark: The Cucumber framework(s) expect Gherkin specifications to be written in files with extension ".feature".

CLI

The package provides a Command Line Interface (CLI) script. Here is its help message:

gherkin-interpretation --help

# Usage:
#   gherkin-interpretation <fileName> [-l|--from-lang=<Str>] [-t|--to-lang=<Str>] [-o|--output=<Str>] -- Interprets Gherkin specifications.
#
#     -l|--from-lang=<Str>    Natural language in which the feature specification is written in. [default: 'English']
#     -t|--to-lang=<Str>      Language to interpret (translate) the specification to. [default: 'Raku']
#     -o|--output=<Str>       File to place the interpretation to. (If '-' stdout is used.) [default: '-']

References

Articles

[Wk1] Wikipedia entry, "Cucumber (software)". See also cucumber.io.

[Wk2] Wikipedia entry, "Behavior-driven development".

[SB1] SmartBear, "Gherkin Reference", (2023), cucumber.io.

Packages

[AAp1] Anton Antonov, Markdown::Grammar Raku package, (2022-2023), GitHub/antononcube.

[RLp1] Robert Lemmen, Cucumis Sextus Raku package, (2017-2020), GitHub/robertlemmen.