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
• ✅ Configurable: Easy to enable/disable via environment variables
• ✅ Custom Report Paths: Configure report directories 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-helper

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

# 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-helper";

export default defineConfig({
  testDir: "./tests",
  // ... other config
  
  // Add Xray integration
   globalSetup: require.resolve(
    "playwright-xray-helper/dist/src/setup/xray-global-setup"
  ),
  globalTeardown: require.resolve(
    "playwright-xray-helper/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 { setupXh, teardownXh } from "playwright-xray-helper";

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

  test.afterEach(async ({ page }, testInfo) => {
    // Your custom cleanup
    
    // Xray integration
    await teardownXh(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 | Custom Playwright report directory | ./playwright-report | | CUSTOM_REPORTS_DIR | Custom reports directory | ./reports | | CUSTOM_UPLOAD_DIR | Custom directory to upload as ZIP | "" (disabled) |

Configuration File

Create xrayconfig.json for test execution configuration:

{
  "testExecutionKey": "PROJ-123"
}

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
• Uploads custom directory as ZIP attachment (if configured)
• 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.

Why Use the NPM Package?

✅ Simplified Setup

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

✅ Easy Maintenance

• Automatic updates via npm update playwright-xray-helper
• 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 report directory exists (default: ./playwright-report)
   • If using custom paths, ensure PLAYWRIGHT_REPORT_DIR is correctly set in .env

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 using environment variables in your .env file:

# Custom Playwright report directory (default: ./playwright-report)
PLAYWRIGHT_REPORT_DIR=./my-custom-playwright-reports

# Custom reports directory (default: ./reports)
CUSTOM_REPORTS_DIR=./my-custom-reports

Custom Directory Upload

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

# Upload screenshots directory
CUSTOM_UPLOAD_DIR=./test-results/screenshots

# Upload logs directory
CUSTOM_UPLOAD_DIR=./test-results/logs

# Upload any custom directory
CUSTOM_UPLOAD_DIR=./my-custom-files

Features:

• ✅ Automatic ZIP Creation: Directory is automatically compressed
• ✅ Timestamped Filename: Files are named with timestamps for uniqueness
• ✅ Conditional Upload: Only uploads if directory exists and is configured
• ✅ Debug Logging: Full logging of upload process

Example .env configuration:

# Xray integration settings
XRAY_INTEGRATION=true
XRAY_CLIENT_ID=your_client_id_here
XRAY_CLIENT_SECRET=your_client_secret_here

# Custom report paths
PLAYWRIGHT_REPORT_DIR=./test-results/playwright-reports
CUSTOM_REPORTS_DIR=./test-results/custom-reports

# Custom directory upload (optional)
CUSTOM_UPLOAD_DIR=./test-results/screenshots

Conditional Integration

You can conditionally enable Xray integration based on environment:

// In your test files
if (process.env.XRAY_INTEGRATION === 'true') {
  await beforeEach(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, "-")}`;

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]
• Secondary Email: [email protected]
• Bitbucket: @repository
• Website: mla.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.