reimplement publish functionality as a plugin

docs/plugins.md

@@ -0,0 +1,61 @@
+🚨 This functionality is a work in progress and not yet available in a released version of Cucumber. If you have any
+feedback about how plugins are going to work, please jump into the comments
+on <https://github.com/cucumber/cucumber-js/discussions/2091> 🚨
+
+- - -
+
+# Plugins
+
+You can extend Cucumber's functionality by writing plugins. They allow you to:
+
+- Listen to Cucumber's message stream
+- Hook into core behaviour and change things
+- Output extra information for the user
+
+The API is described below. Our own Publish functionality is [implemented as a plugin](../src/publish/publish_plugin.ts), which you might find useful as an example.
+
+## Writing a plugin
+
+A plugin in its simplest form is a function. It should be the default export of your plugin package. Here's the signature:
+
+```js
+export default async({
+  on,
+  logger,
+  configuration,
+  environment
+}) => {
+  // do stuff here
+}
+```
+
+### Lifecycle
+
+Your plugin is initialised early in Cucumber's lifecycle, just after we have resolved the configuration. You can do async setup work in your plugin function - Cucumber will await the promise.
+
+Your plugin is stopped after the test run finishes, just before Cucumber exits. If you need to do cleanup work, your plugin function can return a cleanup function - it will be executed (and awaited if it returns a promise) before Cucumber exits.
+
+A plugin function accepts a single argument which provides the context for your plugin. It has:
+
+- `on(event: string, handler: Function)` - function for registering handlers for events (see below for supported events) - you can call this as many times as you'd like
+- `logger` - a console instance that directs output to stderr (or other appropriate stream)
+- `configuration` - the final resolved configuration object being used for this execution of Cucumber
+- `environment` - details of the environment for this execution of Cucumber
+
+### Events
+
+These are the events for which you can register handlers:
+
+| Name      | Signature                     | Notes                                                                                                                                                                                                                                              |
+|-----------|-------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `message` | `(message: Envelope) => void` | Cucumber emits a message for all significant events over the course of a test run. These are most commonly consumed by formatters, but have other uses too. Note that you can do async work in this handler, but Cucumber won't await the promise. |
+
+
+
+
+
+
+
+
+
+

features/publish.feature

@@ -106,7 +106,7 @@ Feature: Publish reports
   @spawn
   Scenario: when results are not published due to an error raised by the server, the banner is displayed
     When I run cucumber-js with env `CUCUMBER_PUBLISH_TOKEN=keyboardcat`
