@m00nsolutions/playwright-reporter 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 M00n Solutions
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,248 @@
+# @m00nsolutions/playwright-reporter
+
+Official Playwright test reporter for [M00n Report](https://m00nreport.com) - a real-time test reporting dashboard.
+
+## Features
+
+- 🚀 **Real-time streaming** - Watch test steps execute live in the dashboard
+- 📎 **Attachment support** - Screenshots, videos, traces, and custom files
+- 🔄 **Retry tracking** - Automatic tracking of test retries with attempt history
+- 🏷️ **Tags & attributes** - Organize runs with custom metadata
+- 📊 **Performance metrics** - Detailed timing and bottleneck analysis
+- 🔒 **Secure** - API key authentication per project
+
+## Installation
+
+```bash
+npm install @m00nsolutions/playwright-reporter --save-dev
+# or
+yarn add @m00nsolutions/playwright-reporter --dev
+# or
+pnpm add @m00nsolutions/playwright-reporter --save-dev
+```
+
+## Quick Start
+
+### 1. Get your API key
+
+1. Log in to [M00n Report](https://m00nreport.com)
+2. Navigate to your project settings
+3. Generate or copy your project API key
+
+### 2. Configure Playwright
+
+Add the reporter to your `playwright.config.ts`:
+
+```typescript
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  reporter: [
+    ['list'], // Keep default console output
+    ['@m00nsolutions/playwright-reporter', {
+      serverUrl: 'https://ingest.m00nreport.com', // Or your self-hosted URL
+      apiKey: process.env.M00N_API_KEY,           // Your project API key
+      launch: 'Regression Suite',                  // Optional: run title
+      tags: ['smoke', 'regression'],               // Optional: tags
+      attributes: {                                // Optional: custom metadata
+        environment: 'staging',
+        branch: process.env.GIT_BRANCH,
+      },
+    }],
+  ],
+});
+```
+
+### 3. Run your tests
+
+```bash
+npx playwright test
+```
+
+That's it! Your test results will appear in the M00n Report dashboard in real-time.
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `serverUrl` | `string` | **required** | M00n Report ingest service URL |
+| `apiKey` | `string` | **required** | Project API key (identifies org and project) |
+| `launch` | `string` | `'Run {date}'` | Title for this test run |
+| `tags` | `string[]` | `[]` | Tags to categorize the run |
+| `attributes` | `object` | `{}` | Custom key-value metadata |
+| `realtime` | `boolean` | `true` | Enable real-time step streaming |
+| `binaryAttachments` | `boolean` | `true` | Use efficient binary uploads |
+| `debug` | `boolean` | `false` | Enable debug logging |
+| `verbose` | `boolean` | `false` | Enable performance timing logs |
+| `logFile` | `string` | `null` | Path to save performance metrics |
+
+## Environment Variables
+
+You can also configure the reporter via environment variables:
+
+```bash
+M00N_SERVER_URL=https://ingest.m00nreport.com
+M00N_API_KEY=m00n_xxxxxxxxxxxxx
+M00N_LAUNCH="Nightly Build"
+M00N_TAGS=smoke,regression
+```
+
+## Usage Examples
+
+### Basic Configuration
+
+```typescript
+reporter: [
+  ['@m00nsolutions/playwright-reporter', {
+    serverUrl: 'https://ingest.m00nreport.com',
+    apiKey: process.env.M00N_API_KEY,
+  }],
+],
+```
+
+### CI/CD Configuration
+
+```typescript
+reporter: [
+  ['@m00nsolutions/playwright-reporter', {
+    serverUrl: 'https://ingest.m00nreport.com',
+    apiKey: process.env.M00N_API_KEY,
+    launch: `Build #${process.env.BUILD_NUMBER}`,
+    tags: [process.env.CI_ENVIRONMENT, 'automated'],
+    attributes: {
+      ciJobUrl: process.env.CI_JOB_URL,
+      gitBranch: process.env.GIT_BRANCH,
+      gitCommit: process.env.GIT_COMMIT,
+      triggeredBy: process.env.GITLAB_USER_LOGIN,
+    },
+  }],
+],
+```
+
+### Link Test Cases
+
+Use annotations to link tests to test case IDs in your test management system:
+
+```typescript
+import { test } from '@playwright/test';
+
+test('user can login @caseId=TC-123', async ({ page }) => {
+  // Your test code
+});
+
+// Or use the annotation API
+test('user can logout', async ({ page }) => {
+  test.info().annotations.push({ type: 'caseId', description: 'TC-456' });
+  // Your test code
+});
+```
+
+### Custom Tags per Test
+
+```typescript
+test('critical checkout flow', async ({ page }) => {
+  test.info().annotations.push({ type: 'tags', description: ['critical', 'checkout'] });
+  // Your test code
+});
+```
+
+## Real-time Step Streaming
+
+When `realtime: true` (default), the reporter streams test steps to the dashboard as they execute. This allows you to:
+
+- Watch tests execute in real-time
+- See which step is currently running
+- Identify failures immediately without waiting for test completion
+
+## Attachment Handling
+
+The reporter automatically uploads all Playwright attachments:
+
+- **Screenshots** - Captured on failure or explicitly
+- **Videos** - When video recording is enabled
+- **Traces** - Playwright trace files for debugging
+- **Custom files** - Any files you attach in tests
+
+```typescript
+test('with attachments', async ({ page }) => {
+  // Screenshot on failure is automatic
+  
+  // Explicit screenshot
+  await page.screenshot({ path: 'screenshot.png' });
+  
+  // Custom attachment
+  await test.info().attach('api-response', {
+    body: JSON.stringify(response),
+    contentType: 'application/json',
+  });
+});
+```
+
+## Performance Optimization
+
+For high-parallelism runs (30+ workers), the reporter includes:
+
+- **Upload concurrency limiting** - Prevents server overload
+- **Request batching** - Reduces HTTP overhead
+- **Large file streaming** - Efficient handling of big traces
+- **Backpressure control** - Graceful degradation under load
+
+Enable verbose logging to analyze performance:
+
+```typescript
+reporter: [
+  ['@m00nsolutions/playwright-reporter', {
+    serverUrl: 'https://ingest.m00nreport.com',
+    apiKey: process.env.M00N_API_KEY,
+    verbose: true,
+    logFile: './m00n-performance.log',
+  }],
+],
+```
+
+## Self-Hosted
+
+For self-hosted M00n Report installations, point to your ingest service:
+
+```typescript
+reporter: [
+  ['@m00nsolutions/playwright-reporter', {
+    serverUrl: 'https://your-domain.com:4001', // Your ingest service
+    apiKey: process.env.M00N_API_KEY,
+  }],
+],
+```
+
+## Troubleshooting
+
+### Reporter is disabled
+
+Check the console output for messages like:
+- `"serverUrl" is required` - Ensure serverUrl is configured
+- `"apiKey" is required` - Ensure apiKey is configured
+- `Server unavailable` - Check network connectivity to the server
+
+### Missing test results
+
+1. Ensure the ingest service is running and accessible
+2. Check your API key is valid for the project
+3. Enable debug mode to see detailed logging:
+   ```typescript
+   debug: true
+   ```
+
+### Large trace files
+
+For very large trace files (>100MB), increase timeouts or consider:
+- Using `retain-on-failure` instead of `on` for traces
+- Reducing trace content with `screenshots: 'off'`
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Support
+
+- 📖 [Documentation](https://docs.m00nreport.com)
+- 🐛 [Report Issues](https://github.com/m00nsolutions/m00nreport/issues)
+- 💬 [Community Discord](https://discord.gg/m00nreport)