@playwright-mocks/reporters/README.md

Single Playwright reporter for mock interceptor with configurable logging and HTML report generation utility

# @playwright-mocks/reporters

Custom Playwright reporter for detailed mock usage tracking and reporting. This package provides a single reporter that collects test data during execution and can optionally generate beautiful HTML reports.

**Note**: This package exposes TypeScript files directly - no build step required! Playwright can read TypeScript files natively.

## 🚀 Features

- **📊 Single Reporter**: One reporter that handles all mock data collection and logging
- **🌐 HTML Report Utility**: Generate beautiful HTML reports from collected test data
- **📸 Screenshot Support**: Automatic screenshot collection and display
- **🎨 Customizable Logging**: Control console output with `logs` and `verbose` options
- **🔍 Detailed Analysis**: Mock usage, errors, response times, and more
- **📈 Statistics**: Comprehensive mock statistics and success rates
- **💡 IntelliSense**: Full TypeScript support with autocomplete
- **⚡ No Build Required**: Direct TypeScript support - no compilation needed

## 📦 Installation

```bash
npm install @playwright-mocks/reporters
```

## 🔧 Configuration

### Basic Configuration

Add the reporter to your `playwright.config.ts`:

```typescript
import { defineConfig } from '@playwright/test';
import { createMocksReporter } from '@playwright-mocks/reporters';

export default defineConfig({
  reporter: [
    ['html'],
    createMocksReporter({
      logs: true,
      verbose: false,
      generateHtml: true,
      htmlOutputDir: './mocks-report',
      htmlTitle: 'Playwright Mocks Report'
    })
  ],
  // ... rest of your config
});
```

### Advanced Configuration

```typescript
import { defineConfig } from '@playwright/test';
import { createMocksReporter } from '@playwright-mocks/reporters';

export default defineConfig({
  reporter: [
    ['html'],
    createMocksReporter({
      // Logging options
      logs: true,           // Enable console logging
      verbose: true,        // Enable verbose logging with detailed information
      
      // HTML report options
      generateHtml: true,   // Generate HTML report at end
      htmlOutputDir: './test-results/mocks-report',
      htmlTitle: 'My Project Mock Report',
      includeDetails: true,
      includeBodies: false,
      showFinalScreenshot: true,
      openReport: true      // Auto-open report in browser
    })
  ],
  // ... rest of your config
});
```

### Minimal Configuration (Console Only)

```typescript
import { defineConfig } from '@playwright/test';
import { createMocksReporter } from '@playwright-mocks/reporters';

export default defineConfig({
  reporter: [
    ['html'],
    createMocksReporter({
      logs: true,           // Only console logging, no HTML report
      verbose: false
    })
  ],
});
```

## 📊 Console Output

The reporter provides real-time feedback when `logs: true`:

### Basic Logging (`logs: true, verbose: false`)
```
--- Playwright Mocks Reporter ---
Total tests: 5
Test: should fetch user data | Status: passed | Duration: 1234ms
Test: should handle API error | Status: failed | Duration: 567ms

--- Test Summary ---
- should fetch user data [passed] (1234ms)
- should handle API error [failed] (567ms)
```

### Verbose Logging (`logs: true, verbose: true`)
```
--- Playwright Mocks Reporter ---
Total tests: 5
Configuration: { logs: true, verbose: true, generateHtml: true, htmlOutputDir: './mocks-report', htmlTitle: 'Playwright Mocks Report' }
Test: should fetch user data | Status: passed | Duration: 1234ms
  File: tests/api.spec.ts
  Attachments: 3
  Mock attachments: 2
    - mock-data.json (application/json)
    - screenshot.png (image/png)

--- Test Summary ---
- should fetch user data [passed] (1234ms)
- should handle API error [failed] (567ms)

Detailed Summary:
Total tests: 5
Passed: 4
Failed: 1
Skipped: 0
```

## 🌐 HTML Report

The HTML report is generated as a **utility function**, not a Playwright reporter. It can be:

1. **Automatically generated** by the reporter when `generateHtml: true`
2. **Manually called** after test execution using the `generateHtmlReport` utility

### Automatic Generation

