Enterprise Boozang: Working with GitHub

This article explains how to use GitHub as a repository for Cucumber feature files, and how to synchronize these with Boozang.

This article is part of the article series “Enterprise Boozang”.

Having a Cloud-based versioning system has many benefit when it comes to remote work and collaboration. In some cases, customers are using a BDD-like approach with feature files written in Cucumber/Gherkin syntax.

Boozang has integrations to the following versioning systems

• GitHub
• BitBucket
• GitLab
• Azure

In this market, GitHub is definitely the dominant player, even though the exact numbers differ (https://thenewstack.io/i-dont-git-it-tracking-the-source-collaboration-market/). We therefore start with a step-by-step instruction on how to integrate Boozang with GitHub.

Boozang runs in the Cloud completely independent of any versioning system, and with its support of branching and merging, it’s a versioning system in itself. There are some benefits of keeping Cucumber feature files in a separate versioning system

• Align feature files with the application code
• Use your favourite text editor

Adding features to your GitHub repo

Start by writing a few feature files for your project. The following feature example works well with Boozang:

@Authentication
Feature: Authentication

The authentication features tests login and logout for different users.

@Smoke @Login
Scenario: Login
"""
Tests login functionality.
"""
Given I am logged out
When I login
Then I should be logged in

As you can see, I use tags and comments at both feature and scenario level. This is not mandatory, but will help us in the house-keeping of our tests.

There are a few different conventions on how to maintain your features, but I usually maintain my features with the application under test, with the source code.

My application directory usually looks something like

app/
public/
features/

The good thing about keeping your features with your source code instead of a separate repository, is that your features gets branched alongside the code. This way you don’t have to mirror branches between two different repositories. This does depend a lot of team setup, and every team should do what works for them.

Getting the GitHub access token

If you decide to use a publicly accessible GitHub repository for your features, you can skip this step. As we are doing read-only operations only, you will not need a GitHub access token for public repositories.

Find, retrieve the API token in GitHub by going to

Account -> Settings -> Developer Settings -> Personal Access Tokens

If you don’t have an API token, make sure to generate one, and give it full repo access

Setting up the Boozang integration

If you decide to maintain your Cucumber features in GitHub, you will need to synchronize your GitHub repository with Boozang. We do this by adding the GitHub API information (including access token) into Boozang.

Start by opening Boozang and navigate to

Settings > Integrations > Load features from VCS

Select GitHub from the dropdown menu, and replace the following tokens:

• {YOUR-GITHUB-ACCOUNT-NAME}: Your GitHub user name
• {YOUR-GITHUB-REPOSITORY-NAME}: The name of your repo
• /features: The feature directory name
• {MATCH-CURRENT-BZ-BRANCH}: Replace with hardcoded branch if needed, otherwise Boozang project branch will be inserted
• {YOUR-GITHUB-ACCOUNT-TOKEN}: Your GitHub API token

After this has been filled in, simply click “Check” button to verify the integration. A list of features should be shown.

Importing the features

Now it’s time to synchronize your feature files into Boozang. Make sure you are at the root directory of your project and click the “Kebab menu” (…) in the side-bar. You can also use the quick key combo “Ctrl + I”.

Sidebar Kebab -> Import features

Go ahead and click it and start synchronizing your features. As you can see, the features will be listed in the preview window before importing. If you want, you can click on an individual feature file to verify its contents before synchronizing.

After importing the features into Boozang, you can actually run any scenario. In the test report, you will simply say “NOT IMPLEMENTED”.

As soon as you update your Cucumber tests, simply re-import them again. None of the existing test mappings will be affected.

What now?

Now you can start mapping individual test steps to Boozang tests, increasing your test coverage step by step. I like to write a whole set of features up-front, import them in Boozang, and set up a test suite where I plug in all features, even if they are empty. I’ll copy down the test suite URL and plug it into my CI server, producing Cucumber reports showing all my features as “not implemented”. As features are being completed, I’ll create the automation code, and I can see from the CI job the progress I’m making in my project.