Getting Started With Cucumber Pro

August 9, 2018

HEADS UP - March 22, 2019 UPDATE

Cucumber Pro has been relaunched as Jam. I’ll be leaving this post the way it is, but pretend that any time you see Pro that it actually says Jam. :)

Cucumber’s latest offering for enabling teams to expose living documentation across teams in an easy and collaborative way is here!


It’s wonderful!


Let’s back it up first!

Some of you have probably heard about or interacted with something called Relish. Relish was the Cucumber team’s original tool for publishing documentation from feature files. Cucumber Pro is like Relish and there are definitely parallels between the two services, like being able to select particular branches in the same place, but Cucumber Pro has taken what Relish did and improved upon it. Cucumber Pro is not just better, it’s way better. It’s still in beta so there are places for improvements, but the place that it’s in now offers a ton of useful and awesome behavior, my favorite of which is the ability to post test results to it from your favorite CI/CD system. Cucumber Pro displays your test results in some really awesome and easy to read ways, which is a fantastic win for a platform that’s meant to be used by all members of a company, not just the technical folks.

This article isn’t about the various features of Cucumber Pro but rather about how to get yourself set up and some of the things that I’ve worked out that might not be currently easily determinable at first glance.

*A note before we get started: As of writing on Aug 9, 2018, Cucumber Pro is still in beta and it’s still very early days. The only way that I know of to get into Cucumber Pro is via an invite. Also, there will be tons of improvements and features added, so this article may have places where it becomes out of date. I can’t promise all will stay current, but some of the topics will likely be timeless.*

It Begins

There are a few things you need to do before we can get cracking with Cucumber Pro. You’ll be walked through or there will be very readable buttons for the following steps on the Cucumber Pro page after signing up/in.

  1. Create a license
  2. Add a project (So far I’ve been naming mine the same as the git repos they’ll be interacting with)
  3. Create and set your web hook.

Once you do the above, you should have your project show up in Cucumber Pro and look something like this:


๐Ÿ˜Ž Cool. ๐Ÿ˜Ž

Now you might be wondering, “Okay, so… where is everything?” There are a few points to that answer. The simplest and fastest being that there’s a drop down in the top left-hand corner that says. “Table of contents” that’ll display all features in your project.

The longer answer is that if your project is anything like some of mine (mostly flat and only base cucumber items), there will need to be some changes made to help Cucumber Pro best display things for you.

Landing Documentation

If you revisit the initial screenshot that I shared, you’ll see that the data displayed there isn’t actually Gherkin and there’s nothing that look like Scenarios. That’s because Cucumber Pro enables you to have a main/landing documentation page. This of this as a way to give an over-arching description and to set up a curated table of contents for yourself if you’d like. Cucumber Pro’s documentation has a page like this that links to current features and also contains information around road map plans.

To set your project up to be able to display this type of data, create a file in the foot of your Features directory. Cucumber Pro will automatically handle this file for you!

Cucumber Pro tip: In order to link to your feature files from this location, you’ll need to use relative links and include the branch ‘master’ in them all, regardless of whether or not you’re on a trunk or feature branch. For instance in my example, the link to the Funky feature is master/features/funky/funky.feature

If you set up your repo to be watched and you set up a landing doc page fine, but when you hit the table of contents, you find this:


It’s likely your feature directory is flat, and looks something like this:

โ”œโ”€โ”€ features
โ”‚  โ”œโ”€โ”€ funky.feature
โ”‚  โ”œโ”€โ”€ jive.feature
โ”‚  โ”œโ”€โ”€
โ”‚  โ”œโ”€โ”€ step_definitions
โ”‚  โ”‚  โ”œโ”€โ”€ funky_steps.rb
โ”‚  โ”‚  โ””โ”€โ”€ jive_steps.rb
โ”‚  โ””โ”€โ”€ support
โ”‚     โ””โ”€โ”€ env.rb
โ”œโ”€โ”€ Gemfile
โ”œโ”€โ”€ Gemfile.lock

To get it to look like this:


You’ll want to group similar features into their own directories like this:

โ”œโ”€โ”€ features
โ”‚  โ”œโ”€โ”€ funky
โ”‚  โ”‚  โ””โ”€โ”€ funky.feature
โ”‚  โ”œโ”€โ”€ jive
โ”‚  โ”‚  โ””โ”€โ”€ jive.feature
โ”‚  โ”œโ”€โ”€
โ”‚  โ”œโ”€โ”€ step_definitions
โ”‚  โ”‚  โ”œโ”€โ”€ funky_steps.rb
โ”‚  โ”‚  โ””โ”€โ”€ jive_steps.rb
โ”‚  โ””โ”€โ”€ support
โ”‚     โ””โ”€โ”€ env.rb
โ”œโ”€โ”€ Gemfile
โ”œโ”€โ”€ Gemfile.lock

It’s a simple change, but absolutely necessary to help you help Cucumber Pro help you. :p

My favorite feature: Test Visualization

As I mentioned before and showed in my screenshot (though MUCH more data is possible to be shown), Cucumber Pro has the ability to display your test run data on the same page as your living documentation! It’ll show passes, fails, and flaky tests in a super easy to read manner but in order to do this, Cucumber Pro has to get the data from whatever CI/CD tool you’re using. The team has offered up a few different options for some languages, though not all have package support for Cucumber Pro just yet so for now scripts will need to be used.


The CI software I’m most comfortable with is CircleCI and it’s what I used to connect my test project to Cucumber Pro. I’ve got my build set up to the the usual things, but have it outputting test results to a particular place for later. When later comes around, the following script works:

    - &sync_cucumber_pro
        name: Sync Cucumber Pro
        command: |
          env | \
              grep --extended-regexp --ignore-case --invert-match "^.*(${mask}).*=" | \
              curl \
                --fail \
                --request POST \
                --form env=@- \
                --form "profileName=$PROFILE_NAME" \
                --form "payload=@$RESULTS_PATH;type=application/x.cucumber.rb.results+json" \
        when: always

Cucumber Pro tip: If you don’t include the when: always line in the job and your test step fails, CircleCI will not run your script step afterward!

There are data points above covered in Cucumber Pro’s offering of the scripts in case some things don’t make sense. To find this data, you’ll need to go into the settings for your particular project and then scroll down to below the web hook area. Once you got that rigged up, you should start seeing your CI/CD runner’s results in Cucumber Pro! Simple!


There you have it! There are the initial steps to getting started with Cucumber Pro and some hopefully really useful pointers to make that process smoother for you! If you’d like to check out my demo project you can see it here.

If you have any questions, comments, etc, please reach out or leave a comment below!