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

``bash
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

$3

Add the helper to your codecept.conf.js:

`javascript
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'
}
}
};
`

$3

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

`env
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

`javascript
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

$3

`bash


Generate HTML reports only

npx codeceptjs run --grep "KSYS-22"

Generate HTML reports with detailed steps

npx codeceptjs run --grep "KSYS-22" --steps
`

$3

`bash


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"
`

$3

`bash


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 |

$3

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

$3

`javascript
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

$3

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

`bash


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.

$3

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

`bash


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.

$3

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

$3

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

$3

Enable debug logging:

`bash
DEBUG=qase* npx codeceptjs run
`

TypeScript Support

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

`typescript
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.