@cucumber/cucumber 10.0.1 → 10.2.1

package/lib/api/run_cucumber.js

@@ -5,32 +5,37 @@ const node_events_1 = require("node:events");
 const messages_1 = require("@cucumber/messages");
 const helpers_1 = require("../formatter/helpers");
 const helpers_2 = require("../cli/helpers");
-const paths_1 = require("./paths");
+const paths_1 = require("../paths");
 const runtime_1 = require("./runtime");
 const formatters_1 = require("./formatters");
 const support_1 = require("./support");
 const environment_1 = require("./environment");
 const gherkin_1 = require("./gherkin");
 const plugins_1 = require("./plugins");
-const console_logger_1 = require("./console_logger");
 /**
- * Execute a Cucumber test run.
+ * Execute a Cucumber test run and return the overall result
  *
  * @public
- * @param configuration - Configuration loaded from `loadConfiguration`.
- * @param environment - Project environment.
- * @param onMessage - Callback fired each time Cucumber emits a message.
+ * @param options - Options for the run, obtainable via {@link loadConfiguration}
+ * @param environment - Project environment
+ * @param onMessage - Callback fired each time Cucumber emits a message
  */
-async function runCucumber(configuration, environment = {}, onMessage) {
-    const { cwd, stdout, stderr, env, debug } = (0, environment_1.mergeEnvironment)(environment);
-    const logger = new console_logger_1.ConsoleLogger(stderr, debug);
+async function runCucumber(options, environment = {}, onMessage) {
+    const mergedEnvironment = (0, environment_1.mergeEnvironment)(environment);
+    const { cwd, stdout, stderr, env, logger } = mergedEnvironment;
     const newId = messages_1.IdGenerator.uuid();
-    const supportCoordinates = 'World' in configuration.support
-        ? configuration.support.originalCoordinates
-        : configuration.support;
-    const { unexpandedFeaturePaths, featurePaths, requirePaths, importPaths } = await (0, paths_1.resolvePaths)(logger, cwd, configuration.sources, supportCoordinates);
-    const supportCodeLibrary = 'World' in configuration.support
-        ? configuration.support
+    const supportCoordinates = 'originalCoordinates' in options.support
+        ? options.support.originalCoordinates
+        : options.support;
+    const pluginManager = await (0, plugins_1.initializeForRunCucumber)(logger, {
+        ...options,
+        support: supportCoordinates,
+    }, mergedEnvironment);
+    const resolvedPaths = await (0, paths_1.resolvePaths)(logger, cwd, options.sources, supportCoordinates);
+    pluginManager.emit('paths:resolve', resolvedPaths);
+    const { sourcePaths, requirePaths, importPaths } = resolvedPaths;
+    const supportCodeLibrary = 'originalCoordinates' in options.support
+        ? options.support
         : await (0, support_1.getSupportCodeLibrary)({
             cwd,
             newId,
@@ -38,12 +43,11 @@ async function runCucumber(configuration, environment = {}, onMessage) {
             importPaths,
             requireModules: supportCoordinates.requireModules,
         });
-    const plugins = await (0, plugins_1.initializePlugins)(logger, configuration, environment);
     const eventBroadcaster = new node_events_1.EventEmitter();
     if (onMessage) {
         eventBroadcaster.on('envelope', onMessage);
     }
-    eventBroadcaster.on('envelope', (value) => plugins.emit('message', value));
+    eventBroadcaster.on('envelope', (value) => pluginManager.emit('message', value));
     const eventDataCollector = new helpers_1.EventDataCollector(eventBroadcaster);
     let formatterStreamError = false;
     const cleanupFormatters = await (0, formatters_1.initializeFormatters)({
@@ -55,23 +59,23 @@ async function runCucumber(configuration, environment = {}, onMessage) {
         onStreamError: () => (formatterStreamError = true),
         eventBroadcaster,
         eventDataCollector,
-        configuration: configuration.formats,
+        configuration: options.formats,
         supportCodeLibrary,
     });
     await (0, helpers_2.emitMetaMessage)(eventBroadcaster, env);
     let pickleIds = [];
     let parseErrors = [];
-    if (featurePaths.length > 0) {
-        const gherkinResult = await (0, gherkin_1.getFilteredPicklesAndErrors)({
+    if (sourcePaths.length > 0) {
+        const gherkinResult = await (0, gherkin_1.getPicklesAndErrors)({
             newId,
             cwd,
-            logger,
-            unexpandedFeaturePaths,
-            featurePaths,
-            coordinates: configuration.sources,
+            sourcePaths,
+            coordinates: options.sources,
             onEnvelope: (envelope) => eventBroadcaster.emit('envelope', envelope),
         });
-        pickleIds = gherkinResult.filteredPickles.map(({ pickle }) => pickle.id);
+        const filteredPickles = await pluginManager.transform('pickles:filter', gherkinResult.filterablePickles);
+        const orderedPickles = await pluginManager.transform('pickles:order', filteredPickles);
+        pickleIds = orderedPickles.map(({ pickle }) => pickle.id);
         parseErrors = gherkinResult.parseErrors;
     }
     if (parseErrors.length) {
@@ -79,7 +83,7 @@ async function runCucumber(configuration, environment = {}, onMessage) {
             logger.error(`Parse error in "${parseError.source.uri}" ${parseError.message}`);
         });
         await cleanupFormatters();
-        await plugins.cleanup();
+        await pluginManager.cleanup();
         return {
             success: false,
             support: supportCodeLibrary,
@@ -101,11 +105,11 @@ async function runCucumber(configuration, environment = {}, onMessage) {
         requireModules: supportCoordinates.requireModules,
         requirePaths,
         importPaths,
-        options: configuration.runtime,
+        options: options.runtime,
     });
     const success = await runtime.start();
     await cleanupFormatters();
-    await plugins.cleanup();
+    await pluginManager.cleanup();
     return {
         success: success && !formatterStreamError,
         support: supportCodeLibrary,

package/lib/api/run_cucumber.js.map

@@ -1 +1 @@
-{"version":3,"file":"run_cucumber.js","sourceRoot":"","sources":["../../src/api/run_cucumber.ts"],"names":[],"mappings":"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","sourcesContent":["import { EventEmitter } from 'node:events'\nimport { Envelope, IdGenerator, ParseError } from '@cucumber/messages'\nimport { EventDataCollector } from '../formatter/helpers'\nimport { emitMetaMessage, emitSupportCodeMessages } from '../cli/helpers'\nimport { ILogger } from '../logger'\nimport { IRunOptions, IRunEnvironment, IRunResult } from './types'\nimport { resolvePaths } from './paths'\nimport { makeRuntime } from './runtime'\nimport { initializeFormatters } from './formatters'\nimport { getSupportCodeLibrary } from './support'\nimport { mergeEnvironment } from './environment'\nimport { getFilteredPicklesAndErrors } from './gherkin'\nimport { initializePlugins } from './plugins'\nimport { ConsoleLogger } from './console_logger'\n\n/**\n * Execute a Cucumber test run.\n *\n * @public\n * @param configuration - Configuration loaded from `loadConfiguration`.\n * @param environment - Project environment.\n * @param onMessage - Callback fired each time Cucumber emits a message.\n */\nexport async function runCucumber(\n  configuration: IRunOptions,\n  environment: IRunEnvironment = {},\n  onMessage?: (message: Envelope) => void\n): Promise<IRunResult> {\n  const { cwd, stdout, stderr, env, debug } = mergeEnvironment(environment)\n  const logger: ILogger = new ConsoleLogger(stderr, debug)\n\n  const newId = IdGenerator.uuid()\n\n  const supportCoordinates =\n    'World' in configuration.support\n      ? configuration.support.originalCoordinates\n      : configuration.support\n\n  const { unexpandedFeaturePaths, featurePaths, requirePaths, importPaths } =\n    await resolvePaths(logger, cwd, configuration.sources, supportCoordinates)\n\n  const supportCodeLibrary =\n    'World' in configuration.support\n      ? configuration.support\n      : await getSupportCodeLibrary({\n          cwd,\n          newId,\n          requirePaths,\n          importPaths,\n          requireModules: supportCoordinates.requireModules,\n        })\n\n  const plugins = await initializePlugins(logger, configuration, environment)\n\n  const eventBroadcaster = new EventEmitter()\n  if (onMessage) {\n    eventBroadcaster.on('envelope', onMessage)\n  }\n  eventBroadcaster.on('envelope', (value) => plugins.emit('message', value))\n  const eventDataCollector = new EventDataCollector(eventBroadcaster)\n\n  let formatterStreamError = false\n  const cleanupFormatters = await initializeFormatters({\n    env,\n    cwd,\n    stdout,\n    stderr,\n    logger,\n    onStreamError: () => (formatterStreamError = true),\n    eventBroadcaster,\n    eventDataCollector,\n    configuration: configuration.formats,\n    supportCodeLibrary,\n  })\n  await emitMetaMessage(eventBroadcaster, env)\n\n  let pickleIds: string[] = []\n  let parseErrors: ParseError[] = []\n  if (featurePaths.length > 0) {\n    const gherkinResult = await getFilteredPicklesAndErrors({\n      newId,\n      cwd,\n      logger,\n      unexpandedFeaturePaths,\n      featurePaths,\n      coordinates: configuration.sources,\n      onEnvelope: (envelope) => eventBroadcaster.emit('envelope', envelope),\n    })\n    pickleIds = gherkinResult.filteredPickles.map(({ pickle }) => pickle.id)\n    parseErrors = gherkinResult.parseErrors\n  }\n  if (parseErrors.length) {\n    parseErrors.forEach((parseError) => {\n      logger.error(\n        `Parse error in \"${parseError.source.uri}\" ${parseError.message}`\n      )\n    })\n    await cleanupFormatters()\n    await plugins.cleanup()\n    return {\n      success: false,\n      support: supportCodeLibrary,\n    }\n  }\n\n  emitSupportCodeMessages({\n    eventBroadcaster,\n    supportCodeLibrary,\n    newId,\n  })\n\n  const runtime = makeRuntime({\n    cwd,\n    logger,\n    eventBroadcaster,\n    eventDataCollector,\n    pickleIds,\n    newId,\n    supportCodeLibrary,\n    requireModules: supportCoordinates.requireModules,\n    requirePaths,\n    importPaths,\n    options: configuration.runtime,\n  })\n  const success = await runtime.start()\n  await cleanupFormatters()\n  await plugins.cleanup()\n\n  return {\n    success: success && !formatterStreamError,\n    support: supportCodeLibrary,\n  }\n}\n"]}
+{"version":3,"file":"run_cucumber.js","sourceRoot":"","sources":["../../src/api/run_cucumber.ts"],"names":[],"mappings":"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","sourcesContent":["import { EventEmitter } from 'node:events'\nimport { Envelope, IdGenerator, ParseError } from '@cucumber/messages'\nimport { EventDataCollector } from '../formatter/helpers'\nimport { emitMetaMessage, emitSupportCodeMessages } from '../cli/helpers'\nimport { resolvePaths } from '../paths'\nimport { SupportCodeLibrary } from '../support_code_library_builder/types'\nimport { IRunOptions, IRunEnvironment, IRunResult } from './types'\nimport { makeRuntime } from './runtime'\nimport { initializeFormatters } from './formatters'\nimport { getSupportCodeLibrary } from './support'\nimport { mergeEnvironment } from './environment'\nimport { getPicklesAndErrors } from './gherkin'\nimport { initializeForRunCucumber } from './plugins'\n\n/**\n * Execute a Cucumber test run and return the overall result\n *\n * @public\n * @param options - Options for the run, obtainable via {@link loadConfiguration}\n * @param environment - Project environment\n * @param onMessage - Callback fired each time Cucumber emits a message\n */\nexport async function runCucumber(\n  options: IRunOptions,\n  environment: IRunEnvironment = {},\n  onMessage?: (message: Envelope) => void\n): Promise<IRunResult> {\n  const mergedEnvironment = mergeEnvironment(environment)\n  const { cwd, stdout, stderr, env, logger } = mergedEnvironment\n\n  const newId = IdGenerator.uuid()\n\n  const supportCoordinates =\n    'originalCoordinates' in options.support\n      ? options.support.originalCoordinates\n      : options.support\n\n  const pluginManager = await initializeForRunCucumber(\n    logger,\n    {\n      ...options,\n      support: supportCoordinates,\n    },\n    mergedEnvironment\n  )\n\n  const resolvedPaths = await resolvePaths(\n    logger,\n    cwd,\n    options.sources,\n    supportCoordinates\n  )\n  pluginManager.emit('paths:resolve', resolvedPaths)\n  const { sourcePaths, requirePaths, importPaths } = resolvedPaths\n\n  const supportCodeLibrary =\n    'originalCoordinates' in options.support\n      ? (options.support as SupportCodeLibrary)\n      : await getSupportCodeLibrary({\n          cwd,\n          newId,\n          requirePaths,\n          importPaths,\n          requireModules: supportCoordinates.requireModules,\n        })\n\n  const eventBroadcaster = new EventEmitter()\n  if (onMessage) {\n    eventBroadcaster.on('envelope', onMessage)\n  }\n  eventBroadcaster.on('envelope', (value) =>\n    pluginManager.emit('message', value)\n  )\n  const eventDataCollector = new EventDataCollector(eventBroadcaster)\n\n  let formatterStreamError = false\n  const cleanupFormatters = await initializeFormatters({\n    env,\n    cwd,\n    stdout,\n    stderr,\n    logger,\n    onStreamError: () => (formatterStreamError = true),\n    eventBroadcaster,\n    eventDataCollector,\n    configuration: options.formats,\n    supportCodeLibrary,\n  })\n  await emitMetaMessage(eventBroadcaster, env)\n\n  let pickleIds: string[] = []\n  let parseErrors: ParseError[] = []\n  if (sourcePaths.length > 0) {\n    const gherkinResult = await getPicklesAndErrors({\n      newId,\n      cwd,\n      sourcePaths,\n      coordinates: options.sources,\n      onEnvelope: (envelope) => eventBroadcaster.emit('envelope', envelope),\n    })\n    const filteredPickles = await pluginManager.transform(\n      'pickles:filter',\n      gherkinResult.filterablePickles\n    )\n    const orderedPickles = await pluginManager.transform(\n      'pickles:order',\n      filteredPickles\n    )\n    pickleIds = orderedPickles.map(({ pickle }) => pickle.id)\n    parseErrors = gherkinResult.parseErrors\n  }\n  if (parseErrors.length) {\n    parseErrors.forEach((parseError) => {\n      logger.error(\n        `Parse error in \"${parseError.source.uri}\" ${parseError.message}`\n      )\n    })\n    await cleanupFormatters()\n    await pluginManager.cleanup()\n    return {\n      success: false,\n      support: supportCodeLibrary,\n    }\n  }\n\n  emitSupportCodeMessages({\n    eventBroadcaster,\n    supportCodeLibrary,\n    newId,\n  })\n\n  const runtime = makeRuntime({\n    cwd,\n    logger,\n    eventBroadcaster,\n    eventDataCollector,\n    pickleIds,\n    newId,\n    supportCodeLibrary,\n    requireModules: supportCoordinates.requireModules,\n    requirePaths,\n    importPaths,\n    options: options.runtime,\n  })\n  const success = await runtime.start()\n  await cleanupFormatters()\n  await pluginManager.cleanup()\n\n  return {\n    success: success && !formatterStreamError,\n    support: supportCodeLibrary,\n  }\n}\n"]}

package/lib/api/runtime.d.ts

@@ -3,7 +3,7 @@ import { EventEmitter } from 'node:events';
 import { IdGenerator } from '@cucumber/messages';
 import { IRuntime } from '../runtime';
 import { EventDataCollector } from '../formatter/helpers';
-import { ISupportCodeLibrary } from '../support_code_library_builder/types';
+import { SupportCodeLibrary } from '../support_code_library_builder/types';
 import { ILogger } from '../logger';
 import { IRunOptionsRuntime } from './types';
 export declare function makeRuntime({ cwd, logger, eventBroadcaster, eventDataCollector, pickleIds, newId, supportCodeLibrary, requireModules, requirePaths, importPaths, options: { parallel, ...options }, }: {
@@ -13,7 +13,7 @@ export declare function makeRuntime({ cwd, logger, eventBroadcaster, eventDataCo
     eventDataCollector: EventDataCollector;
     newId: IdGenerator.NewId;
     pickleIds: string[];
-    supportCodeLibrary: ISupportCodeLibrary;
+    supportCodeLibrary: SupportCodeLibrary;
     requireModules: string[];
     requirePaths: string[];
     importPaths: string[];

package/lib/api/runtime.js.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../src/api/runtime.ts"],"names":[],"mappings":";;;;;;AAEA,yDAA8C;AAG9C,kFAAyD;AAIzD,SAAgB,WAAW,CAAC,EAC1B,GAAG,EACH,MAAM,EACN,gBAAgB,EAChB,kBAAkB,EAClB,SAAS,EACT,KAAK,EACL,kBAAkB,EAClB,cAAc,EACd,YAAY,EACZ,WAAW,EACX,OAAO,EAAE,EAAE,QAAQ,EAAE,GAAG,OAAO,EAAE,GAalC;IACC,IAAI,QAAQ,GAAG,CAAC,EAAE;QAChB,OAAO,IAAI,qBAAW,CAAC;YACrB,GAAG;YACH,MAAM;YACN,gBAAgB;YAChB,kBAAkB;YAClB,SAAS;YACT,OAAO;YACP,KAAK;YACL,kBAAkB;YAClB,cAAc;YACd,YAAY;YACZ,WAAW;YACX,eAAe,EAAE,QAAQ;SAC1B,CAAC,CAAA;KACH;IACD,OAAO,IAAI,iBAAO,CAAC;QACjB,gBAAgB;QAChB,kBAAkB;QAClB,KAAK;QACL,SAAS;QACT,kBAAkB;QAClB,OAAO;KACR,CAAC,CAAA;AACJ,CAAC;AAjDD,kCAiDC","sourcesContent":["import { EventEmitter } from 'node:events'\nimport { IdGenerator } from '@cucumber/messages'\nimport Runtime, { IRuntime } from '../runtime'\nimport { EventDataCollector } from '../formatter/helpers'\nimport { ISupportCodeLibrary } from '../support_code_library_builder/types'\nimport Coordinator from '../runtime/parallel/coordinator'\nimport { ILogger } from '../logger'\nimport { IRunOptionsRuntime } from './types'\n\nexport function makeRuntime({\n  cwd,\n  logger,\n  eventBroadcaster,\n  eventDataCollector,\n  pickleIds,\n  newId,\n  supportCodeLibrary,\n  requireModules,\n  requirePaths,\n  importPaths,\n  options: { parallel, ...options },\n}: {\n  cwd: string\n  logger: ILogger\n  eventBroadcaster: EventEmitter\n  eventDataCollector: EventDataCollector\n  newId: IdGenerator.NewId\n  pickleIds: string[]\n  supportCodeLibrary: ISupportCodeLibrary\n  requireModules: string[]\n  requirePaths: string[]\n  importPaths: string[]\n  options: IRunOptionsRuntime\n}): IRuntime {\n  if (parallel > 0) {\n    return new Coordinator({\n      cwd,\n      logger,\n      eventBroadcaster,\n      eventDataCollector,\n      pickleIds,\n      options,\n      newId,\n      supportCodeLibrary,\n      requireModules,\n      requirePaths,\n      importPaths,\n      numberOfWorkers: parallel,\n    })\n  }\n  return new Runtime({\n    eventBroadcaster,\n    eventDataCollector,\n    newId,\n    pickleIds,\n    supportCodeLibrary,\n    options,\n  })\n}\n"]}
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../src/api/runtime.ts"],"names":[],"mappings":";;;;;;AAEA,yDAA8C;AAG9C,kFAAyD;AAIzD,SAAgB,WAAW,CAAC,EAC1B,GAAG,EACH,MAAM,EACN,gBAAgB,EAChB,kBAAkB,EAClB,SAAS,EACT,KAAK,EACL,kBAAkB,EAClB,cAAc,EACd,YAAY,EACZ,WAAW,EACX,OAAO,EAAE,EAAE,QAAQ,EAAE,GAAG,OAAO,EAAE,GAalC;IACC,IAAI,QAAQ,GAAG,CAAC,EAAE;QAChB,OAAO,IAAI,qBAAW,CAAC;YACrB,GAAG;YACH,MAAM;YACN,gBAAgB;YAChB,kBAAkB;YAClB,SAAS;YACT,OAAO;YACP,KAAK;YACL,kBAAkB;YAClB,cAAc;YACd,YAAY;YACZ,WAAW;YACX,eAAe,EAAE,QAAQ;SAC1B,CAAC,CAAA;KACH;IACD,OAAO,IAAI,iBAAO,CAAC;QACjB,gBAAgB;QAChB,kBAAkB;QAClB,KAAK;QACL,SAAS;QACT,kBAAkB;QAClB,OAAO;KACR,CAAC,CAAA;AACJ,CAAC;AAjDD,kCAiDC","sourcesContent":["import { EventEmitter } from 'node:events'\nimport { IdGenerator } from '@cucumber/messages'\nimport Runtime, { IRuntime } from '../runtime'\nimport { EventDataCollector } from '../formatter/helpers'\nimport { SupportCodeLibrary } from '../support_code_library_builder/types'\nimport Coordinator from '../runtime/parallel/coordinator'\nimport { ILogger } from '../logger'\nimport { IRunOptionsRuntime } from './types'\n\nexport function makeRuntime({\n  cwd,\n  logger,\n  eventBroadcaster,\n  eventDataCollector,\n  pickleIds,\n  newId,\n  supportCodeLibrary,\n  requireModules,\n  requirePaths,\n  importPaths,\n  options: { parallel, ...options },\n}: {\n  cwd: string\n  logger: ILogger\n  eventBroadcaster: EventEmitter\n  eventDataCollector: EventDataCollector\n  newId: IdGenerator.NewId\n  pickleIds: string[]\n  supportCodeLibrary: SupportCodeLibrary\n  requireModules: string[]\n  requirePaths: string[]\n  importPaths: string[]\n  options: IRunOptionsRuntime\n}): IRuntime {\n  if (parallel > 0) {\n    return new Coordinator({\n      cwd,\n      logger,\n      eventBroadcaster,\n      eventDataCollector,\n      pickleIds,\n      options,\n      newId,\n      supportCodeLibrary,\n      requireModules,\n      requirePaths,\n      importPaths,\n      numberOfWorkers: parallel,\n    })\n  }\n  return new Runtime({\n    eventBroadcaster,\n    eventDataCollector,\n    newId,\n    pickleIds,\n    supportCodeLibrary,\n    options,\n  })\n}\n"]}

package/lib/api/support.d.ts

@@ -1,9 +1,9 @@
 import { IdGenerator } from '@cucumber/messages';
-import { ISupportCodeLibrary } from '../support_code_library_builder/types';
+import { SupportCodeLibrary } from '../support_code_library_builder/types';
 export declare function getSupportCodeLibrary({ cwd, newId, requireModules, requirePaths, importPaths, }: {
     cwd: string;
     newId: IdGenerator.NewId;
     requireModules: string[];
     requirePaths: string[];
     importPaths: string[];
-}): Promise<ISupportCodeLibrary>;
+}): Promise<SupportCodeLibrary>;

package/lib/api/support.js.map

@@ -1 +1 @@
-{"version":3,"file":"support.js","sourceRoot":"","sources":["../../src/api/support.ts"],"names":[],"mappings":";;;;;;AAAA,uCAAwC;AAGxC,mGAAuE;AACvE,iEAAuC;AAEhC,KAAK,UAAU,qBAAqB,CAAC,EAC1C,GAAG,EACH,KAAK,EACL,cAAc,EACd,YAAY,EACZ,WAAW,GAOZ;IACC,sCAAyB,CAAC,KAAK,CAAC,GAAG,EAAE,KAAK,EAAE;QAC1C,cAAc;QACd,YAAY;QACZ,WAAW;KACZ,CAAC,CAAA;IAEF,cAAc,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,IAAA,qBAAU,EAAC,MAAM,CAAC,CAAC,CAAA;IAClD,YAAY,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAA,qBAAU,EAAC,IAAI,CAAC,CAAC,CAAA;IAE5C,KAAK,MAAM,IAAI,IAAI,WAAW,EAAE;QAC9B,MAAM,MAAM,CAAC,IAAA,wBAAa,EAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAA;KAC7C;IAED,OAAO,sCAAyB,CAAC,QAAQ,EAAE,CAAA;AAC7C,CAAC;AA3BD,sDA2BC","sourcesContent":["import { pathToFileURL } from 'node:url'\nimport { IdGenerator } from '@cucumber/messages'\nimport { ISupportCodeLibrary } from '../support_code_library_builder/types'\nimport supportCodeLibraryBuilder from '../support_code_library_builder'\nimport tryRequire from '../try_require'\n\nexport async function getSupportCodeLibrary({\n  cwd,\n  newId,\n  requireModules,\n  requirePaths,\n  importPaths,\n}: {\n  cwd: string\n  newId: IdGenerator.NewId\n  requireModules: string[]\n  requirePaths: string[]\n  importPaths: string[]\n}): Promise<ISupportCodeLibrary> {\n  supportCodeLibraryBuilder.reset(cwd, newId, {\n    requireModules,\n    requirePaths,\n    importPaths,\n  })\n\n  requireModules.map((module) => tryRequire(module))\n  requirePaths.map((path) => tryRequire(path))\n\n  for (const path of importPaths) {\n    await import(pathToFileURL(path).toString())\n  }\n\n  return supportCodeLibraryBuilder.finalize()\n}\n"]}
+{"version":3,"file":"support.js","sourceRoot":"","sources":["../../src/api/support.ts"],"names":[],"mappings":";;;;;;AAAA,uCAAwC;AAGxC,mGAAuE;AACvE,iEAAuC;AAEhC,KAAK,UAAU,qBAAqB,CAAC,EAC1C,GAAG,EACH,KAAK,EACL,cAAc,EACd,YAAY,EACZ,WAAW,GAOZ;IACC,sCAAyB,CAAC,KAAK,CAAC,GAAG,EAAE,KAAK,EAAE;QAC1C,cAAc;QACd,YAAY;QACZ,WAAW;KACZ,CAAC,CAAA;IAEF,cAAc,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,IAAA,qBAAU,EAAC,MAAM,CAAC,CAAC,CAAA;IAClD,YAAY,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAA,qBAAU,EAAC,IAAI,CAAC,CAAC,CAAA;IAE5C,KAAK,MAAM,IAAI,IAAI,WAAW,EAAE;QAC9B,MAAM,MAAM,CAAC,IAAA,wBAAa,EAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAA;KAC7C;IAED,OAAO,sCAAyB,CAAC,QAAQ,EAAE,CAAA;AAC7C,CAAC;AA3BD,sDA2BC","sourcesContent":["import { pathToFileURL } from 'node:url'\nimport { IdGenerator } from '@cucumber/messages'\nimport { SupportCodeLibrary } from '../support_code_library_builder/types'\nimport supportCodeLibraryBuilder from '../support_code_library_builder'\nimport tryRequire from '../try_require'\n\nexport async function getSupportCodeLibrary({\n  cwd,\n  newId,\n  requireModules,\n  requirePaths,\n  importPaths,\n}: {\n  cwd: string\n  newId: IdGenerator.NewId\n  requireModules: string[]\n  requirePaths: string[]\n  importPaths: string[]\n}): Promise<SupportCodeLibrary> {\n  supportCodeLibraryBuilder.reset(cwd, newId, {\n    requireModules,\n    requirePaths,\n    importPaths,\n  })\n\n  requireModules.map((module) => tryRequire(module))\n  requirePaths.map((path) => tryRequire(path))\n\n  for (const path of importPaths) {\n    await import(pathToFileURL(path).toString())\n  }\n\n  return supportCodeLibraryBuilder.finalize()\n}\n"]}

package/lib/api/types.d.ts

@@ -1,55 +1,84 @@
 /// <reference types="node" />
 /// <reference types="node" />
 import { Writable } from 'node:stream';
-import { ISupportCodeLibrary } from '../support_code_library_builder/types';
-import { FormatOptions, IPublishConfig } from '../formatter';
-import { PickleOrder } from '../models/pickle_order';
-import { IRuntimeOptions } from '../runtime';
+import { JsonObject } from 'type-fest';
+import { IPublishConfig } from '../publish';
 import { IConfiguration } from '../configuration';
+import { IPickleOrder } from '../filter';
 /**
+ * Options for {@link loadConfiguration}
  * @public
  */
 export interface ILoadConfigurationOptions {
     /**
-     * Path to load configuration file from (defaults to `cucumber.(js|cjs|mjs|json)` if omitted).
+     * Path to load configuration file from, or `false` to skip
+     * @default `cucumber.(json|yaml|yml|js|cjs|mjs)`
      */
-    file?: string;
+    file?: string | false;
     /**
-     * Zero or more profile names from which to source configuration (if omitted or empty, the `default` profile will be used).
+     * Zero or more profile names from which to source configuration in the file
+     * @remarks
+     * If omitted or empty, the `default` profile will be used.
      */
     profiles?: string[];
     /**
-     * Ad-hoc configuration options to be applied over the top of whatever is loaded from the configuration file/profiles.
+     * Ad-hoc configuration options to be merged over the top of whatever is
+     * loaded from the configuration file/profiles
      */
     provided?: Partial<IConfiguration>;
 }
 /**
+ * Response from {@link loadConfiguration}
  * @public
  */
 export interface IResolvedConfiguration {
     /**
-     * The final flat configuration object resolved from the configuration file/profiles plus any extra provided.
+     * The final flat configuration object resolved from the configuration
+     * file/profiles plus any extra provided
      */
     useConfiguration: IConfiguration;
     /**
-     * The format that can be passed into `runCucumber`.
+     * The format that can be passed into {@link runCucumber}
      */
     runConfiguration: IRunConfiguration;
 }
 /**
+ * Options relating to sources (i.e. feature files) - where to load them from,
+ * how to interpret, filter and order them
  * @public
  */
 export interface ISourcesCoordinates {
+    /**
+     * Default Gherkin dialect
+     * @remarks
+     * Used if no dialect is specified in the feature file itself.
+     */
     defaultDialect: string;
+    /**
+     * Paths and/or glob expressions to feature files
+     */
     paths: string[];
+    /**
+     * Regular expressions of which scenario names should match one of to be run
+     */
     names: string[];
+    /**
+     * Tag expression to filter which scenarios should be run
+     */
     tagExpression: string;
-    order: PickleOrder;
+    /**
+     * Run in the order defined, or in a random order
+     */
+    order: IPickleOrder;
 }
 /**
+ * A pickle that has been successfully compiled from a source
  * @public
  */
 export interface IPlannedPickle {
+    /**
+     * Name of the pickle (after parameter resolution)
+     */
     name: string;
     uri: string;
     location: {
@@ -58,6 +87,7 @@ export interface IPlannedPickle {
     };
 }
 /**
+ * An error encountered when parsing a source
  * @public
  */
 export interface ISourcesError {
@@ -66,46 +96,133 @@ export interface ISourcesError {
         line: number;
         column?: number;
     };
+    /**
+     * Error message explaining what went wrong with the parse
+     */
     message: string;
 }
 /**
+ * Response from {@link loadSources}
  * @public
  */
 export interface ILoadSourcesResult {
+    /**
+     * Pickles that have been successfully compiled, in the order they would be
+     * run in
+     */
     plan: IPlannedPickle[];
+    /**
+     * Any errors encountered when parsing sources
+     */
     errors: ISourcesError[];
 }
 /**
+ * Options relating to user code (aka support code) - where to load it from and
+ * how to preprocess it
  * @public
  */
 export interface ISupportCodeCoordinates {
+    /**
+     * Names of transpilation modules to load, via `require()`
+     */
     requireModules: string[];
+    /**
+     * Paths and/or glob expressions of user code to load, via `require()`
+     */
     requirePaths: string[];
+    /**
+     * Paths and/or glob expressions of user code to load, via `import()`
+     */
     importPaths: string[];
 }
 /**
+ * Options for {@link loadSupport}
  * @public
+ * @remarks
+ * A subset of {@link IRunConfiguration}
  */
 export interface ILoadSupportOptions {
+    /**
+     * @remarks
+     * This is needed because the default support path locations are derived from
+     * feature file locations.
+     */
     sources: ISourcesCoordinates;
     support: ISupportCodeCoordinates;
 }
 /**
+ * Options relating to behaviour when actually running tests
  * @public
  */
-export interface IRunOptionsRuntime extends IRuntimeOptions {
+export interface IRunOptionsRuntime {
+    /**
+     * Perform a dry run, where a test run is prepared but nothing is executed
+     */
+    dryRun: boolean;
+    /**
+     * Stop running tests when a test fails
+     */
+    failFast: boolean;
+    /**
+     * Filter out stack frames from Cucumber's code when formatting stack traces
+     */
+    filterStacktraces: boolean;
+    /**
+     * Run tests in parallel with the given number of worker processes
+     */
     parallel: number;
+    /**
+     * Retry failing tests up to the given number of times
+     */
+    retry: number;
+    /**
+     * Tag expression to filter which scenarios can be retried
+     */
+    retryTagFilter: string;
+    /**
+     * Fail the test run if there are pending steps
+     */
+    strict: boolean;
+    /**
+     * Parameters to be passed to the World
+     * @remarks
+     * The value must be a JSON-serializable object.
+     */
+    worldParameters: JsonObject;
 }
 /**
+ * Options relating to formatters - which ones to use, where to write their
+ * output, how they should behave
  * @public
  */
 export interface IRunOptionsFormats {
+    /**
+     * Name/path of the formatter to use for `stdout` output
+     */
     stdout: string;
+    /**
+     * Zero or more mappings of file output path (key) to name/path of the
+     * formatter to use (value)
+     * @example
+     * \{
+     *   "./reports/cucumber.html": "html",
+     *   "./reports/custom.txt": "./custom-formatter.js"
+     * \}
+     */
     files: Record<string, string>;
+    /**
+     * Options for report publication, or `false` to disable publication
+     */
     publish: IPublishConfig | false;
-    options: FormatOptions;
+    /**
+     * Options to be provided to formatters
+     * @remarks
+     * The value must be a JSON-serializable object.
+     */
+    options: JsonObject;
 }
 /**
+ * Structured configuration object suitable for passing to {@link runCucumber}
  * @public
  */
 export interface IRunConfiguration {
@@ -115,14 +232,32 @@ export interface IRunConfiguration {
     formats: IRunOptionsFormats;
 }
 /**
+ * A collection of user-defined code and setup ("support code") that can be
+ * used for a test run
  * @public
+ * @remarks
+ * This is mostly a marker interface. The actual instance is a complex object
+ * that you shouldn't interact with directly, but some functions return and/or
+ * accept it as a means of optimising a test workflow.
  */
-export type ISupportCodeCoordinatesOrLibrary = ISupportCodeCoordinates | ISupportCodeLibrary;
+export interface ISupportCodeLibrary {
+    readonly originalCoordinates: ISupportCodeCoordinates;
+}
 /**
+ * Either an actual {@link ISupportCodeLibrary | support code library}, or the
+ * {@link ISupportCodeCoordinates | coordinates} required to create and
+ * populate one
  * @public
+ * @remarks
+ * This alias exists because {@link runCucumber} will accept an existing
+ * support code library in its options and thus avoid trying to load it again,
+ * improving performance and avoiding cache issues for use cases where multiple
+ * test runs happen within the same process. Note this is only useful in serial
+ * mode, as parallel workers will each load the support code themselves anyway.
  */
-export type { ISupportCodeLibrary };
+export type ISupportCodeCoordinatesOrLibrary = ISupportCodeCoordinates | ISupportCodeLibrary;
 /**
+ * Options for {@link runCucumber}
  * @public
  */
 export interface IRunOptions {
@@ -132,44 +267,53 @@ export interface IRunOptions {
     formats: IRunOptionsFormats;
 }
 /**
- * Contextual data about the project environment.
- *
+ * Contextual data about the project environment
  * @public
  */
 export interface IRunEnvironment {
     /**
-     * Working directory for the project (defaults to `process.cwd()` if omitted).
+     * Working directory for the project
+     * @default process.cwd()
      */
     cwd?: string;
     /**
-     * Writable stream where the test run's main output is written (defaults to `process.stdout` if omitted).
+     * Writable stream where the test run's main formatter output is written
+     * @default process.stdout
      */
     stdout?: Writable;
     /**
-     * Writable stream where the test run's warning/error output is written (defaults to `process.stderr` if omitted).
+     * Writable stream where the test run's warning/error output is written
+     * @default process.stderr
      */
     stderr?: Writable;
     /**
-     * Environment variables (defaults to `process.env` if omitted).
+     * Environment variables
+     * @default process.env
      */
     env?: NodeJS.ProcessEnv;
     /**
-     * Whether debug logging is enabled.
+     * Whether debug logging should be emitted to {@link IRunEnvironment.stderr}
+     * @default false
+     * @see {@link https://github.com/cucumber/cucumber-js/blob/main/docs/debugging.md}
      */
     debug?: boolean;
 }
 /**
- * Result of a Cucumber test run.
- *
+ * Response from {@link runCucumber}
  * @public
  */
 export interface IRunResult {
     /**
-     * Whether the test run was overall successful i.e. no failed scenarios. The exact meaning can vary based on the `strict` configuration option.
+     * Whether the test run was overall successful
+     * @remarks
+     * The exact meaning can vary based on the `strict` configuration option.
      */
     success: boolean;
     /**
-     * The support code library that was used in the test run; can be reused in subsequent `runCucumber` calls.
+     * The support code library that was used in the test run
+     * @remarks
+     * This can be reused in subsequent {@link runCucumber} calls,
+     * see {@link ISupportCodeCoordinatesOrLibrary}
      */
     support: ISupportCodeLibrary;
 }

package/lib/api/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/api/types.ts"],"names":[],"mappings":"","sourcesContent":["import { Writable } from 'node:stream'\nimport { ISupportCodeLibrary } from '../support_code_library_builder/types'\nimport { FormatOptions, IPublishConfig } from '../formatter'\nimport { PickleOrder } from '../models/pickle_order'\nimport { IRuntimeOptions } from '../runtime'\nimport { IConfiguration } from '../configuration'\n\n/**\n * @public\n */\nexport interface ILoadConfigurationOptions {\n  /**\n   * Path to load configuration file from (defaults to `cucumber.(js|cjs|mjs|json)` if omitted).\n   */\n  file?: string\n  /**\n   * Zero or more profile names from which to source configuration (if omitted or empty, the `default` profile will be used).\n   */\n  profiles?: string[]\n  /**\n   * Ad-hoc configuration options to be applied over the top of whatever is loaded from the configuration file/profiles.\n   */\n  provided?: Partial<IConfiguration>\n}\n\n/**\n * @public\n */\nexport interface IResolvedConfiguration {\n  /**\n   * The final flat configuration object resolved from the configuration file/profiles plus any extra provided.\n   */\n  useConfiguration: IConfiguration\n  /**\n   * The format that can be passed into `runCucumber`.\n   */\n  runConfiguration: IRunConfiguration\n}\n\n/**\n * @public\n */\nexport interface ISourcesCoordinates {\n  defaultDialect: string\n  paths: string[]\n  names: string[]\n  tagExpression: string\n  order: PickleOrder\n}\n\n/**\n * @public\n */\nexport interface IPlannedPickle {\n  name: string\n  uri: string\n  location: {\n    line: number\n    column?: number\n  }\n}\n\n/**\n * @public\n */\nexport interface ISourcesError {\n  uri: string\n  location: {\n    line: number\n    column?: number\n  }\n  message: string\n}\n\n/**\n * @public\n */\nexport interface ILoadSourcesResult {\n  plan: IPlannedPickle[]\n  errors: ISourcesError[]\n}\n\n/**\n * @public\n */\nexport interface ISupportCodeCoordinates {\n  requireModules: string[]\n  requirePaths: string[]\n  importPaths: string[]\n}\n\n/**\n * @public\n */\nexport interface ILoadSupportOptions {\n  sources: ISourcesCoordinates\n  support: ISupportCodeCoordinates\n}\n\n/**\n * @public\n */\nexport interface IRunOptionsRuntime extends IRuntimeOptions {\n  parallel: number\n}\n\n/**\n * @public\n */\nexport interface IRunOptionsFormats {\n  stdout: string\n  files: Record<string, string>\n  publish: IPublishConfig | false\n  options: FormatOptions\n}\n\n/**\n * @public\n */\nexport interface IRunConfiguration {\n  sources: ISourcesCoordinates\n  support: ISupportCodeCoordinates\n  runtime: IRunOptionsRuntime\n  formats: IRunOptionsFormats\n}\n\n/**\n * @public\n */\nexport type ISupportCodeCoordinatesOrLibrary =\n  | ISupportCodeCoordinates\n  | ISupportCodeLibrary\n\n/**\n * @public\n */\nexport type { ISupportCodeLibrary }\n\n/**\n * @public\n */\nexport interface IRunOptions {\n  sources: ISourcesCoordinates\n  support: ISupportCodeCoordinatesOrLibrary\n  runtime: IRunOptionsRuntime\n  formats: IRunOptionsFormats\n}\n\n/**\n * Contextual data about the project environment.\n *\n * @public\n */\nexport interface IRunEnvironment {\n  /**\n   * Working directory for the project (defaults to `process.cwd()` if omitted).\n   */\n  cwd?: string\n  /**\n   * Writable stream where the test run's main output is written (defaults to `process.stdout` if omitted).\n   */\n  stdout?: Writable\n  /**\n   * Writable stream where the test run's warning/error output is written (defaults to `process.stderr` if omitted).\n   */\n  stderr?: Writable\n  /**\n   * Environment variables (defaults to `process.env` if omitted).\n   */\n  env?: NodeJS.ProcessEnv\n  /**\n   * Whether debug logging is enabled.\n   */\n  debug?: boolean\n}\n\n/**\n * Result of a Cucumber test run.\n *\n * @public\n */\nexport interface IRunResult {\n  /**\n   * Whether the test run was overall successful i.e. no failed scenarios. The exact meaning can vary based on the `strict` configuration option.\n   */\n  success: boolean\n  /**\n   * The support code library that was used in the test run; can be reused in subsequent `runCucumber` calls.\n   */\n  support: ISupportCodeLibrary\n}\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/api/types.ts"],"names":[],"mappings":"","sourcesContent":["import { Writable } from 'node:stream'\nimport { JsonObject } from 'type-fest'\nimport { IPublishConfig } from '../publish'\nimport { IConfiguration } from '../configuration'\nimport { IPickleOrder } from '../filter'\n\n/**\n * Options for {@link loadConfiguration}\n * @public\n */\nexport interface ILoadConfigurationOptions {\n  /**\n   * Path to load configuration file from, or `false` to skip\n   * @default `cucumber.(json|yaml|yml|js|cjs|mjs)`\n   */\n  file?: string | false\n  /**\n   * Zero or more profile names from which to source configuration in the file\n   * @remarks\n   * If omitted or empty, the `default` profile will be used.\n   */\n  profiles?: string[]\n  /**\n   * Ad-hoc configuration options to be merged over the top of whatever is\n   * loaded from the configuration file/profiles\n   */\n  provided?: Partial<IConfiguration>\n}\n\n/**\n * Response from {@link loadConfiguration}\n * @public\n */\nexport interface IResolvedConfiguration {\n  /**\n   * The final flat configuration object resolved from the configuration\n   * file/profiles plus any extra provided\n   */\n  useConfiguration: IConfiguration\n  /**\n   * The format that can be passed into {@link runCucumber}\n   */\n  runConfiguration: IRunConfiguration\n}\n\n/**\n * Options relating to sources (i.e. feature files) - where to load them from,\n * how to interpret, filter and order them\n * @public\n */\nexport interface ISourcesCoordinates {\n  /**\n   * Default Gherkin dialect\n   * @remarks\n   * Used if no dialect is specified in the feature file itself.\n   */\n  defaultDialect: string\n  /**\n   * Paths and/or glob expressions to feature files\n   */\n  paths: string[]\n  /**\n   * Regular expressions of which scenario names should match one of to be run\n   */\n  names: string[]\n  /**\n   * Tag expression to filter which scenarios should be run\n   */\n  tagExpression: string\n  /**\n   * Run in the order defined, or in a random order\n   */\n  order: IPickleOrder\n}\n\n/**\n * A pickle that has been successfully compiled from a source\n * @public\n */\nexport interface IPlannedPickle {\n  /**\n   * Name of the pickle (after parameter resolution)\n   */\n  name: string\n  uri: string\n  location: {\n    line: number\n    column?: number\n  }\n}\n\n/**\n * An error encountered when parsing a source\n * @public\n */\nexport interface ISourcesError {\n  uri: string\n  location: {\n    line: number\n    column?: number\n  }\n  /**\n   * Error message explaining what went wrong with the parse\n   */\n  message: string\n}\n\n/**\n * Response from {@link loadSources}\n * @public\n */\nexport interface ILoadSourcesResult {\n  /**\n   * Pickles that have been successfully compiled, in the order they would be\n   * run in\n   */\n  plan: IPlannedPickle[]\n  /**\n   * Any errors encountered when parsing sources\n   */\n  errors: ISourcesError[]\n}\n\n/**\n * Options relating to user code (aka support code) - where to load it from and\n * how to preprocess it\n * @public\n */\nexport interface ISupportCodeCoordinates {\n  /**\n   * Names of transpilation modules to load, via `require()`\n   */\n  requireModules: string[]\n  /**\n   * Paths and/or glob expressions of user code to load, via `require()`\n   */\n  requirePaths: string[]\n  /**\n   * Paths and/or glob expressions of user code to load, via `import()`\n   */\n  importPaths: string[]\n}\n\n/**\n * Options for {@link loadSupport}\n * @public\n * @remarks\n * A subset of {@link IRunConfiguration}\n */\nexport interface ILoadSupportOptions {\n  /**\n   * @remarks\n   * This is needed because the default support path locations are derived from\n   * feature file locations.\n   */\n  sources: ISourcesCoordinates\n  support: ISupportCodeCoordinates\n}\n\n/**\n * Options relating to behaviour when actually running tests\n * @public\n */\nexport interface IRunOptionsRuntime {\n  /**\n   * Perform a dry run, where a test run is prepared but nothing is executed\n   */\n  dryRun: boolean\n  /**\n   * Stop running tests when a test fails\n   */\n  failFast: boolean\n  /**\n   * Filter out stack frames from Cucumber's code when formatting stack traces\n   */\n  filterStacktraces: boolean\n  /**\n   * Run tests in parallel with the given number of worker processes\n   */\n  parallel: number\n  /**\n   * Retry failing tests up to the given number of times\n   */\n  retry: number\n  /**\n   * Tag expression to filter which scenarios can be retried\n   */\n  retryTagFilter: string\n  /**\n   * Fail the test run if there are pending steps\n   */\n  strict: boolean\n  /**\n   * Parameters to be passed to the World\n   * @remarks\n   * The value must be a JSON-serializable object.\n   */\n  worldParameters: JsonObject\n}\n\n/**\n * Options relating to formatters - which ones to use, where to write their\n * output, how they should behave\n * @public\n */\nexport interface IRunOptionsFormats {\n  /**\n   * Name/path of the formatter to use for `stdout` output\n   */\n  stdout: string\n  /**\n   * Zero or more mappings of file output path (key) to name/path of the\n   * formatter to use (value)\n   * @example\n   * \\{\n   *   \"./reports/cucumber.html\": \"html\",\n   *   \"./reports/custom.txt\": \"./custom-formatter.js\"\n   * \\}\n   */\n  files: Record<string, string>\n  /**\n   * Options for report publication, or `false` to disable publication\n   */\n  publish: IPublishConfig | false\n  /**\n   * Options to be provided to formatters\n   * @remarks\n   * The value must be a JSON-serializable object.\n   */\n  options: JsonObject\n}\n\n/**\n * Structured configuration object suitable for passing to {@link runCucumber}\n * @public\n */\nexport interface IRunConfiguration {\n  sources: ISourcesCoordinates\n  support: ISupportCodeCoordinates\n  runtime: IRunOptionsRuntime\n  formats: IRunOptionsFormats\n}\n\n/**\n * A collection of user-defined code and setup (\"support code\") that can be\n * used for a test run\n * @public\n * @remarks\n * This is mostly a marker interface. The actual instance is a complex object\n * that you shouldn't interact with directly, but some functions return and/or\n * accept it as a means of optimising a test workflow.\n */\nexport interface ISupportCodeLibrary {\n  readonly originalCoordinates: ISupportCodeCoordinates\n}\n\n/**\n * Either an actual {@link ISupportCodeLibrary | support code library}, or the\n * {@link ISupportCodeCoordinates | coordinates} required to create and\n * populate one\n * @public\n * @remarks\n * This alias exists because {@link runCucumber} will accept an existing\n * support code library in its options and thus avoid trying to load it again,\n * improving performance and avoiding cache issues for use cases where multiple\n * test runs happen within the same process. Note this is only useful in serial\n * mode, as parallel workers will each load the support code themselves anyway.\n */\nexport type ISupportCodeCoordinatesOrLibrary =\n  | ISupportCodeCoordinates\n  | ISupportCodeLibrary\n\n/**\n * Options for {@link runCucumber}\n * @public\n */\nexport interface IRunOptions {\n  sources: ISourcesCoordinates\n  support: ISupportCodeCoordinatesOrLibrary\n  runtime: IRunOptionsRuntime\n  formats: IRunOptionsFormats\n}\n\n/**\n * Contextual data about the project environment\n * @public\n */\nexport interface IRunEnvironment {\n  /**\n   * Working directory for the project\n   * @default process.cwd()\n   */\n  cwd?: string\n  /**\n   * Writable stream where the test run's main formatter output is written\n   * @default process.stdout\n   */\n  stdout?: Writable\n  /**\n   * Writable stream where the test run's warning/error output is written\n   * @default process.stderr\n   */\n  stderr?: Writable\n  /**\n   * Environment variables\n   * @default process.env\n   */\n  env?: NodeJS.ProcessEnv\n  /**\n   * Whether debug logging should be emitted to {@link IRunEnvironment.stderr}\n   * @default false\n   * @see {@link https://github.com/cucumber/cucumber-js/blob/main/docs/debugging.md}\n   */\n  debug?: boolean\n}\n\n/**\n * Response from {@link runCucumber}\n * @public\n */\nexport interface IRunResult {\n  /**\n   * Whether the test run was overall successful\n   * @remarks\n   * The exact meaning can vary based on the `strict` configuration option.\n   */\n  success: boolean\n  /**\n   * The support code library that was used in the test run\n   * @remarks\n   * This can be reused in subsequent {@link runCucumber} calls,\n   * see {@link ISupportCodeCoordinatesOrLibrary}\n   */\n  support: ISupportCodeLibrary\n}\n"]}

package/lib/cli/helpers.d.ts

@@ -6,9 +6,9 @@ import { Readable } from 'node:stream';
 import { IdGenerator } from '@cucumber/messages';
 import { EventDataCollector } from '../formatter/helpers';
 import PickleFilter from '../pickle_filter';
-import { ISupportCodeLibrary } from '../support_code_library_builder/types';
-import { PickleOrder } from '../models/pickle_order';
+import { SupportCodeLibrary } from '../support_code_library_builder/types';
 import { ILogger } from '../logger';
+import { IPickleOrder } from '../filter';
 interface IParseGherkinMessageStreamRequest {
     cwd?: string;
     eventBroadcaster: EventEmitter;
@@ -27,11 +27,11 @@ interface IParseGherkinMessageStreamRequest {
  * @param pickleFilter
  */
 export declare function parseGherkinMessageStream({ eventBroadcaster, eventDataCollector, gherkinMessageStream, order, pickleFilter, }: IParseGherkinMessageStreamRequest): Promise<string[]>;
-export declare function orderPickles<T = string>(pickleIds: T[], order: PickleOrder, logger: ILogger): void;
+export declare function orderPickles<T = string>(pickleIds: T[], order: IPickleOrder, logger: ILogger): void;
 export declare function emitMetaMessage(eventBroadcaster: EventEmitter, env: NodeJS.ProcessEnv): Promise<void>;
 export declare function emitSupportCodeMessages({ eventBroadcaster, supportCodeLibrary, newId, }: {
     eventBroadcaster: EventEmitter;
-    supportCodeLibrary: ISupportCodeLibrary;
+    supportCodeLibrary: SupportCodeLibrary;
     newId: IdGenerator.NewId;
 }): void;
 export {};