Nexus · test management for Jira
Menu
Get started

Connect your automation tools to Nexus

Keep running tests with the tools you already use. Send their results to Nexus to record executions against your Jira Test Cases. Your computer or CI runner executes the tests; Nexus receives the report and matches each result using its Automation Key.

Start with one existing test. Configure Nexus once, follow the section for your tool, then check that its result appears in Jira. When that works, use the CI setup guide to automate delivery after every pipeline run.

1. Prepare Nexus

  1. Open your Jira project's Project settings → Nexus → CI. Ask your project administrator for access if needed.
  2. Create an API key with ingest permission if the scope selector is available. Give it a recognisable label, such as Web tests — staging. Copy it when shown; the full key is only displayed once.
  3. Copy the results URL from the same page. Use this complete address, not your Jira project URL or the separate CI API URL.
  4. Open an existing Test Case, set its Automation Key to a unique value such as NEX-12, and make sure it is Ready. The examples below use NEX-12; replace it with your actual Automation Key. Setting a test's name alone does not create its matching Test Case.
  5. Note your Jira project key, such as NEX. Optionally note the Test Set (cycle) key you want results recorded against.

2. Make the connection values available

All methods below read these environment variables. Keep the API key outside source files and test configuration.

Variable Value
NEXUS_URL The complete results URL copied from Nexus
NEXUS_API_KEY Your Nexus ingest key, not an Atlassian account token
NEXUS_PROJECT Your Jira project key, for example NEX
NEXUS_ENVIRONMENT An environment label, for example staging
NEXUS_TEST_SET Optional existing Test Set/cycle key

For a local check, set the values in the terminal that will run your tests. These examples prompt for credentials rather than placing them in command history.

Bash:

read -r -s -p 'Nexus results URL: ' NEXUS_URL
printf '\n'
read -r -s -p 'Nexus ingest key: ' NEXUS_API_KEY
printf '\n'
export NEXUS_URL NEXUS_API_KEY
export NEXUS_PROJECT='NEX'
export NEXUS_ENVIRONMENT='staging'

PowerShell 7:

$env:NEXUS_URL = Read-Host 'Nexus results URL' -MaskInput
$env:NEXUS_API_KEY = Read-Host 'Nexus ingest key' -MaskInput
$env:NEXUS_PROJECT = 'NEX'
$env:NEXUS_ENVIRONMENT = 'staging'

Replace NEX with your project key. Close this terminal after your check. In CI, store the URL and key in the provider's secret store and expose them to the test or upload step; the CI guide explains each provider.

3. Choose one delivery method

Your test tool Recommended route Who sends the results?
Playwright Nexus Playwright reporter The reporter at the end of the run
Selenium with pytest Nexus pytest plugin The plugin at the end of the session
Cypress JUnit XML + upload CLI A separate upload step
Cucumber Cucumber JSON + upload CLI A separate upload step
JUnit / Maven Surefire XML + upload CLI A separate upload step
Mocha Mocha JSON + upload CLI A separate upload step

Send each report once. If you use the Playwright reporter or pytest plugin, do not also upload that run's report from your pipeline. A second submission can create duplicate executions.

For the four file-upload routes, download the standalone upload CLI, save it as nexus-upload.mjs in the root of your test project and run it with Node.js 22. It needs no package installation. This is the same file used in the CI guide. Keep the API key out of this file. Checksums are available for download verification.

Open the instructions for your framework below. These steps extend an existing working test suite; keep its browser, test dependencies and application setup.

Playwright

Install the Nexus reporter in your existing Playwright project:

npm install --save-dev https://nexus.resync.nz/downloads/nexus-playwright-reporter-0.1.0.tgz

Add this reporter setting to your existing defineConfig in playwright.config.ts, retaining your other settings:

reporter: [
  ['list'],
  ['@resyncnz/nexus-playwright-reporter', {
    failOnUploadError: true,
  }],
],

Rename one existing test to begin with its Automation Key: NEX-12: valid user signs in. Put the key on the individual test title, not just the enclosing describe.

