@stanterprise/playwright-reporter 1.0.0 → 1.0.1

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,12 +41,16 @@ 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
         grpcTimeout: 1000, // Timeout for gRPC calls in milliseconds
+        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
       },
     ],
   ],
@@ -58,22 +63,205 @@ export default defineConfig({
 You can also configure the reporter using environment variables:
 
 - `STANTERPRISE_GRPC_ADDRESS`: gRPC server address (default: `localhost:50051`)
+- `STANTERPRISE_GRPC_HOST`: gRPC server host
 - `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
+
+Any environment variable with the `STANTERPRISE_META_` prefix will be automatically included in the test run metadata. The prefix is stripped from the key name.
+
+For example:
+
+- `STANTERPRISE_META_BUILD_ID=12345` becomes `BUILD_ID: 12345` in metadata
+- `STANTERPRISE_META_BRANCH=main` becomes `BRANCH: main` in metadata
+- `STANTERPRISE_META_COMMIT_SHA=abc123` becomes `COMMIT_SHA: abc123` in metadata
 
 Example:
 
 ```bash
-STANTERPRISE_GRPC_ADDRESS=myserver.com:50051 npx playwright test
+STANTERPRISE_GRPC_ADDRESS=myserver.com:50051 \
+STANTERPRISE_META_BUILD_ID=12345 \
+STANTERPRISE_META_BRANCH=main \
+npx playwright test
 ```
 
 ## Configuration Options
 
-| Option         | Type    | Default          | Description                               |
-| -------------- | ------- | ---------------- | ----------------------------------------- |
-| `grpcAddress`  | string  | `localhost:50051`| gRPC server address                       |
-| `grpcEnabled`  | boolean | `true`           | Enable/disable gRPC reporting             |
-| `grpcTimeout`  | number  | `1000`           | Timeout for gRPC calls in milliseconds    |
-| `verbose`      | boolean | `false`          | Enable verbose logging                    |
+| Option               | Type    | Default                    | Description                                                                                                                                                                                 |
+| -------------------- | ------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `grpcAddress`        | string  | `localhost:50051`          | Full gRPC server address. Takes precedence over `grpcHost` and `grpcPort`.                                                                                                                  |
+| `grpcHost`           | string  |                            | gRPC server host. Used when `grpcAddress` is not provided. Combined with `grpcPort` to form the address.                                                                                    |
+| `grpcPort`           | number  | `50051`                    | gRPC server port. Used when `grpcAddress` is not provided. Combined with `grpcHost` to form the address.                                                                                    |
+| `grpcEnabled`        | boolean | `true`                     | Enable/disable gRPC reporting                                                                                                                                                               |
+| `grpcTimeout`        | number  | `1000`                     | Timeout for gRPC calls in milliseconds                                                                                                                                                      |
+| `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
+
+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:
+
+- `shard.current`: The current shard number (1-based)
+- `shard.total`: The total number of shards
+
+### Configuring Sharding
+
+In your `playwright.config.ts`:
+
+```typescript
+import { defineConfig } from "@playwright/test";
+
+export default defineConfig({
+  shard: { total: 5, current: 1 },
+  reporter: [["stanterprise-playwright-reporter"]],
+});
+```
+
+Or via CLI:
+
+```bash
+npx playwright test --shard=1/5
+npx playwright test --shard=2/5
+# ... etc
+```
+
+### Aggregating Results Across Shards
+
+**Important:** To have a complete set of tests accumulated in the observability server, you must specify the same `STANTERPRISE_RUN_ID` environment variable for all shards. This ensures that results from all shards are associated with the same test run.
+
+```bash
+# Set the same run ID for all shards
+export STANTERPRISE_RUN_ID="my-test-run-123"
+
+# Run all shards with the same run ID
+npx playwright test --shard=1/5
+npx playwright test --shard=2/5
+npx playwright test --shard=3/5
+npx playwright test --shard=4/5
+npx playwright test --shard=5/5
+```
+
+In CI/CD environments, you can use a unique identifier from your CI system:
+
+```bash
+# GitHub Actions example
+STANTERPRISE_RUN_ID="${GITHUB_RUN_ID}" npx playwright test --shard=1/5
+
+# GitLab CI example
+STANTERPRISE_RUN_ID="${CI_PIPELINE_ID}" npx playwright test --shard=1/5
+
+# Jenkins example
+STANTERPRISE_RUN_ID="${BUILD_ID}" npx playwright test --shard=1/5
+```
+
+Without a shared `STANTERPRISE_RUN_ID`, each shard will generate its own unique run ID, and the results will be reported as separate test runs rather than a single aggregated run.
+
+The shard information is automatically included in the metadata sent to the server, allowing you to:
+
+- Track which tests ran on which shard
+- Aggregate results from multiple shards
+- Debug shard-specific issues
+
+When verbose logging is enabled, you'll see shard information in the console output:
+
+```
+Stanterprise Reporter: Test run started with ID: 123e4567-e89b-12d3-a456-426614174000
+Number of tests: 42
+Run started at: 2026-01-25T10:30:00.000Z
+Shard: 1 of 5
+```
 
 ## What Gets Reported
 
@@ -91,6 +279,7 @@ STANTERPRISE_GRPC_ADDRESS=myserver.com:50051 npx playwright test
 ### Attachments
 
 The reporter automatically processes and sends:
+
 - Screenshots
 - Videos
 - Trace files
@@ -133,6 +322,8 @@ const reporter = new StanterpriseReporter({
   grpcAddress: "localhost:50051",
   grpcEnabled: true,
   grpcTimeout: 1000,
+  grpcMaxMessageSize: 104857600, // 100MB
+  maxAttachmentSize: 10485760, // 10MB
   verbose: false,
 });
 ```
@@ -184,9 +375,62 @@ 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
 
+### gRPC Error 13 INTERNAL: failed to publish event
+
+This error typically occurs due to one of two issues:
+
+**1. Metadata Serialization (Most Common)**
+
+If you see this error with the stack trace mentioning "metadata is not iterable" or serialization issues, it was a bug in v0.0.13 and earlier versions. **Solution: Upgrade to v0.0.14 or later.**
+
+**2. Large Attachments**
+
+This error can also occur when test event payloads exceed the gRPC message size limit. Common causes:
+
+1. **Large attachments**: Tests with large screenshots, videos, or trace files
+2. **Default size limits**: gRPC has a default 4MB message size limit
+
+**Solutions:**
+
+1. **Increase message size limits** (recommended):
+
+   ```typescript
+   reporter: [
+     [
+       "stanterprise-playwright-reporter",
+       {
+         grpcMaxMessageSize: 104857600, // 100MB (default)
+         maxAttachmentSize: 10485760,   // 10MB (default)
+       },
+     ],
+   ],
+   ```
+
+2. **Reduce attachment sizes**:
+   - Configure Playwright to save attachments to disk instead of embedding them
+   - The reporter automatically uses file paths when available instead of content
+
+   ```typescript
+   use: {
+     screenshot: "only-on-failure",
+     video: "retain-on-failure",
+     trace: "retain-on-failure",
+   },
+   ```
+
+3. **Monitor payload sizes**: Enable verbose logging to see actual payload sizes:
+   ```typescript
+   reporter: [
+     ["stanterprise-playwright-reporter", { verbose: true }],
+   ],
+   ```
+
+The reporter will log warnings when attachments exceed the size limit and automatically skip their content while preserving metadata.
+
 ### Connection Issues
 
 If you see gRPC connection errors:
@@ -216,6 +460,7 @@ Contributions are welcome! Please feel free to submit a Pull Request.
 The repository uses GitHub Actions to automatically publish to NPM when a version tag is pushed:
 
 1. Update the version following [semantic versioning](https://semver.org/):
+
    ```bash
    npm version patch  # for bug fixes (1.0.0 → 1.0.1)
    npm version minor  # for new features (1.0.0 → 1.1.0)
@@ -223,6 +468,7 @@ The repository uses GitHub Actions to automatically publish to NPM when a versio
    ```
 
 2. Push the version tag to GitHub:
+
    ```bash
    git push --follow-tags
    ```
@@ -239,16 +485,19 @@ The repository uses GitHub Actions to automatically publish to NPM when a versio
 Alternatively, you can publish manually:
 
 1. Ensure all tests pass:
+
    ```bash
    npm test
    ```
 
 2. Update the version:
+
    ```bash
    npm version patch|minor|major
    ```
 
 3. Publish to NPM (prepublishOnly script will build automatically):
+
    ```bash
    npm publish
    ```
@@ -261,10 +510,12 @@ Alternatively, you can publish manually:
 ### What Gets Published
 
 The package includes:
+
 - `dist/` - Compiled JavaScript and TypeScript declarations
 - `README.md` - Documentation
 
 The following are excluded via `.npmignore`:
+
 - Source files (`src/`, `tests/`, `examples/`)
 - Development configuration files
 - Build artifacts and logs
@@ -276,4 +527,3 @@ ISC - See [LICENSE](LICENSE) file for details
 ## Support
 
 For issues and questions, please visit the [GitHub repository](https://github.com/stanterprise/stanterprise-playwright-reporter).
-

package/dist/client/grpcClient.d.ts

@@ -0,0 +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.
+ *
+ * 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, grpcPath: string, message: {
+    serialize?: (w?: any) => Uint8Array;
+    serializeBinary?: () => Uint8Array;
+}, deadlineMs?: number, queue?: MessageQueue): Promise<Buffer>;

package/dist/client/grpcClient.js

@@ -0,0 +1,172 @@
+"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.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
+        const credentials = options.tls
+            ? grpc.credentials.createSsl()
+            : grpc.credentials.createInsecure();
+        return new grpc.Client(options.grpcAddress, credentials, {
+            "grpc.max_send_message_length": maxMessageSize,
+            "grpc.max_receive_message_length": maxMessageSize,
+        });
+    }
+    catch (e) {
+        console.error("Failed to create gRPC client", e);
+    }
+    return null;
+}
+/**
+ * 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
+            ? m.serializeBinary()
+            : m?.serialize
+                ? m.serialize()
+                : new Uint8Array(0);
+        return Buffer.from(bytes);
+    };
+    const resDeserialize = (bytes) => bytes;
+    const metadata = new grpc.Metadata();
+    const callOptions = {
+        deadline: new Date(Date.now() + deadlineMs),
+    };
+    return new Promise((resolve, reject) => {
+        try {
+            grpcClient.makeUnaryRequest(path, reqSerialize, resDeserialize, message, metadata, callOptions, (err, response) => {
+                if (err)
+                    return reject(err);
+                resolve(response);
+            });
+        }
+        catch (e) {
+            reject(e);
+        }
+    });
+}
+/**
+ * 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.
+ *
+ * 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, grpcPath, message, deadlineMs = 1000, queue) {
+    if (!options.grpcEnabled || !grpcClient) {
+        return Buffer.alloc(0);
+    }
+    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/index.d.ts

@@ -0,0 +1,9 @@
+import { handleOnBeginEvent } from "./onBeginHandler";
+import { handleOnEndEvent } from "./onEndHandler";
+import { handleOnStepBeginEvent } from "./onStepBeginHandler";
+import { handleOnStepEndEvent } from "./onStepEndHandler";
+import { handleOnTestBeginEvent } from "./onTestBeginHandler";
+import { handleOnTestEndEvent } from "./onTestEndHandler";
+import { handleOnTestFailEvent } from "./onTestFailHandler";
+import { handleOnErrorEvent } from "./onErrorHandler";
+export { handleOnBeginEvent, handleOnEndEvent, handleOnStepBeginEvent, handleOnStepEndEvent, handleOnTestBeginEvent, handleOnTestEndEvent, handleOnTestFailEvent, handleOnErrorEvent, };