README-work

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);

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');

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

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.

Gherkin::Grammar v0.1.0

Gherkin grammar and actions.

Authors

  • Anton Antonov

License

Artistic-2.0

Dependencies

Markdown::Grammar:ver<0.4.7+>

Test Dependencies

Provides

  • Gherkin::Actions::Raku::TestTemplate
  • Gherkin::Grammar
  • Gherkin::Grammar::Internationalization
  • Gherkin::Grammarish

The Camelia image is copyright 2009 by Larry Wall. "Raku" is trademark of the Yet Another Society. All rights reserved.