@stanterprise/playwright-reporter 0.0.18 → 0.0.20

package/README.md

@@ -9,12 +9,13 @@ Custom Playwright test reporter that sends test results to Stanterprise via gRPC
 - 📎 **Attachment Support**: Handles screenshots, videos, and other test attachments
 - 🔌 **gRPC Integration**: Communicates with Stanterprise backend via gRPC protocol
 - ⚙️ **Configurable**: Supports environment variables and configuration options
+- 🐛 **Debug Mode**: Captures outgoing gRPC messages to a JSONL file for troubleshooting
 - 🛡️ **Error Resilient**: Graceful error handling that doesn't interrupt test execution
 
 ## Installation
 
 ```bash
-npm install stanterprise-playwright-reporter --save-dev
+npm install @stanterprise/playwright-reporter --save-dev
 ```
 
 ## Configuration
@@ -27,7 +28,7 @@ Add the reporter to your `playwright.config.ts`:
 import { defineConfig } from "@playwright/test";
 
 export default defineConfig({
-  reporter: [["stanterprise-playwright-reporter"]],
+  reporter: [["@stanterprise/playwright-reporter"]],
   // ... other config
 });
 ```
@@ -40,7 +41,7 @@ import { defineConfig } from "@playwright/test";
 export default defineConfig({
   reporter: [
     [
-      "stanterprise-playwright-reporter",
+      "@stanterprise/playwright-reporter",
       {
         grpcAddress: "localhost:50051", // gRPC server address
         grpcEnabled: true, // Enable/disable gRPC reporting
@@ -48,6 +49,8 @@ export default defineConfig({
         grpcMaxMessageSize: 104857600, // Max message size (100MB default)
         maxAttachmentSize: 10485760, // Max attachment size (10MB default)
         verbose: false, // Enable verbose logging
+        debug: false,          // Enable debug mode (writes gRPC messages to JSONL file)
+        debugFile: "stanterprise-debug.jsonl", // Path for debug JSONL output
       },
     ],
   ],
@@ -62,6 +65,8 @@ You can also configure the reporter using environment variables:
 - `STANTERPRISE_GRPC_ADDRESS`: gRPC server address (default: `localhost:50051`)
 - `STANTERPRISE_GRPC_ENABLED`: Enable/disable gRPC reporting (default: `true`)
 - `STANTERPRISE_META_*`: Custom metadata fields for test runs (prefix will be stripped)
+- `STANTERPRISE_DEBUG`: Enable debug mode — captures outgoing gRPC messages to a JSONL file (default: `false`; case-insensitive: `"true"`, `"TRUE"`, `"True"` all work)
+- `STANTERPRISE_DEBUG_FILE`: File path for debug JSONL output (default: `stanterprise-debug.jsonl`)
 
 #### Custom Metadata
 
@@ -92,6 +97,93 @@ npx playwright test
 | `grpcMaxMessageSize` | number  | `104857600`       | Max message size in bytes (100MB default)           |
 | `maxAttachmentSize`  | number  | `10485760`        | Max attachment content size in bytes (10MB default) |
 | `verbose`            | boolean | `false`           | Enable verbose logging                              |
+| `grpcMaxRetries`     | number  | `3`               | Maximum number of retry attempts for failed gRPC calls  |
+| `grpcRetryDelay`     | number  | `100`             | Initial delay for retries in ms (uses exponential backoff) |
+| `debug`              | boolean | `false`           | Enable debug mode — writes all outgoing gRPC messages to a JSONL file. **Warning:** output may include sensitive request payloads and grow very large. Use only in controlled environments. |
+| `debugFile`          | string  | `stanterprise-debug.jsonl` | File path for debug JSONL output. Parent directories are created automatically if they do not exist. |
+
+### Retry Configuration
+
+The reporter automatically retries failed gRPC calls for transient errors using exponential backoff:
+
+- **Retryable errors**: `UNAVAILABLE`, `DEADLINE_EXCEEDED`, `INTERNAL`, `UNKNOWN`
+- **Non-retryable errors**: `INVALID_ARGUMENT`, `NOT_FOUND`, `PERMISSION_DENIED`, `UNAUTHENTICATED`, `ALREADY_EXISTS`
+
+**Exponential backoff formula**: `grpcRetryDelay * (2 ^ attemptNumber)`
+
+Example with default settings (`grpcRetryDelay: 100`, `grpcMaxRetries: 3`):
+- Initial attempt: Immediate
+- Retry 1: Wait 100ms (100 * 2^0)
+- Retry 2: Wait 200ms (100 * 2^1)
+- Retry 3: Wait 400ms (100 * 2^2)
+
+```typescript
+export default defineConfig({
+  reporter: [
+    [
+      "stanterprise-playwright-reporter",
+      {
+        grpcMaxRetries: 5,        // Try up to 5 times
+        grpcRetryDelay: 200,      // Start with 200ms delay
+        verbose: true,            // Log retry attempts
+      },
+    ],
+  ],
+});
+```
+
+To disable retries:
+
+```typescript
+{
+  grpcMaxRetries: 0  // No retries, fail fast
+}
+```
+
+## Debug Mode
+
+The reporter includes an opt-in debug mode that captures every outgoing gRPC message to a JSONL file. This is useful for troubleshooting, auditing what is sent to the backend, or diagnosing unexpected behavior.
+
+> **Warning:** Debug output may include full request payloads — including attachment content and metadata — which can contain sensitive values. Debug files may also grow very large. Enable this only in controlled environments and handle the output file securely.
+
+### Enabling Debug Mode
+
+Via configuration:
+
+```typescript
+export default defineConfig({
+  reporter: [
+    [
+      "@stanterprise/playwright-reporter",
+      {
+        debug: true,
+        debugFile: "debug-output.jsonl", // optional, defaults to stanterprise-debug.jsonl
+      },
+    ],
+  ],
+});
+```
+
+Via environment variables:
+
+```bash
+STANTERPRISE_DEBUG=true STANTERPRISE_DEBUG_FILE=debug-output.jsonl npx playwright test
+```
+
+### Debug File Format
+
+Each line is a JSON object with three fields:
+
+```json
+{"timestamp":"2026-03-23T04:10:00.000Z","path":"/testsystem.v1.observer.TestEventCollector/ReportRunStart","message":{"run_id":"abc-123","name":"My Run"}}
+{"timestamp":"2026-03-23T04:10:01.000Z","path":"/testsystem.v1.observer.TestEventCollector/ReportTestBegin","message":{"test_case":{"id":"t1","name":"login test"}}}
+```
+
+- `timestamp` — ISO 8601 timestamp when the message was sent
+- `path` — gRPC method path
+- `message` — full serialized request payload
+
+The debug file is created/truncated at reporter initialization, so each test run starts with a clean file. Entries are only written for messages that are actually dispatched (i.e., when gRPC is enabled). Writes are performed asynchronously to minimize overhead.
 
 ## Sharding Support
 
@@ -279,6 +371,7 @@ The reporter is organized into several modules:
 - **utils/statusMapper.ts**: Maps Playwright statuses to protobuf enums
 - **utils/attachmentProcessor.ts**: Processes test attachments
 - **utils/timeHelpers.ts**: Handles timestamp and duration conversions
+- **utils/debugLogger.ts**: Writes outgoing gRPC messages to a JSONL file when debug mode is enabled
 
 ## Troubleshooting
 

package/dist/client/grpcClient.d.ts

@@ -1,6 +1,9 @@
 import { StanterpriseReporterOptions } from "../types";
 import * as grpc from "@grpc/grpc-js";
 export default function getClient(options: StanterpriseReporterOptions): grpc.Client | null;
+/**
+ * Helper: generic unary call using raw method path with retry support
+ */
 export declare function reportUnary(options: StanterpriseReporterOptions, grpcClient: grpc.Client, path: string, message: {
     serialize?: (w?: any) => Uint8Array;
     serializeBinary?: () => Uint8Array;

package/dist/client/grpcClient.js

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = getClient;
 exports.reportUnary = reportUnary;
 const grpc = __importStar(require("@grpc/grpc-js"));
+const debugLogger_1 = require("../utils/debugLogger");
 function getClient(options) {
     try {
         const maxMessageSize = options.grpcMaxMessageSize || 104857600; // 100MB default
@@ -49,11 +50,28 @@ function getClient(options) {
     }
     return null;
 }
-// Helper: generic unary call using raw method path
-async function reportUnary(options, grpcClient, path, message, deadlineMs = 1000) {
-    if (!options.grpcEnabled || !grpcClient) {
-        return Buffer.alloc(0);
-    }
+/**
+ * Determines if a gRPC error code represents a transient failure worth retrying
+ */
+function shouldAttemptRetryForCode(errorCode) {
+    const transientCodes = new Set([
+        grpc.status.UNAVAILABLE,
+        grpc.status.DEADLINE_EXCEEDED,
+        grpc.status.INTERNAL,
+        grpc.status.UNKNOWN,
+    ]);
+    return transientCodes.has(errorCode);
+}
+/**
+ * Calculates wait time using power-of-two exponential backoff
+ */
+function calculateWaitDuration(baseDelayMs, attemptsSoFar) {
+    return baseDelayMs * Math.pow(2, attemptsSoFar);
+}
+/**
+ * Performs a single gRPC unary request attempt
+ */
+function executeSingleAttempt(grpcClient, path, message, deadlineMs) {
     const reqSerialize = (arg) => {
         const m = arg;
         const bytes = m?.serializeBinary
@@ -81,3 +99,60 @@ async function reportUnary(options, grpcClient, path, message, deadlineMs = 1000
         }
     });
 }
+/**
+ * Pauses execution for specified milliseconds with unref'd timer to avoid blocking shutdown
+ */
+function pauseExecution(durationMs) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, durationMs);
+        // Unref the timer so it doesn't keep the process alive
+        timer.unref();
+    });
+}
+/**
+ * Attempts gRPC call with exponential backoff retry logic using iterative approach
+ */
+async function attemptWithRetries(options, grpcClient, path, message, deadlineMs, maxRetries) {
+    let attemptNumber = 0;
+    let lastError = null;
+    // Try initial attempt + retries
+    for (let retriesRemaining = maxRetries; retriesRemaining >= 0; retriesRemaining--) {
+        try {
+            return await executeSingleAttempt(grpcClient, path, message, deadlineMs);
+        }
+        catch (err) {
+            lastError = err;
+            const grpcErr = err;
+            const statusCode = grpcErr?.code ?? grpc.status.UNKNOWN;
+            // Check if we should retry this error
+            const isRetryable = shouldAttemptRetryForCode(statusCode);
+            const hasRetriesLeft = retriesRemaining > 0;
+            if (!isRetryable || !hasRetriesLeft) {
+                throw err;
+            }
+            // Log retry attempt if verbose
+            if (options.verbose) {
+                console.log(`gRPC call failed (code: ${statusCode}), retrying... ` +
+                    `(attempt ${attemptNumber + 1}, ${retriesRemaining} retries left)`);
+            }
+            // Calculate and wait for backoff duration
+            const baseDelay = options.grpcRetryDelay ?? 100;
+            const waitTime = calculateWaitDuration(baseDelay, attemptNumber);
+            await pauseExecution(waitTime);
+            attemptNumber++;
+        }
+    }
+    // This should never be reached due to the throw in the loop, but TypeScript needs it
+    throw lastError || new Error("Retry loop exhausted without result");
+}
+/**
+ * Helper: generic unary call using raw method path with retry support
+ */
+async function reportUnary(options, grpcClient, path, message, deadlineMs = 1000) {
+    if (!options.grpcEnabled || !grpcClient) {
+        return Buffer.alloc(0);
+    }
+    await (0, debugLogger_1.writeDebugEntry)(options, path, message);
+    const maxRetries = options.grpcMaxRetries ?? 3;
+    return attemptWithRetries(options, grpcClient, path, message, deadlineMs, maxRetries);
+}

package/dist/reporter.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 const crypto_1 = require("crypto");
 const optionsMapper_1 = __importDefault(require("./utils/optionsMapper"));
+const debugLogger_1 = require("./utils/debugLogger");
 const grpcClient_1 = __importDefault(require("./client/grpcClient"));
 const handlers_1 = require("./handlers");
 class StanterpriseReporter {
@@ -26,6 +27,8 @@ class StanterpriseReporter {
         }
         // Generate a UUID for runId
         this.runId = process.env.STANTERPRISE_RUN_ID || (0, crypto_1.randomUUID)();
+        // Initialize debug file (creates/truncates it) when debug mode is enabled
+        (0, debugLogger_1.initDebugFile)(this.options);
     }
     onBegin(config, suite) {
         // Lazily create the client if enabled.

package/dist/types.d.ts

@@ -36,6 +36,33 @@ export interface StanterpriseReporterOptions {
      * @default false
      */
     verbose?: boolean;
+    /**
+     * Maximum number of retry attempts for failed gRPC calls
+     * @default 3
+     */
+    grpcMaxRetries?: number;
+    /**
+     * Initial delay between retry attempts in milliseconds
+     * Actual delay uses exponential backoff: initialDelay * (2 ^ attemptNumber)
+     * @default 100
+     */
+    grpcRetryDelay?: number;
+    /**
+     * Whether to enable debug mode, which writes all outgoing gRPC messages to a JSONL file.
+     * Warning: debug output may include full request payloads, including attachment content
+     * and metadata, which can contain sensitive values. Debug files may also grow very large.
+     * Enable this only for troubleshooting in controlled environments.
+     * @default false or process.env.STANTERPRISE_DEBUG === "true"
+     */
+    debug?: boolean;
+    /**
+     * File path for debug JSONL output when debug mode is enabled.
+     * Warning: the file may contain sensitive request data and can become very large,
+     * especially when attachments are included. Use only in controlled environments and
+     * handle the output file securely.
+     * @default "stanterprise-debug.jsonl" or process.env.STANTERPRISE_DEBUG_FILE
+     */
+    debugFile?: string;
 }
 /**
  * Internal type for managing test execution state

package/dist/utils/debugLogger.d.ts

@@ -0,0 +1,13 @@
+import { StanterpriseReporterOptions } from "../types";
+/**
+ * Creates or truncates the debug JSONL file so each test run starts with a clean file.
+ * No-op when debug mode is disabled.
+ */
+export declare function initDebugFile(options: StanterpriseReporterOptions): void;
+/**
+ * Appends a single JSONL entry for an outgoing gRPC message.
+ * Each entry is a JSON object on its own line containing the timestamp,
+ * gRPC method path, and the serialized message payload.
+ * No-op when debug mode is disabled.
+ */
+export declare function writeDebugEntry(options: StanterpriseReporterOptions, path: string, message: unknown): Promise<void>;

package/dist/utils/debugLogger.js

@@ -0,0 +1,87 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initDebugFile = initDebugFile;
+exports.writeDebugEntry = writeDebugEntry;
+const fs = __importStar(require("fs"));
+const nodePath = __importStar(require("path"));
+/**
+ * Ensures the parent directory of `filePath` exists, creating it recursively if needed.
+ */
+function ensureParentDir(filePath) {
+    const dir = nodePath.dirname(filePath);
+    if (dir && dir !== ".") {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+}
+/**
+ * Creates or truncates the debug JSONL file so each test run starts with a clean file.
+ * No-op when debug mode is disabled.
+ */
+function initDebugFile(options) {
+    if (!options.debug)
+        return;
+    const filePath = options.debugFile || "stanterprise-debug.jsonl";
+    try {
+        ensureParentDir(filePath);
+        fs.writeFileSync(filePath, "");
+    }
+    catch (e) {
+        console.error(`Stanterprise Reporter: Failed to initialize debug file "${filePath}":`, e);
+    }
+}
+/**
+ * Appends a single JSONL entry for an outgoing gRPC message.
+ * Each entry is a JSON object on its own line containing the timestamp,
+ * gRPC method path, and the serialized message payload.
+ * No-op when debug mode is disabled.
+ */
+async function writeDebugEntry(options, path, message) {
+    if (!options.debug)
+        return;
+    const filePath = options.debugFile || "stanterprise-debug.jsonl";
+    const entry = {
+        timestamp: new Date().toISOString(),
+        path,
+        message,
+    };
+    try {
+        ensureParentDir(filePath);
+        await fs.promises.appendFile(filePath, JSON.stringify(entry) + "\n");
+    }
+    catch (e) {
+        console.error(`Stanterprise Reporter: Failed to write debug entry to "${filePath}":`, e);
+    }
+}

package/dist/utils/index.d.ts

@@ -7,3 +7,4 @@ export * from "./timeHelpers";
 export * from "./idGenerators";
 export * from "./envRetriever";
 export * from "./metadataHelpers";
+export * from "./debugLogger";

package/dist/utils/index.js

@@ -23,3 +23,4 @@ __exportStar(require("./timeHelpers"), exports);
 __exportStar(require("./idGenerators"), exports);
 __exportStar(require("./envRetriever"), exports);
 __exportStar(require("./metadataHelpers"), exports);
+__exportStar(require("./debugLogger"), exports);

package/dist/utils/optionsMapper.js

@@ -16,6 +16,17 @@ function defineOptions(providedOptions) {
         providedOptions.grpcEnabled ??
             (process.env.STANTERPRISE_GRPC_ENABLED || "true").toLowerCase() !== "false";
     result.grpcTimeout = providedOptions.grpcTimeout || 1000;
+    result.grpcMaxMessageSize = providedOptions.grpcMaxMessageSize || 104857600;
+    result.maxAttachmentSize = providedOptions.maxAttachmentSize || 10485760;
     result.verbose = providedOptions.verbose || false;
+    result.grpcMaxRetries = providedOptions.grpcMaxRetries ?? 3;
+    result.grpcRetryDelay = providedOptions.grpcRetryDelay || 100;
+    result.debug =
+        providedOptions.debug ??
+            (process.env.STANTERPRISE_DEBUG || "").toLowerCase() === "true";
+    result.debugFile =
+        providedOptions.debugFile ||
+            process.env.STANTERPRISE_DEBUG_FILE ||
+            "stanterprise-debug.jsonl";
     return result;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stanterprise/playwright-reporter",
-  "version": "0.0.18",
+  "version": "0.0.20",
   "description": "Custom Playwright test reporter that sends test results to Stanterprise via gRPC",
   "homepage": "https://github.com/stanterprise/stanterprise-playwright-reporter#readme",
   "bugs": {