@letsrunit/gherker 0.1.0

package/README.md

@@ -0,0 +1,40 @@
+# Gherker Package (`@letsrunit/gherker`)
+
+## Installation
+
+```bash
+npm install @letsrunit/gherker
+# or
+yarn add @letsrunit/gherker
+```
+
+A lightweight Gherkin microrunner for executing scenarios step-by-step. It provides a simple and fast alternative to full-blown BDD frameworks, optimized for the `letsrunit` platform.
+
+## Exported Classes
+
+### `Runner<TWorld>`
+
+The core class for defining and running Gherkin steps.
+
+#### Methods:
+
+- **`defineStep(type, expression, fn, comment)`**: Defines a new Gherkin step.
+    - `type`: `'Given' | 'When' | 'Then' | 'And' | 'But'`.
+    - `expression`: A string or regular expression. Supports Cucumber expressions.
+    - `fn`: The handler function. Receives arguments from the expression and the world object as `this`.
+- **`defineParameterType(type)`**: Registers a custom parameter type for Cucumber expressions.
+- **`parse(feature)`**: Parses a Gherkin feature and returns a list of its steps and their matches.
+- **`run(feature, worldFactory, wrapRun, opts)`**: Executes a Gherkin feature.
+    - `feature`: The Gherkin feature text.
+    - `worldFactory`: A value or function that provides the `World` object.
+    - `wrapRun`: An optional wrapper for each step execution (useful for logging or reporting).
+    - `opts`: Includes an `AbortSignal`.
+- **`reset()`**: Clears all defined steps and parameter types.
+
+## Testing
+
+Run tests for this package:
+
+```bash
+yarn test
+```

package/dist/index.d.ts

@@ -0,0 +1,60 @@
+import { Expression, Argument, ParameterTypeRegistry } from '@cucumber/cucumber-expressions';
+import { ParameterTypeDefinition } from '@letsrunit/gherkin';
+
+type World = {
+    cleanup?: () => void | Promise<void>;
+    [_: string]: any;
+};
+type StepHandler<T> = (this: T, ...args: any[]) => Promise<void> | void;
+type StepType = 'Given' | 'When' | 'Then';
+interface StepDefinition<T> {
+    type: StepType;
+    expr: Expression;
+    fn: StepHandler<T>;
+    source: string;
+    comment?: string;
+}
+interface ParsedStep {
+    text: string;
+    def?: string;
+    values?: unknown[];
+}
+interface Result<TWorld extends World = any> {
+    world: TWorld;
+    status: 'passed' | 'failed';
+    steps: Array<{
+        text: string;
+        status?: 'success' | 'failure';
+    }>;
+    reason?: Error;
+}
+
+type StepResult = {
+    status: 'success' | 'failure';
+    reason?: Error;
+};
+type StepDescription = {
+    id: string;
+    text: string;
+    args: readonly Argument[];
+};
+type StepWrapper = (step: StepDescription, run: () => Promise<StepResult>) => Promise<StepResult>;
+declare class Runner<TWorld extends World> {
+    private _registry;
+    get registry(): ParameterTypeRegistry;
+    private _defs;
+    get defs(): StepDefinition<TWorld>[];
+    defineStep(type: StepType, expression: string | RegExp, fn: StepHandler<TWorld>, comment?: string): void;
+    defineParameterType(type: ParameterTypeDefinition<unknown>): void;
+    parse(feature: string): ParsedStep[];
+    run(feature: string, worldFactory: TWorld | (() => Promise<TWorld> | TWorld), wrapRun?: StepWrapper, { signal }?: {
+        signal?: AbortSignal;
+    }): Promise<Result<TWorld>>;
+    reset(): void;
+    private match;
+    private describeStep;
+    private compile;
+    private runStep;
+}
+
+export { type ParsedStep, type Result, Runner, type StepDescription, type StepHandler, type StepResult };

package/dist/index.js

