Gherkin Laravel Package

Getting Started

Install via Composer: composer require behat/gherkin. The entry point is the Gherkin\Parser class—pass in your Gherkin source (string or file path) to get an AST. Start by parsing a simple .feature file:

use Gherkin\Parser;

$parser = new Parser();
$feature = $parser->parse(file_get_contents('tests/features/login.feature'));
// $feature is now an AST root node (typically a FeatureNode)

Inspect the structure using the AST node types (FeatureNode, ScenarioNode, StepNode, etc.). The Gherkin\Node namespace contains all AST classes—use PHP’s var_dump() or Xdebug to explore. For quick validation, try parsing with Parser::parse() wrapped in try/catch to catch syntax errors.

Implementation Patterns

• AST Traversal: Implement custom visitors (using Gherkin\Node\Visitor\AstDumper as a reference) to walk nodes and collect metadata (e.g., all steps with a @slow tag).
• Custom Test Runners: Replace Behat’s internal parser by feeding behat/gherkin’s AST to your own runner that executes step definitions (e.g., mapping Given /^I log in$/ → actual test logic).
• Tooling Integrations: Build a CLI linter that validates Gherkin against business rules (e.g., “scenarios must have a @smoke tag in production features”) by walking the AST and raising warnings.
• Dynamic Gherkin Generation: Use the AST in reverse—construct nodes programmatically to auto-generate feature files (e.g., from API contracts or database schemas).
• Dialects: Use Parser::setLanguage($locale) (e.g., fr, de) to parse non-English .feature files. Extend Gherkin\Language for custom keywords.

Gotchas and Tips

• AST immutability: Nodes are immutable—modifications require reconstructing the tree. Use Gherkin\Node\Visitor\NodeTransformer or walk the tree and build a new structure.
• Location tracking: All nodes have getLine() and getFile() (if provided via parse($source, $file)), but be aware that multi-line elements (e.g., tables, doc strings) report only the first line.
• Whitespace sensitivity: Leading whitespace in step texts matters if not normalized. Always trim() step arguments if using raw text.
• Dialect gotcha: If parsing fails silently, double-check the language (e.g., Gherkin::LANGUAGE_EN is default, but @fr might be misapplied).
• Performance: Parsing huge files (>10k lines) can be heavy—consider incremental parsing or skipping large feature files via pre-filters.
• Extending the parser: Use Gherkin\Tokenizer and Gherkin\Lexer for custom lexing (e.g., extend step syntax). Avoid forking—override via composition instead.