npx playwright test --grep "NEX-12:"

The reporter reads your environment variables and sends the results automatically. failOnUploadError: true makes a failed upload visible as a failed run; without it, upload errors only produce warnings. See Playwright's reporter documentation for combining reporters.

Selenium with pytest

Selenium drives the browser; pytest supplies the results. In the environment where your existing pytest suite runs, install the Nexus plugin:

pip install https://nexus.resync.nz/downloads/pytest_nexus-0.1.0-py3-none-any.whl

Rename an existing test function to include test_NEX_12_valid_user_signs_in. Nexus recognises the code-safe NEX_12 as Automation Key NEX-12.

pytest -k NEX_12 --nexus-fail-on-upload-error

The plugin loads automatically, creates a temporary JUnit report and sends it. If you already use --junitxml, it sends that file instead. No separate upload is needed. For Selenium suites using another test runner, generate a supported report and use the CLI route.

Cypress

Start an existing test's title with NEX-12:. Use Cypress's built-in JUnit reporter; [hash] keeps different spec files from overwriting each other's reports.

npx cypress run --reporter junit --reporter-options "mochaFile=results/cypress-[hash].xml,toConsole=true"

Upload each XML file generated by this run separately. The CLI takes one filename, not a wildcard. For example, replacing the filename with an actual generated file:

node nexus-upload.mjs results/cypress-REPORT_HASH.xml --format junit-xml

Use a clean results directory for each run so stale files are not uploaded again. See Cypress reporting.

Cucumber

Start an existing scenario's name with NEX-12: or tag that scenario @NEX-12. For an existing Cucumber.js project, generate its legacy JSON report:

npx cucumber-js --format "json:results.json"
node nexus-upload.mjs results.json --format cucumber-json

Choose JSON, not the message formatter: newline-delimited Cucumber Messages are a different format. The JSON report is an array of features. Other Cucumber implementations can use the same upload command once configured to produce that report. See Cucumber.js formatters.

JUnit with Maven

In your existing JUnit suite, include NEX_12 in a test method name, for example NEX_12_validUserSignsIn. Nexus normalises this to NEX-12.

mvn test

Maven Surefire writes XML reports under target/surefire-reports/. Upload each newly generated TEST-*.xml file separately, using its actual filename:

node nexus-upload.mjs target/surefire-reports/TEST-com.example.LoginTest.xml --format junit-xml

Use XML reports, not the .txt summaries or HTML pages. Check the XML test name includes your key if your JUnit configuration changes display names.

Mocha

Start an existing it title with NEX-12:. Generate a report directly to a file, then upload it:

npx mocha --reporter json --reporter-option output=results.json
node nexus-upload.mjs results.json --format mocha-json

Mocha's JSON reporter writes the report even when tests fail. Use json, not json-stream.

4. Verify the first result

Run the test command and upload command as separate steps. If a test fails, still send the report it produced. In CI, configure the upload to run after failed tests without hiding the original test failure; see the provider examples.

  1. Look for HTTP 202 in the sender's output. This means accepted for background processing, not that every result has been recorded.
  2. Return to Project settings → Nexus → CI and inspect the delivery log. Confirm the result is matched to the expected Test Case.
  3. Open that Test Case's execution and check its status and environment. If you supplied NEXUS_TEST_SET, also check the intended cycle.

If something does not appear

What you see What to check
Missing configuration Variables must be set in the same terminal or CI step as the sender.
HTTP 401 Check the ingest key, its scope and project; replace revoked keys.
Unmatched result Check the Automation Key field and the name inside the actual report.
Skipped result Read the delivery-log reason and check the Test Case's state.
Missing report Confirm the test command ran, the output path and the working directory.
Invalid format / HTTP 400 Send the actual XML/JSON report, using the matching format above.
Report too large / HTTP 413 Split runs into reports under 5 MB and at most 500 results each.
Duplicate executions Keep only one sender per run; exclude old report files.

Once one test matches correctly, apply the naming convention to the rest of your suite and follow Connect your CI pipeline for repeatable delivery.