@@ -0,0 +1,123 @@
+import { ParameterTypeRegistry, CucumberExpression, RegularExpression, ParameterType } from '@cucumber/cucumber-expressions';
+import { generateMessages } from '@cucumber/gherkin';
+import { SourceMediaType, IdGenerator } from '@cucumber/messages';
+import { sanitizeStepDefinition } from '@letsrunit/gherkin';
+
+// src/runner.ts
+var Runner = class {
+  _registry = new ParameterTypeRegistry();
+  // Private instead of readonly, because `reset()`
+  get registry() {
+    return this._registry;
+  }
+  _defs = [];
+  get defs() {
+    return this._defs;
+  }
+  defineStep(type, expression, fn, comment) {
+    const expr = typeof expression === "string" ? new CucumberExpression(sanitizeStepDefinition(expression), this.registry) : new RegularExpression(expression, this.registry);
+    this.defs.push({ type, expr, fn, source: String(expression), comment });
+  }
+  defineParameterType(type) {
+    const paramType = new ParameterType(type.name, type.regexp, null, type.transformer, type.useForSnippets);
+    this._registry.defineParameterType(paramType);
+  }
+  parse(feature) {
+    const pickles = this.compile(feature);
+    if (pickles.length > 1) {
+      throw new Error("Multiple scenarios not supported");
+    }
+    const pickle = pickles[0];
+    return pickle.steps.map((step) => {
+      const match = this.match(step.text);
+      return {
+        text: step.text,
+        def: match?.def ? `${match?.def.type} ${match?.def.source}` : void 0,
+        values: match?.values
+      };
+    });
+  }
+  async run(feature, worldFactory, wrapRun, { signal } = {}) {
+    const pickles = this.compile(feature);
+    if (pickles.length > 1) {
+      throw new Error("Multiple scenarios not supported");
+    }
+    wrapRun ??= (_step, run) => run();
+    const world = typeof worldFactory === "function" ? await worldFactory() : worldFactory;
+    const pickle = pickles[0];
+    let completed = 0;
+    let error;
+    for (const step of pickle.steps) {
+      if (signal?.aborted) {
+        error = signal.reason instanceof Error ? signal.reason : new Error(String(signal.reason));
+        break;
+      }
+      try {
+        const { status, reason } = await wrapRun(this.describeStep(step), () => this.runStep(world, step));
+        if (status === "success") completed++;
+        if (status === "failure") {
+          error = reason ?? new Error("Unknown error");
+          break;
+        }
+      } catch (e) {
+        error = e;
+        break;
+      }
+    }
+    if (typeof world.cleanup === "function") await world.cleanup();
+    const steps = pickle.steps.map((step, i) => ({
+      text: step.text,
+      status: completed > i ? "success" : completed === i ? "failure" : void 0
+    }));
+    return { world, status: !error ? "passed" : "failed", steps, reason: error };
+  }
+  reset() {
+    this._registry = new ParameterTypeRegistry();
+    this._defs = [];
+  }
+  match(text) {
+    for (const def of this.defs) {
+      const args = def.expr.match(text);
+      if (args) return { def, values: args.map((a) => a.getValue(null)) };
+    }
+    return null;
+  }
+  describeStep(step) {
+    const def = this.defs.find(({ expr }) => !!expr.match(step.text));
+    const text = def ? `${def.type} ${step.text}` : step.text;
+    const args = def?.expr.match(step.text) || [];
+    return { id: step.id, text, args };
+  }
+  compile(feature, uri = "inline.feature") {
+    const envelopes = generateMessages(feature, uri, SourceMediaType.TEXT_X_CUCUMBER_GHERKIN_PLAIN, {
+      newId: () => IdGenerator.uuid().toString(),
+      includeGherkinDocument: true,
+      includePickles: true,
+      includeSource: false
+    });
+    const pickles = envelopes.filter((e) => e.pickle).map((e) => e.pickle);
+    if (!pickles.length) throw new Error("No scenarios found");
+    return pickles;
+  }
+  async runStep(world, step) {
+    try {
+      const text = step.text;
+      const match = this.match(text);
+      if (!match) throw new Error(`Undefined step: ${text}`);
+      let extra;
+      if (step.argument?.docString) {
+        extra = step.argument.docString.content;
+      } else if (step.argument?.dataTable) {
+        extra = step.argument.dataTable.rows.map((r) => r.cells.map((c) => c.value));
+      }
+      await match.def.fn.apply(world, [...match.values, ...extra !== void 0 ? [extra] : []]);
+      return { status: "success" };
+    } catch (e) {
+      return { status: "failure", reason: e };
+    }
+  }
+};
+
+export { Runner };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/runner.ts"],"names":[],"mappings":";;;;;;AAgBO,IAAM,SAAN,MAAmC;AAAA,EAChC,SAAA,GAAY,IAAI,qBAAA,EAAsB;AAAA;AAAA,EAE9C,IAAI,QAAA,GAAkC;AACpC,IAAA,OAAO,IAAA,CAAK,SAAA;AAAA,EACd;AAAA,EAEQ,QAAkC,EAAC;AAAA,EAE3C,IAAI,IAAA,GAAiC;AACnC,IAAA,OAAO,IAAA,CAAK,KAAA;AAAA,EACd;AAAA,EAEA,UAAA,CAAW,IAAA,EAAgB,UAAA,EAA6B,EAAA,EAAyB,OAAA,EAAkB;AACjG,IAAA,MAAM,OACJ,OAAO,UAAA,KAAe,QAAA,GAClB,IAAI,mBAAmB,sBAAA,CAAuB,UAAU,CAAA,EAAG,IAAA,CAAK,QAAQ,CAAA,GACxE,IAAI,iBAAA,CAAkB,UAAA,EAAY,KAAK,QAAQ,CAAA;AACrD,IAAA,IAAA,CAAK,IAAA,CAAK,IAAA,CAAK,EAAE,IAAA,EAAM,IAAA,EAAM,EAAA,EAAI,MAAA,EAAQ,MAAA,CAAO,UAAU,CAAA,EAAG,OAAA,EAAS,CAAA;AAAA,EACxE;AAAA,EAEA,oBAAoB,IAAA,EAAwC;AAC1D,IAAA,MAAM,SAAA,GAAY,IAAI,aAAA,CAAc,IAAA,CAAK,IAAA,EAAM,IAAA,CAAK,MAAA,EAAQ,IAAA,EAAM,IAAA,CAAK,WAAA,EAAa,IAAA,CAAK,cAAc,CAAA;AAEvG,IAAA,IAAA,CAAK,SAAA,CAAU,oBAAoB,SAAS,CAAA;AAAA,EAC9C;AAAA,EAEA,MAAM,OAAA,EAA+B;AACnC,IAAA,MAAM,OAAA,GAAU,IAAA,CAAK,OAAA,CAAQ,OAAO,CAAA;AACpC,IAAA,IAAI,OAAA,CAAQ,SAAS,CAAA,EAAG;AACtB,MAAA,MAAM,IAAI,MAAM,kCAAkC,CAAA;AAAA,IACpD;AAEA,IAAA,MAAM,MAAA,GAAS,QAAQ,CAAC,CAAA;AAExB,IAAA,OAAO,MAAA,CAAO,KAAA,CAAM,GAAA,CAAI,CAAC,IAAA,KAAS;AAChC,MAAA,MAAM,KAAA,GAAQ,IAAA,CAAK,KAAA,CAAM,IAAA,CAAK,IAAI,CAAA;AAElC,MAAA,OAAO;AAAA,QACL,MAAM,IAAA,CAAK,IAAA;AAAA,QACX,GAAA,EAAK,KAAA,EAAO,GAAA,GAAM,CAAA,EAAG,KAAA,EAAO,GAAA,CAAI,IAAI,CAAA,CAAA,EAAI,KAAA,EAAO,GAAA,CAAI,MAAM,CAAA,CAAA,GAAK,MAAA;AAAA,QAC9D,QAAQ,KAAA,EAAO;AAAA,OACjB;AAAA,IACF,CAAC,CAAA;AAAA,EACH;AAAA,EAEA,MAAM,IACJ,OAAA,EACA,YAAA,EACA,SACA,EAAE,MAAA,EAAO,GAA8B,EAAC,EACf;AACzB,IAAA,MAAM,OAAA,GAAU,IAAA,CAAK,OAAA,CAAQ,OAAO,CAAA;AACpC,IAAA,IAAI,OAAA,CAAQ,SAAS,CAAA,EAAG;AACtB,MAAA,MAAM,IAAI,MAAM,kCAAkC,CAAA;AAAA,IACpD;AAEA,IAAA,OAAA,KAAY,CAAC,KAAA,EAAO,GAAA,KAAQ,GAAA,EAAI;AAEhC,IAAA,MAAM,QAAQ,OAAO,YAAA,KAAiB,UAAA,GAAa,MAAM,cAAa,GAAI,YAAA;AAC1E,IAAA,MAAM,MAAA,GAAS,QAAQ,CAAC,CAAA;AACxB,IAAA,IAAI,SAAA,GAAY,CAAA;AAChB,IAAA,IAAI,KAAA;AAEJ,IAAA,KAAA,MAAW,IAAA,IAAQ,OAAO,KAAA,EAAO;AAC/B,MAAA,IAAI,QAAQ,OAAA,EAAS;AACnB,QAAA,KAAA,GAAQ,MAAA,CAAO,MAAA,YAAkB,KAAA,GAAQ,MAAA,CAAO,MAAA,GAAS,IAAI,KAAA,CAAM,MAAA,CAAO,MAAA,CAAO,MAAM,CAAC,CAAA;AACxF,QAAA;AAAA,MACF;AAEA,MAAA,IAAI;AACF,QAAA,MAAM,EAAE,MAAA,EAAQ,MAAA,EAAO,GAAI,MAAM,OAAA,CAAQ,IAAA,CAAK,YAAA,CAAa,IAAI,GAAG,MAAM,IAAA,CAAK,OAAA,CAAQ,KAAA,EAAO,IAAI,CAAC,CAAA;AAEjG,QAAA,IAAI,WAAW,SAAA,EAAW,SAAA,EAAA;AAE1B,QAAA,IAAI,WAAW,SAAA,EAAW;AACxB,UAAA,KAAA,GAAQ,MAAA,IAAU,IAAI,KAAA,CAAM,eAAe,CAAA;AAC3C,UAAA;AAAA,QACF;AAAA,MACF,SAAS,CAAA,EAAG;AACV,QAAA,KAAA,GAAQ,CAAA;AACR,QAAA;AAAA,MACF;AAAA,IACF;AAEA,IAAA,IAAI,OAAO,KAAA,CAAM,OAAA,KAAY,UAAA,EAAY,MAAM,MAAM,OAAA,EAAQ;AAE7D,IAAA,MAAM,QAAQ,MAAA,CAAO,KAAA,CAAM,GAAA,CAAI,CAAC,MAAM,CAAA,MAAO;AAAA,MAC3C,MAAM,IAAA,CAAK,IAAA;AAAA,MACX,QACE,SAAA,GAAY,CAAA,GAAI,SAAA,GAAc,SAAA,KAAc,IAAI,SAAA,GAAY;AAAA,KAChE,CAAE,CAAA;AAEF,IAAA,OAAO,EAAE,OAAO,MAAA,EAAQ,CAAC,QAAQ,QAAA,GAAW,QAAA,EAAU,KAAA,EAAO,MAAA,EAAQ,KAAA,EAAM;AAAA,EAC7E;AAAA,EAEA,KAAA,GAAQ;AACN,IAAA,IAAA,CAAK,SAAA,GAAY,IAAI,qBAAA,EAAsB;AAC3C,IAAA,IAAA,CAAK,QAAQ,EAAC;AAAA,EAChB;AAAA,EAEQ,MAAM,IAAA,EAAc;AAC1B,IAAA,KAAA,MAAW,GAAA,IAAO,KAAK,IAAA,EAAM;AAC3B,MAAA,MAAM,IAAA,GAAO,GAAA,CAAI,IAAA,CAAK,KAAA,CAAM,IAAI,CAAA;AAChC,MAAA,IAAI,IAAA,EAAM,OAAO,EAAE,GAAA,EAAK,MAAA,EAAQ,IAAA,CAAK,GAAA,CAAI,CAAC,CAAA,KAAM,CAAA,CAAE,QAAA,CAAS,IAAI,CAAC,CAAA,EAAE;AAAA,IACpE;AACA,IAAA,OAAO,IAAA;AAAA,EACT;AAAA,EAEQ,aAAa,IAAA,EAAmC;AACtD,IAAA,MAAM,GAAA,GAAM,IAAA,CAAK,IAAA,CAAK,IAAA,CAAK,CAAC,EAAE,IAAA,EAAK,KAAM,CAAC,CAAC,IAAA,CAAK,KAAA,CAAM,IAAA,CAAK,IAAI,CAAC,CAAA;AAEhE,IAAA,MAAM,IAAA,GAAO,MAAM,CAAA,EAAG,GAAA,CAAI,IAAI,CAAA,CAAA,EAAI,IAAA,CAAK,IAAI,CAAA,CAAA,GAAK,IAAA,CAAK,IAAA;AACrD,IAAA,MAAM,OAAO,GAAA,EAAK,IAAA,CAAK,MAAM,IAAA,CAAK,IAAI,KAAK,EAAC;AAE5C,IAAA,OAAO,EAAE,EAAA,EAAI,IAAA,CAAK,EAAA,EAAI,MAAM,IAAA,EAAK;AAAA,EACnC;AAAA,EAEQ,OAAA,CAAQ,OAAA,EAAiB,GAAA,GAAM,gBAAA,EAAkB;AACvD,IAAA,MAAM,SAAA,GAAY,gBAAA,CAAiB,OAAA,EAAS,GAAA,EAAK,gBAAgB,6BAAA,EAA+B;AAAA,MAC9F,KAAA,EAAO,MAAM,WAAA,CAAY,IAAA,GAAO,QAAA,EAAS;AAAA,MACzC,sBAAA,EAAwB,IAAA;AAAA,MACxB,cAAA,EAAgB,IAAA;AAAA,MAChB,aAAA,EAAe;AAAA,KAChB,CAAA;AACD,IAAA,MAAM,OAAA,GAAU,SAAA,CAAU,MAAA,CAAO,CAAC,CAAA,KAAM,CAAA,CAAE,MAAM,CAAA,CAAE,GAAA,CAAI,CAAC,CAAA,KAAM,CAAA,CAAE,MAAO,CAAA;AACtE,IAAA,IAAI,CAAC,OAAA,CAAQ,MAAA,EAAQ,MAAM,IAAI,MAAM,oBAAoB,CAAA;AACzD,IAAA,OAAO,OAAA;AAAA,EACT;AAAA,EAEA,MAAc,OAAA,CAAQ,KAAA,EAAe,IAAA,EAAuC;AAC1E,IAAA,IAAI;AACF,MAAA,MAAM,OAAO,IAAA,CAAK,IAAA;AAClB,MAAA,MAAM,KAAA,GAAQ,IAAA,CAAK,KAAA,CAAM,IAAI,CAAA;AAE7B,MAAA,IAAI,CAAC,KAAA,EAAO,MAAM,IAAI,KAAA,CAAM,CAAA,gBAAA,EAAmB,IAAI,CAAA,CAAE,CAAA;AAGrD,MAAA,IAAI,KAAA;AACJ,MAAA,IAAI,IAAA,CAAK,UAAU,SAAA,EAAW;AAC5B,QAAA,KAAA,GAAQ,IAAA,CAAK,SAAS,SAAA,CAAU,OAAA;AAAA,MAClC,CAAA,MAAA,IAAW,IAAA,CAAK,QAAA,EAAU,SAAA,EAAW;AACnC,QAAA,KAAA,GAAQ,IAAA,CAAK,QAAA,CAAS,SAAA,CAAU,IAAA,CAAK,IAAI,CAAC,CAAA,KAAM,CAAA,CAAE,KAAA,CAAM,GAAA,CAAI,CAAC,CAAA,KAAM,CAAA,CAAE,KAAK,CAAC,CAAA;AAAA,MAC7E;AAEA,MAAA,MAAM,MAAM,GAAA,CAAI,EAAA,CAAG,KAAA,CAAM,KAAA,EAAO,CAAC,GAAG,KAAA,CAAM,MAAA,EAAQ,GAAI,UAAU,KAAA,CAAA,GAAY,CAAC,KAAK,CAAA,GAAI,EAAG,CAAC,CAAA;AAE1F,MAAA,OAAO,EAAE,QAAQ,SAAA,EAAU;AAAA,IAC7B,SAAS,CAAA,EAAG;AACV,MAAA,OAAO,EAAE,MAAA,EAAQ,SAAA,EAAW,MAAA,EAAQ,CAAA,EAAW;AAAA,IACjD;AAAA,EACF;AACF","file":"index.js","sourcesContent":["import {\n  Argument,\n  CucumberExpression,\n  ParameterType,\n  ParameterTypeRegistry,\n  RegularExpression,\n} from '@cucumber/cucumber-expressions';\nimport { generateMessages } from '@cucumber/gherkin';\nimport { IdGenerator, Pickle, PickleStep, SourceMediaType } from '@cucumber/messages';\nimport { ParameterTypeDefinition, sanitizeStepDefinition } from '@letsrunit/gherkin';\nimport { ParsedStep, Result, StepDefinition, StepHandler, StepType, World } from './types';\n\nexport type StepResult = { status: 'success' | 'failure'; reason?: Error };\nexport type StepDescription = { id: string, text: string; args: readonly Argument[] };\ntype StepWrapper = (step: StepDescription, run: () => Promise<StepResult>) => Promise<StepResult>;\n\nexport class Runner<TWorld extends World> {\n  private _registry = new ParameterTypeRegistry(); // Private instead of readonly, because `reset()`\n\n  get registry(): ParameterTypeRegistry {\n    return this._registry;\n  }\n\n  private _defs: StepDefinition<TWorld>[] = [];\n\n  get defs(): StepDefinition<TWorld>[] {\n    return this._defs;\n  }\n\n  defineStep(type: StepType, expression: string | RegExp, fn: StepHandler<TWorld>, comment?: string) {\n    const expr =\n      typeof expression === 'string'\n        ? new CucumberExpression(sanitizeStepDefinition(expression), this.registry)\n        : new RegularExpression(expression, this.registry);\n    this.defs.push({ type, expr, fn, source: String(expression), comment });\n  }\n\n  defineParameterType(type: ParameterTypeDefinition<unknown>) {\n    const paramType = new ParameterType(type.name, type.regexp, null, type.transformer, type.useForSnippets);\n\n    this._registry.defineParameterType(paramType);\n  }\n\n  parse(feature: string): ParsedStep[] {\n    const pickles = this.compile(feature);\n    if (pickles.length > 1) {\n      throw new Error('Multiple scenarios not supported');\n    }\n\n    const pickle = pickles[0];\n\n    return pickle.steps.map((step) => {\n      const match = this.match(step.text);\n\n      return {\n        text: step.text,\n        def: match?.def ? `${match?.def.type} ${match?.def.source}` : undefined,\n        values: match?.values,\n      };\n    });\n  }\n\n  async run(\n    feature: string,\n    worldFactory: TWorld | (() => Promise<TWorld> | TWorld),\n    wrapRun?: StepWrapper,\n    { signal }: { signal?: AbortSignal } = {},\n  ): Promise<Result<TWorld>> {\n    const pickles = this.compile(feature);\n    if (pickles.length > 1) {\n      throw new Error('Multiple scenarios not supported');\n    }\n\n    wrapRun ??= (_step, run) => run();\n\n    const world = typeof worldFactory === 'function' ? await worldFactory() : worldFactory;\n    const pickle = pickles[0];\n    let completed = 0;\n    let error: Error | undefined;\n\n    for (const step of pickle.steps) {\n      if (signal?.aborted) {\n        error = signal.reason instanceof Error ? signal.reason : new Error(String(signal.reason));\n        break;\n      }\n\n      try {\n        const { status, reason } = await wrapRun(this.describeStep(step), () => this.runStep(world, step));\n\n        if (status === 'success') completed++;\n\n        if (status === 'failure') {\n          error = reason ?? new Error('Unknown error');\n          break;\n        }\n      } catch (e) {\n        error = e as Error;\n        break;\n      }\n    }\n\n    if (typeof world.cleanup === 'function') await world.cleanup();\n\n    const steps = pickle.steps.map((step, i) => ({\n      text: step.text,\n      status:\n        completed > i ? 'success' : ((completed === i ? 'failure' : undefined) as 'success' | 'failure' | undefined),\n    }));\n\n    return { world, status: !error ? 'passed' : 'failed', steps, reason: error };\n  }\n\n  reset() {\n    this._registry = new ParameterTypeRegistry();\n    this._defs = [];\n  }\n\n  private match(text: string) {\n    for (const def of this.defs) {\n      const args = def.expr.match(text);\n      if (args) return { def, values: args.map((a) => a.getValue(null)) };\n    }\n    return null;\n  }\n\n  private describeStep(step: PickleStep): StepDescription {\n    const def = this.defs.find(({ expr }) => !!expr.match(step.text));\n\n    const text = def ? `${def.type} ${step.text}` : step.text;\n    const args = def?.expr.match(step.text) || [];\n\n    return { id: step.id, text, args };\n  }\n\n  private compile(feature: string, uri = 'inline.feature') {\n    const envelopes = generateMessages(feature, uri, SourceMediaType.TEXT_X_CUCUMBER_GHERKIN_PLAIN, {\n      newId: () => IdGenerator.uuid().toString(),\n      includeGherkinDocument: true,\n      includePickles: true,\n      includeSource: false,\n    });\n    const pickles = envelopes.filter((e) => e.pickle).map((e) => e.pickle!) as Pickle[];\n    if (!pickles.length) throw new Error('No scenarios found');\n    return pickles;\n  }\n\n  private async runStep(world: TWorld, step: PickleStep): Promise<StepResult> {\n    try {\n      const text = step.text;\n      const match = this.match(text);\n\n      if (!match) throw new Error(`Undefined step: ${text}`);\n\n      // DocString/DataTable\n      let extra: any | undefined;\n      if (step.argument?.docString) {\n        extra = step.argument.docString.content;\n      } else if (step.argument?.dataTable) {\n        extra = step.argument.dataTable.rows.map((r) => r.cells.map((c) => c.value));\n      }\n\n      await match.def.fn.apply(world, [...match.values, ...(extra !== undefined ? [extra] : [])]);\n\n      return { status: 'success' };\n    } catch (e) {\n      return { status: 'failure', reason: e as Error };\n    }\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@letsrunit/gherker",
+  "version": "0.1.0",
+  "description": "A gherkin microrunner",
+  "keywords": [
+    "testing",
+    "gherkin",
+    "runner",
+    "letsrunit"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/letsrunit/letsrunit.git",
+    "directory": "packages/gherker"
+  },
+  "bugs": "https://github.com/letsrunit/letsrunit/issues",
+  "homepage": "https://github.com/letsrunit/letsrunit#readme",
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "../../node_modules/.bin/tsup",
+    "test": "vitest run",
+    "test:cov": "vitest run --coverage",
+    "typecheck": "tsc --noEmit"
+  },
+  "packageManager": "yarn@4.10.3",
+  "dependencies": {
+    "@cucumber/cucumber-expressions": "^18.1.0",
+    "@cucumber/gherkin": "^37.0.1",
+    "@cucumber/messages": "^31.2.0",
+    "@letsrunit/gherkin": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.9",
+    "vitest": "^4.0.17"
+  },
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './runner';
+export type { Result, StepHandler, ParsedStep } from "./types";

