@inovvia/japa-reporter-report-portal

Report Portal reporter for the Japa test framework. Send your test results to Report Portal for centralized test reporting and analytics.

Features

• Seamless Integration - Works directly with Japa's reporter system
• Full Test Hierarchy - Preserves suites, groups, and tests structure in Report Portal
• Detailed Error Reporting - Automatically logs errors and stack traces
• Flexible Authentication - Supports both API key and OAuth authentication
• TypeScript First - Full type definitions included
• Configurable - Extensive options for customization
• Launch Merging - Support for parallel test runs with launch merge

Table of Contents

• Installation
• Quick Start
• Configuration
  • Required Options
  • Optional Options
  • OAuth Authentication
• Advanced Usage
  • Launch Attributes
  • Debug Mode
  • Conditional Activation
  • Launch Modes
• Environment Variables
• TypeScript Support
• Test Structure Mapping
• Troubleshooting
• Contributing
• License

Installation

npm install @inovvia/japa-reporter-report-portal

Peer Dependencies

This package requires @japa/runner version 5.0.0 or higher:

npm install @japa/runner

Quick Start

1. Configure Japa

In your test configuration file (e.g., bin/test.js or bin/test.ts):

import { configure, processCLIArgs, run } from '@japa/runner'
import { RPReporter } from '@inovvia/japa-reporter-report-portal'

processCLIArgs(process.argv.splice(2))

configure({
  files: ['tests/**/*.spec.js'],
  
  reporters: {
    activated: ['spec', 'report-portal'],
    list: [
      spec(),
      {
        name: 'report-portal',
        handler: (runner, emitter) => {
          const reporter = new RPReporter({
            endpoint: 'http://your-rp-server:8080/api/v2',
            project: 'your-project',
            launch: 'Your Launch Name',
            apiKey: 'your-api-key',
          })
          reporter.boot(runner, emitter)
        },
      },
    ],
  },
})

run()

2. Using Environment Variables (Recommended)

For better security, use environment variables for sensitive configuration:

import 'dotenv/config' // optional, for loading .env files
import { configure, processCLIArgs, run } from '@japa/runner'
import { RPReporter } from '@inovvia/japa-reporter-report-portal'

const rpConfig = {
  endpoint: process.env.RP_ENDPOINT,
  project: process.env.RP_PROJECT,
  launch: process.env.RP_LAUNCH || 'Japa Tests',
  apiKey: process.env.RP_API_KEY,
}

configure({
  files: ['tests/**/*.spec.js'],
  
  reporters: {
    activated: ['spec', 'report-portal'],
    list: [
      spec(),
      {
        name: 'report-portal',
        handler: (runner, emitter) => new RPReporter(rpConfig).boot(runner, emitter),
      },
    ],
  },
})

run()

Create a .env file in your project root:

RP_ENDPOINT=http://your-rp-server:8080/api/v2
RP_PROJECT=your-project
RP_LAUNCH=Japa Tests
RP_API_KEY=your-api-key

Configuration

Required Options

