Cucumber-CPP

Overview

Cucumber-Cpp allows Cucumber to support step definitions written in C++.

• Cucumber-Cpp Website
• Cucumber-Cpp Documentation
• Cucumber Website
• Get in touch

If you need to ask a question, post on the Cucumber discussion group.

If you want to contribute code to the project, guidelines are in CONTRIBUTING.md.

Dependencies

It relies on a few executables:

• cmake 3.16 or later. Required to setup environment and build software

It relies on a few libraries:

• Asio 1.18.1 or later.
• Boost.Test 1.70. Optional for the Boost Test driver.
• GTest 1.11.0 or later. Optional for the GTest driver.
• GMock 1.11.0 or later. Optional for the internal test suite.
• nlohmann-json 3.10.5 or later.
• Qt6 or Qt5. Optional for the CalcQt example and QtTest driver.
• TCLAP 1.2.5 or later.

It might work with earlier versions of the libraries, but it was not tested with them. See the CI scripts for details about dependency installation.

Cucumber-Cpp uses the wire protocol at the moment, so you will need Cucumber-Ruby and its cucumber-wire plugin installed and available on the path. They are also needed to run the functional test suite.

Cucumber-Cpp is tested with Cucumber-Ruby 7.1 and 10. Later versions are not supported yet, because there is no cucumber-wire release for them. Cucumber-Ruby 10 needs Ruby 3.1 or later.

To install the Ruby prerequisites:

gem install bundler // For windows: gem install bundle
bundle install

This installs Cucumber-Ruby 7.1. To use Cucumber-Ruby 10 instead, set the environment variable CUCUMBER_VERSION=10 before running bundle install and keep it set when running bundle exec.

Windows vs. Linux

To get an inspiration on how to set up the dependencies on your specific system (Windows or Linux), you may want to have a look at the workflow files for Windows and for Linux.

Build

Building Cucumber-Cpp with tests and samples:

# Create build directory
cmake -E make_directory build

# Generate Makefiles
cmake -E chdir build cmake \
    -DCUKE_ENABLE_BOOST_TEST=on \
    -DCUKE_ENABLE_GTEST=on \
    -DCUKE_ENABLE_QT_6=on \
    -DCUKE_TESTS_UNIT=on \
    -DCUKE_ENABLE_EXAMPLES=on \
    ..

# Build cucumber-cpp
cmake --build build

# Run unit tests
cmake --build build --target test

# Run install
cmake --install build

Running the Calc example on Unix:

build/examples/Calc/BoostCalculatorSteps >/dev/null &
(cd examples/Calc; cucumber)

Running the Calc example on Windows (NMake):

start build\examples\Calc\BoostCalculatorSteps.exe
cd examples\Calc
cucumber

The way it works

(This is a great explanation by paoloambrosio copied from stackoverflow)

The way Cucumber-CPP currently works is by having Cucumber-Ruby connecting to a TCP port where the C++ implementation is listening. When the wire protocol is defined in the cucumber.wire file, with host and port where your C++ wire protocol server is listening, Cucumber-Ruby will try and run them with Cucumber-CPP.

C++ is a compiled language, so step definitions must be compiled first. The examples provided use CMake, as described in the README. Cucumber-CPP needs to be linked to the step definitions and to everything that they use (usually the application under test), creating an executable file that will listen to the wire protocol port (defaults to localhost:3902) for Cucumber-Ruby to connect to (and exiting when it disconnects).

                    +------------------------------------------+
                    |                                          |
+----------+        | +----------+  +----------+  +----------+ |
|          |        | |          |  |          |  |          | |
| Cucumber |        | | Cucumber |  | C++ Step |  | Your     | |
| Ruby     |--------->| CPP Wire |--| Defs     |--| CPP App  | |
|          |        | | Server   |  |          |  |          | |
|          |        | |          |  |          |  |          | |
+----------+        | +----------+  +----------+  +----------+ |
                    |                                          |
                    +------------------------------------------+

Getting started

Here is a basic example on how to get started with cucumber-cpp. First you need to create the basic feature structure:

cucumber --init

Then create a cucumber.wire file in the features/step_definitions folder with the following content:

host: localhost
port: 3902

Cucumber-Ruby 8 and later ignore the cucumber.wire file unless the wire protocol plugin is loaded. Create a wire.rb file in the features/support folder with the following content (Cucumber-Ruby 7.1 works with it as well):

require 'cucumber/wire'

Create your first feature (an example is available here).

Then create your step definition runner (an example is available here). In order to compile the step definition runner, make sure to add cucumber include directory to the include path and link with libcucumber-cpp.a and additional testing libraries (boost unit test).

Run the step definition runner in the background and then cucumber, like in the Calc example in the previous section. Start cucumber in the folder that contains the features folder, otherwise it does not find the cucumber.wire file. The step definition runner should exit after the feature is run and cucumber exits.