Playwright Xray Integration - Plug and Play

This is a plug-and-play solution for integrating Playwright test results with Jira Xray. It provides automatic test execution tracking, status reporting, and report uploads to Xray.

Features

• ✅ Automatic Test Execution Creation: Creates test executions in Jira Xray
• ✅ Real-time Status Updates: Reports test status (PASS/FAIL/EXECUTING) to Xray
• ✅ Report Uploads: Automatically uploads Playwright HTML reports and custom reports
• ✅ Custom Directory Uploads: Upload any directory to Jira as ZIP attachments
• ✅ Configurable: Easy to enable/disable via environment variables
• ✅ Debug Logging: Comprehensive logging for troubleshooting
• ✅ TypeScript Support: Full TypeScript definitions included
• ✅ Zero Configuration: No need to copy files or modify project structure
• ✅ Version Management: Easy updates and dependency management via npm

Quick Start

1. Install the Package

npm install playwright-xray-integration

Current Version: 1.0.2

2. Install Additional Dependencies

npm install dotenv
npm install --save-dev @playwright/test @types/node typescript

3. Configure Environment

Create a .env file based on .env.example:

# Enable Xray integration
XRAY_INTEGRATION=true

# Xray Cloud API credentials
XRAY_CLIENT_ID=your_client_id_here
XRAY_CLIENT_SECRET=your_client_secret_here
XRAY_BASE_URL=https://xray.cloud.getxray.app
XRAY_PROJECT_KEY=PROJ
JIRA_URL=https://example.com
[email protected]
JIRA_TOKEN=your_jira_token_value
JIRA_ADD_ATTACHMENT=true

# Optional
CUSTOM_UPLOAD_DIR=./custom-uploads

# Enable debug logging
XRAY_DEBUG=true

4. Update Playwright Config

Update your playwright.config.ts:

import { defineConfig, devices } from "@playwright/test";
import { globalSetup, globalTeardown } from "playwright-xray-integration";

export default defineConfig({
  testDir: "./tests",
  // ... other config
  
    // Add Xray integration
  globalSetup: require.resolve(
    "playwright-xray-integration/dist/src/setup/xray-global-setup"
  ),
  globalTeardown: require.resolve(
    "playwright-xray-integration/dist/src/teardown/xray-teardown"
  ),
  
  projects: [
    // ... your projects
  ],
});

5. Use in Your Tests

In your test files, import and use the Xray hooks:

import test, { expect } from "@playwright/test";
import { startXrayTest, finishXrayTest } from "playwright-xray-integration";

test.describe("My Test Suite", () => {
  test.beforeEach(async ({ page }, testInfo) => {
    // Xray integration
    await startXrayTest(page, testInfo);
    
    // Your custom setup
    await page.goto("https://example.com");
  });

  test.afterEach(async ({ page }, testInfo) => {
    // Your custom cleanup
    
    // Xray integration
    await finishXrayTest(page, testInfo);
  });

  test("My test", async ({ page }) => {
    await expect(page).toHaveTitle(/Example/);
  });
});

Configuration Options

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | XRAY_INTEGRATION | Enable/disable Xray integration | false | | XRAY_CLIENT_ID | Xray Cloud API client ID | Required | | XRAY_CLIENT_SECRET | Xray Cloud API client secret | Required | | XRAY_BASE_URL | Xray Cloud base URL | https://xray.cloud.getxray.app | | XRAY_PROJECT_KEY | Your Jira project key | Required | | XRAY_DEBUG | Enable debug logging | false | | PLAYWRIGHT_REPORT_DIR | Path to Playwright HTML reports | ./playwright-report | | CUSTOM_REPORTS_DIR | Path to custom reports directory | ./reports | | CUSTOM_UPLOAD_DIR | Path to custom directory for upload | "" (disabled) |

Configuration File

Create xrayconfig.json for test execution configuration:

{
  "testExecutionKey": "PROJ-123"
}

Note: The testExecutionKey is optional. If not provided, a new test execution will be created automatically.

