GitHub - testpointcorp/vansah-cucumber: Import Cucumber test results into Vansah Test Management for Jira automatically using APIs. Seamlessly integrates with Maven, Selenium, Playwright, and any Cucumber-based automation framework.

Import Cucumber test results to Vansah Test Management for Jira automatically via API. Seamlessly integrates with any Cucumber-based project regardless of programming language.

Website • More Connect Integrations

Prerequisites

1. Vansah API Token

You need a Vansah API token to authenticate with the API.

First generate a Jira API Token from your Atlassian account
In your Jira workspace go to Apps → Vansah → Settings → Vansah API Tokens
Click Create API Token and fill in:
- Label - a name to identify the token
- Jira Email Address
- Jira API Token (from step 1)
- Expiry Date
Click Create and copy the token immediately - it is shown only once and cannot be retrieved again

Full guide: Create Vansah API Token

2. Vansah API URL

Your API URL is unique to your Jira workspace region. To find it:

Go to Apps → Vansah → Settings → Vansah API Tokens
The API Connect URL is displayed on that page

Use this URL as VANSAH_URL in your configuration. It may differ depending on your workspace's data residency location.

Full guide: Vansah API Connect URL

How It Works

Your Cucumber Tests (any language)
        │
        ▼
  cucumber.json  ◄── test result/report file, same format regardless of language
        │
        ▼
  import_results.sh  OR  import_results.ps1
        │
        ▼
  Vansah Test Management (Jira)

Step 1 - Get Your Feature File

You have two options: export directly from Vansah (recommended) or tag your existing scenarios manually.

Option A - Export from Vansah UI (Recommended)

If your test cases are already defined in Vansah, you can export them as a ready-to-use .feature file with @TC-KEY tags pre-populated - no manual tagging needed.

Open your Jira project and navigate to Vansah
Go to the Test Repository / Work Item / Test Plan and select the test cases you want to export
Click Export → Test Cases and Test Script → Cucumber (.feature)
Vansah reads your BDD-style test cases and downloads a valid .feature file

The exported file is immediately usable in any Cucumber framework - just drop it into your features/ directory.

For a full walkthrough see the Cucumber Feature Export article.

Option B - Tag Your Scenarios Manually

If you are writing feature files from scratch, add a Vansah test case tag to each scenario:

Feature: User Authentication

  @TEST-C1
  Scenario: Valid login with correct credentials
    Given I am on the login page
    When I enter valid credentials
    Then I should see the dashboard

  @TEST-C2
  Scenario: Invalid login with wrong password
    Given I am on the login page
    When I enter wrong credentials
    Then I should see an error message

Supported tag format

Format	Example
`@{PROJECT}-C{NUMBER}`	`@TEST-C44`

Scenarios without a Vansah tag are silently skipped during import - your test suite keeps running normally.

Step 2 - Generate cucumber.json

Configure your Cucumber runner to output a JSON report. The command differs per language but the output format is identical.

JavaScript / TypeScript

npx cucumber-js --format json:cucumber.json

Java (Maven)

Add the JSON formatter to your runner class:

@CucumberOptions(plugin = {"json:target/cucumber-reports/cucumber.json"})

Then run your tests:

mvn test

Python (behave)

behave --format json -o cucumber.json

Ruby

cucumber --format json --out cucumber.json

.NET (SpecFlow)

Add the SpecFlow.Plus.LivingDocPlugin NuGet package for JSON output, then run your tests:

dotnet test

Step 3 - Configure

Copy env.example to .env and fill in your values:

VANSAH_TOKEN=your_token_here
VANSAH_PROJECT_KEY=SCRUM
VANSAH_URL=https://prod.vansah.com

# Provide one of the following (required):
TEST_FOLDER_PATH=folderPath/
# JIRA_ISSUE_KEY=SCRUM-1
# STANDARD_TEST_PLAN_KEY=SCRUM-P2

# Advanced Test Plan (optional) - if set, also requires TEST_FOLDER_PATH or JIRA_ISSUE_KEY above
# ADVANCED_TEST_PLAN_KEY=SCRUM-P1

# Optional
# SPRINT_NAME=Sprint 1
# RELEASE_NAME=v1.0.0
# ENVIRONMENT_NAME=UAT

Where to find these values:

VANSAH_TOKEN - See Prerequisites → Vansah API Token
VANSAH_URL - See Prerequisites → Vansah API URL
TEST_FOLDER_PATH - See Getting the Folder Path of a Test Folder

Step 4 - Import Results

Option A - Shell script

macOS / Linux

Run with the default report path (target/cucumber-reports/cucumber.json):

./import_results.sh

Or specify a custom report path using the -f flag:

./import_results.sh -f path/to/cucumber.json

Windows (PowerShell)

PowerShell 5.1 is pre-installed on Windows 10/11 - no admin or extra tools required.

Run with the default report path (cucumber.json):

.\import_results.ps1

Or specify a custom report path using the -f flag:

.\import_results.ps1 -f path\to\cucumber.json

Running into an error? See Troubleshooting → PowerShell Script (Windows).

Troubleshooting

Solutions to common errors across the import scripts.

If your issue is not listed here, open a GitHub issue and describe the error, the script/tool you are using, and the full output.

PowerShell Script (Windows)

Script cannot be loaded - execution policy

Error

