Overview

Some customers ask whether they should integrate WebdriverIO and SpiraTest using a direct reporter, such as a framework-specific plugin (e.g. our Mocha or Jasmine integration). While that can work in some stacks, for WebdriverIO + Cucumber the cleaner and more maintainable option is usually:

  1. Author and run tests in WebdriverIO + Cucumber
  2. Generate JUnit XML result files
  3. Import those results into SpiraTest using our xUnit importer

This pattern keeps execution and result publication loosely coupled. It also makes the automation framework easier to maintain because the test suite continues to use standard WebdriverIO reporting, while Spira consumes the resulting XML through its documented xUnit interface.

You can use either the NodeJS or Python versions of our xUnit importer, but since WebdriverIO normally uses NodeJS, we recommend the former option.

Why This Approach Is Recommended

This integration pattern is recommended for several reasons.

  1. WebdriverIO already provides an official JUnit reporter that creates JUnit-compatible XML files. That makes it a natural fit for teams already running WebdriverIO in local environments, CI servers, or containerized pipelines.
  2. WebdriverIO supports Cucumber as a first-class framework option, so customers using BDD scenarios do not need to restructure their framework or move to Mocha just to report to Spira.
  3. Our xUnit integration is specifically intended to read xUnit-format XML files and import the results into Spira. It uses a configuration file to connect XML test identifiers to Spira test cases and optionally to a release or test set.

Finally, this approach works well in CI/CD because the XML output becomes a reusable artifact. Teams can archive it, inspect it for troubleshooting, publish it to CI dashboards, and then import the same result set into Spira. WebdriverIO’s JUnit reporter documentation also notes that XML files are generated per runner/spec, which fits well with parallel execution.

High-Level Workflow

A typical end-to-end workflow looks like this:

  • Create or maintain the corresponding test cases in SpiraTest
  • Configure WebdriverIO to run with the Cucumber framework
  • Add the JUnit reporter to WebdriverIO
  • Execute the automated tests
  • Generate one or more JUnit XML files
  • Run our Spira xUnit importer
  • Have the importer publish the results into SpiraTest

At that point, the test run results are available inside Spira and can be associated with the relevant release, test set, and test cases configured in the integration settings.

Prerequisites

Before setting up the integration, make sure you have:

  • A working SpiraTest, SpiraTeam, or SpiraPlan environment
  • A valid Spira user account and RSS token for API-based result submission
  • A working WebdriverIO project
  • The Cucumber framework adapter installed in that WebdriverIO project
  • The JUnit reporter installed in the WebdriverIO project
  • NodeJS available on the machine or build agent that will run the Spira xUnit importer

The NodeJS version of the Spira xUnit integration is available for download on the official NPM site.

Step 1: Configure WebdriverIO to Use Cucumber

In your wdio.conf.js or equivalent configuration file, make sure WebdriverIO is set to use the Cucumber framework:

framework: 'cucumber'
 

WebdriverIO documents Cucumber support through the @wdio/cucumber-framework package and configuration option.

Step 2: Install and Configure the JUnit Reporter

Install the reporter in your WebdriverIO project:

npm install @wdio/junit-reporter --save-dev

Then add it to the reporters section of your WebdriverIO configuration. A simple example is:

reporters: [[
'junit',
{
outputDir: './results/junit'
}
]]

WebdriverIO’s JUnit reporter is designed to create Jenkins-compatible XML reports. WebdriverIO also recommends file-based output for reporters like JUnit, which makes outputDir an important part of the setup.

Step 3: Use Stable Test Names

Our Spira xUnit importer maps XML test results to Spira test cases using test identifiers from the XML. For that reason, it is important to keep your WebdriverIO JUnit output stable and predictable.

In practice, this means:

  • Avoid changing feature and scenario names unnecessarily
  • Use consistent naming conventions
  • Configure reporter options so the XML suite/class names are deterministic
  • Verify the generated XML before setting up the final Spira mapping

This matters because the xUnit integration expects test result names from the XML to match entries in the spira.cfg mapping file.

Step 4: Create the Spira Configuration File

Inflectra’s xUnit importer uses a configuration file, typically named spira.cfg, to connect the XML results to Spira.

A representative configuration looks like this:

[credentials]
url = https://mycompany.spiraservice.net
username = automation.user
token = {RSS_TOKEN}
project_id = 1
release_id = 2
test_set_id = 3
create_build = true

[test_cases]
LoginFeature.valid_login = 101
LoginFeature.invalid_login = 102
CheckoutFeature.submit_order = 103

In this configuration:

  • url points to the Spira system
  • username and token provide authentication
  • project_id identifies the product in Spira
  • release_id is optional but useful when you want results tied to a release
  • test_set_id is optional if you want the run associated with a specific test set
  • [test_cases] maps XML identifiers to Spira test case IDs

Our Spira xUnit integration documentation describes these configuration elements and explains that the importer can report against a release and optional test set.

Step 5: Install the Inflectra xUnit Importer

On the machine that will publish results to Spira, install the Spira xUnit integration package:

npm install spira-addons-xunit

Then invoke the importer against the XML output and configuration file:

node spira-xunit-reader.js ./results/junit/results.xml spira.cfg

We recommend installation via npm and execution through the spira_xunit_reader module.

Step 6: Run the Full Flow

A simple pipeline sequence looks like this:

npx wdio run wdio.conf.js
node spira-xunit-reader.js ./results/junit/results.xml spira.cfg

In CI/CD, this is typically split into two stages:

  1. Execute automation
  2. Publish test results to Spira

That separation usually makes troubleshooting easier. If a test fails, the XML is still available for inspection before the import step runs. WebdriverIO’s JUnit reporter is also commonly used in CI systems such as Jenkins for exactly this kind of artifact-based reporting flow.

Best Practices

Keep the XML Names Predictable

The most important implementation detail is naming consistency. If your XML identifiers change from run to run, the mapping to Spira test case IDs becomes fragile. Use stable feature and scenario names and review the XML structure early in the setup.

Start with a Small Pilot

Begin with a small set of Cucumber scenarios and a few Spira test cases. Once the mapping is working correctly, expand the integration to additional features. This reduces setup time and makes naming issues easier to catch.

Use CI/CD Artifacts

Store the generated JUnit XML as a pipeline artifact. This gives the team a permanent record of the original execution results and simplifies troubleshooting when imports do not behave as expected. This is especially useful because WebdriverIO’s JUnit reporter generates XML files intended for external consumption by CI tools.

Model Automated Tests Clearly in Spira

In Spira, the simplest pattern is often to use one automated test case per scenario or logical automated test and keep the linkage between requirements, releases, and automation clear. The xUnit importer then becomes the bridge between the automation result and the Spira artifact model.