Use vansah-connect to send automated test results to Vansah after your tests run. It is a command-line tool you can call from a continuous integration and delivery (CI/CD) pipeline, such as GitHub Actions, Jenkins, GitLab CI, Bitbucket Pipelines or Azure DevOps.

This guide covers vansah-connect 2.0.0. It supports TestNG XML reports, Cucumber JSON reports and individual Test Case results. The tool records results in Vansah; it does not run your tests.

Before you begin

Install Vansah Test Management for Jira on the Jira site.
Create a Vansah API token and find your site’s API Connect URL.
Have the Jira space key, such as DEMO. It is required for all three upload methods in this version.
Install Node.js 18 or newer and npm on the machine or pipeline runner.
Create the Test Cases and destination work item, Test Folder or Test Plan in Vansah. For a plan, the target iteration must already exist.

1. Install the tool

npm install -g @vansah/vansah-connect
vansah-connect --version
vansah-connect --help

Use --version to check the installed release and --help to view its commands.

2. Configure the connection

For a pipeline, store the token in the pipeline’s secret store and provide these environment variables:

Variable	Value
`VANSAH_TOKEN`	Your Vansah API token.
`VANSAH_URL`	The API Connect URL shown in Vansah settings. Use your site’s URL; it may differ by region.
`VANSAH_PROJECT_KEY`	The Jira space key, such as DEMO.

For local use, save the settings with separate configuration commands:

vansah-connect -c "YOUR_VANSAH_TOKEN"
vansah-connect -v "YOUR_API_CONNECT_URL"
vansah-connect -p DEMO

Saved settings are stored in ~/.vansah-connect/.env. Values are read in this order: shell or pipeline environment variables → saved user settings → a .env file in the current directory → defaults. Keep credentials out of version control.

Run configuration commands separately from upload commands. Optional run properties can be supplied through VANSAH_ENVIRONMENT_NAME, VANSAH_SPRINT_NAME and VANSAH_RELEASE_NAME, or saved first:

vansah-connect --environment UAT --sprint "Sprint 1" --release "v1.2"

Environment applies to Cucumber uploads and individual results. Sprint and release apply to Cucumber uploads. TestNG uses the custom attributes in its XML report.

3. Choose an upload method

Option A: Upload a TestNG XML report

Add Vansah custom attributes to your TestNG test methods so the report identifies the existing Test Case and target Jira work item:

@Test(attributes = {
    @CustomAttribute(name = "Case Key", values = "DEMO-C1"),
    @CustomAttribute(name = "Tested Issue", values = "DEMO-9"),
    @CustomAttribute(name = "Tested Sprint", values = "Sprint 1"),
    @CustomAttribute(name = "Tested Environment", values = "UAT")
})
public void additionTest() {
    Assert.assertEquals(3 + 2, 5);
}

Case Key and Tested Issue are required. Tested Sprint and Tested Environment are optional. Attribute names are case-sensitive.

Run the tests, then upload the report:

vansah-connect -f ./target/testng-results.xml --format testng

TestNG uses the destinations in the XML. Plan flags and --itr do not retarget a TestNG report. See the TestNG XML import guide for report details.

Option B: Upload a Cucumber JSON report

Tag each scenario with its existing Vansah Test Case key, such as @DEMO-C54:

Feature: Login

  @DEMO-C54
  Scenario: Successful login
    Given a registered user
    When the user signs in with valid credentials
    Then the dashboard is displayed

You can also export tagged Cucumber feature files from Vansah. Scenarios without a valid Vansah Test Case tag are skipped.

Generate a Cucumber JSON report using your runner. For Cucumber.js, for example:

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

Upload it to a Jira work item or Test Folder:

# Jira work item
vansah-connect -f ./cucumber.json --format cucumber -a DEMO-9

# Test Folder
vansah-connect -f ./cucumber.json --format cucumber -a "regression/login/"

A value containing / is treated as a Test Folder path. Otherwise, -a is treated as a Jira work item key. See Getting the folder path of a Test Folder if you need the path.

Option C: Record an individual Test Case result

Use this when you want to record one result without a report file:

vansah-connect -t DEMO-C50 -s passed -a DEMO-9

For -s, use passed (or pass), failed, n/a, untested, n/a-in-progress, failed-in-progress or passed-in-progress. Use -a for a Jira work item key or Test Folder path.

4. Target a Test Plan and iteration

Cucumber uploads and individual results can target a Standard Test Plan or Advanced Test Plan. Use the plan’s key. For an Advanced Test Plan, also specify the work item or folder containing the case within the plan.

Target	Options
Standard Test Plan	`--stp DEMO-P2 --itr 2`
Advanced Test Plan	`--atp DEMO-P1 -a DEMO-9 --itr 2`

# Cucumber results in Standard Test Plan iteration 2
vansah-connect -f ./cucumber.json --format cucumber --stp DEMO-P2 --itr 2

# Cucumber results in Advanced Test Plan iteration 2
vansah-connect -f ./cucumber.json --format cucumber --atp DEMO-P1 -a DEMO-9 --itr 2

# Individual result in Advanced Test Plan iteration 2
vansah-connect -t DEMO-C50 -s passed --atp DEMO-P1 -a DEMO-9 --itr 2

Important: Create the iteration in Vansah first. --itr must be a positive whole number. The tool uses the inline value first, then VANSAH_ITERATION, then 1. It does not create a missing iteration.

Inline plan and iteration options affect the current upload without changing saved settings. Used without an upload, --mode, --stp, --atp and --itr save defaults. Passing -a overrides a saved plan mode unless you also select the plan inline. Use --mode normal on its own to save work item or folder targeting as the default.

5. Add the upload to your pipeline

Add an upload step after your tests. The following GitHub Actions example expects a VANSAH_TOKEN repository secret and a VANSAH_URL repository variable. Replace DEMO and DEMO-9 with your own keys.

- name: Upload Cucumber results to Vansah
  if: ${{ !cancelled() }}
  env:
    VANSAH_TOKEN: ${{ secrets.VANSAH_TOKEN }}
    VANSAH_URL: ${{ vars.VANSAH_URL }}
    VANSAH_PROJECT_KEY: DEMO
  run: |
    npm install -g @vansah/vansah-connect
    vansah-connect -f ./cucumber.json --format cucumber -a DEMO-9

The step runs unless the workflow is canceled. Ensure your test step produces cucumber.json even when tests fail, and adjust the report path to match your project.

6. Check the results in Vansah

Open the destination Jira work item, Test Folder or Test Plan.
For a plan, select the iteration used in the upload.
Check the Test Case keys, recorded results and available step details. Review the upload output for skipped or failed entries.

Troubleshooting

Problem	What to check
Missing token or Jira space key	Set VANSAH_TOKEN and VANSAH_PROJECT_KEY in the environment used by the upload step. Check whether saved user settings override a local .env file.
Missing or unsupported report format	Every file upload needs `--format testng` or `--format cucumber`.
Report file not found	Check that tests generated the report and that the upload command runs from the expected directory.
Unauthorized or Not Found	Check the token, its expiry, the site’s API Connect URL, Jira space key and your access to the destination.
Cucumber scenarios skipped	Check each scenario’s Vansah tag and confirm that its Test Case exists in the target space.
Plan or iteration error	Check the exact plan key, existing iteration number and Advanced Test Plan work item or folder context.

More help

See the official vansah-connect repository for current commands and examples, or contact Vansah Support with the command and error output. Remove credentials before sharing logs.

Sending Automated Test Results to Vansah from CI/CD