.\import_results.ps1 cannot be loaded because running scripts is disabled on this system.

Fix - Run once in PowerShell (no admin required):

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

.env file not being picked up

Symptom: Variables set in .env are not recognised even though the file exists.

Fix: Make sure the .env file is in the same directory you are running the script from, and that there are no spaces around the = sign:

VANSAH_TOKEN=your_token_here   # correct
VANSAH_TOKEN = your_token_here # incorrect - spaces cause parse failure

Script file not found

Error

The term '.\import_results.ps1' is not recognized

Fix: Make sure you are in the repository root directory before running the script:

cd path\to\vansah-cucumber
.\import_results.ps1 -f path\to\cucumber.json

ADVANCED_TEST_PLAN_KEY used without folder or issue

Error

Error: ADVANCED_TEST_PLAN_KEY requires TEST_FOLDER_PATH or JIRA_ISSUE_KEY

Fix: Add one of the required context assets alongside ADVANCED_TEST_PLAN_KEY in your .env:

ADVANCED_TEST_PLAN_KEY=TEST-P1
TEST_FOLDER_PATH=TEST/Test Repository   # add this

Bash Script (macOS / Linux)

Permission denied

Error

bash: ./import_results.sh: Permission denied

Fix: Make the script executable:

chmod +x import_results.sh

Report file not found

Error

❌ Error: Report not found: cucumber.json

Fix: Run your Cucumber tests first to generate the report (see Step 2), then import:

./import_results.sh -f path/to/cucumber.json

VANSAH_TOKEN not set

Error

❌ Error: VANSAH_TOKEN not set

Fix: Either add it to your .env file or export it in your shell:

export VANSAH_TOKEN=your_token_here

ADVANCED_TEST_PLAN_KEY used without folder or issue

Error

❌ Error: When using ADVANCED_TEST_PLAN_KEY, you must also provide TEST_FOLDER_PATH or JIRA_ISSUE_KEY

Fix: Add one of the required context assets alongside ADVANCED_TEST_PLAN_KEY in your .env:

ADVANCED_TEST_PLAN_KEY=TEST-P1
TEST_FOLDER_PATH=TEST/Test Repository   # add this

API Errors

HTTP 401 - Unauthorized

Cause: The VANSAH_TOKEN is invalid, expired, or missing.

Fix:

Confirm the token is copied correctly with no extra spaces
Check the token expiry date in Apps → Vansah → Settings → Vansah API Tokens
Generate a new token if expired - see Create Vansah API Token

HTTP 403 - Forbidden

Cause: The token does not have permission for this project.

Fix: Ensure the Jira account used to generate the token has access to the project specified in VANSAH_PROJECT_KEY.

HTTP 404 - Not Found

Cause: Wrong API URL or project key.

Fix:

Verify VANSAH_URL matches your workspace's API Connect URL - see Vansah API Connect URL
Verify VANSAH_PROJECT_KEY matches your Jira project key exactly (case-sensitive)

HTTP 500 - Internal Server Error

Cause: An unexpected error on the Vansah server side.

Fix: Retry after a short wait. If the error persists, contact Vansah support with the response body.

Still stuck?

If your issue is not covered above, open a GitHub issue and include:

The script you are using (import_results.sh or import_results.ps1)
The full error message or output
Your OS and shell

Developed by Vansah

Name		Name	Last commit message	Last commit date
.gitignore		.gitignore
README.md		README.md
env.example		env.example
import_results.ps1		import_results.ps1
import_results.sh		import_results.sh

Navigation Menu

Repository files navigation

Table of Contents

Prerequisites

1. Vansah API Token

2. Vansah API URL

How It Works

Step 1 - Get Your Feature File

Option A - Export from Vansah UI (Recommended)

Option B - Tag Your Scenarios Manually

Supported tag format

Step 2 - Generate cucumber.json

Step 3 - Configure

Step 4 - Import Results

Option A - Shell script

Troubleshooting

PowerShell Script (Windows)

Script cannot be loaded - execution policy

.env file not being picked up

Script file not found

ADVANCED_TEST_PLAN_KEY used without folder or issue

Bash Script (macOS / Linux)

Permission denied

Report file not found

VANSAH_TOKEN not set

ADVANCED_TEST_PLAN_KEY used without folder or issue

API Errors

HTTP 401 - Unauthorized

HTTP 403 - Forbidden

HTTP 404 - Not Found

HTTP 500 - Internal Server Error

Still stuck?

About

Releases

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Table of Contents

Prerequisites

1. Vansah API Token

2. Vansah API URL

How It Works

Step 1 - Get Your Feature File

Option A - Export from Vansah UI (Recommended)

Option B - Tag Your Scenarios Manually

Supported tag format

Step 2 - Generate cucumber.json

Step 3 - Configure

Step 4 - Import Results

Option A - Shell script

Troubleshooting

PowerShell Script (Windows)

Script cannot be loaded - execution policy

.env file not being picked up

Script file not found

ADVANCED_TEST_PLAN_KEY used without folder or issue

Bash Script (macOS / Linux)

Permission denied

Report file not found

VANSAH_TOKEN not set

ADVANCED_TEST_PLAN_KEY used without folder or issue

API Errors

HTTP 401 - Unauthorized

HTTP 403 - Forbidden

HTTP 404 - Not Found

HTTP 500 - Internal Server Error

Still stuck?

About

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages