DOCSEARCHbyAlgolia
Submit Docs

Gherkin Parser and Compiler

repository·main·Indexed 18 days ago

https://github.com/cucumber/gherkin

A parser and compiler for the Gherkin language that transforms feature files into Abstract Syntax Trees (AST) and Pickles. It is available as a library for multiple languages including C, C++, Dart, .NET, Elixir, Go, Java, JavaScript, Perl, PHP, and Python, and supports output via the Cucumber Messages protocol.

Tokens
21.7K
Snippets
75
Records
116
Agent score
62%

What's inside Gherkin

  1. Use Gherkin for Java

    main
    Gherkin for Java is a parser and compiler for Gherkin feature files. It allows Java applications to parse Gherkin syntax into an Abstract Syntax Tree (AST) or Pickles for programmatic manipulation and execution. For implementation details and sample usage, refer to the GherkinParserTest class in the source repository.

  3. Use Gherkin for PHP

    main
    Gherkin for PHP is a parser and compiler for Gherkin feature files, designed for use within PHP environments. It allows developers to parse Gherkin syntax into structured data for use in testing frameworks or other tools. For general information about the Gherkin language specification, refer to the main Gherkin repository.

  4. Use Gherkin for JavaScript

    main
    The @cucumber/gherkin package provides a parser and compiler for Gherkin language files in JavaScript environments. It allows you to parse Gherkin feature files into an Abstract Syntax Tree (AST) or into 'Pickles' (an intermediate representation used for execution).

  5. Use Gherkin for Python

    main
    Gherkin for Python is a parser and compiler for Gherkin language files, designed for use within the Python ecosystem. It allows developers to parse Gherkin feature files into an Abstract Syntax Tree (AST) or 'Pickles' for programmatic manipulation and execution.

  6. What is Markdown with Gherkin (MDG)

    main

    Markdown with Gherkin (MDG) is a dialect of Markdown that is a strict superset of GitHub Flavored Markdown (GFM). It allows you to embed Gherkin scenarios directly within Markdown documents, enabling the creation of rich, living documentation that can be rendered by any GFM-compliant tool.

    Requirements:

    • Files must use the .feature.md extension.
    • Support for MDG is currently only available in the @cucumber/gherkin (JavaScript) implementation, version 19.0.0 and above.

  7. Parsing behavior and AST notes for MDG

    main

    MDG is parsed using the same Parser class as Gherkin Classic, but utilizes a GherkinInMarkdownTokenMatcher.

    Key Parsing Behaviors:

    • Prose Handling: The GherkinInMarkdownTokenMatcher treats all lines not recognized as special Gherkin tokens as Empty. This allows Markdown prose to exist alongside Gherkin without causing errors.
    • AST Impact: Because prose is treated as Empty, the resulting GherkinDocument AST will have empty description properties. Consequently, the JSON formatter will not include a description property for scenarios.

  8. How the Gherkin architecture works

    main

    Gherkin processing follows a three-stage pipeline:

    1. Scanner: Reads a Gherkin document (typically a .feature file) and produces a stream of Tokens. If the scanner encounters a #language header, it dynamically reconfigures itself to use keywords defined in gherkin-languages.json for that specific language.
    2. Parser: Consumes the tokens to produce an Abstract Syntax Tree (AST). The parser is generated using the Berp parser generator.
    3. Compiler: Transforms the AST into Pickles, which are a simplified data structure suitable for execution by Cucumber.

  9. Understand the Abstract Syntax Tree (AST) structure

    main

    The AST is a tree of simple data objects representing the Gherkin document. Every node in the AST includes a Location (1-indexed line and column) indicating its position in the source file.

    Key AST Nodes and Fields:

    • GherkinDocument: Contains a Feature, optional Comments, and a language.
    • Feature: Contains name, description, keyword, tags, Background, Rules, and ScenarioDefinitions.
    • Rule: Contains name, description, keyword, tags, and ScenarioDefinitions.
    • ScenarioDefinition (Base for Scenario and ScenarioOutline): Contains keyword, name, description, tags, and steps.
    • ScenarioOutline: Contains Examples.
    • Examples: Contains keyword, name, description, tags, a header (TableRow), and multiple rows (TableRows).
    • Step: Contains keyword, text, and optionally one DataTable and one DocString.
    • DataTable: Contains rows (TableRows).
    • TableRow: Contains cells (TableCells).
    • TableCell: Contains a value.
    • DocString: Contains content and contentType.
    • Tag: Contains a name.
    • Comment: Contains text.

    Note: All fields are strings except for Location.line and Location.column. In JSON representations, every node includes a type property matching its node type.

  10. Implement a custom IdGenerator

    main
    The Gherkin library includes a default IncrementingIdGenerator which generates IDs as strings like "1", "2", etc. If your application requires UUIDs, you must provide your own implementation of the id_generator.h interface that generates UUID strings.

  11. What are Pickles and why are they used?

    main

    Pickles are a simplified, flattened version of the Gherkin AST. While the AST represents the full structure of the document, Pickles are designed for execution by Cucumber.

    Compilation Logic:

    • Each Scenario is compiled into a Pickle.
    • Each Examples row in a Scenario Outline is compiled into a Pickle.
    • Background steps are compiled into a Pickle.
    • Every Tag (e.g., @a) is compiled into a Pickle, inheriting tags from its parent elements.

    Benefits:

    • Decoupling: Allows Cucumber to support alternative formats (like Markdown) without changing its core execution engine.
    • Simplicity: Provides a streamlined data structure for Cucumber's internals.
    • Traceability: Each Pickle contains the path to the original source file, enabling accurate reporting and stack traces during failures.

  12. Integrate Gherkin into a CMake project

    main

    If Gherkin is installed on your system, you can use find_package to integrate it into your C++ project.

    cmake_minimum_required(VERSION 3.0)
project(gherkincsample)
list(APPEND CMAKE_PREFIX_PATH "INSTALLATION_DIRECTORY")
set(CMAKE_CXX_STANDARD 11)
find_package(gherkin REQUIRED)
add_executable(gherkincsample main.cpp)
target_link_libraries(gherkincsample gherkin::gherkin)
    cmake_minimum_required(VERSION 3.0)
project(gherkincsample)
list(APPEND CMAKE_PREFIX_PATH "INSTALLATION_DIRECTORY")
set(CMAKE_CXX_STANDARD 11)
find_package(gherkin REQUIRED)
add_executable(gherkincsample main.cpp)
target_link_libraries(gherkincsample gherkin::gherkin)