npm package: @m00nsolutions/playwright-reporter
Description: Playwright test reporter for M00N Report dashboard - real-time test result streaming with step tracking, attachments, and retry support
Author: M00n Solutions
Latest version: 1.0.9

# @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
- 🔒 **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 [m00nreport.com](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://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 |

## Environment Variables

You can also configure the reporter via environment variables:

```bash
M00N_SERVER_URL=https://m00nreport.com
M00N_API_KEY=m00n_xxxxxxxxxxxxx
M00N_LAUNCH="Nightly Build"
M00N_TAGS=smoke,regression
```

## CI/CD Auto-Detection

The reporter **automatically detects** CI/CD environment variables from popular providers and includes them as run attributes. No configuration needed - just run your tests in CI and the dashboard will display branch, commit, build URL, and more.

### Supported Providers

| Provider | Detection Variable |
|---|---|
| **GitHub Actions** | `GITHUB_ACTIONS` |
| **GitLab CI** | `GITLAB_CI` |
| **Jenkins** | `JENKINS_URL` |
| **Bitbucket Pipelines** | `BITBUCKET_PIPELINE_UUID` |
| **Azure DevOps** | `TF_BUILD` |
| **CircleCI** | `CIRCLECI` |
| **Travis CI** | `TRAVIS` |

### Auto-Detected Attributes

The following attributes are automatically populated when running in a supported CI environment:

| Attribute | Description | GitHub Actions | GitLab CI | Jenkins | Bitbucket | Azure DevOps | CircleCI | Travis CI |
|---|---|---|---|---|---|---|---|---|
| `ci_provider` | CI provider name | `GitHub Actions` | `GitLab CI` | `Jenkins` | `Bitbucket Pipelines` | `Azure DevOps` | `CircleCI` | `Travis CI` |
| `branch` | Git branch | `GITHUB_REF_NAME` | `CI_COMMIT_REF_NAME` | `BRANCH_NAME` | `BITBUCKET_BRANCH` | `BUILD_SOURCEBRANCH` | `CIRCLE_BRANCH` | `TRAVIS_BRANCH` |
| `commit` | Git commit SHA | `GITHUB_SHA` | `CI_COMMIT_SHA` | `GIT_COMMIT` | `BITBUCKET_COMMIT` | `BUILD_SOURCEVERSION` | `CIRCLE_SHA1` | `TRAVIS_COMMIT` |
| `pipeline` | Pipeline/workflow name | `GITHUB_WORKFLOW` | `CI_PIPELINE_NAME` | `JOB_NAME` | - | `BUILD_DEFINITIONNAME` | `CIRCLE_WORKFLOW_JOB_NAME` | - |
| `build_number` | Build number | `GITHUB_RUN_NUMBER` | `CI_PIPELINE_ID` | `BUILD_NUMBER` | `BITBUCKET_BUILD_NUMBER` | `BUILD_BUILDNUMBER` | `CIRCLE_BUILD_NUM` | `TRAVIS_BUILD_NUMBER` |
| `build_url` | Link to build | Auto-composed | `CI_PIPELINE_URL` | `BUILD_URL` | Auto-composed | Auto-composed | `CIRCLE_BUILD_URL` | `TRAVIS_BUILD_WEB_URL` |
| `trigger` | What triggered the build | `GITHUB_EVENT_NAME` | `CI_PIPELINE_SOURCE` | - | - | `BUILD_REASON` | - | `TRAVIS_EVENT_TYPE` |
| `triggered_by` | User who triggered | `GITHUB_ACTOR` | `CI_GITLAB_USER_LOGIN` | - | - | - | `CIRCLE_USERNAME` | - |

### Manual Override

User-provided attributes always take precedence over auto-detected values. To override any auto-detected attribute, simply set it in the `attributes` config:

```typescript
reporter: [
  ['@m00nsolutions/playwright-reporter', {
    serverUrl: 'https://m00nreport.com',
    apiKey: process.env.M00N_API_KEY,
    attributes: {
      branch: 'my-custom-branch',  // Overrides auto-detected branch
      environment: 'staging',       // Custom attribute (not auto-detected)
    },
  }],
],
```

### Custom CI Variables

For unsupported CI providers or additional metadata, pass any key-value pairs via `attributes`:

```typescript
attributes: {
  build_url: process.env.MY_CI_BUILD_URL,
  branch: process.env.MY_CI_BRANCH,
  commit: process.env.MY_CI_COMMIT,
  environment: 'production',
  region: 'us-east-1',
},
```

The dashboard recognizes these attribute keys and displays them in the CI/CD banner: `branch`, `commit`, `pipeline`, `build_number`, `build_url`, `environment`, `trigger`.

## Usage Examples

### Basic Configuration

```typescript
reporter: [
  ['@m00nsolutions/playwright-reporter', {
    serverUrl: 'https://m00nreport.com',
    apiKey: process.env.M00N_API_KEY,
  }],
],
```

### GitHub Actions Example

```yaml
# .github/workflows/tests.yml
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx playwright test
        env:
          M00N_API_KEY: ${{ secrets.M00N_API_KEY }}
```

The reporter will automatically capture `branch`, `commit`, `build_url`, `pipeline`, `build_number`, `trigger`, and `triggered_by` from GitHub Actions environment variables.

### GitLab CI Example

```yaml
# .gitlab-ci.yml
test:
  script:
    - npx playwright test
  variables:
    M00N_API_KEY: $M00N_API_KEY
```

## 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',
  });
});
```

## License

MIT License - see [LICENSE](LICENSE) for details.

## Support

- 📖 [Documentation](https://m00nreport.com/documentation)
- 🐛 [Report Issues](https://github.com/m00nsolutions/m00nreport/issues)
- 💬 [Community Discord](https://discord.gg/hzZvyVWS3Q)