JIRA Xray Test Integration

A comprehensive Node.js package for integrating test automation with JIRA Xray Test Management. This package provides seamless test execution status updates, dynamic scenario name matching, and automated report attachments.

Features

✅ Dynamic Scenario Matching - Automatically matches test scenarios with JIRA test cases
✅ Status Updates - Update test execution status (PASS, FAIL, EXECUTING, TODO)
✅ Report Attachments - Attach HTML/JSON reports to test executions
✅ Multiple API Methods - Supports various Xray API endpoints for compatibility
✅ Fuzzy Matching - Intelligent matching with confidence scoring
✅ Batch Operations - Update multiple tests in a single operation

Installation

npm install jira-xray-test-integration

Quick Start

const { JiraTestResultUpdater, createJiraUpdater } = require('jira-xray-test-integration');

// Create JIRA updater instance
const jiraUpdater = createJiraUpdater({
  jiraUrl: 'https://jira.company.com',
  username: 'your-username',
  password: 'your-password-or-api-token'
});

// Update test status by scenario name (auto-matching)
await jiraUpdater.updateTestByScenarioName(
  'PROJ-123',                          // Test Execution Key
  'Verify login functionality',        // Scenario Name
  'PASS',                              // Status
  'Test passed successfully'           // Comment
);

// Attach report to test execution
await jiraUpdater.attachFileToIssue(
  'PROJ-123',                          // Test Execution Key
  './reports/test-report.html',        // Report Path
  'execution-report.html'              // Filename
);

API Reference

JiraTestResultUpdater

Main class for interacting with JIRA Xray APIs.

Constructor

const jiraUpdater = new JiraTestResultUpdater({
  jiraUrl: 'https://jira.company.com',    // Required
  username: 'your-username',               // Required
  password: 'your-password',               // Required
  projectKey: 'PROJ'                       // Optional
});

Methods

updateTestByScenarioName(testExecutionKey, scenarioName, status, comment, cachedMappings)

Automatically finds and updates a test by matching scenario name with test summaries.

Parameters:

• testExecutionKey (string) - Test execution issue key (e.g., 'PROJ-123')
• scenarioName (string) - Running scenario name to match
• status (string) - Test status: 'PASS', 'FAIL', 'EXECUTING', 'TODO'
• comment (string, optional) - Additional comment
• cachedMappings (object, optional) - Cached test mappings for performance

Returns: Promise

const result = await jiraUpdater.updateTestByScenarioName(
  'PROJ-123',
  'TC1_Verify login with valid credentials',
  'PASS',
  'All assertions passed'
);

if (result.success) {
  console.log(`Updated ${result.testKey} with ${result.confidence}% confidence match`);
}

updateTestExecutionStatus(testExecutionKey, testKey, status, comment)

Directly update a specific test's status (when you know the exact test key).

Parameters:

• testExecutionKey (string) - Test execution issue key
• testKey (string) - Specific test issue key (e.g., 'PROJ-456')
• status (string) - Test status
• comment (string, optional) - Additional comment

Returns: Promise

await jiraUpdater.updateTestExecutionStatus(
  'PROJ-123',
  'PROJ-456',
  'FAIL',
  'Assertion failed on line 45'
);

attachFileToIssue(issueKey, filePath, filename)

Attach a file (report, screenshot, log) to a JIRA issue.

Parameters:

• issueKey (string) - JIRA issue key
• filePath (string) - Path to the file
• filename (string, optional) - Custom filename for attachment

Returns: Promise

await jiraUpdater.attachFileToIssue(
  'PROJ-123',
  './reports/execution-report.html',
  'report-2025-11-11.html'
);

getAllTestsFromExecution(testExecutionKey)

Retrieve all tests associated with a test execution.

Parameters:

• testExecutionKey (string) - Test execution issue key

Returns: Promise

const result = await jiraUpdater.getAllTestsFromExecution('PROJ-123');

console.log(`Found ${result.totalTests} tests`);
result.testDetails.forEach(test => {
  console.log(`${test.key}: ${test.summary}`);
});

batchUpdateTestResults(testResults)

Update multiple test results in a single batch operation.

Parameters:

• testResults (Array) - Array of test configurations

Returns: Promise

const results = await jiraUpdater.batchUpdateTestResults([
  {
    testExecutionKey: 'PROJ-123',
    testKey: 'PROJ-456',
    status: 'PASS',
    comment: 'Test 1 passed',
    reportPath: './reports/test1.html'
  },
  {
    testExecutionKey: 'PROJ-123',
    testKey: 'PROJ-457',
    status: 'FAIL',
    comment: 'Test 2 failed'
  }
]);

JiraReportAttacher

