Setting up a BDD project with Test Collab

Introduction

Behavior Driven Development (BDD) helps teams describe system behavior in plain English using Gherkin syntax. With Test Collab, you can connect your .feature files from Git and sync them into your projects.

In this guide you’ll learn how to:

Try the BDD Demo Project
Create a new BDD project from scratch
Sync and update .feature files
Fix common setup errors

Step 1: Create a Project in Test Collab

When you click Add Project, you’ll see two options:

BDD Project
Choose this if you plan to sync .feature files from Git using Gherkin.
Regular Project
Choose this if you want to manage test cases directly in the Test Collab interface.

👉 For this guide, select BDD Project.

Note: This choice is mainly informational — it highlights your workflow but does not restrict functionality.

After creating the project, note down its Project ID. You can find it in the project’s URL in your browser. Example:

https://app.testcollab.com/projects/123 → the ID is 123.

Step 2: Fork our BDD demo Project (Optional) (or use your own repo)

If you want to see BDD in action before setting up your own, try our BDD Demo Project on GitHub.

The demo repo already includes:

A sample features/ folder with .feature files
Instructions for syncing with Test Collab
Example outputs so you know what to expect

Quick start commands:

git clone https://github.com/TCSoftInc/testcollab-bdd-demo.git

cd testcollab-bdd-demo

If you are using your own repo, make sure 'features' directory exists along with at least one .feature file.

Step 3: Create API key + Setup

Generate an API Token

Go to My Profile Settings > API Token.
Click Generate Token and copy it.
Keep it secure — you’ll need it for syncing.

1. Setup NPM package testcollab-cli

a) Global install

npm install -g testcollab-cli

# verify installation
tc --help

-or-

b) Set up as dev dependency

npm install --save-dev testcollab-cli

# verify installation
npx tc --help

Add a Feature File to your repo (skip if you already have these)

Inside features/, create login.feature:

Feature: Login

  Scenario: Successful login
    Given user is on the login page
    When user enters valid credentials
    Then user should be redirected to the dashboard

Run Initial Sync

Export your token and run sync op:

export TESTCOLLAB_TOKEN=your_token   # macOS/Linux
set TESTCOLLAB_TOKEN=your_token      # Windows

tc sync --project YOUR_PROJECT_ID

✅ Example output:

Sync started...
Uploading features/login.feature
Sync completed successfully. 1 feature(s) synced.

Now go to your project in Test Collab and you should see all test cases and test suites created.

Step 4: Updating and Re-syncing

Edit your .feature files locally
Save and commit with Git
Run the sync command again

Your changes will now appear in Test Collab like this:

Step 5: Setup CI sync

Ideally you would want to call sync everytime a new .feature file is added or the existing ones are modified. In order to achieve that you need to fire same command we used before:

tc sync --project YOUR_PROJECT_ID

from within your CI process. This will keep all changes synced, as make your git repo as source of truth for all scenarios.

Following snippets show how to achieve this with GitHub and GitLab

GitHub Actions

Create TESTCOLLAB_TOKEN as a secret

name: Sync Feature Files
on:
  push:
    branches: [main]
    paths: ['**/*.feature']

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0  # Important: fetch full history
      
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      - run: npm install -g testcollab-cli
      
      - run: tc featuresync --project ${{ secrets.TESTCOLLAB_PROJECT_ID }}
        env:
          TESTCOLLAB_TOKEN: ${{ secrets.TESTCOLLAB_TOKEN }}

GitLab CI

Add TESTCOLLAB_TOKEN as build environment variable.

In your .gitlab-ci.yml add following job:

sync-features:
  stage: test
  image: node:18
  before_script:
    - npm install -g testcollab-cli
  script:
    - tc featuresync --project $TESTCOLLAB_PROJECT_ID
  variables:
    TESTCOLLAB_TOKEN: $TESTCOLLAB_TOKEN
  only:
    changes:
      - "**/*.feature"

Modify 'stage' as per your workflow.

Troubleshooting

“Not inside Git repo” → Run git init.
“Missing TESTCOLLAB_TOKEN” → Export your API token before syncing.
API/Network issues → Check your internet connection or regenerate token.
400 Error codes → Permissions issues, make sure user who generated API token has all permissions required to create / edit test cases and test suites

Next Steps

Now that your BDD project is set up, you can:

Add more .feature files for broader coverage
Organize scenarios into suites

Copying test cases to another project

TestCollab Cypress Reporter Plugin

Set up Asana defect management integration