Gherkin Generator

Gherkin is a powerful standard for BDD (Behavior-Driven Development). .feature files describe expected behavior in natural language: Given, When, Then. Readable by everyone — product owners, QA, developers.

But writing these specs by hand quickly becomes painful:

What if you could do everything programmatically?

Gherkin Generator is a complete Swift library for the .feature file lifecycle. Instead of writing Gherkin by hand, you build it in code — with validation, autocompletion, and the full power of Swift.

Result: an immutable, validated Feature object, ready to be exported to .feature, JSON or Markdown.

It's no longer just a generator. It's a complete toolkit: builder, parser, validator, formatter, exporter, importer, streaming, batch processing, and CLI.

The API is designed to reflect Gherkin's natural structure. Each method returns a new copy — everything is immutable and Sendable.

Chain And and But steps after any primary step:

Define common preconditions executed before each scenario. The closure receives a BackgroundBuilder:

Use addOutline for parameterized scenarios. Placeholders in angle brackets (<email>) are substituted from the examples table:

Named and tagged example blocks are also supported via .examples(_:name:tags:).

Attach a data table to any step. The first row is the header:

Attach multi-line text with an optional media type:

Apply tags at the feature level with .tags() and at the scenario level with .scenarioTags(). Tags are used for filtering, categorization, and hook targeting:

Group scenarios under named business rules to structure complex features:

The real power: generate hundreds of scenarios programmatically. The immutable API is used with var and reassignment:

For a mutating approach, use appendScenario(_:) or appendOutline(_:).

Before export, validate your features against 5 built-in rules. The validator reports all errors found, not just the first one:

Conform to the ValidationRule protocol to add your own checks. Rules are composable:

BatchValidator is an actor that parses and validates all .feature files in a directory in parallel:

streamValidation(at:) provides an AsyncStream for progressive reporting.

GherkinParser uses a recursive descent parser. It automatically detects the language from a # language: header or falls back to English:

Also parses directly from a Gherkin string:

Map CSV columns to Gherkin step types via CSVImportConfiguration. Each row becomes a scenario:

Custom delimiter and optional tag column supported.

JSONFeatureParser decodes JSON produced by GherkinExporter, guaranteeing a perfect round-trip — export to JSON then reimport produces an identical Feature:

Parse informal text into scenarios. Lines starting with Given/When/Then become steps, --- separates scenarios:

All prefixes and the separator are configurable via PlainTextImportConfiguration.

ExcelParser reads .xlsx files natively thanks to a built-in ZIP/OOXML reader — no third-party dependencies. Cross-platform: macOS, iOS, Linux via the system zlib library.

The tagColumn parameter maps a column to per-scenario tags (space or comma-separated). The sheetIndex parameter selects the worksheet to read.

BatchImporter is an actor that scans a directory of .feature files and parses them in parallel:

streamDirectory(at:) provides an AsyncStream for progressive processing.

GherkinExporter writes a feature to your chosen format — .feature, JSON or Markdown:

Render in memory without writing to disk:

GherkinFormatter converts a Feature to properly indented Gherkin with aligned tables. Three presets available:

For large volumes, the library provides dedicated actors with AsyncStream patterns.

StreamingExporter is an actor that writes features line by line, without loading everything into memory. Suitable for features with hundreds of scenarios:

Get an AsyncStream<String> of formatted lines for custom processing:

Track export progress:

BatchExporter is an actor that exports multiple features to individual files in a target directory. Files are written in parallel via TaskGroup. Titles are automatically slugified to filenames, and duplicates receive numeric suffixes (login.feature, login-1.feature, login-2.feature):

Track progress with exportAllWithProgress:

Gherkin supports 70+ languages. Gherkin Generator does too — with official keywords from Cucumber's gherkin-languages.json.

15 common languages have static shortcuts: .english, .french, .german, .spanish, .italian, .portuguese, .japanese, .chinese, .russian, .arabic, .korean, .dutch, .polish, .turkish, .swedish.

Access any language by ISO code or list all available languages:

The parser automatically detects # language: directives and the formatter produces output with the correct localized keywords.

gherkin-gen is a command-line tool with 7 subcommands for composing, validating, and converting .feature files directly from the terminal.

Options --given, --when, --then, and --tag are repeatable. --language for non-English features (default: en).

--strict enables all rules by default. --quiet suppresses success messages.

Customizable columns with --scenario-column, --given-column, --when-column, --then-column, --tag-column. CSV delimiter with --delimiter.

Generated .feature files are compatible with all Gherkin tools:

Gherkin Generator is part of a set of complementary tools for a complete BDD workflow in Swift:

Two complementary tools: one generates specs, the other executes them.