@stanterprise/playwright-reporter 0.0.19 → 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
 
@@ -94,6 +99,8 @@ npx playwright test
 | `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
 
@@ -133,6 +140,51 @@ To disable retries:
 }
 ```
 
+## 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
 
 The reporter automatically detects and reports when tests are running in sharded mode. When sharding is configured, the reporter includes the following metadata in test run events:
@@ -319,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.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
@@ -151,6 +152,7 @@ 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

@@ -47,6 +47,22 @@ export interface StanterpriseReporterOptions {
      * @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

@@ -21,5 +21,12 @@ function defineOptions(providedOptions) {
     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.19",
+  "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": {