@gherkle/runner 0.1.0

package/README.md

@@ -0,0 +1,482 @@
+# @gherkle/runner
+
+Test runner agent for Gherkle. Connects to the Gherkle platform over WebSocket, receives Gherkin feature files, executes them against a configured test framework, and streams results back in real time.
+
+## Installation
+
+### Option 1 — npm (recommended)
+
+Global install gives you the `gherkle-runner` CLI:
+
+```bash
+npm install -g @gherkle/runner @playwright/test playwright-core
+npx playwright install chromium
+gherkle-runner start --token ghr_xxxxx --url https://gherkle-runner.osita.ai
+```
+
+Or one-shot via `npx` (no global install):
+
+```bash
+npm install @playwright/test playwright-core
+npx playwright install chromium
+npx @gherkle/runner start --token ghr_xxxxx --url https://gherkle-runner.osita.ai
+```
+
+`@playwright/test` and `playwright-core` are peer dependencies — install
+them alongside the runner. AI-generated step definitions import `expect`
+from `@playwright/test`, and the bundled Cucumber executor drives
+`playwright-core` for browser automation.
+
+### Option 2 — Docker
+
+A prebuilt image with browsers preinstalled is available at the
+monorepo's `packages/runner/Dockerfile.browsers`. Build locally:
+
+```bash
+git clone https://github.com/rvasqz86/gherkle-monorepo.git
+cd gherkle-monorepo
+docker build -t gherkle-runner -f packages/runner/Dockerfile.browsers .
+docker run --rm \
+  -e GHERKLE_API_URL=https://gherkle-runner.osita.ai \
+  -e GHERKLE_TOKEN=ghr_xxxxx \
+  gherkle-runner
+```
+
+### Option 3 — From source (for development)
+
+```bash
+git clone https://github.com/rvasqz86/gherkle-monorepo.git
+cd gherkle-monorepo
+npm install
+npm run build --workspace=@gherkle/runner
+npx playwright install chromium
+node packages/runner/bin/gherkle-runner.js start \
+  --token ghr_xxxxx \
+  --url https://gherkle-runner.osita.ai
+```
+
+## How runs work
+
+When you click **Run** in Gherkle the server pushes the feature file AND the
+saved AI-generated step definitions (`step_definition_files` table) to your
+runner over the existing WebSocket. The runner materializes a self-contained
+temp project on disk, forks `@cucumber/cucumber`, and streams pass/fail
+results back. **No step-definition code needs to exist on the runner machine.**
+
+For the BYO workflow (your own step-defs already committed to disk), set
+`stepDefinitionsPath` in `gherkle-runner.config.js` and dispatch with a
+project that has no saved step-defs — the runner falls back to the legacy
+Playwright executor against your local files.
+
+## Quick Start
+
+### 1. Generate a config file
+
+```bash
+gherkle-runner init
+```
+
+This creates `gherkle-runner.config.js` in the current directory.
+
+### 2. Set your runner token
+
+```bash
+export GHERKLE_TOKEN=ghr_xxxxx
+```
+
+### 3. Start the runner
+
+```bash
+gherkle-runner start
+```
+
+The runner connects to Gherkle and waits for test runs. It automatically reconnects if the connection drops.
+
+## CLI Reference
+
+```
+gherkle-runner <command> [options]
+```
+
+### `start`
+
+Start the runner agent and connect to Gherkle.
+
+| Option                        | Description                                            |
+| ----------------------------- | ------------------------------------------------------ |
+| `-t, --token <token>`         | Runner token (overrides `GHERKLE_TOKEN` env var)       |
+| `-n, --name <name>`           | Runner name                                            |
+| `-u, --url <url>`             | Gherkle API URL                                        |
+| `-f, --framework <framework>` | Test framework: `playwright`, `cypress`, or `cucumber` |
+| `--headless`                  | Run browsers in headless mode (default: `true`)        |
+| `--no-headless`               | Run browsers with visible UI                           |
+
+```bash
+gherkle-runner start --token ghr_xxxxx --name ci-runner --framework playwright
+```
+
+### `init`
+
+Generate a sample `gherkle-runner.config.js` in the current directory. Fails if one already exists.
+
+```bash
+gherkle-runner init
+```
+
+### `status`
+
+Print runner version, config file detection, and token status.
+
+```bash
+gherkle-runner status
+```
+
+## Configuration
+
+Configuration is resolved by merging sources in this order (later wins):
+
+1. Built-in defaults
+2. Config file
+3. Environment variables
+4. CLI options
+
+### Config File
+
+The runner looks for config files in the working directory, checking these names in order:
+
+- `gherkle-runner.config.js`
+- `gherkle-runner.config.mjs`
+- `gherkle-runner.config.ts`
+- `.gherklerc.js`
+- `.gherklerc.json`
+
+Example config:
+
+```js
+// gherkle-runner.config.js
+module.exports = {
+  // Connection (required)
+  token: process.env.GHERKLE_TOKEN,
+
+  // Runner identification
+  name: "my-runner",
+  labels: ["local", "dev"],
+
+  // Test framework
+  framework: "playwright", // 'playwright' | 'cypress' | 'cucumber'
+
+  // Paths
+  featuresPath: "./features",
+  stepDefinitionsPath: "./steps",
+  supportPath: "./support",
+
+  // Browser configuration (E2E only)
+  browsers: ["chromium"],
+  headless: true,
+
+  // Timeouts
+  testTimeout: 30000,
+  stepTimeout: 10000,
+
+  // Artifacts
+  screenshots: "on-failure", // 'always' | 'on-failure' | 'never'
+  video: "never", // 'always' | 'on-failure' | 'never'
+
+  // Environment
+  baseUrl: process.env.BASE_URL || "http://localhost:3000",
+  env: {
+    API_URL: process.env.API_URL,
+  },
+};
+```
+
+### Environment Variables
+
+| Variable              | Maps to  |
+| --------------------- | -------- |
+| `GHERKLE_TOKEN`       | `token`  |
+| `GHERKLE_API_URL`     | `apiUrl` |
+| `GHERKLE_RUNNER_NAME` | `name`   |
+
+### Config Options Reference
+
+| Option                | Type       | Default                   | Description                                                  |
+| --------------------- | ---------- | ------------------------- | ------------------------------------------------------------ |
+| `token`               | `string`   | **required**              | Runner authentication token                                  |
+| `apiUrl`              | `string`   | `https://app.gherkle.com` | Gherkle platform URL                                         |
+| `name`                | `string`   | `gherkle-runner`          | Display name for this runner                                 |
+| `labels`              | `string[]` | `[]`                      | Labels for filtering/routing runs to this runner             |
+| `framework`           | `string`   | `playwright`              | Test framework: `playwright`, `cypress`, or `cucumber`       |
+| `featuresPath`        | `string`   | `./features`              | Directory containing `.feature` files                        |
+| `stepDefinitionsPath` | `string`   | `./steps`                 | Directory containing step definition files                   |
+| `supportPath`         | `string`   | `./support`               | Directory containing support/helper files                    |
+| `browsers`            | `string[]` | `['chromium']`            | Browsers to use: `chromium`, `firefox`, `webkit`             |
+| `headless`            | `boolean`  | `true`                    | Run browsers without UI                                      |
+| `testTimeout`         | `number`   | `30000`                   | Max duration per test scenario (ms)                          |
+| `stepTimeout`         | `number`   | `10000`                   | Max duration per step (ms)                                   |
+| `screenshots`         | `string`   | `on-failure`              | When to capture screenshots: `always`, `on-failure`, `never` |
+| `video`               | `string`   | `never`                   | When to record video: `always`, `on-failure`, `never`        |
+| `baseUrl`             | `string`   | `undefined`               | Base URL for the application under test                      |
+| `env`                 | `object`   | `{}`                      | Key-value pairs passed to step definitions as `context.env`  |
+
+## Writing Step Definitions
+
+Step definition files are loaded from `stepDefinitionsPath`. The runner scans recursively for files matching:
+
+- `*.steps.ts` / `*.steps.js`
+- `*.step.ts` / `*.step.js`
+- `*_steps.ts` / `*_steps.js`
+
+### Step File Format
+
+A step file exports a function that receives registration helpers:
+
+```js
+// steps/login.steps.js
+module.exports = function ({ Given, When, Then }) {
+  Given(/the user is on the login page/, async (context) => {
+    await context.page.goto(`${context.baseUrl}/login`);
+  });
+
+  When(
+    /the user enters "(.*)" and "(.*)"/,
+    async (context, username, password) => {
+      await context.page.fill("#username", username);
+      await context.page.fill("#password", password);
+      await context.page.click('button[type="submit"]');
+    },
+  );
+
+  Then(/the user sees the dashboard/, async (context) => {
+    await context.page.waitForURL("**/dashboard");
+  });
+};
+```
+
+### Step Context
+
+Every step function receives a `StepContext` object as its first argument:
+
+| Property    | Type                        | Description                                        |
+| ----------- | --------------------------- | -------------------------------------------------- |
+| `page`      | `playwright.Page`           | Playwright Page instance for the current scenario  |
+| `context`   | `playwright.BrowserContext` | Playwright BrowserContext for the current scenario |
+| `baseUrl`   | `string \| undefined`       | The configured `baseUrl`                           |
+| `env`       | `Record<string, string>`    | Environment variables from config                  |
+| `dataTable` | `string[][] \| undefined`   | Data table attached to the current step            |
+| `docString` | `string \| undefined`       | Doc string attached to the current step            |
+
+Capture groups from the step pattern regex are passed as additional string arguments after the context.
+
+### Keyword Matching
+
+Steps registered with `Given`, `When`, or `Then` are matched by keyword first. Steps using `And` or `But` in the feature file inherit their effective keyword from the preceding step. If no keyword-specific match is found, the runner falls back to matching against all registered steps regardless of keyword.
+
+## Gherkin Parser
+
+The runner includes a built-in Gherkin parser (`@cucumber/gherkin`) that supports:
+
+- Feature descriptions and tags
+- Scenarios with Given/When/Then/And/But steps
+- Background sections (run before each scenario)
+- Scenario Outlines with Examples tables (expanded into individual scenarios)
+- Data Tables on steps
+- Doc Strings on steps
+- Multiple Examples blocks per outline
+- Tags at feature, scenario, and examples level
+
+## Architecture
+
+```
+bin/gherkle-runner.js     CLI entrypoint (commander)
+src/
+  index.ts                Public API exports
+  types.ts                Type definitions and WebSocket message types
+  config.ts               Config loading, merging, validation
+  agent.ts                GherkleAgent - WebSocket client, run orchestration
+  step-registry.ts        Step definition registry and matching
+  gherkin-parser.ts       Gherkin AST parsing
+  frameworks/
+    playwright.ts         Playwright executor (browser launch, scenario execution)
+```
+
+### How It Works
+
+1. **Connect** -- `GherkleAgent` opens a WebSocket connection to the Gherkle platform, authenticating with the runner token.
+2. **Wait** -- The agent sends heartbeats every 30 seconds and waits for an `execute` message.
+3. **Execute** -- When a run is dispatched, the agent parses the received Gherkin feature files, loads step definitions, launches a browser, and runs each scenario.
+4. **Stream** -- Step and scenario results are sent back to Gherkle in real time over the WebSocket (`scenario:started`, `step:completed`, `scenario:completed`).
+5. **Artifacts** -- On step failure (when `screenshots` is not `never`), a full-page screenshot is captured and reported as an artifact. Screenshots are saved to `.gherkle-artifacts/` in the working directory.
+6. **Complete** -- A `run:completed` message with the full summary is sent when all features finish.
+
+The agent automatically reconnects after 5 seconds if the WebSocket connection drops.
+
+## Programmatic API
+
+The package exports the agent and config loader for use in custom tooling:
+
+```ts
+import { GherkleAgent, loadConfig } from "@gherkle/runner";
+
+const config = loadConfig({
+  token: "ghr_xxxxx",
+  framework: "playwright",
+});
+
+const agent = new GherkleAgent(config);
+
+// Handle shutdown
+process.on("SIGINT", () => agent.stop());
+
+await agent.start();
+```
+
+### Exports
+
+| Export                   | Description                                                                          |
+| ------------------------ | ------------------------------------------------------------------------------------ |
+| `GherkleAgent`           | Main agent class. Call `start()` to connect, `stop()` to disconnect.                 |
+| `loadConfig(overrides?)` | Load and merge config from file, env, and provided overrides. Returns `AgentConfig`. |
+| `AgentConfig`            | Configuration interface                                                              |
+| `RunnerStatus`           | `'online' \| 'offline' \| 'busy' \| 'error'`                                         |
+| `TestStatus`             | `'pending' \| 'running' \| 'passed' \| 'failed' \| 'skipped'`                        |
+| `Framework`              | `'playwright' \| 'cypress' \| 'cucumber'`                                            |
+| `StepResult`             | Result of a single step execution                                                    |
+| `ScenarioResult`         | Result of a scenario including all steps and artifacts                               |
+| `RunSummary`             | Aggregate pass/fail/skip counts and duration                                         |
+| `FeatureContent`         | Feature file id, name, path, and raw content                                         |
+| `TestConfig`             | Framework and path configuration for a test run                                      |
+| `ArtifactInfo`           | Metadata for a captured artifact (screenshot, video, trace, log)                     |
+| `RunnerMessage`          | Union type of all messages sent from runner to server                                |
+| `ServerMessage`          | Union type of all messages sent from server to runner                                |
+
+## Docker
+
+Two Dockerfiles are provided depending on your workload:
+
+| File                  | Base image                     | Size    | Use case                                                          |
+| --------------------- | ------------------------------ | ------- | ----------------------------------------------------------------- |
+| `Dockerfile`          | `node:22-slim`                 | ~200 MB | Step definitions, assertions, API tests, any non-browser workload |
+| `Dockerfile.browsers` | `mcr.microsoft.com/playwright` | ~2 GB   | E2E tests requiring Chromium, Firefox, or WebKit                  |
+
+Use the default `Dockerfile` unless your step definitions launch a browser.
+
+### Build
+
+Both Dockerfiles must be built from the **monorepo root** so the workspace lockfile is available:
+
+```bash
+# Standard image (step definitions + assertions, no browsers)
+docker build -t gherkle-runner -f packages/runner/Dockerfile .
+
+# With Playwright browsers for E2E
+docker build -t gherkle-runner-browsers -f packages/runner/Dockerfile.browsers .
+```
+
+### Run
+
+```bash
+docker run --rm \
+  -e GHERKLE_TOKEN=ghr_xxxxx \
+  gherkle-runner
+```
+
+### Mount step definitions and features
+
+Bind-mount your project directories so the runner can find your test code:
+
+```bash
+docker run --rm \
+  -e GHERKLE_TOKEN=ghr_xxxxx \
+  -v $(pwd)/features:/app/features \
+  -v $(pwd)/steps:/app/steps \
+  -v $(pwd)/support:/app/support \
+  gherkle-runner
+```
+
+### Pass CLI options
+
+Arguments after the image name are forwarded to `gherkle-runner start`:
+
+```bash
+docker run --rm \
+  -e GHERKLE_TOKEN=ghr_xxxxx \
+  gherkle-runner start --name ci-runner --framework cucumber
+```
+
+### Use a config file
+
+Mount a config file into `/app`:
+
+```bash
+docker run --rm \
+  -v $(pwd)/gherkle-runner.config.js:/app/gherkle-runner.config.js \
+  -v $(pwd)/features:/app/features \
+  -v $(pwd)/steps:/app/steps \
+  gherkle-runner
+```
+
+### Docker Compose
+
+```yaml
+services:
+  # Headless step execution (API tests, assertions, etc.)
+  gherkle-runner:
+    build:
+      context: .
+      dockerfile: packages/runner/Dockerfile
+    environment:
+      - GHERKLE_TOKEN=${GHERKLE_TOKEN}
+      - GHERKLE_RUNNER_NAME=docker-runner
+    volumes:
+      - ./features:/app/features
+      - ./steps:/app/steps
+      - ./support:/app/support
+    restart: unless-stopped
+
+  # E2E variant with Playwright browsers
+  gherkle-runner-e2e:
+    build:
+      context: .
+      dockerfile: packages/runner/Dockerfile.browsers
+    environment:
+      - GHERKLE_TOKEN=${GHERKLE_TOKEN}
+      - GHERKLE_RUNNER_NAME=docker-e2e-runner
+    volumes:
+      - ./features:/app/features
+      - ./steps:/app/steps
+      - ./support:/app/support
+    restart: unless-stopped
+```
+
+### Environment variables
+
+All [configuration environment variables](#environment-variables) work inside the container. Both images run as a non-root user (`gherkle` / `pwuser`) by default.
+
+## Requirements
+
+- Node.js >= 18
+- Playwright browsers installed (for E2E execution): `npx playwright install`
+
+## Development
+
+```bash
+# Build
+npm run build
+
+# Watch mode
+npm run dev
+
+# Run tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Lint
+npm run lint
+```
+
+## License
+
+MIT

package/bin/gherkle-runner.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+
+/**
+ * Gherkle Runner CLI
+ *
+ * Usage:
+ *   gherkle-runner start --token=ghr_xxxxx
+ *   gherkle-runner init
+ *   gherkle-runner status
+ */
+
+const { program } = require('commander');
+const path = require('path');
+const fs = require('fs');
+
+// Try to load the compiled version, fall back to ts-node for development
+let GherkleAgent, loadConfig, generateSampleConfig;
+try {
+  const dist = require('../dist/index.js');
+  GherkleAgent = dist.GherkleAgent;
+  loadConfig = dist.loadConfig;
+  generateSampleConfig = dist.generateSampleConfig;
+} catch {
+  console.log('Note: Running in development mode');
+  // In development, you'd use ts-node or similar
+  process.exit(1);
+}
+
+program
+  .name('gherkle-runner')
+  .description('Test runner agent for Gherkle')
+  .version('0.1.0');
+
+// Start command
+program
+  .command('start')
+  .description('Start the runner agent and connect to Gherkle')
+  .option('-t, --token <token>', 'Runner token (or use GHERKLE_TOKEN env var)')
+  .option('-n, --name <name>', 'Runner name')
+  .option('-u, --url <url>', 'Gherkle API URL')
+  .option('-f, --framework <framework>', 'Test framework (playwright, cypress, cucumber)')
+  .option('--headless', 'Run browsers in headless mode', true)
+  .option('--no-headless', 'Run browsers with UI')
+  .action(async (options) => {
+    try {
+      const config = loadConfig({
+        token: options.token,
+        name: options.name,
+        apiUrl: options.url,
+        framework: options.framework,
+        headless: options.headless,
+      });
+
+      const agent = new GherkleAgent(config);
+
+      // Handle shutdown signals
+      process.on('SIGINT', async () => {
+        console.log('\nReceived SIGINT, shutting down...');
+        await agent.stop();
+        process.exit(0);
+      });
+
+      process.on('SIGTERM', async () => {
+        console.log('\nReceived SIGTERM, shutting down...');
+        await agent.stop();
+        process.exit(0);
+      });
+
+      await agent.start();
+
+      // Keep the process alive
+      console.log('\n👀 Waiting for test runs... (Ctrl+C to stop)\n');
+    } catch (err) {
+      console.error('Error:', err.message);
+      process.exit(1);
+    }
+  });
+
+// Init command
+program
+  .command('init')
+  .description('Generate a sample configuration file')
+  .action(() => {
+    const configPath = path.join(process.cwd(), 'gherkle-runner.config.js');
+
+    if (fs.existsSync(configPath)) {
+      console.error('Error: Configuration file already exists');
+      process.exit(1);
+    }
+
+    fs.writeFileSync(configPath, generateSampleConfig());
+    console.log('✅ Created gherkle-runner.config.js');
+    console.log('\nNext steps:');
+    console.log('1. Edit the config file with your settings');
+    console.log('2. Set GHERKLE_TOKEN environment variable');
+    console.log('3. Run: gherkle-runner start');
+  });
+
+// Status command
+program
+  .command('status')
+  .description('Check runner status')
+  .action(() => {
+    console.log('Gherkle Runner Status');
+    console.log('---------------------');
+    console.log('Version: 0.1.0');
+    console.log('Config file:', fs.existsSync('gherkle-runner.config.js') ? 'Found' : 'Not found');
+    console.log('Token:', process.env.GHERKLE_TOKEN ? 'Set (from env)' : 'Not set');
+  });
+
+program.parse();

package/dist/__tests__/agent-executor-selection.test.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Tests for GherkleAgent.executeRun executor selection logic.
+ *
+ * The agent branches based on the incoming 'execute' WebSocket message:
+ *   stepDefinitions non-empty           → CucumberSubprocessExecutor.executeAll
+ *   empty + stepDefinitionsPath set     → PlaywrightExecutor.execute (BYO)
+ *   empty + no path                     → throw "No step definitions"
+ *
+ * Also covers:
+ *   - Busy-guard (refuses 2nd 'execute' while first is in flight)
+ *   - cancelRun routes to currentCucumberExecutor.cancel()
+ *   - cancelRun for non-matching runId is a no-op
+ */
+export {};
+//# sourceMappingURL=agent-executor-selection.test.d.ts.map

package/dist/__tests__/agent-executor-selection.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-executor-selection.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/agent-executor-selection.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}