Utility class for attaching reports to test executions.

Constructor

const { JiraReportAttacher } = require('jira-xray-test-integration');

const attacher = new JiraReportAttacher({
  jiraUrl: 'https://jira.company.com',
  username: 'your-username',
  password: 'your-password',
  testExecutionKey: 'PROJ-123',
  waitTime: 10000  // Optional: wait time for report generation (ms)
});

Methods

attachReport(reportPath, customFilename)

Attach a single report file.

await attacher.attachReport(
  './reports/test-report.html',
  'execution-report.html'
);

attachReportsWithWait(reportPaths, waitForGeneration)

Attach multiple reports with automatic wait for generation.

const result = await attacher.attachReportsWithWait([
  './reports/execution-report.html',
  './reports/allure-report.html'
], true);

console.log(`Attached ${result.totalAttached}/${result.totalAttempted} reports`);

Usage Examples

Integration with Cucumber Hooks

const { JiraTestResultUpdater } = require('jira-xray-test-integration');

let jiraUpdater;

Before(async function() {
  jiraUpdater = new JiraTestResultUpdater({
    jiraUrl: 'https://jira.company.com',
    username: process.env.JIRA_USERNAME,
    password: process.env.JIRA_PASSWORD
  });
});

After(async function({ result }) {
  const testExecutionKey = process.env.TEST_EXECUTION_KEY;
  const status = result.status === 'PASSED' ? 'PASS' : 'FAIL';
  
  await jiraUpdater.updateTestByScenarioName(
    testExecutionKey,
    this.scenarioName,
    status,
    result.message
  );
});

Standalone Report Attachment

const { createReportAttacher } = require('jira-xray-test-integration');

async function attachTestReports() {
  const attacher = createReportAttacher({
    jiraUrl: 'https://jira.company.com',
    username: process.env.JIRA_USERNAME,
    password: process.env.JIRA_PASSWORD,
    testExecutionKey: 'PROJ-123',
    waitTime: 15000
  });

  const result = await attacher.attachReportsWithWait([
    './reports/html-report.html',
    './reports/json-report.json'
  ]);

  if (result.success) {
    console.log('All reports attached successfully!');
  }
}

attachTestReports();

Batch Test Updates

const { createJiraUpdater } = require('jira-xray-test-integration');

async function updateAllTests(testResults) {
  const jiraUpdater = createJiraUpdater({
    jiraUrl: 'https://jira.company.com',
    username: process.env.JIRA_USERNAME,
    password: process.env.JIRA_PASSWORD
  });

  const updates = testResults.map(test => ({
    testExecutionKey: 'PROJ-123',
    testKey: test.jiraKey,
    status: test.passed ? 'PASS' : 'FAIL',
    comment: test.errorMessage || 'Test completed',
    reportPath: test.reportPath
  }));

  await jiraUpdater.batchUpdateTestResults(updates);
}

Configuration

Environment Variables

# JIRA credentials
export JIRA_URL="https://jira.company.com"
export JIRA_USERNAME="your-username"
export JIRA_PASSWORD="your-password-or-api-token"

# Test execution key
export TEST_EXECUTION_KEY="PROJ-123"

Supported Status Values

• PASS / PASSED / SUCCESS → PASS
• FAIL / FAILED / ERROR → FAIL
• EXECUTING → EXECUTING
• TODO → TODO

Dynamic Scenario Matching

The package includes intelligent scenario name matching with multiple strategies:

1. Exact Match - 100% confidence
2. Partial Match - Contains matching (70%+ confidence)
3. Keyword Match - Word-based matching (30%+ confidence)
4. Fuzzy Match - Character-based similarity

// Scenario: "TC1_Verify login with valid credentials"
// Will match JIRA test: "Verify login with valid credentials" (100%)
// Will match JIRA test: "TC1 - Verify login functionality" (85%)
// Will match JIRA test: "Login verification test" (60%)

Error Handling

All methods return a result object with success status:

const result = await jiraUpdater.updateTestByScenarioName(...);

if (result.success) {
  console.log('✅ Success:', result.testKey);
} else {
  console.error('❌ Error:', result.error);
  
  // Check for suggestions
  if (result.suggestions) {
    console.log('💡 Did you mean:');
    result.suggestions.forEach(s => {
      console.log(`  - ${s.summary} (${s.confidence}%)`);
    });
  }
}

Requirements

• Node.js >= 14.0.0
• @playwright/test >= 1.40.0 (peer dependency)
• JIRA with Xray plugin installed
• Valid JIRA credentials with appropriate permissions

License

MIT

Author

Dhivakar AnthonyDoss

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions, please open an issue on GitHub.