Rework internals around environment and logging (#2460)

exports/api/report.api.md

@@ -101,7 +101,7 @@ export interface IRunConfiguration {
 export interface IRunEnvironment {
     cwd?: string;
     debug?: boolean;
-    env?: NodeJS.ProcessEnv;
+    env?: Record<string, string | undefined>;
     stderr?: Writable;
     stdout?: Writable;
 }

src/api/convert_configuration.ts

@@ -4,7 +4,7 @@ import {
   splitFormatDescriptor,
 } from '../configuration'
 import { IPublishConfig } from '../publish'
-import { ILogger } from '../logger'
+import { ILogger } from '../environment'
 import { IRunConfiguration } from './types'
 
 export async function convertConfiguration(

src/api/formatters.ts

@@ -5,7 +5,7 @@ import { IFormatterStream } from '../formatter'
 import { EventDataCollector } from '../formatter/helpers'
 import { SupportCodeLibrary } from '../support_code_library_builder/types'
 import FormatterBuilder from '../formatter/builder'
-import { ILogger } from '../logger'
+import { ILogger } from '../environment'
 import { createStream } from '../formatter/create_stream'
 import { resolveImplementation } from '../formatter/resolve_implementation'
 import { PluginManager } from '../plugin'
@@ -74,7 +74,6 @@ export async function initializeFormatters({
       await pluginManager.initFormatter(
         implementation,
         configuration.options,
-        logger,
         stream.write.bind(stream),
         directory
       )

src/api/index.ts

@@ -8,6 +8,7 @@
  */
 
 export { IConfiguration } from '../configuration'
+export { IRunEnvironment } from '../environment'
 export { IPickleOrder } from '../filter'
 export { IPublishConfig } from '../publish'
 export * from './load_configuration'

src/api/load_configuration.ts

@@ -6,13 +6,9 @@ import {
   parseConfiguration,
   validateConfiguration,
 } from '../configuration'
+import { IRunEnvironment, makeEnvironment } from '../environment'
 import { convertConfiguration } from './convert_configuration'
-import { mergeEnvironment } from './environment'
-import {
-  IRunEnvironment,
-  IResolvedConfiguration,
-  ILoadConfigurationOptions,
-} from './types'
+import { IResolvedConfiguration, ILoadConfigurationOptions } from './types'
 
 /**
  * Load user-authored configuration to be used in a test run
@@ -25,7 +21,7 @@ export async function loadConfiguration(
   options: ILoadConfigurationOptions = {},
   environment: IRunEnvironment = {}
 ): Promise<IResolvedConfiguration> {
-  const { cwd, env, logger } = mergeEnvironment(environment)
+  const { cwd, env, logger } = makeEnvironment(environment)
   const configFile = options.file ?? locateFile(cwd)
   if (configFile) {
     logger.debug(`Configuration will be loaded from "${configFile}"`)

src/api/load_configuration_spec.ts

@@ -1,5 +1,5 @@
 import { expect } from 'chai'
-import { IRunEnvironment } from './types'
+import { IRunEnvironment } from '../environment'
 import { setupEnvironment, teardownEnvironment } from './test_helpers'
 import { loadConfiguration } from './load_configuration'
 

src/api/load_sources.ts

@@ -1,13 +1,12 @@
 import { IdGenerator } from '@cucumber/messages'
 import { resolvePaths } from '../paths'
+import { IRunEnvironment, makeEnvironment } from '../environment'
 import {
   ILoadSourcesResult,
   IPlannedPickle,
-  IRunEnvironment,
   ISourcesCoordinates,
   ISourcesError,
 } from './types'
-import { mergeEnvironment } from './environment'
 import { getPicklesAndErrors } from './gherkin'
 import { initializeForLoadSources } from './plugins'
 
@@ -23,11 +22,10 @@ export async function loadSources(
   coordinates: ISourcesCoordinates,
   environment: IRunEnvironment = {}
 ): Promise<ILoadSourcesResult> {
-  const mergedEnvironment = mergeEnvironment(environment)
+  const mergedEnvironment = makeEnvironment(environment)
   const { cwd, logger } = mergedEnvironment
   const newId = IdGenerator.uuid()
   const pluginManager = await initializeForLoadSources(
-    logger,
     coordinates,
     mergedEnvironment
   )

src/api/load_sources_spec.ts

@@ -3,7 +3,7 @@ import { PassThrough } from 'node:stream'
 import { expect } from 'chai'
 import fs from 'mz/fs'
 import { IdGenerator } from '@cucumber/messages'
-import { IRunEnvironment } from './types'
+import { IRunEnvironment } from '../environment'
 import { loadSources } from './load_sources'
 
 const newId = IdGenerator.uuid()

src/api/load_support.ts

@@ -1,12 +1,8 @@
 import { IdGenerator } from '@cucumber/messages'
 import { resolvePaths } from '../paths'
-import {
-  ILoadSupportOptions,
-  IRunEnvironment,
-  ISupportCodeLibrary,
-} from './types'
+import { IRunEnvironment, makeEnvironment } from '../environment'
+import { ILoadSupportOptions, ISupportCodeLibrary } from './types'
 import { getSupportCodeLibrary } from './support'
-import { mergeEnvironment } from './environment'
 import { initializeForLoadSupport } from './plugins'
 
 /**
@@ -20,7 +16,7 @@ export async function loadSupport(
   options: ILoadSupportOptions,
   environment: IRunEnvironment = {}
 ): Promise<ISupportCodeLibrary> {
-  const mergedEnvironment = mergeEnvironment(environment)
+  const mergedEnvironment = makeEnvironment(environment)
   const { cwd, logger } = mergedEnvironment
   const newId = IdGenerator.uuid()
   const supportCoordinates = Object.assign(
@@ -32,7 +28,7 @@ export async function loadSupport(
     },
     options.support
   )
-  const pluginManager = await initializeForLoadSupport()
+  const pluginManager = await initializeForLoadSupport(mergedEnvironment)
   const resolvedPaths = await resolvePaths(
     logger,
     cwd,

src/api/load_support_spec.ts

@@ -1,6 +1,6 @@
 import path from 'node:path'
 import { expect } from 'chai'
-import { IRunEnvironment } from './types'
+import { IRunEnvironment } from '../environment'
 import { loadSupport } from './load_support'
 import { loadConfiguration } from './load_configuration'
 import { setupEnvironment, teardownEnvironment } from './test_helpers'

src/api/plugins.ts

@@ -1,55 +1,41 @@
 import { PluginManager } from '../plugin'
 import publishPlugin from '../publish'
-import { ILogger } from '../logger'
 import filterPlugin from '../filter'
-import {
-  IRunConfiguration,
-  IRunEnvironment,
-  ISourcesCoordinates,
-} from './types'
+import { UsableEnvironment } from '../environment'
+import { IRunConfiguration, ISourcesCoordinates } from './types'
 
 export async function initializeForLoadSources(
-  logger: ILogger,
   coordinates: ISourcesCoordinates,
-  environment: Required<IRunEnvironment>
+  environment: UsableEnvironment
 ): Promise<PluginManager> {
   // eventually we'll load plugin packages here
-  const pluginManager = new PluginManager()
-  await pluginManager.initCoordinator(
-    'loadSources',
-    filterPlugin,
-    coordinates,
-    logger,
-    environment
-  )
+  const pluginManager = new PluginManager(environment)
+  await pluginManager.initCoordinator('loadSources', filterPlugin, coordinates)
   return pluginManager
 }
 
-export async function initializeForLoadSupport(): Promise<PluginManager> {
+export async function initializeForLoadSupport(
+  environment: UsableEnvironment
+): Promise<PluginManager> {
   // eventually we'll load plugin packages here
-  return new PluginManager()
+  return new PluginManager(environment)
 }
 
 export async function initializeForRunCucumber(
-  logger: ILogger,
   configuration: IRunConfiguration,
-  environment: Required<IRunEnvironment>
+  environment: UsableEnvironment
 ): Promise<PluginManager> {
   // eventually we'll load plugin packages here
-  const pluginManager = new PluginManager()
+  const pluginManager = new PluginManager(environment)
   await pluginManager.initCoordinator(
     'runCucumber',
     publishPlugin,
-    configuration.formats.publish,
-    logger,
-    environment
+    configuration.formats.publish
   )
   await pluginManager.initCoordinator(
     'runCucumber',
     filterPlugin,
-    configuration.sources,
-    logger,
-    environment
+    configuration.sources
   )
   return pluginManager
 }

src/api/run_cucumber.ts

@@ -7,10 +7,10 @@ import { SupportCodeLibrary } from '../support_code_library_builder/types'
 import { version } from '../version'
 import { IFilterablePickle } from '../filter'
 import { makeRuntime } from '../runtime'
-import { IRunOptions, IRunEnvironment, IRunResult } from './types'
+import { IRunEnvironment, makeEnvironment } from '../environment'
+import { IRunOptions, IRunResult } from './types'
 import { initializeFormatters } from './formatters'
 import { getSupportCodeLibrary } from './support'
-import { mergeEnvironment } from './environment'
 import { getPicklesAndErrors } from './gherkin'
 import { initializeForRunCucumber } from './plugins'
 
@@ -27,7 +27,7 @@ export async function runCucumber(
   environment: IRunEnvironment = {},
   onMessage?: (message: Envelope) => void
 ): Promise<IRunResult> {
-  const mergedEnvironment = mergeEnvironment(environment)
+  const mergedEnvironment = makeEnvironment(environment)
   const { cwd, stdout, stderr, env, logger } = mergedEnvironment
 
   logger.debug(`Running cucumber-js ${version} 
@@ -51,7 +51,6 @@ Running from: ${__dirname}
         )
 
   const pluginManager = await initializeForRunCucumber(
-    logger,
     {
       ...options,
       support: supportCoordinates,

src/api/run_cucumber_spec.ts

@@ -1,7 +1,7 @@
 import { Envelope, TestStepResultStatus } from '@cucumber/messages'
 import { expect } from 'chai'
+import { IRunEnvironment } from '../environment'
 import { runCucumber } from './run_cucumber'
-import { IRunEnvironment } from './types'
 import { loadSupport } from './load_support'
 import { loadConfiguration } from './load_configuration'
 import { setupEnvironment, teardownEnvironment } from './test_helpers'

src/api/support.ts

@@ -4,7 +4,7 @@ import { IdGenerator } from '@cucumber/messages'
 import { SupportCodeLibrary } from '../support_code_library_builder/types'
 import supportCodeLibraryBuilder from '../support_code_library_builder'
 import tryRequire from '../try_require'
-import { ILogger } from '../logger'
+import { ILogger } from '../environment'
 
 export async function getSupportCodeLibrary({
   logger,

src/api/test_helpers.ts

@@ -3,7 +3,7 @@ import { PassThrough } from 'node:stream'
 import fs from 'mz/fs'
 import { reindent } from 'reindent-template-literals'
 import { IdGenerator } from '@cucumber/messages'
-import { IRunEnvironment } from './types'
+import { IRunEnvironment } from '../environment'
 
 const newId = IdGenerator.uuid()
 

src/api/types.ts

@@ -1,4 +1,3 @@
-import { Writable } from 'node:stream'
 import { JsonObject } from 'type-fest'
 import { IPublishConfig } from '../publish'
 import { IConfiguration } from '../configuration'
@@ -295,39 +294,6 @@ export interface IRunOptions {
   formats: IRunOptionsFormats
 }
 
-/**
- * Contextual data about the project environment
- * @public
- */
-export interface IRunEnvironment {
-  /**
-   * Working directory for the project
-   * @default process.cwd()
-   */
-  cwd?: string
-  /**
-   * 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
-   * @default process.stderr
-   */
-  stderr?: Writable
-  /**
-   * Environment variables
-   * @default process.env
-   */
-  env?: NodeJS.ProcessEnv
-  /**
-   * 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
-}
-
 /**
  * Response from {@link runCucumber}
  * @public

src/cli/helpers.ts

@@ -8,7 +8,7 @@ import { SupportCodeLibrary } from '../support_code_library_builder/types'
 import TestCaseHookDefinition from '../models/test_case_hook_definition'
 import TestRunHookDefinition from '../models/test_run_hook_definition'
 import { version } from '../version'
-import { ILogger } from '../logger'
+import { ILogger } from '../environment'
 import { ILineAndUri } from '../types'
 import { IPickleOrder } from '../filter'
 

src/configuration/from_file.ts

@@ -4,7 +4,7 @@ import { promisify } from 'node:util'
 import { pathToFileURL } from 'node:url'
 import YAML from 'yaml'
 import readPkgUp from 'read-pkg-up'
-import { ILogger } from '../logger'
+import { ILogger } from '../environment'
 import { IConfiguration } from './types'
 import { mergeConfigurations } from './merge_configurations'
 import { parseConfiguration } from './parse_configuration'

src/configuration/parse_configuration.ts

@@ -1,5 +1,5 @@
 import stringArgv from 'string-argv'
-import { ILogger } from '../logger'
+import { ILogger } from '../environment'
 import { IConfiguration } from './types'
 import ArgvParser from './argv_parser'
 import { checkSchema } from './check_schema'

src/configuration/split_format_descriptor.ts

@@ -1,4 +1,4 @@
-import { ILogger } from '../logger'
+import { ILogger } from '../environment'
 
 export function splitFormatDescriptor(
   logger: ILogger,

src/configuration/validate_configuration.ts

@@ -1,4 +1,4 @@
-import { ILogger } from '../logger'
+import { ILogger } from '../environment'
 import { IConfiguration } from './types'
 
 export function validateConfiguration(