@stanterprise/playwright-reporter 0.0.19 → 0.0.21

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.d.ts

@@ -1,10 +1,16 @@
 import { StanterpriseReporterOptions } from "../types";
 import * as grpc from "@grpc/grpc-js";
+import { MessageQueue } from "./messageQueue";
 export default function getClient(options: StanterpriseReporterOptions): grpc.Client | null;
 /**
- * Helper: generic unary call using raw method path with retry support
+ * Helper: generic unary call using raw method path with retry support.
+ *
+ * When a `queue` is provided the call is enqueued and executed only after all
+ * previously enqueued calls have completed, guaranteeing sequential delivery to
+ * the server. Without a queue the call is executed immediately (legacy / test
+ * behaviour).
  */
-export declare function reportUnary(options: StanterpriseReporterOptions, grpcClient: grpc.Client, path: string, message: {
+export declare function reportUnary(options: StanterpriseReporterOptions, grpcClient: grpc.Client, grpcPath: string, message: {
     serialize?: (w?: any) => Uint8Array;
     serializeBinary?: () => Uint8Array;
-}, deadlineMs?: number): Promise<Buffer>;
+}, deadlineMs?: number, queue?: MessageQueue): Promise<Buffer>;

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
@@ -145,12 +146,24 @@ async function attemptWithRetries(options, grpcClient, path, message, deadlineMs
     throw lastError || new Error("Retry loop exhausted without result");
 }
 /**
- * Helper: generic unary call using raw method path with retry support
+ * Helper: generic unary call using raw method path with retry support.
+ *
+ * When a `queue` is provided the call is enqueued and executed only after all
+ * previously enqueued calls have completed, guaranteeing sequential delivery to
+ * the server. Without a queue the call is executed immediately (legacy / test
+ * behaviour).
  */
