Qase CodeceptJS Helper

A TypeScript-based CodeceptJS helper that automatically generates HTML reports and integrates with Qase.io test management platform. Features include detailed test step extraction with the --steps flag, browser version detection, and comprehensive reporting capabilities.

Installation

npm install qase-codeceptjs-helper

Features

• ✅ HTML Report Generation - Beautiful, responsive reports with test statistics
• ✅ Qase.io API Integration - Automatic submission of test results to Qase.io
• ✅ Test Plan Linking - Link test runs to existing test plans in Qase.io
• ✅ --steps Flag Support - Detailed step extraction when using --steps flag
• ✅ Multi-Browser Support - Works with Playwright, Puppeteer, WebDriver, and TestCafe
• ✅ Browser Version Detection - Automatically detects browser versions
• ✅ Environment Support - Supports dev, release, prod_eu, prod_uk, prod_us environments
• ✅ TypeScript Support - Full TypeScript implementation with type definitions
• ✅ Rate Limiting - Built-in API rate limiting for Qase.io integration

Quick Start

1. Configure CodeceptJS

Add the helper to your codecept.conf.js:

module.exports = {
  helpers: {
    // Your existing helper (Playwright, Puppeteer, WebDriver, etc.)
    Playwright: {
      url: 'http://localhost:3000',
      show: false,
      browser: 'chromium'
    },
    
    // Add QaseHelper
    QaseHelper: {
      require: 'qase-codeceptjs-helper',
      enableQaseIntegration: process.env.QASE_ENABLED === 'true',
      apiToken: process.env.QASE_API_TOKEN,
      projectCode: process.env.QASE_PROJECT_CODE,
      testCasePrefix: 'KSYS', // Your test case prefix
      enableReporting: true,
      reportPath: './reports'
    }
  }
};

2. Environment Configuration

Create a .env.automation file in your project root:

QASE_API_TOKEN=your_qase_api_token_here
QASE_PROJECT_CODE=your_project_code_here
QASE_ENABLED=true

# Optional: Link test runs to a test plan
QASE_PLAN_ID=3

# Optional: Set the author for all test results
QASE_AUTHOR_ID=123

3. Write Tests with Case IDs

Feature('Sample Tests');

Scenario('Login Test @KSYS-22 @login', async ({ I }) => {
    // Step 1: Navigate to login page
    // Action: Open login page
    // Expected Result: Login form is displayed
    I.say('Step 1: Navigate to login page');
    I.amOnPage('/login');
    I.see('Login');
    
    // Step 2: Enter credentials
    // Action: Fill username and password fields
    // Expected Result: Credentials are accepted
    I.say('Step 2: Enter credentials');
    I.fillField('username', 'testuser');
    I.fillField('password', 'password123');
    
    // Step 3: Submit login
    // Action: Click login button
    // Expected Result: User is redirected to dashboard
    I.say('Step 3: Submit login');
    I.click('Login');
    I.see('Dashboard');
});

Usage Examples

Basic HTML Reports (No Qase Integration)

# Generate HTML reports only
npx codeceptjs run --grep "KSYS-22"

# Generate HTML reports with detailed steps
npx codeceptjs run --grep "KSYS-22" --steps

Full Qase Integration

# Run with Qase integration (no step extraction)
QASE_ENABLED=true npx codeceptjs run --grep "KSYS-22"

# Run with Qase integration and detailed steps
QASE_ENABLED=true npx codeceptjs run --grep "KSYS-22" --steps

# Link test run to an existing test plan
QASE_ENABLED=true QASE_PLAN_ID=3 npx codeceptjs run --grep "KSYS-22"

Environment-Specific Testing

# Test in different environments
ENV=dev QASE_ENABLED=true npx codeceptjs run --grep "KSYS-22"
ENV=prod_eu QASE_ENABLED=true npx codeceptjs run --grep "KSYS-22"

Configuration Options

| Option | Description | Default | Required | |--------|-------------|---------|----------| | enableQaseIntegration | Enable Qase.io integration | false | No | | apiToken | Qase.io API token | undefined | Yes (if Qase enabled) | | projectCode | Qase.io project code | undefined | Yes (if Qase enabled) | | testPlanId | Link test run to test plan ID | undefined | No | | testCasePrefix | Test case ID prefix | 'C' | No | | enableReporting | Enable HTML report generation | true | No | | reportPath | Path for HTML reports | './reports' | No |

Environment Variables

All configuration options can be set via environment variables:

| Variable | Description | Example | |----------|-------------|---------| | QASE_API_TOKEN | Your Qase.io API token | abc123... | | QASE_PROJECT_CODE | Your project code | PROJ | | QASE_PLAN_ID | Test plan ID to link runs to | 3 | | QASE_AUTHOR_ID | Author/member ID for test results | 123 | | QASE_ENABLED | Enable Qase integration | true | | QASE_ENABLE_STEPS | Enable step extraction | true | | QASE_RUN_TITLE | Custom test run title | My Test Run | | QASE_RUN_DESCRIPTION | Custom run description | Automated tests |

Test Case ID Formats

The helper supports multiple test case ID formats:

• @KSYS-22 - Tag format
• KSYS-22 - Title format
• KSYS: 22 - Colon format
• [KSYS123] - Bracket format
• .tag('KSYS22') - Tag method format

Step Extraction

When using the --steps flag, the helper extracts detailed test steps from:

1. Comment Blocks: Step comments with Action and Expected Result
2. I.say Statements: Step descriptions in your test code

Example with Step Comments:

Scenario('Test with detailed steps @KSYS-22', async ({ I }) => {
    // Step 1: Navigate to homepage
    // Action: Open the homepage URL
    // Expected Result: Homepage loads successfully
    I.say('Step 1: Navigate to homepage');
    I.amOnPage('/');
    
    // Step 2: Search for product
    // Action: Enter product name in search field
    // Expected Result: Search results are displayed
    I.say('Step 2: Search for product');
    I.fillField('search', 'laptop');
    I.click('Search');
});

Browser Support

The helper automatically detects browser versions for:

• ✅ Playwright - Chrome, Firefox, Safari, Edge
• ✅ Puppeteer - Chrome/Chromium
• ✅ WebDriver - Chrome, Firefox, Safari, Edge
• ✅ TestCafe - All supported browsers

Environment Detection

Supports automatic environment detection:

• dev - Development environment
• release - Release environment
• prod_eu - Production EU
• prod_uk - Production UK
• prod_us - Production US

HTML Reports

Generated HTML reports include:

• Test execution summary and statistics
• Individual test results with timing
• Browser version and environment information
• Detailed step execution (when --steps flag is used)
• Responsive design for mobile and desktop viewing

API Integration

When Qase integration is enabled:

• Automatic test run creation in Qase.io
• Optional test plan linking via QASE_PLAN_ID
• Test results sent to Qase.io API
• Case ID mapping from test titles and tags
• Step-by-step execution details (with --steps flag)
• Browser version included in test run descriptions

Linking to Test Plans

To associate your test runs with existing test plans in Qase.io:

# Set the test plan ID as an environment variable
export QASE_PLAN_ID=3

# Or pass it inline
QASE_PLAN_ID=3 npx codeceptjs run

# Run without a test plan (creates standalone test run)
npx codeceptjs run

When QASE_PLAN_ID is set, the test run will be linked to the specified test plan in Qase.io. If not set, test runs are created without plan association.

Setting Test Result Author

To assign all automated test results to a specific team member:

# Set the author ID in .env.automation
QASE_AUTHOR_ID=123

# Or pass it as an environment variable
QASE_AUTHOR_ID=123 npx codeceptjs run

When QASE_AUTHOR_ID is set, all test results will be assigned to that team member in Qase.io. This prevents mixed member assignments and makes it clear which tests are automated. To find your member ID, go to your Qase.io workspace settings and check the team member's profile.

Submission Logging

When test results are submitted to Qase, you'll see a summary:

✅ Successfully submitted 10 test results to Qase (Run ID: 123)
   📊 Results: 8 passed, 2 failed, 0 skipped
   👤 Author ID: 456

This confirms:

• Total number of tests submitted
• Breakdown of passed/failed/skipped tests
• Author ID (if configured)

Troubleshooting

Common Issues

1. Missing API Token: Ensure QASE_API_TOKEN is set in environment or .env.automation
2. Case IDs Not Detected: Verify test case ID format matches your testCasePrefix
3. Browser Version Not Detected: Ensure your browser helper is properly configured
4. Steps Not Extracted: Use --steps flag or set QASE_ENABLE_STEPS=true

Debug Mode

Enable debug logging:

DEBUG=qase* npx codeceptjs run

TypeScript Support

The helper is written in TypeScript and includes full type definitions:

import { QaseHelper } from 'qase-codeceptjs-helper';

// Type definitions are automatically available
const helper = new QaseHelper({
  enableQaseIntegration: true,
  apiToken: 'your-token',
  projectCode: 'PROJECT'
});

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

• GitHub Issues: Report bugs and request features
• Documentation: View full documentation

Changelog

See CHANGELOG.md for release history and updates.