@stanterprise/playwright-reporter 0.0.17 → 0.0.19

package/README.md

@@ -92,6 +92,120 @@ 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) |
+
+### 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
+}
+```
+
+## 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
 
@@ -240,7 +354,6 @@ This error can also occur when test event payloads exceed the gRPC message size
    ```
 
 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
 

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

@@ -49,11 +49,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 +98,59 @@ 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);
+    }
+    const maxRetries = options.grpcMaxRetries ?? 3;
+    return attemptWithRetries(options, grpcClient, path, message, deadlineMs, maxRetries);
+}

package/dist/handlers/onBeginHandler.js

@@ -19,6 +19,11 @@ function handleOnBeginEvent(config, suite, name, runId, client, options) {
     variables.forEach((value, key) => {
         metadata[key] = value;
     });
+    // Add shard information if present
+    if (config.shard) {
+        metadata["shard.current"] = String(config.shard.current);
+        metadata["shard.total"] = String(config.shard.total);
+    }
     const request = new events_1.ReportRunStartEventRequest({
         run_id: runId,
         name: name,

package/dist/reporter.js

@@ -45,6 +45,9 @@ class StanterpriseReporter {
             console.log(`Stanterprise Reporter: Test run started with ID: ${this.runId}`);
             console.log(`Number of tests: ${suite.allTests().length}`);
             console.log(`Run started at: ${this.runStartTime.toISOString()}`);
+            if (config.shard) {
+                console.log(`Shard: ${config.shard.current} of ${config.shard.total}`);
+            }
         }
         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);

package/dist/types.d.ts

@@ -36,6 +36,17 @@ 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;
 }
 /**
  * Internal type for managing test execution state

package/dist/utils/optionsMapper.js

@@ -16,6 +16,10 @@ 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;
     return result;
 }

package/package.json

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