| Option | Type | Description | |--------|------|-------------| | endpoint | string | Report Portal API endpoint URL (e.g., http://localhost:8080/api/v2) | | project | string | Report Portal project name | | launch | string | Name of the launch in Report Portal | | apiKey | string | Report Portal API key (found in User Profile > API Keys) |

Optional Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | description | string | - | Description for the launch | | attributes | Attribute[] | - | Array of attributes to attach to the launch | | mode | LAUNCH_MODES | 'DEFAULT' | Launch mode: 'DEFAULT' or 'DEBUG' | | debug | boolean | false | Enable debug logging | | launchId | string | - | Existing launch ID to use (for merge launches) | | rerun | boolean | false | Mark as rerun | | rerunOf | string | - | UUID of the launch to rerun | | skippedIssue | boolean | true | Report skipped tests as issues | | extendTestDescriptionWithLastError | boolean | true | Add error message to test description | | isLaunchMergeRequired | boolean | false | Enable launch merge mode | | headers | Record<string, string> | - | Custom HTTP headers | | restClientConfig | AxiosRequestConfig | - | Custom Axios configuration |

OAuth Authentication

Instead of apiKey, you can use OAuth authentication:

const rpConfig = {
  endpoint: 'http://your-rp-server:8080/api/v2',
  project: 'your-project',
  launch: 'Your Launch Name',
  oauth: {
    tokenEndpoint: 'http://your-auth-server/oauth/token',
    username: 'your-username',
    password: 'your-password',
    clientId: 'your-client-id',
    clientSecret: 'your-client-secret', // optional
    scope: 'your-scope', // optional
  },
}

Advanced Usage

Launch Attributes

Add metadata to your launches for better filtering and organization:

const rpConfig = {
  endpoint: process.env.RP_ENDPOINT,
  project: process.env.RP_PROJECT,
  launch: process.env.RP_LAUNCH,
  apiKey: process.env.RP_API_KEY,
  description: 'Automated test run for feature X',
  attributes: [
    { key: 'environment', value: 'staging' },
    { key: 'browser', value: 'chrome' },
    { key: 'version', value: '1.2.3' },
    { value: 'smoke-test' }, // key is optional
  ],
}

Debug Mode

Enable debug mode to see detailed logs of what's being sent to Report Portal:

const rpConfig = {
  // ... other options
  debug: true,
}

Or via environment variable:

RP_DEBUG=true npm test

Conditional Activation

Only enable Report Portal when properly configured:

const rpConfig = {
  endpoint: process.env.RP_ENDPOINT,
  project: process.env.RP_PROJECT,
  launch: process.env.RP_LAUNCH,
  apiKey: process.env.RP_API_KEY,
}

const isRPConfigured = rpConfig.apiKey && rpConfig.endpoint

configure({
  files: ['tests/**/*.spec.js'],
  
  reporters: {
    activated: isRPConfigured ? ['spec', 'report-portal'] : ['spec'],
    list: [
      spec(),
      ...(isRPConfigured ? [{
        name: 'report-portal',
        handler: (runner, emitter) => new RPReporter(rpConfig).boot(runner, emitter),
      }] : []),
    ],
  },
})

Launch Modes

| Mode | Description | |------|-------------| | DEFAULT | Normal launch mode (visible in Report Portal UI) | | DEBUG | Debug mode (launches are hidden by default in UI) |

import { RPReporter, LAUNCH_MODES } from '@inovvia/japa-reporter-report-portal'

const rpConfig = {
  // ... other options
  mode: LAUNCH_MODES.DEBUG,
}

Environment Variables

| Variable | Description | |----------|-------------| | RP_ENDPOINT | Report Portal API endpoint | | RP_PROJECT | Report Portal project name | | RP_LAUNCH | Launch name | | RP_API_KEY | API key for authentication | | RP_LAUNCH_ID | Existing launch ID (for merge mode) | | RP_DEBUG | Enable debug logging (true or 1) |

TypeScript Support

This package includes TypeScript type definitions. Import types as needed:

import { 
  RPReporter, 
  ReportPortalConfig, 
  Attribute,
  STATUSES,
  LAUNCH_MODES,
} from '@inovvia/japa-reporter-report-portal'

const config: ReportPortalConfig = {
  endpoint: 'http://localhost:8080/api/v2',
  project: 'my-project',
  launch: 'My Tests',
  apiKey: 'my-api-key',
}

const reporter = new RPReporter(config)

Test Structure Mapping

The reporter maps Japa's test structure to Report Portal:

| Japa | Report Portal | |------|---------------| | Suite | Suite | | Group (test.group()) | Suite | | Test (test()) | Step |

Test Status Mapping

| Japa Status | Report Portal Status | |-------------|---------------------| | Passed | PASSED | | Failed | FAILED | | Skipped | SKIPPED | | Todo | SKIPPED (with todo attribute) |

Troubleshooting

If you see ECONNREFUSED errors:

1. Verify your endpoint URL is correct and accessible
2. Check if Report Portal server is running
3. Ensure there are no firewall/proxy issues
4. Try accessing the endpoint in a browser

If tests appear in Report Portal but without details:

1. Enable debug mode (debug: true) to see what's being sent
2. Check the Report Portal server logs for errors
3. Verify your API key has write permissions

If you receive 401/403 errors:

1. Verify your API key is correct
2. Check if the API key has expired
3. Ensure the API key has access to the specified project

Related Projects

• Japa - A simple yet powerful testing framework for Node.js
• Report Portal - AI-powered Test Automation Dashboard
• @reportportal/client-javascript - Official Report Portal JavaScript client

Contributing

Contributions are welcome! Please read our Contributing Guide for details on our code of conduct and the process for submitting pull requests.

License

MIT - see the LICENSE file for details.