@alphabin/trx/README.md

TRX reporter for Playwright tests with Azure Blob Storage upload support

# TRX Playwright Reporter

*Maintained by Ayush Mania (GitHub: [@alphabin-01](https://github.com/alphabin-01))*

[![npm version](https://badge.fury.io/js/%40alphabin%2Ftrx.svg)](https://badge.fury.io/js/%40alphabin%2Ftrx)

A Playwright reporter that sends detailed test results and environment metadata to the TRX server for advanced test analytics and reporting.

## Features

- 📊 Automatically sends Playwright test results to the TRX server.
- 🔍 Collects comprehensive metadata about your test runs:
  - **Git:** Branch, commit (hash, message, author, email, timestamp), repository (name, URL), PR details (if available).
  - **CI/CD:** Provider detection (GitHub Actions, GitLab CI, Jenkins, etc.), pipeline (ID, name, URL), build (number, trigger), environment details.
  - **System:** Hostname, CPU (count, model), memory, OS, Node.js version, Playwright version.
  - **Test Configuration:** Detailed info including browsers used (ID, name, version, viewport, headless, retries), workers, timeouts, reporters configured, grep filters, and more.
- 🏷️ Support for associating custom tags with test runs via reporter options.
- 🔁 Built-in retry mechanism for API requests to the TRX server.
- 🔒 Secure API key authentication.
- 📝 Optional verbose debug logging via the `debug` option or by setting `DEBUG=alphabin:trx`.

## Installation

```bash
npm install --save-dev @alphabin/trx
# or
yarn add --dev @alphabin/trx
# or
pnpm add --save-dev @alphabin/trx
```

## Configuration

Add the reporter to your `playwright.config.js` or `playwright.config.ts`. You **must** also include Playwright's built-in `json` reporter, as `@alphabin/trx` reads its output.

```javascript
// playwright.config.js
const { defineConfig } = require('@playwright/test');

module.exports = defineConfig({
  // ... other config settings
  reporter: [
    // Required reporters
    ['json', { outputFile: 'test-results/report.json' }],
    ['@alphabin/trx', {
      serverUrl: process.env.TRX_SERVER_URL || 'YOUR_TRX_SERVER_URL',
      apiKey: process.env.TRX_API_KEY,

      // Optional: Add custom tags to the run
      tags: ['smoke-test', process.env.CI_COMMIT_REF_SLUG]
      
      // ... see options below
    }],
    // If you want to upload media to cloud, enable HTML reporter like given below
    ['html', {
      outputDir: 'playwright-report',
      open: 'never'
    }],
  ],
  // ... rest of your config
});
```

> **Important**: Ensure the `json` reporter is configured to output a file (e.g., `test-results/report.json`). The `@alphabin/trx` reporter will read this file after the test run finishes.

## Reporter Options

The `@alphabin/trx` reporter accepts the following options:

| Option                 | Type    | Required | Default        | Description                                            |
| :--------------------- | :------ | :------- | :------------- | :----------------------------------------------------- |
| `serverUrl`            | string  | Yes      | -              | URL of the TRX server instance.               |
| `apiKey`               | string  | Yes      | -              | API key for authenticating with the server.            |
| `tags`                 | string[]| No       | `[]`           | Array of custom string tags to associate with the run. |
| `reportDir`            | string  | No       | `./test-results`| Directory where the `report.json` file is expected.    |
| `debug`                | boolean | No       | `false`        | Enable verbose debug logging for the reporter.         |
| `timeout`              | number  | No       | `30000`        | Timeout for API requests to the server (in ms).        |
| `retries`              | number  | No       | `3`            | Number of retry attempts for failed API requests.      |

## Environment Variables

You can configure required options via environment variables:

- `TRX_SERVER_URL` – Sets the `serverUrl`.
- `TRX_API_KEY` – Sets the `apiKey`.

For debugging, set the `DEBUG` environment variable:

```bash
DEBUG=alphabin:trx npx playwright test
```

## Metadata Structure

The reporter collects and sends following metadata to the TRX server:

```json
{
  "git": {
    "branch": "string",
    "commit": {
      "hash": "string",
      "message": "string"
    },
    "repository": {
      "name": "string",
      "url": "string"
    },
    "pr": {
      "id": "string",
      "title": "string",
      "url": "string"
    }
  },
  "ci": {
    "provider": "string",
    "pipeline": {
      "id": "string",
      "name": "string",
      "url": "string"
    },
    "build": {
      "number": "string",
      "trigger": "string"
    },
    "environment": {
      "name": "string",
      "type": "string",
      "os": "string",
      "node": "string"
    }
  },
  "system": {
    "hostname": "string",
    "cpu": {
      "count": "number",
      "model": "string"
    },
    "memory": {
      "total": "string"
    },
    "os": "string",
    "nodejs": "string",
    "playwright": "string"
  },
  "test": {
    "config": {
      "browsers": [
        {
          "browserId": "string",
          "name": "string",
          "version": "string",
          "viewport": "string",
          "headless": "boolean",
          "repeatEach": "number",
          "retries": "number",
          "testDir": "string",
          "outputDir": "string"
        }
      ],
      "actualWorkers": "number",
      "timeout": "number",
      "preserveOutput": "string",
      "fullyParallel": "boolean",
      "forbidOnly": "boolean",
      "projects": "number",
      "shard": "string | null",
      "reporters": [
        {
          "name": "string",
          "options": "any"
        }
      ],
      "grep": "any",
      "grepInvert": "any"
    },
    "customTags": ["string"]
  }
}
```

## Supported CI/CD Providers

The reporter automatically detects and collects information from the following CI/CD providers by checking standard environment variables:

- GitHub Actions
- GitLab CI
- CircleCI
- Jenkins
- Azure DevOps
- (Generic `CI=true` detection)

## Examples

See the [examples](./examples) directory for sample `playwright.config.js` files.

## License

MIT