```typescript
import { defineConfig } from '@playwright/test';
import { createMocksReporter } from '@playwright-mocks/reporters';

export default defineConfig({
  reporter: [
    createMocksReporter({
      logs: true,
      generateHtml: true,        // Auto-generate HTML report
      htmlOutputDir: './mocks-report',
      htmlTitle: 'My Mock Report',
      openReport: true           // Auto-open in browser
    })
  ],
});
```

### Manual Generation

```typescript
import { generateHtmlReport } from '@playwright-mocks/reporters';

// After your tests complete, generate the report manually
const testData = [/* your test data */];
generateHtmlReport(testData, {
  outputDir: './mocks-report',
  title: 'My Custom Report',
  includeDetails: true,
  includeBodies: false,
  showFinalScreenshot: true,
  openReport: true
});
```

## 📋 API Reference

### Reporter Options

```typescript
interface ReporterOptions {
  // Logging options
  logs?: boolean;        // Enable console logging (default: false)
  verbose?: boolean;     // Enable verbose logging (default: false)
  
  // HTML report options
  generateHtml?: boolean;     // Generate HTML report at end (default: false)
  htmlOutputDir?: string;     // HTML report output directory (default: "./mocks-report")
  htmlTitle?: string;         // HTML report title (default: "Playwright Mocks Report")
  includeDetails?: boolean;   // Include detailed mock information (default: true)
  includeBodies?: boolean;    // Include request/response bodies (default: false)
  showFinalScreenshot?: boolean; // Show final screenshot prominently (default: true)
  openReport?: boolean;       // Auto-open HTML report (default: true)
}
```

### HTML Report Options

```typescript
interface HtmlReportOptions {
  outputDir: string;           // Output directory for the HTML report
  title: string;               // Report title
  includeDetails: boolean;     // Include detailed mock information
  includeBodies: boolean;      // Include request/response bodies
  showFinalScreenshot: boolean; // Show final screenshot prominently
  openReport: boolean;         // Auto-open report in browser
}
```

## 🔄 Migration from Previous Versions

### Breaking Changes in v1.4.0

- **Single Reporter**: Only one reporter is now exposed (`createMocksReporter`)
- **HTML Report is a Utility**: HTML report generation is now a utility function, not a Playwright reporter
- **New Options**: `logs` and `verbose` options control console output
- **Removed**: Old separate HTML and console reporters
- **No Build Required**: Package now exposes TypeScript files directly

### Migration Guide

#### Old Configuration
```typescript
// OLD - Multiple reporters
export default defineConfig({
  reporter: [
    ['@playwright-mocks/reporters', {
      html: {
        outputDir: './mocks-report',
        title: 'My Report'
      },
      console: {
        showDetailedMockInfo: true
      }
    }]
  ],
});
```

#### New Configuration
```typescript
// NEW - Single reporter with options
import { createMocksReporter } from '@playwright-mocks/reporters';

export default defineConfig({
  reporter: [
    createMocksReporter({
      logs: true,                    // Console output (replaces console reporter)
      verbose: true,                 // Detailed logging
      generateHtml: true,            // HTML report generation
      htmlOutputDir: './mocks-report',
      htmlTitle: 'My Report'
    })
  ],
});
```

## 🛠️ Troubleshooting

### Common Issues

1. **No console output appears**
   - Ensure `logs: true` is set in your configuration
   - Check that tests are actually running with mocks

2. **HTML report is not generated**
   - Ensure `generateHtml: true` is set
   - Check that the output directory is writable
   - Verify that tests are actually running

3. **Missing mock data**
   - Ensure you're using the latest version of `@playwright-mocks/core`
   - Check that mocks are properly configured in your tests
   - Verify the interceptor is working correctly

4. **TypeScript compilation errors**
   - This package exposes TypeScript files directly
   - Make sure your project has TypeScript configured
   - No build step is required for this package

### Debug Mode

Enable verbose logging for detailed debugging:

```typescript
createMocksReporter({
  logs: true,
  verbose: true  // This will show detailed information
})
```

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## 📄 License

MIT License - see the [LICENSE](LICENSE) file for details.

## 🔗 Related Packages

- [@playwright-mocks/core](https://www.npmjs.com/package/@playwright-mocks/core) - Core mock interceptor functionality
- [@playwright-mocks/ui](https://www.npmjs.com/package/@playwright-mocks/ui) - Desktop UI for managing mocks