How It Works

1. Global Setup

• Creates a test execution in Jira Xray
• Stores the test execution key and report link
• Runs before all tests

2. Test Execution

• Before Each Test: Starts test execution with "EXECUTING" status
• After Each Test: Updates test status to "PASS" or "FAIL"

3. Global Teardown

• Waits for Playwright HTML report generation
• Uploads Playwright report as ZIP attachment
• Uploads custom reports from ./reports directory
• Cleans up temporary files

File Structure

your-project/
├── tests/
│   └── your-tests.spec.ts          # Your test files
├── .env                            # Environment variables
├── xrayconfig.json                 # Xray configuration
└── playwright.config.ts            # Playwright configuration

Note: No need to copy any integration files! The package handles everything internally.

Package Structure

The package provides the following exports:

// Main functions for test integration
import { startXrayTest, finishXrayTest } from "playwright-xray-integration";

// Global setup and teardown for Playwright config
import { globalSetup, globalTeardown } from "playwright-xray-integration";

// Configuration and utilities
import { XRAY_CONFIG, logXray } from "playwright-xray-integration";

// TypeScript types
import { XRAY_STATUS, TestRunParams } from "playwright-xray-integration";

Why Use the NPM Package?

✅ Simplified Setup

• Single command installation: npm install playwright-xray-integration
• No file copying or manual configuration required
• Automatic TypeScript definitions included

✅ Easy Maintenance

• Automatic updates via npm update playwright-xray-integration
• Version management and dependency tracking
• Bug fixes and new features delivered automatically

✅ Clean Project Structure

• No additional source files cluttering your project
• All integration logic is contained within the package
• Your project remains focused on your actual tests

✅ Professional Integration

• Proper module exports and TypeScript support
• Consistent API across different projects
• Better error handling and debugging capabilities

Troubleshooting

Enable Debug Logging

Set XRAY_DEBUG=true in your .env file to see detailed logs:

[XRAY DEBUG] Xray integration is ENABLED, creating test execution
[XRAY DEBUG] Test execution summary: AUTOMATION-EXECUTION-2024-01-15T10-30-00.000Z
[XRAY DEBUG] Xray test execution created successfully

Common Issues

1. "Xray integration is DISABLED"

   • Check that XRAY_INTEGRATION=true in your .env file

2. Authentication errors

   • Verify your XRAY_CLIENT_ID and XRAY_CLIENT_SECRET
   • Ensure your Xray Cloud instance is accessible

3. Report upload failures

   • Check that Playwright HTML reports are being generated
   • Verify the ./playwright-report directory exists

4. Test execution not created

   • Check Xray Cloud API connectivity
   • Verify your project key is correct

Advanced Usage

Custom Report Paths

You can customize report paths in src/config/xray-config.ts:

export const XRAY_CONFIG = {
  // ... other config
  PLAYWRIGHT_REPORT_DIR: "./custom-playwright-reports",
  CUSTOM_REPORTS_DIR: "./custom-reports",
};

Conditional Integration

You can conditionally enable Xray integration based on environment:

// In your test files
if (process.env.XRAY_INTEGRATION === 'true') {
  await startXrayTest(page, testInfo);
}

Custom Test Execution Summary

Modify the test execution summary in src/setup/xray-global-setup.ts:

const summary = `CUSTOM-PREFIX-${new Date().toISOString().replace(/:/g, "-")}`;

Custom Directory Upload

You can upload any custom directory to Jira as a ZIP attachment by setting the CUSTOM_UPLOAD_DIR environment variable:

# In your .env file
CUSTOM_UPLOAD_DIR=./my-custom-reports

The directory will be automatically zipped and uploaded to the test execution in Jira.

Support

For issues with the xray-helper-integration package itself, refer to the official documentation.

For issues with this integration setup, check the debug logs and ensure all configuration is correct.

Author

Darvin Patel

• Email: [email protected]
• GitHub: @darvinpatel
• Website: darvinpatel.com

License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.