-    Then it fails
+    Then it passes
     And the error output contains the text:
       """
       ┌─────────────────────┐

src/api/convert_configuration.ts

@@ -3,7 +3,7 @@ import {
   isTruthyString,
   OptionSplitter,
 } from '../configuration'
-import { IPublishConfig } from '../formatter/publish'
+import { IPublishConfig } from '../formatter'
 import { IRunConfiguration } from './types'
 
 export async function convertConfiguration(

src/api/formatters.ts

@@ -7,19 +7,12 @@ import { WriteStream as TtyWriteStream } from 'tty'
 import FormatterBuilder from '../formatter/builder'
 import fs from 'mz/fs'
 import path from 'path'
-import { DEFAULT_CUCUMBER_PUBLISH_URL } from '../formatter/publish'
-import HttpStream from '../formatter/http_stream'
-import { Writable } from 'stream'
-import { supportsColor } from 'supports-color'
 import { IRunOptionsFormats } from './types'
-import hasAnsi from 'has-ansi'
-import stripAnsi from 'strip-ansi'
 
 export async function initializeFormatters({
   env,
   cwd,
   stdout,
-  stderr,
   logger,
   onStreamError,
   eventBroadcaster,
@@ -83,38 +76,7 @@ export async function initializeFormatters({
     formatters.push(await initializeFormatter(stream, target, type))
   }
 
-  if (configuration.publish) {
-    const { url = DEFAULT_CUCUMBER_PUBLISH_URL, token } = configuration.publish
-    const headers: { [key: string]: string } = {}
-    if (token !== undefined) {
-      headers.Authorization = `Bearer ${token}`
-    }
-    const stream = new HttpStream(url, 'GET', headers)
-    const readerStream = new Writable({
-      objectMode: true,
-      write: function (responseBody: string, encoding, writeCallback) {
-        logger.error(sanitisePublishOutput(responseBody, stderr))
-        writeCallback()
-      },
-    })
-    stream.pipe(readerStream)
-    formatters.push(await initializeFormatter(stream, url, 'message'))
-  }
-
   return async function () {
     await Promise.all(formatters.map(async (f) => await f.finished()))
   }
 }
-
-/*
-This is because the Cucumber Reports service returns a pre-formatted console message
-including ANSI escapes, so if our stderr stream doesn't support those we need to
-strip them back out. Ideally we should get structured data from the service and
-compose the console message on this end.
- */
-function sanitisePublishOutput(raw: string, stderr: IFormatterStream) {
-  if (!supportsColor(stderr) && hasAnsi(raw)) {
-    return stripAnsi(raw)
-  }
-  return raw
-}

src/api/plugins.ts

@@ -0,0 +1,18 @@
+import { Plugin, PluginManager } from '../plugin'
+import publishPlugin from '../publish'
+import { IRunEnvironment, IRunOptions } from './types'
+
+const INTERNAL_PLUGINS: Record<string, Plugin> = {
+  publish: publishPlugin,
+}
+
+export async function initializePlugins(
+  logger: Console,
+  configuration: IRunOptions,
+  environment: IRunEnvironment
+): Promise<PluginManager> {
+  // eventually we'll load plugin packages here
+  const pluginManager = new PluginManager(Object.values(INTERNAL_PLUGINS))
+  await pluginManager.init(logger, configuration, environment)
+  return pluginManager
+}

src/api/run_cucumber.ts

@@ -10,6 +10,7 @@ import { getSupportCodeLibrary } from './support'
 import { Console } from 'console'
 import { mergeEnvironment } from './environment'
 import { getFilteredPicklesAndErrors } from './gherkin'
+import { initializePlugins } from './plugins'
 
 /**
  * Execute a Cucumber test run.
@@ -25,7 +26,7 @@ export async function runCucumber(
   onMessage?: (message: Envelope) => void
 ): Promise<IRunResult> {
   const { cwd, stdout, stderr, env } = mergeEnvironment(environment)
-  const logger = new Console(stdout, stderr)
+  const logger = new Console(stderr)
   const newId = IdGenerator.uuid()
 
   const supportCoordinates =
@@ -47,14 +48,17 @@ export async function runCucumber(
           requireModules: supportCoordinates.requireModules,
         })
 
+  const plugins = await initializePlugins(logger, configuration, environment)
+
   const eventBroadcaster = new EventEmitter()
   if (onMessage) {
     eventBroadcaster.on('envelope', onMessage)
   }
+  eventBroadcaster.on('envelope', (value) => plugins.emit('message', value))
   const eventDataCollector = new EventDataCollector(eventBroadcaster)
 
   let formatterStreamError = false
-  const cleanup = await initializeFormatters({
+  const cleanupFormatters = await initializeFormatters({
     env,
     cwd,
     stdout,
@@ -89,7 +93,8 @@ export async function runCucumber(
         `Parse error in "${parseError.source.uri}" ${parseError.message}`
       )
     })
-    await cleanup()
+    await cleanupFormatters()
+    await plugins.cleanup()
     return {
       success: false,
       support: supportCodeLibrary,
@@ -116,7 +121,8 @@ export async function runCucumber(
     options: configuration.runtime,
   })
   const success = await runtime.start()
-  await cleanup()
+  await cleanupFormatters()
+  await plugins.cleanup()
 
   return {
     success: success && !formatterStreamError,

src/api/types.ts

@@ -1,9 +1,9 @@
 import { ISupportCodeLibrary } from '../support_code_library_builder/types'
-import { FormatOptions, IFormatterStream } from '../formatter'
+import { FormatOptions, IPublishConfig } from '../formatter'
 import { PickleOrder } from '../models/pickle_order'
 import { IRuntimeOptions } from '../runtime'
 import { IConfiguration } from '../configuration'
-import { IPublishConfig } from '../formatter/publish'
+import { Writable } from 'stream'
 
 /**
  * @public
@@ -154,11 +154,11 @@ export interface IRunEnvironment {
   /**
    * Writable stream where the test run's main output is written (defaults to `process.stdout` if omitted).
    */
-  stdout?: IFormatterStream
+  stdout?: Writable
   /**
    * Writable stream where the test run's warning/error output is written (defaults to `process.stderr` if omitted).
    */
-  stderr?: IFormatterStream
+  stderr?: Writable
   /**
    * Environment variables (defaults to `process.env` if omitted).
    */

src/formatter/index.ts

@@ -1,12 +1,9 @@
 import { IColorFns } from './get_color_fns'
 import { EventDataCollector } from './helpers'
 import StepDefinitionSnippetBuilder from './step_definition_snippet_builder'
-import { PassThrough, Writable as WritableStream } from 'stream'
+import { Writable } from 'stream'
 import { ISupportCodeLibrary } from '../support_code_library_builder/types'
-import { WriteStream as FsWriteStream } from 'fs'
-import { WriteStream as TtyWriteStream } from 'tty'
 import { EventEmitter } from 'events'
-import HttpStream from './http_stream'
 import { valueOrDefault } from '../value_checker'
 import { SnippetInterface } from './step_definition_snippet_builder/snippet_syntax'
 
@@ -23,11 +20,12 @@ export interface FormatOptions {
   [customKey: string]: any
 }
 
-export type IFormatterStream =
-  | FsWriteStream
-  | TtyWriteStream
-  | PassThrough
-  | HttpStream
+export interface IPublishConfig {
+  url: string
+  token: string
+}
+
+export type IFormatterStream = Writable
 export type IFormatterLogFn = (buffer: string | Uint8Array) => void
 export type IFormatterCleanupFn = () => Promise<any>
 
@@ -39,7 +37,7 @@ export interface IFormatterOptions {
   log: IFormatterLogFn
   parsedArgvOptions: FormatOptions
   snippetBuilder: StepDefinitionSnippetBuilder
-  stream: WritableStream
+  stream: Writable
   cleanup: IFormatterCleanupFn
   supportCodeLibrary: ISupportCodeLibrary
 }
@@ -50,7 +48,7 @@ export default class Formatter {
   protected eventDataCollector: EventDataCollector
   protected log: IFormatterLogFn
   protected snippetBuilder: StepDefinitionSnippetBuilder
-  protected stream: WritableStream
+  protected stream: Writable
   protected supportCodeLibrary: ISupportCodeLibrary
   protected printAttachments: boolean
   private readonly cleanup: IFormatterCleanupFn

src/plugin/index.ts

@@ -0,0 +1,2 @@
+export * from './types'
+export * from './plugin_manager'

src/plugin/plugin_manager.ts

@@ -0,0 +1,48 @@
+import { Plugin, PluginCleanup, PluginEvents } from './types'
+import { IRunEnvironment, IRunOptions } from '../api'
+
+type HandlerRegistry = {
+  [K in keyof PluginEvents]: Array<(value: PluginEvents[K]) => void>
+}
+
+export class PluginManager {
+  private handlers: HandlerRegistry = { message: [] }
+  private cleanupFns: PluginCleanup[] = []
+
+  constructor(private pluginFns: Plugin[]) {}
+
+  private async register<K extends keyof PluginEvents>(
+    event: K,
+    handler: (value: PluginEvents[K]) => void
+  ) {
+    this.handlers[event].push(handler)
+  }
+
+  async init(
+    logger: Console,
+    configuration: IRunOptions,
+    environment: IRunEnvironment
+  ) {
+    for (const pluginFn of this.pluginFns) {
+      const cleanupFn = await pluginFn({
+        on: this.register.bind(this),
+        logger,
+        configuration,
+        environment,
+      })
+      if (cleanupFn) {
+        this.cleanupFns.push(cleanupFn)
+      }
+    }
+  }
+
+  emit<K extends keyof PluginEvents>(event: K, value: PluginEvents[K]): void {
+    this.handlers[event].forEach((handler) => handler(value))
+  }
+
+  async cleanup(): Promise<void> {
+    for (const cleanupFn of this.cleanupFns) {
+      await cleanupFn()
+    }
+  }
+}

src/plugin/types.ts

@@ -0,0 +1,20 @@
+import { IRunEnvironment, IRunOptions } from '../api'
+import { Envelope } from '@cucumber/messages'
+
+export interface PluginEvents {
+  message: Envelope
+}
+
+export interface PluginContext {
+  on: <K extends keyof PluginEvents>(
+    event: K,
+    handler: (value: PluginEvents[K]) => void
+  ) => void
+  logger: Console
+  configuration: IRunOptions
+  environment: IRunEnvironment
+}
+
+export type PluginCleanup = () => any | void | Promise<any | void>
+
+export type Plugin = (context: PluginContext) => Promise<PluginCleanup | void>

src/publish/index.ts

@@ -0,0 +1,3 @@
+import { publishPlugin } from './publish_plugin'
+
+export default publishPlugin