-async function reportUnary(options, grpcClient, path, message, deadlineMs = 1000) {
+async function reportUnary(options, grpcClient, grpcPath, message, deadlineMs = 1000, queue) {
     if (!options.grpcEnabled || !grpcClient) {
         return Buffer.alloc(0);
     }
-    const maxRetries = options.grpcMaxRetries ?? 3;
-    return attemptWithRetries(options, grpcClient, path, message, deadlineMs, maxRetries);
+    const execute = async () => {
+        await (0, debugLogger_1.writeDebugEntry)(options, grpcPath, message);
+        const maxRetries = options.grpcMaxRetries ?? 3;
+        return attemptWithRetries(options, grpcClient, grpcPath, message, deadlineMs, maxRetries);
+    };
+    if (queue) {
+        return queue.enqueue(execute);
+    }
+    return execute();
 }

package/dist/client/messageQueue.d.ts

@@ -0,0 +1,27 @@
+/**
+ * A sequential async message queue that processes enqueued tasks one at a time,
+ * guaranteeing that each task completes before the next one begins.
+ *
+ * This ensures that gRPC messages are delivered to the server in the exact order
+ * they were enqueued, regardless of how quickly each individual call completes.
+ * It also serializes debug file writes as a side effect, since those are performed
+ * inside each task.
+ */
+export declare class MessageQueue {
+    private tasks;
+    private processing;
+    private drainResolvers;
+    /**
+     * Adds a task to the queue and returns a Promise that resolves (or rejects)
+     * when the task has been executed. If the queue is idle the task starts
+     * immediately; otherwise it waits for all preceding tasks to finish first.
+     */
+    enqueue<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Returns a Promise that resolves once the queue has been fully drained
+     * (i.e. all currently enqueued tasks have finished). Resolves immediately
+     * if the queue is already empty.
+     */
+    drain(): Promise<void>;
+    private processNext;
+}

package/dist/client/messageQueue.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MessageQueue = void 0;
+/**
+ * A sequential async message queue that processes enqueued tasks one at a time,
+ * guaranteeing that each task completes before the next one begins.
+ *
+ * This ensures that gRPC messages are delivered to the server in the exact order
+ * they were enqueued, regardless of how quickly each individual call completes.
+ * It also serializes debug file writes as a side effect, since those are performed
+ * inside each task.
+ */
+class MessageQueue {
+    constructor() {
+        this.tasks = [];
+        this.processing = false;
+        this.drainResolvers = [];
+    }
+    /**
+     * Adds a task to the queue and returns a Promise that resolves (or rejects)
+     * when the task has been executed. If the queue is idle the task starts
+     * immediately; otherwise it waits for all preceding tasks to finish first.
+     */
+    enqueue(fn) {
+        return new Promise((resolve, reject) => {
+            this.tasks.push(async () => {
+                try {
+                    const result = await fn();
+                    resolve(result);
+                }
+                catch (e) {
+                    reject(e);
+                }
+            });
+            if (!this.processing) {
+                this.processNext();
+            }
+        });
+    }
+    /**
+     * Returns a Promise that resolves once the queue has been fully drained
+     * (i.e. all currently enqueued tasks have finished). Resolves immediately
+     * if the queue is already empty.
+     */
+    drain() {
+        if (!this.processing && this.tasks.length === 0) {
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => {
+            this.drainResolvers.push(resolve);
+        });
+    }
+    async processNext() {
+        this.processing = true;
+        while (this.tasks.length > 0) {
+            const task = this.tasks.shift();
+            try {
+                await task();
+            }
+            catch {
+                // Each task's promise already carries the error to its caller.
+                // Errors must not stop the queue from processing subsequent tasks.
+            }
+        }
+        this.processing = false;
+        const resolvers = this.drainResolvers;
+        this.drainResolvers = [];
+        resolvers.forEach((r) => r());
+    }
+}
+exports.MessageQueue = MessageQueue;

package/dist/handlers/onBeginHandler.d.ts

@@ -2,4 +2,5 @@ import { FullConfig } from "@playwright/test";
 import { Suite } from "@playwright/test/reporter";
 import { StanterpriseReporterOptions } from "../types";
 import * as grpc from "@grpc/grpc-js";
-export declare function handleOnBeginEvent(config: FullConfig, suite: Suite, name: string, runId: string, client: grpc.Client, options: StanterpriseReporterOptions): void;
+import { MessageQueue } from "../client/messageQueue";
+export declare function handleOnBeginEvent(config: FullConfig, suite: Suite, name: string, runId: string, client: grpc.Client, options: StanterpriseReporterOptions, queue?: MessageQueue): void;

package/dist/handlers/onBeginHandler.js

@@ -6,7 +6,7 @@ const grpcClient_1 = require("../client/grpcClient");
 const entities_1 = require("@stanterprise/protobuf/testsystem/v1/entities");
 const utils_1 = require("../utils");
 const common_1 = require("@stanterprise/protobuf/testsystem/v1/common");
-function handleOnBeginEvent(config, suite, name, runId, client, options) {
+function handleOnBeginEvent(config, suite, name, runId, client, options, queue) {
     // Report root suite and all child suites recursively
     // Convert all metadata values to strings for protobuf compatibility
     // Use plain object instead of Map - protobuf expects object literals
@@ -31,7 +31,7 @@ function handleOnBeginEvent(config, suite, name, runId, client, options) {
         total_tests: suite.allTests().length,
         metadata: (0, utils_1.toMetadataMap)(metadata),
     });
-    (0, grpcClient_1.reportUnary)(options, client, "/testsystem.v1.observer.TestEventCollector/ReportRunStart", request, options.grpcTimeout).catch((e) => {
+    (0, grpcClient_1.reportUnary)(options, client, "/testsystem.v1.observer.TestEventCollector/ReportRunStart", request, options.grpcTimeout, queue).catch((e) => {
         const details = e instanceof Error ? `${e.message}` : String(e);
         console.warn(`onBegin. gRPC disabled for the remainder of the run. Address=${options.grpcAddress}. Details: ${details}`);
     });

package/dist/handlers/onEndHandler.d.ts

@@ -1,4 +1,5 @@
 import { FullResult } from "@playwright/test/reporter";
 import { StanterpriseReporterOptions } from "../types";
 import * as grpc from "@grpc/grpc-js";
-export declare function handleOnEndEvent(result: FullResult, runId: string, client: grpc.Client, options: StanterpriseReporterOptions): void;
+import { MessageQueue } from "../client/messageQueue";
+export declare function handleOnEndEvent(result: FullResult, runId: string, client: grpc.Client, options: StanterpriseReporterOptions, queue?: MessageQueue): void;

package/dist/handlers/onEndHandler.js

@@ -19,7 +19,7 @@ function mapTestStatus(status) {
             return common_1.TestStatus.UNKNOWN;
     }
 }
-function handleOnEndEvent(result, runId, client, options) {
+function handleOnEndEvent(result, runId, client, options, queue) {
     // Validate and sanitize inputs to prevent serialization failures
     const startTimeMs = result.startTime?.getTime();
     const duration = result.duration;
@@ -36,7 +36,7 @@ function handleOnEndEvent(result, runId, client, options) {
         start_time: (0, utils_1.createTimestampFromMs)(validStartTimeMs),
         duration: (0, utils_1.createDuration)(validDuration),
     });
-    (0, grpcClient_1.reportUnary)(options, client, "/testsystem.v1.observer.TestEventCollector/ReportRunEnd", request, options.grpcTimeout).catch((error) => {
+    (0, grpcClient_1.reportUnary)(options, client, "/testsystem.v1.observer.TestEventCollector/ReportRunEnd", request, options.grpcTimeout, queue).catch((error) => {
         if (error instanceof Error) {
             console.error(`Failed to report end event: ${error.message}`, {
                 stack: error.stack,

package/dist/handlers/onErrorHandler.d.ts

@@ -1,4 +1,5 @@
 import { TestError } from "@playwright/test/reporter";
 import { StanterpriseReporterOptions } from "../types";
 import * as grpc from "@grpc/grpc-js";
-export declare function handleOnErrorEvent(error: TestError, runId: string, grpcClient: grpc.Client, options: StanterpriseReporterOptions): void;
+import { MessageQueue } from "../client/messageQueue";
+export declare function handleOnErrorEvent(error: TestError, runId: string, grpcClient: grpc.Client, options: StanterpriseReporterOptions, queue?: MessageQueue): void;

package/dist/handlers/onErrorHandler.js

@@ -4,12 +4,12 @@ exports.handleOnErrorEvent = handleOnErrorEvent;
 const events_1 = require("@stanterprise/protobuf/testsystem/v1/events");
 const timeHelpers_1 = require("../utils/timeHelpers");
 const grpcClient_1 = require("../client/grpcClient");
-function handleOnErrorEvent(error, runId, grpcClient, options) {
+function handleOnErrorEvent(error, runId, grpcClient, options, queue) {
     const request = new events_1.StdErrorEventRequest({
         run_id: runId,
         message: error.message,
         timestamp: (0, timeHelpers_1.createTimestampFromMs)(Date.now()),
     });
     // Fire-and-forget to avoid slowing tests
-    (0, grpcClient_1.reportUnary)(options, grpcClient, "/testsystem.v1.observer.TestEventCollector/ReportStdError", request, options.grpcTimeout).catch((e) => console.error("Failed to report standard error", e));
+    (0, grpcClient_1.reportUnary)(options, grpcClient, "/testsystem.v1.observer.TestEventCollector/ReportStdError", request, options.grpcTimeout, queue).catch((e) => console.error("Failed to report standard error", e));
 }

package/dist/handlers/onStepBeginHandler.d.ts

@@ -1,4 +1,5 @@
 import { TestCase, TestResult, TestStep } from "@playwright/test/reporter";
 import { StanterpriseReporterOptions } from "../types";
 import * as grpc from "@grpc/grpc-js";
-export declare function handleOnStepBeginEvent(test: TestCase, result: TestResult, step: TestStep, runId: string, client: grpc.Client, options: StanterpriseReporterOptions): void;
+import { MessageQueue } from "../client/messageQueue";
+export declare function handleOnStepBeginEvent(test: TestCase, result: TestResult, step: TestStep, runId: string, client: grpc.Client, options: StanterpriseReporterOptions, queue?: MessageQueue): void;

package/dist/handlers/onStepBeginHandler.js

@@ -7,7 +7,7 @@ const utils_1 = require("../utils");
 const grpcClient_1 = require("../client/grpcClient");
 const utils_2 = require("../utils");
 const common_1 = require("@stanterprise/protobuf/testsystem/v1/common");
-function handleOnStepBeginEvent(test, result, step, runId, client, options) {
+function handleOnStepBeginEvent(test, result, step, runId, client, options, queue) {
     // Build metadata from step annotations
     const metadata = (0, utils_1.buildStepMetadata)(step);
     // Get parent step ID if this step has a parent
@@ -34,5 +34,5 @@ function handleOnStepBeginEvent(test, result, step, runId, client, options) {
         }),
     });
     // Fire-and-forget to avoid slowing tests
-    (0, grpcClient_1.reportUnary)(options, client, "/testsystem.v1.observer.TestEventCollector/ReportStepBegin", request, options.grpcTimeout).catch((e) => console.error("Failed to report step begin", e));
+    (0, grpcClient_1.reportUnary)(options, client, "/testsystem.v1.observer.TestEventCollector/ReportStepBegin", request, options.grpcTimeout, queue).catch((e) => console.error("Failed to report step begin", e));
 }

package/dist/handlers/onStepEndHandler.d.ts

@@ -1,4 +1,5 @@
 import { TestCase, TestResult, TestStep } from "@playwright/test/reporter";
 import { StanterpriseReporterOptions } from "../types";
 import * as grpc from "@grpc/grpc-js";
-export declare function handleOnStepEndEvent(test: TestCase, result: TestResult, step: TestStep, runId: string, client: grpc.Client, options: StanterpriseReporterOptions): void;
+import { MessageQueue } from "../client/messageQueue";
+export declare function handleOnStepEndEvent(test: TestCase, result: TestResult, step: TestStep, runId: string, client: grpc.Client, options: StanterpriseReporterOptions, queue?: MessageQueue): void;

package/dist/handlers/onStepEndHandler.js

@@ -6,7 +6,7 @@ const events_1 = require("@stanterprise/protobuf/testsystem/v1/events");
 const utils_1 = require("../utils");
 const grpcClient_1 = require("../client/grpcClient");
 const utils_2 = require("../utils");
-function handleOnStepEndEvent(test, result, step, runId, client, options) {
+function handleOnStepEndEvent(test, result, step, runId, client, options, queue) {
     // Map step error to status
     const stepStatus = (0, utils_1.mapStepStatus)(!!step.error);
     // Build metadata from step annotations
@@ -55,5 +55,5 @@ function handleOnStepEndEvent(test, result, step, runId, client, options) {
         }),
     });
     // Fire-and-forget to avoid slowing tests
-    (0, grpcClient_1.reportUnary)(options, client, "/testsystem.v1.observer.TestEventCollector/ReportStepEnd", request, options.grpcTimeout).catch((e) => console.error("Failed to report step end", e));
+    (0, grpcClient_1.reportUnary)(options, client, "/testsystem.v1.observer.TestEventCollector/ReportStepEnd", request, options.grpcTimeout, queue).catch((e) => console.error("Failed to report step end", e));
 }

package/dist/handlers/onTestBeginHandler.d.ts

@@ -1,4 +1,5 @@
 import { TestCase, TestResult } from "@playwright/test/reporter";
 import { StanterpriseReporterOptions } from "../types";
 import * as grpc from "@grpc/grpc-js";
-export declare function handleOnTestBeginEvent(test: TestCase, result: TestResult, runId: string, client: grpc.Client, options: StanterpriseReporterOptions): void;
+import { MessageQueue } from "../client/messageQueue";
+export declare function handleOnTestBeginEvent(test: TestCase, result: TestResult, runId: string, client: grpc.Client, options: StanterpriseReporterOptions, queue?: MessageQueue): void;

package/dist/handlers/onTestBeginHandler.js

@@ -6,7 +6,7 @@ const events_1 = require("@stanterprise/protobuf/testsystem/v1/events");
 const utils_1 = require("../utils");
 const grpcClient_1 = require("../client/grpcClient");
 const common_1 = require("@stanterprise/protobuf/testsystem/v1/common");
-function handleOnTestBeginEvent(test, result, runId, client, options) {
+function handleOnTestBeginEvent(test, result, runId, client, options, queue) {
     // Build and send the TestBegin event via generic unary call.
     const request = new events_1.TestBeginEventRequest({
         test_case: new entities_1.TestCaseRun({
@@ -25,7 +25,7 @@ function handleOnTestBeginEvent(test, result, runId, client, options) {
         }),
     });
     // Fire-and-forget to avoid slowing tests; log errors once.
-    (0, grpcClient_1.reportUnary)(options, client, "/testsystem.v1.observer.TestEventCollector/ReportTestBegin", request, options.grpcTimeout).catch((e) => {
+    (0, grpcClient_1.reportUnary)(options, client, "/testsystem.v1.observer.TestEventCollector/ReportTestBegin", request, options.grpcTimeout, queue).catch((e) => {
         const details = e instanceof Error ? `${e.message}` : String(e);
         console.warn(`Failed to report test begin. Details: ${details}`);
     });

package/dist/handlers/onTestEndHandler.d.ts

@@ -1,4 +1,5 @@
 import { TestCase, TestResult } from "@playwright/test/reporter";
 import { StanterpriseReporterOptions } from "../types";
 import * as grpc from "@grpc/grpc-js";
-export declare function handleOnTestEndEvent(test: TestCase, result: TestResult, runId: string, client: grpc.Client, options: StanterpriseReporterOptions): void;
+import { MessageQueue } from "../client/messageQueue";
+export declare function handleOnTestEndEvent(test: TestCase, result: TestResult, runId: string, client: grpc.Client, options: StanterpriseReporterOptions, queue?: MessageQueue): void;

package/dist/handlers/onTestEndHandler.js

@@ -10,7 +10,7 @@ const utils_2 = require("../utils");
  * Constant for converting bytes to megabytes
  */
 const BYTES_PER_MB = 1048576;
-function handleOnTestEndEvent(test, result, runId, client, options) {
+function handleOnTestEndEvent(test, result, runId, client, options, queue) {
     // Map Playwright test status to protobuf TestStatus
     const testStatus = (0, utils_1.mapTestStatus)(result.status);
     // Process attachments (screenshots, videos, etc.)
@@ -51,7 +51,7 @@ function handleOnTestEndEvent(test, result, runId, client, options) {
             `Error length: ${errorMessage.length + stackTrace.length} bytes`);
     }
     // Fire-and-forget to avoid slowing tests
-    (0, grpcClient_1.reportUnary)(options, client, "/testsystem.v1.observer.TestEventCollector/ReportTestEnd", request, options.grpcTimeout).catch((e) => {
+    (0, grpcClient_1.reportUnary)(options, client, "/testsystem.v1.observer.TestEventCollector/ReportTestEnd", request, options.grpcTimeout, queue).catch((e) => {
         console.error(`Failed to report test end for "${test.title}" (payload size: ${(payloadSize / BYTES_PER_MB).toFixed(2)}MB)`, e);
     });
 }

package/dist/handlers/onTestFailHandler.d.ts

@@ -1,4 +1,5 @@
 import { TestCase, TestResult } from "@playwright/test/reporter";
 import { StanterpriseReporterOptions } from "../types";
 import * as grpc from "@grpc/grpc-js";
-export declare function handleOnTestFailEvent(test: TestCase, result: TestResult, runId: string, grpcClient: grpc.Client, options: StanterpriseReporterOptions): void;
+import { MessageQueue } from "../client/messageQueue";
+export declare function handleOnTestFailEvent(test: TestCase, result: TestResult, runId: string, grpcClient: grpc.Client, options: StanterpriseReporterOptions, queue?: MessageQueue): void;

package/dist/handlers/onTestFailHandler.js

@@ -4,7 +4,7 @@ exports.handleOnTestFailEvent = handleOnTestFailEvent;
 const utils_1 = require("../utils");
 const events_1 = require("@stanterprise/protobuf/testsystem/v1/events");
 const grpcClient_1 = require("../client/grpcClient");
-function handleOnTestFailEvent(test, result, runId, grpcClient, options) {
+function handleOnTestFailEvent(test, result, runId, grpcClient, options, queue) {
     // Extract failure details
     const { errorMessage: failureMessage, stackTrace } = (0, utils_1.extractErrorInfo)(result);
     // Process attachments for failed tests
@@ -20,5 +20,5 @@ function handleOnTestFailEvent(test, result, runId, grpcClient, options) {
         retry_index: result.retry,
     });
     // Fire-and-forget to avoid slowing tests
-    (0, grpcClient_1.reportUnary)(options, grpcClient, "/testsystem.v1.observer.TestEventCollector/ReportTestFailure", request, options.grpcTimeout).catch((e) => console.error("Failed to report test failure", e));
+    (0, grpcClient_1.reportUnary)(options, grpcClient, "/testsystem.v1.observer.TestEventCollector/ReportTestFailure", request, options.grpcTimeout, queue).catch((e) => console.error("Failed to report test failure", e));
 }

package/dist/reporter.d.ts

@@ -5,6 +5,7 @@ export default class StanterpriseReporter implements Reporter {
     private options;
     private runId;
     private runStartTime;
+    private messageQueue;
     constructor(options?: StanterpriseReporterOptions);
     onBegin(config: FullConfig, suite: Suite): void;
     onExit(): Promise<void>;

package/dist/reporter.js

@@ -5,7 +5,9 @@ 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 messageQueue_1 = require("./client/messageQueue");
 const handlers_1 = require("./handlers");
 class StanterpriseReporter {
     constructor(options = {}) {
@@ -15,6 +17,8 @@ class StanterpriseReporter {
         // Generate a unique run ID for this test run
         this.runId = "";
         this.runStartTime = new Date();
+        // Sequential message queue – guarantees ordered delivery to the server
+        this.messageQueue = new messageQueue_1.MessageQueue();
         this.options = (0, optionsMapper_1.default)(options);
         if (this.options.verbose) {
             console.log("Stanterprise Reporter: Initialized with options:", {
@@ -26,6 +30,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.
@@ -50,10 +56,12 @@ class StanterpriseReporter {
             }
         }
         if (this.options.grpcEnabled) {
-            (0, handlers_1.handleOnBeginEvent)(config, suite, process.env.STANTERPRISE_TEST_RUN_NAME || "Playwright Test Run", this.runId, this.grpcClient, this.options);
+            (0, handlers_1.handleOnBeginEvent)(config, suite, process.env.STANTERPRISE_TEST_RUN_NAME || "Playwright Test Run", this.runId, this.grpcClient, this.options, this.messageQueue);
         }
     }
     async onExit() {
+        // Wait for all enqueued messages to be sent before closing the connection.
+        await this.messageQueue.drain();
         console.log(`Stanterprise Reporter: Test run completed - Run ID: ${this.runId}`);
         // Cleanup gRPC client
         try {
@@ -73,7 +81,7 @@ class StanterpriseReporter {
             console.log(`Playwright start time: ${result.startTime.toISOString()}`);
         }
         if (this.options.grpcEnabled) {
-            (0, handlers_1.handleOnEndEvent)(result, this.runId, this.grpcClient, this.options);
+            (0, handlers_1.handleOnEndEvent)(result, this.runId, this.grpcClient, this.options, this.messageQueue);
         }
         return Promise.resolve();
     }
@@ -85,7 +93,7 @@ class StanterpriseReporter {
             console.log(`  Test ID: ${test.id}`);
         }
         if (this.options.grpcEnabled) {
-            (0, handlers_1.handleOnTestBeginEvent)(test, result, this.runId, this.grpcClient, this.options);
+            (0, handlers_1.handleOnTestBeginEvent)(test, result, this.runId, this.grpcClient, this.options, this.messageQueue);
         }
     }
     async onStepBegin(test, result, step) {
@@ -94,7 +102,7 @@ class StanterpriseReporter {
             console.log(`  Category: ${step.category}`);
         }
         if (this.options.grpcEnabled) {
-            (0, handlers_1.handleOnStepBeginEvent)(test, result, step, this.runId, this.grpcClient, this.options);
+            (0, handlers_1.handleOnStepBeginEvent)(test, result, step, this.runId, this.grpcClient, this.options, this.messageQueue);
         }
     }
     onStepEnd(test, result, step) {
@@ -103,7 +111,7 @@ class StanterpriseReporter {
             console.log(`  Duration: ${step.duration}ms`);
         }
         if (this.options.grpcEnabled) {
-            (0, handlers_1.handleOnStepEndEvent)(test, result, step, this.runId, this.grpcClient, this.options);
+            (0, handlers_1.handleOnStepEndEvent)(test, result, step, this.runId, this.grpcClient, this.options, this.messageQueue);
         }
     }
     onTestEnd(test, result) {
@@ -113,7 +121,7 @@ class StanterpriseReporter {
             console.log(`  Duration: ${result.duration}ms`);
         }
         if (this.options.grpcEnabled) {
-            (0, handlers_1.handleOnTestEndEvent)(test, result, this.runId, this.grpcClient, this.options);
+            (0, handlers_1.handleOnTestEndEvent)(test, result, this.runId, this.grpcClient, this.options, this.messageQueue);
         }
     }
     onTestFail(test, result) {
@@ -121,7 +129,7 @@ class StanterpriseReporter {
             console.log(`Stanterprise Reporter: Test failed - ${test.title}`);
         }
         if (this.options.grpcEnabled) {
-            (0, handlers_1.handleOnTestFailEvent)(test, result, this.runId, this.grpcClient, this.options);
+            (0, handlers_1.handleOnTestFailEvent)(test, result, this.runId, this.grpcClient, this.options, this.messageQueue);
         }
     }
     onError(error) {
@@ -131,7 +139,7 @@ class StanterpriseReporter {
             console.error(`Stack trace: ${error.stack}`);
         }
         if (this.options.grpcEnabled) {
-            (0, handlers_1.handleOnErrorEvent)(error, this.runId, this.grpcClient, this.options);
+            (0, handlers_1.handleOnErrorEvent)(error, this.runId, this.grpcClient, this.options, this.messageQueue);
         }
     }
     onStdErr(chunk, test, result) {

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.21",
   "description": "Custom Playwright test reporter that sends test results to Stanterprise via gRPC",
   "homepage": "https://github.com/stanterprise/stanterprise-playwright-reporter#readme",
   "bugs": {