# 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

### 1. Configure CodeceptJS

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

### 2. Environment Configuration

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. Write Tests with Case IDs

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

### Basic HTML Reports (No Qase Integration)

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

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

### Environment-Specific Testing

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

### 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:

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

### Linking to Test Plans

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.

### Setting Test Result Author

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.

### 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:

```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](https://github.com/your-username/qase-codeceptjs-helper/issues)
- Documentation: [View full documentation](https://github.com/your-username/qase-codeceptjs-helper)

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for release history and updates.