Working sample projects for CucumberSwift,
the Gherkin/BDD test framework for Swift. Each one is a starting point for one way of using
CucumberSwift, and each one is built and tested on every change and every night, against
the latest CucumberSwift release and against CucumberSwift's main.
The documentation describes each sample: what it shows, its platform and test target, the Xcode it needs, and the CucumberSwift it works with. The table links each sample's README.
| Sample | Shows | CucumberSwift |
|---|---|---|
| GettingStarted | The smallest working setup: one test target, one feature file, its step definitions | 6.4.0 or later |
| TestNavigator | How scenarios read in Xcode's test navigator: readable test names, failures at the feature file's line, Scenario Outline examples, skipped scenarios, a test plan per tag | 6.4.0 or later |
| StepDefinitionMacros | Step definitions written as macros, #Given, #When and #Then, checked when they compile: typed closure arguments, the Step argument, a localized macro, and the compiler's errors and fixes |
6.4.0 or later |
| ParallelTesting | Scenarios run side by side with Xcode's parallel testing, through CucumberSwift's experimental parallel testing setting, with a serial test plan to compare | 6.4.0 or later |
| BazelModule | CucumberSwift in a Bazel project: one test target, one feature file, its step definitions, with bazel_dep and git_override |
6.4.0 or later |
A sample's "CucumberSwift" column can name a version that CucumberSwift hasn't released yet, for a
feature that ships with that release. Such a sample builds only against a CucumberSwift
checkout (see Use a local CucumberSwift checkout) until
then. CI still tests it against CucumberSwift's main; its test against the release passes
without building the sample, with a notice that names the version it needs and the latest
release, and builds the sample once that version is released, with no change here.
Each samples release carries the version of the CucumberSwift release it was tested with, such as
6.3.0, and the documentation shows the samples of each release. The earlier samples, step-by-step
CocoaPods, Carthage and Swift Package Manager setups for CucumberSwift 3.x, are kept at the
legacy-3.x tag.
They are no longer maintained or tested.
Each sample is an Xcode project generated by Tuist from its
Project.swift. You need Xcode 16.3 or later, the version CI tests them with, and
mise, which installs the Tuist version pinned in .mise.toml:
mise install
mise run generate
open Tuist/GettingStarted/GettingStarted.xcodeprojmise run test builds and tests every sample, and mise run test GettingStarted tests one.
BazelModule is a Bazel module, not an Xcode project: it needs
Bazelisk, and runs with bazel test //... in its folder.
Each sample's README says how to copy it into a project of your own.
To get the samples as they were tested with one CucumberSwift release, check out the samples
release with the same version, such as git checkout 6.3.0, before you generate the projects.
main can already hold samples for the next CucumberSwift release.
CucumberSwift's step-by-step tutorials set up a test target from scratch, with Swift Package Manager or Carthage. GettingStarted is a working, tested setup to compare yours with, and BazelModule is one for a Bazel project.
The samples depend on CucumberSwift from GitHub. To build them against a checkout of your
own, for example while you work on CucumberSwift, set CUCUMBER_SWIFT_PATH to its absolute
path:
CUCUMBER_SWIFT_PATH=~/src/CucumberSwift mise run generateSee CONTRIBUTING.md, including how to add a sample.