package/src/runner.ts

@@ -0,0 +1,169 @@
+import {
+  Argument,
+  CucumberExpression,
+  ParameterType,
+  ParameterTypeRegistry,
+  RegularExpression,
+} from '@cucumber/cucumber-expressions';
+import { generateMessages } from '@cucumber/gherkin';
+import { IdGenerator, Pickle, PickleStep, SourceMediaType } from '@cucumber/messages';
+import { ParameterTypeDefinition, sanitizeStepDefinition } from '@letsrunit/gherkin';
+import { ParsedStep, Result, StepDefinition, StepHandler, StepType, World } from './types';
+
+export type StepResult = { status: 'success' | 'failure'; reason?: Error };
+export type StepDescription = { id: string, text: string; args: readonly Argument[] };
+type StepWrapper = (step: StepDescription, run: () => Promise<StepResult>) => Promise<StepResult>;
+
+export class Runner<TWorld extends World> {
+  private _registry = new ParameterTypeRegistry(); // Private instead of readonly, because `reset()`
+
+  get registry(): ParameterTypeRegistry {
+    return this._registry;
+  }
+
+  private _defs: StepDefinition<TWorld>[] = [];
+
+  get defs(): StepDefinition<TWorld>[] {
+    return this._defs;
+  }
+
+  defineStep(type: StepType, expression: string | RegExp, fn: StepHandler<TWorld>, comment?: string) {
+    const expr =
+      typeof expression === 'string'
+        ? new CucumberExpression(sanitizeStepDefinition(expression), this.registry)
+        : new RegularExpression(expression, this.registry);
+    this.defs.push({ type, expr, fn, source: String(expression), comment });
+  }
+
+  defineParameterType(type: ParameterTypeDefinition<unknown>) {
+    const paramType = new ParameterType(type.name, type.regexp, null, type.transformer, type.useForSnippets);
+
+    this._registry.defineParameterType(paramType);
+  }
+
+  parse(feature: string): ParsedStep[] {
+    const pickles = this.compile(feature);
+    if (pickles.length > 1) {
+      throw new Error('Multiple scenarios not supported');
+    }
+
+    const pickle = pickles[0];
+
+    return pickle.steps.map((step) => {
+      const match = this.match(step.text);
+
+      return {
+        text: step.text,
+        def: match?.def ? `${match?.def.type} ${match?.def.source}` : undefined,
+        values: match?.values,
+      };
+    });
+  }
+
+  async run(
+    feature: string,
+    worldFactory: TWorld | (() => Promise<TWorld> | TWorld),
+    wrapRun?: StepWrapper,
+    { signal }: { signal?: AbortSignal } = {},
+  ): Promise<Result<TWorld>> {
+    const pickles = this.compile(feature);
+    if (pickles.length > 1) {
+      throw new Error('Multiple scenarios not supported');
+    }
+
+    wrapRun ??= (_step, run) => run();
+
+    const world = typeof worldFactory === 'function' ? await worldFactory() : worldFactory;
+    const pickle = pickles[0];
+    let completed = 0;
+    let error: Error | undefined;
+
+    for (const step of pickle.steps) {
+      if (signal?.aborted) {
+        error = signal.reason instanceof Error ? signal.reason : new Error(String(signal.reason));
+        break;
+      }
+
+      try {
+        const { status, reason } = await wrapRun(this.describeStep(step), () => this.runStep(world, step));
+
+        if (status === 'success') completed++;
+
+        if (status === 'failure') {
+          error = reason ?? new Error('Unknown error');
+          break;
+        }
+      } catch (e) {
+        error = e as Error;
+        break;
+      }
+    }
+
+    if (typeof world.cleanup === 'function') await world.cleanup();
+
+    const steps = pickle.steps.map((step, i) => ({
+      text: step.text,
+      status:
+        completed > i ? 'success' : ((completed === i ? 'failure' : undefined) as 'success' | 'failure' | undefined),
+    }));
+
+    return { world, status: !error ? 'passed' : 'failed', steps, reason: error };
+  }
+
+  reset() {
+    this._registry = new ParameterTypeRegistry();
+    this._defs = [];
+  }
+
+  private match(text: string) {
+    for (const def of this.defs) {
+      const args = def.expr.match(text);
+      if (args) return { def, values: args.map((a) => a.getValue(null)) };
+    }
+    return null;
+  }
+
+  private describeStep(step: PickleStep): StepDescription {
+    const def = this.defs.find(({ expr }) => !!expr.match(step.text));
+
+    const text = def ? `${def.type} ${step.text}` : step.text;
+    const args = def?.expr.match(step.text) || [];
+
+    return { id: step.id, text, args };
+  }
+
+  private compile(feature: string, uri = 'inline.feature') {
+    const envelopes = generateMessages(feature, uri, SourceMediaType.TEXT_X_CUCUMBER_GHERKIN_PLAIN, {
+      newId: () => IdGenerator.uuid().toString(),
+      includeGherkinDocument: true,
+      includePickles: true,
+      includeSource: false,
+    });
+    const pickles = envelopes.filter((e) => e.pickle).map((e) => e.pickle!) as Pickle[];
+    if (!pickles.length) throw new Error('No scenarios found');
+    return pickles;
+  }
+
+  private async runStep(world: TWorld, step: PickleStep): Promise<StepResult> {
+    try {
+      const text = step.text;
+      const match = this.match(text);
+
+      if (!match) throw new Error(`Undefined step: ${text}`);
+
+      // DocString/DataTable
+      let extra: any | undefined;
+      if (step.argument?.docString) {
+        extra = step.argument.docString.content;
+      } else if (step.argument?.dataTable) {
+        extra = step.argument.dataTable.rows.map((r) => r.cells.map((c) => c.value));
+      }
+
+      await match.def.fn.apply(world, [...match.values, ...(extra !== undefined ? [extra] : [])]);
+
+      return { status: 'success' };
+    } catch (e) {
+      return { status: 'failure', reason: e as Error };
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,29 @@
+import { Expression } from '@cucumber/cucumber-expressions';
+
+export type World = { cleanup?: () => void | Promise<void>; [_: string]: any };
+export type StepHandler<T> = (this: T, ...args: any[]) => Promise<void> | void;
+export type StepType = 'Given' | 'When' | 'Then';
+
+export interface StepDefinition<T> {
+  type: StepType;
+  expr: Expression;
+  fn: StepHandler<T>;
+  source: string;
+  comment?: string;
+}
+
+export interface ParsedStep {
+  text: string;
+  def?: string;
+  values?: unknown[];
+}
+
+export interface Result<TWorld extends World = any> {
+  world: TWorld;
+  status: 'passed' | 'failed';
+  steps: Array<{
+    text: string;
+    status?: 'success' | 'failure';
+  }>;
+  reason?: Error;
+}