Cucumber for iOS, tvOS and macOS
Describe it in Gherkin. Prove it in Swift.
CucumberSwift is a lightweight, Swift-only Cucumber implementation. Your .feature files run as XCTest tests, right alongside the rest of your suite in Xcode.
- MIT licensed
- iOS 13+
- macOS 10.15+
- tvOS 13+
Feature: Checkout
Scenario: Paying with a saved card
Given I have 2 items in my cart
When I pay with my saved card
Then I see "Order placed"#Given("I have {int} items in my cart") { (count: Int) in
cart.fill(with: count)
}
#When("I pay with my saved card") {
checkout.payWithSavedCard()
}
#Then("I see {string}") { (message: String) in
XCTAssertEqual(banner.text, message)
}How it works
From a sentence to a passing test in three steps
-
Describe the behaviour
Write scenarios in
.featurefiles that product, QA and engineering can all read. Keywords are localised, so the Gherkin can be in your team's language. -
Match each step
Match steps with macros, using Cucumber Expressions or regular expressions. The compiler checks each parameter's type. Turn on the macros (opens in a new tab) with a package trait.
-
Run it with XCTest
Scenarios run as ordinary tests. For each step without a definition, CucumberSwift prints a stub to paste into your step definitions.
What's included
Small on purpose
CucumberSwift was written to be easy to install and easy to use. It covers what a Swift team needs from Cucumber, and not much else.
-
Cucumber Expressions
Step definitions use readable patterns like
{int}and{string}, and you can add your own typed parameters. -
Six hooks
Six hooks run before and after each feature, scenario and step.
-
JSON reports
CucumberSwift writes a Cucumber JSON report in real time while your tests run.
-
Localised Gherkin
Every Gherkin language has its own keyword functions, such as
ES_Dadofor Spanish.
Install
Add it to your test target
In Xcode, choose File › Add Package Dependencies… and paste the repository URL. Or add it to Package.swift. Carthage is supported too.
Swift Package Manager
dependencies: [
.package(url: "https://github.com/cucumberswift/CucumberSwift",
from: "6.0.0")
],
targets: [
.testTarget(name: "AppTests",
dependencies: ["CucumberSwift"])
]Carthage
github "cucumberswift/CucumberSwift"carthage update && carthage build --platform iOSDocumentation
Read the docs
The docs follow the latest stable release. Each major version has its own docs. Pick a version from the menu next to each library. The samples are working projects for the latest release.
CucumberSwift (opens in a new tab)
The CucumberSwift docs have tutorials for SPM and Carthage, articles on step matching, hooks and reports, and the full API reference.
CucumberSwiftExpressions (opens in a new tab)
CucumberSwiftExpressions is the Cucumber Expressions parser behind step matching. Its docs show how to write custom parameters.
Sample projects (opens in a new tab)
These Xcode projects are built and tested against the latest CucumberSwift release. Start from one, or compare your setup with it.
Community
Built in the open
Chat with us on Slack, or ask questions, report bugs and propose changes on GitHub. Everyone taking part follows the code of conduct.