browsecraft-runner 0.4.0 → 0.5.1

package/README.md

@@ -1,8 +1,8 @@
 # browsecraft-runner
 
-Test runner and CLI for [Browsecraft](https://github.com/rik9564/browsecraft).
+Test runner, parallel scheduler, and multi-browser worker pool for [Browsecraft](https://github.com/rik9564/browsecraft).
 
-Discovers test files, coordinates execution, and reports results. Used internally by the `browsecraft` CLI.
+Provides an event-driven architecture for distributing test scenarios across browser instances with work-stealing scheduling, failure classification, smart retry, and rich result aggregation.
 
 Most users should install [`browsecraft`](https://www.npmjs.com/package/browsecraft) instead — it includes the runner automatically.
 
@@ -12,53 +12,113 @@ Most users should install [`browsecraft`](https://www.npmjs.com/package/browsecr
 npm install browsecraft-runner
 ```
 
-## Usage
+## Core Components
+
+### EventBus
+
+Decouples execution from reporting. Subscribe to lifecycle events:
+
+```js
+import { EventBus } from 'browsecraft-runner';
+
+const bus = new EventBus();
+
+bus.on('item:pass', ({ item, worker, duration }) => {
+  console.log(`✓ ${item.title} on ${worker.browser} (${duration}ms)`);
+});
+
+bus.on('item:fail', ({ item, error }) => {
+  console.log(`✗ ${item.title}: ${error.message}`);
+});
+```
+
+Events: `run:start/end`, `worker:spawn/ready/busy/idle/error/terminate`, `item:enqueue/start/pass/fail/skip/retry/end`, `browser:start/end`, `progress`.
+
+### WorkerPool
+
+Manages browser instances across multiple browsers:
+
+```js
+import { WorkerPool } from 'browsecraft-runner';
+
+const pool = new WorkerPool(bus, {
+  browsers: { chrome: 2, firefox: 1, edge: 1 },
+  maxRetries: 1,
+  bail: false,
+});
+
+await pool.spawn(async (worker) => {
+  const session = await launchBrowser(worker.browser);
+  return { close: () => session.close() };
+});
+```
+
+### Scheduler
+
+Three execution strategies:
+
+| Strategy | How it works |
+|----------|-------------|
+| `parallel` | Distribute scenarios across all browsers simultaneously |
+| `sequential` | One browser at a time |
+| `matrix` | Every scenario × every browser |
+
+```js
+import { Scheduler } from 'browsecraft-runner';
+
+const scheduler = new Scheduler(bus, pool, { strategy: 'matrix' });
+const result = await scheduler.run(scenarios, executor);
+```
+
+### ResultAggregator
+
+Produces scenario × browser matrices with analytics:
+
+```js
+import { ResultAggregator } from 'browsecraft-runner';
+
+const aggregator = new ResultAggregator();
+const summary = aggregator.aggregate(result);
+
+console.log(aggregator.formatMatrix(summary));
+console.log(aggregator.formatSummary(summary));
+```
+
+Includes flaky test detection, cross-browser inconsistency analysis, and timing statistics (min, max, avg, median, p95).
+
+### Failure Classification & Smart Retry
+
+```js
+import { classifyFailure } from 'browsecraft-runner';
+
+const classification = classifyFailure(error);
+// { category: 'network', retryable: true, name: 'ECONNRESET' }
+```
+
+| Category | Retryable | Examples |
+|----------|-----------|----------|
+| `network` | Yes | `ECONNRESET`, `ECONNREFUSED`, socket timeouts |
+| `timeout` | Yes | Navigation timeouts, page load timeouts |
+| `element` | Conditional | Not found (retryable), disabled (not retryable) |
+| `assertion` | No | `Expected "foo" but got "bar"` |
+| `script` | No | `TypeError`, `ReferenceError` |
+
+### TestRunner
+
+Simple test file runner with grep, bail, and retry support:
 
 ```js
 import { TestRunner } from 'browsecraft-runner';
 
 const runner = new TestRunner({
-  config: {
-    browser: 'chrome',
-    headless: true,
-    timeout: 30000,
-    retries: 0,
-    testMatch: ['**/*.test.mjs'],
-    outputDir: 'test-results',
-  },
-  grep: 'login',   // optional: filter tests by name
-  bail: false,      // optional: stop on first failure
+  config: { browser: 'chrome', headless: true, timeout: 30000 },
+  grep: 'login',
+  bail: false,
 });
 
 const exitCode = await runner.run(loadFile, executeTest);
 ```
 
-## Features
-
-- Test file discovery by glob patterns
-- Grep filtering by test name
-- `.only` support for focused tests
-- Retry on failure
-- Bail on first failure
-- Color-coded console reporter
-
-## Configuration
-
-The runner accepts a `BrowsecraftConfig` object:
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `browser` | `string` | `'chrome'` | Browser to use (`chrome`, `firefox`, `edge`) |
-| `headless` | `boolean` | `true` | Run in headless mode |
-| `timeout` | `number` | `30000` | Test timeout in ms |
-| `retries` | `number` | `0` | Retry failed tests |
-| `testMatch` | `string[]` | `['**/*.test.*']` | Glob patterns for test files |
-| `outputDir` | `string` | `'test-results'` | Output directory for artifacts |
-| `viewport` | `object` | `{ width: 1280, height: 720 }` | Browser viewport size |
-| `maximized` | `boolean` | `false` | Maximize the browser window |
-| `baseURL` | `string` | — | Base URL for `page.goto()` |
-| `workers` | `number` | `1` | Number of parallel workers |
-
 ## License
 
 [MIT](LICENSE)

package/dist/index.cjs

@@ -3,6 +3,81 @@
 var fs = require('fs');
 var path = require('path');
 
+// src/runner.ts
+
+// src/smart-retry.ts
+function classifyFailure(error) {
+  if (!(error instanceof Error)) {
+    return { category: "unknown", retryable: true, description: "Non-Error thrown" };
+  }
+  const name = error.name ?? "";
+  const msg = (error.message ?? "").toLowerCase();
+  if (name === "AssertionError" || name === "AssertionError [ERR_ASSERTION]" || name === "ERR_ASSERTION" || error.constructor?.name === "AssertionError") {
+    return {
+      category: "assertion",
+      retryable: false,
+      description: "Assertion failed \u2014 retrying won't help"
+    };
+  }
+  if (msg.includes("expected") && (msg.includes("to equal") || msg.includes("to be") || msg.includes("to have") || msg.includes("to match") || msg.includes("to contain") || msg.includes("but got") || msg.includes("but received"))) {
+    return {
+      category: "assertion",
+      retryable: false,
+      description: "Assertion failed \u2014 retrying won't help"
+    };
+  }
+  if (name === "SyntaxError" || name === "ReferenceError" || name === "TypeError" || name === "RangeError") {
+    return {
+      category: "script",
+      retryable: false,
+      description: `${name} \u2014 code bug, retrying won't help`
+    };
+  }
+  if (name === "ElementNotFoundError") {
+    return {
+      category: "element",
+      retryable: true,
+      description: "Element not found \u2014 page may still be loading"
+    };
+  }
+  if (name === "ElementNotActionableError") {
+    return {
+      category: "actionability",
+      retryable: true,
+      description: "Element not actionable \u2014 may become ready"
+    };
+  }
+  if (name === "NetworkError") {
+    return {
+      category: "network",
+      retryable: true,
+      description: "Network failure \u2014 may be transient"
+    };
+  }
+  if (name === "TimeoutError") {
+    return {
+      category: "timeout",
+      retryable: true,
+      description: "Timed out \u2014 environment may be slow"
+    };
+  }
+  if (msg.includes("timed out") || msg.includes("timeout")) {
+    return {
+      category: "timeout",
+      retryable: true,
+      description: "Timed out \u2014 environment may be slow"
+    };
+  }
+  if (msg.includes("econnrefused") || msg.includes("econnreset") || msg.includes("enotfound") || msg.includes("fetch failed") || msg.includes("network")) {
+    return {
+      category: "network",
+      retryable: true,
+      description: "Network failure \u2014 may be transient"
+    };
+  }
+  return { category: "unknown", retryable: true, description: "Unknown error \u2014 will retry" };
+}
+
 // src/runner.ts
 var TestRunner = class {
   options;
@@ -45,6 +120,10 @@ var TestRunner = class {
           const maxRetries = test.options.retries ?? this.options.config.retries;
           let retryCount = 0;
           while (result.status === "failed" && retryCount < maxRetries) {
+            const classification = classifyFailure(result.error);
+            if (!classification.retryable) {
+              break;
+            }
             retryCount++;
             result = await executeTest(test);
           }
@@ -467,24 +546,27 @@ var WorkerPool = class {
           error: execResult.error
         };
         if (execResult.status === "failed" && this.config.maxRetries > 0) {
-          let attempt = 1;
-          while (attempt <= this.config.maxRetries && finalResult.status === "failed") {
-            this.bus.emit("item:retry", {
-              item,
-              worker: worker.info,
-              attempt,
-              maxRetries: this.config.maxRetries
-            });
-            const retryResult = await executor(item, worker.info);
-            finalResult = {
-              item,
-              worker: worker.info,
-              status: retryResult.status,
-              duration: retryResult.duration,
-              error: retryResult.error,
-              retries: attempt
-            };
-            attempt++;
+          const classification = classifyFailure(execResult.error);
+          if (classification.retryable) {
+            let attempt = 1;
+            while (attempt <= this.config.maxRetries && finalResult.status === "failed") {
+              this.bus.emit("item:retry", {
+                item,
+                worker: worker.info,
+                attempt,
+                maxRetries: this.config.maxRetries
+              });
+              const retryResult = await executor(item, worker.info);
+              finalResult = {
+                item,
+                worker: worker.info,
+                status: retryResult.status,
+                duration: retryResult.duration,
+                error: retryResult.error,
+                retries: attempt
+              };
+              attempt++;
+            }
           }
         }
       } catch (err) {
@@ -985,5 +1067,6 @@ exports.ResultAggregator = ResultAggregator;
 exports.Scheduler = Scheduler;
 exports.TestRunner = TestRunner;
 exports.WorkerPool = WorkerPool;
+exports.classifyFailure = classifyFailure;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map