GherkinTesting

Published on February 7, 2026 · Updated February 7, 2026 · 14 min

Founder & Swift Tech Lead

Swift BDD Gherkin Testing Swift Macros Swift Testing

The gap in the Swift ecosystem

BDD (Behavior-Driven Development) is an industry standard. Ruby has Cucumber, Python has Behave, .NET has SpecFlow. And Swift?

XCTest-Gherkin — Old, poorly maintained, dated API. CucumberSwift — Objective-C under the hood, memory leaks, catastrophic performance. Quick/Nimble — Not really Gherkin, just describe/it.

Result: iOS teams wanting to do BDD struggle. They cobble together partial solutions, import flaky frameworks, or simply give up.

GherkinTesting changes that. A true modern BDD framework, built with Swift Macros, compatible with Swift Testing, designed for 2025 teams.

The approach: native Swift Macros

No runtime parsing, no reflection, no black magic. GherkinTesting uses Swift Macros to transform your types into test suites at compile time.

The @Feature macro transforms this struct into a test suite. Each scenario from the .feature file is executed using the steps defined by @Given, @When, @Then.

Multiple sources

Load your features from multiple sources:

Cucumber Expressions

Cucumber Expressions offer a readable alternative to regex. The framework supports native types and custom types:

Custom types

Define your own parameter types in gherkinConfiguration:

Data Tables

Data Tables allow passing tabular data to a step:

The DataTable API exposes headers, dataRows, asDictionaries and empty for data manipulation.

Doc Strings

Doc Strings allow passing multiline content, with an optional media type:

Mixed captures + DataTable

A step can combine Cucumber Expression parameters and a DataTable:

Scenario Outlines with Examples

Scenario Outlines allow testing the same scenario with different data. Tags on Examples: blocks offer granular filtering:

Native multi-language

Gherkin supports 70+ languages. Your .feature files can be in French, English, German, Japanese... Just add the # language: directive on the first line:

Step definitions remain in Swift — only the .feature files change language.

Hooks: complete lifecycle

Control your test lifecycle with @Before and @After at different scopes:

Hooks support order: parameters to control execution order and tags: for conditional triggering:

Available scopes: .feature, .scenario, .step. @Before hooks run FIFO, @After hooks run LIFO.

Tags and filtering

Organize and filter your tests with boolean expressions:

Supported expressions: @tag, not @tag, @a and @b, @a or @b, parentheses. Filtered scenarios appear as .skipped in reports.

Shared steps

Reuse steps across features with @StepLibrary:

Each library is freshly instantiated per scenario via retyped() to guarantee state isolation.

Rule (Gherkin 6+)

The Rule: keyword allows grouping scenarios under a business constraint:

Scenarios within a Rule inherit the feature's Background.

Reporters: standard formats

Generate reports compatible with all CI/CD tools via the reports: parameter of @Feature:

Three formats available:

Format	Extension	Usage
HTML	.html	Navigable visual report
Cucumber JSON	.json	Compatible with Cucumber dashboards
JUnit XML	.xml	GitHub Actions, Jenkins, Azure DevOps

Reports are automatically written to /tmp/swift-gherkin-testing/reports/ after test execution. You can customize the path:

Dry-run mode

Verify all your steps are implemented without executing tests:

In dry-run mode, the framework inspects scenarios and generates StepSuggestion for each unimplemented step, with the Cucumber expression and suggested Swift signature.

@MainActor and @GlobalActor compatibility

The framework is fully compatible with Swift global actors. You can annotate your features, step handlers, or step libraries:

Also works with custom @GlobalActor and cross-isolation calls via await.

Installation

Requirements

Swift 6.2+ (Xcode 26.2 or later)
Platforms: iOS 17+ · macOS 14+ · tvOS 17+ · watchOS 10+ · visionOS 1+ · Mac Catalyst 17+

Swift Package Manager

Then add the dependency to your test target:

CI / GitHub Actions

The framework integrates natively with CI pipelines. A minimal workflow:

Add JUnit XML report collection as artifact:

By the numbers

Metric	Value
Tests	823+
Coverage	97.59%
Gherkin languages	70+
Report formats	3 (HTML, JSON, JUnit XML)
External dependencies	0
Supported platforms	6 (iOS, macOS, tvOS, watchOS, visionOS, Mac Catalyst)

Features

@Feature, @Given, @When, @Then, @And, @But macros
Multiple sources: .file(), .inline()
Cucumber Expressions: {string}, {int}, {float}, {word}, {}, custom types
Regex patterns as alternative to Cucumber Expressions
Data Tables with full API (headers, dataRows, asDictionaries)
Doc Strings with optional media type
Mixed captures + DataTable / DocString
Scenario Outlines with Examples and tags on Examples blocks
Rule (Gherkin 6+) for business grouping
Background for shared steps
Native multi-language (70+ Gherkin languages)
@Before / @After hooks with .feature, .scenario, .step scopes
Tags and filtering with boolean expressions
Composable Step Libraries with @StepLibrary
Reporters: HTML, Cucumber JSON, JUnit XML
Dry-run mode with step suggestions
@MainActor / @GlobalActor compatibility
Swift 6 ready: async/await, Sendable, actors
Zero external dependencies

Under the hood

Swift Macros — Compile-time transformation, zero runtime overhead
Swift 6 ready — Modern concurrency, actors, Sendable
Protocol-oriented — Extensible, testable, mockable
Zero dependencies — Pure Swift and Apple frameworks
Multi-platform — iOS, macOS, tvOS, watchOS, visionOS, Mac Catalyst

Atelier Socle Gherkin Ecosystem

GherkinTesting is part of a set of complementary tools:

Tool	Role	Status
GherkinTesting	Execute BDD tests in Swift	Open-source
Gherkin Generator	Compose and export `.feature` files	In development
Gherkin Runner	macOS interface for editing and running	In development

Three tools, one complete BDD workflow in Swift.