Add World customisation and injection as this (#47)

Author: davidjgoss

CHANGELOG.md

@@ -6,6 +6,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+### Added
+- Add World customisation and injection as `this` ([#47](https://github.com/cucumber/cucumber-node/pull/47))
 
 ## [0.3.0] - 2025-02-28
 ### Added

README.md

@@ -161,7 +161,6 @@ There are some pretty standard Cucumber features that are missing (but not for l
 - [Filtering by tag expression](https://github.com/cucumber/cucumber-node/issues/9)
 - [BeforeAll/AfterAll hooks](https://github.com/cucumber/cucumber-node/issues/8)
 - [Regular expression steps](https://github.com/cucumber/cucumber-node/issues/6)
-- [Customise World creation and type](https://github.com/cucumber/cucumber-node/issues/7)
 - [Snippets](https://github.com/cucumber/cucumber-node/issues/36)
 
 ## What's different?
@@ -174,6 +173,6 @@ Some behaviour of cucumber-node is different - and better - than in cucumber-js:
 
 ### Arrow functions
 
-There's no reliance on `this` in your step and hook functions to access state, since we pass a context object as the first argument to all functions. This means you're free to use arrow functions as you normally would in JavaScript.
+There's no reliance on `this` in your step and hook functions to access state, since we pass a context object as the first argument to those functions. This means you're free to use arrow functions as you normally would in JavaScript.
 
 

cucumber-node.api.md

@@ -39,7 +39,7 @@ export class DataTable {
 export function Given(text: string, fn: StepFunction): void;
 
 // @public
-export type HookFunction = (context: TestCaseContext) => Promisable<void>;
+export type HookFunction = (this: World, context: TestCaseContext) => Promisable<void>;
 
 // @public
 export type HookOptions = {
@@ -54,13 +54,13 @@ export function ParameterType(options: ParameterTypeOptions): void;
 export type ParameterTypeOptions = {
     name: string;
     regexp: RegExp | string | readonly RegExp[] | readonly string[];
-    transformer?: (...match: string[]) => unknown;
+    transformer?: (this: World, ...match: string[]) => unknown;
     useForSnippets?: boolean;
     preferForRegexpMatch?: boolean;
 };
 
 // @public
-export type StepFunction = (context: TestCaseContext, ...args: any) => Promisable<void>;
+export type StepFunction = (this: World, context: TestCaseContext, ...args: any) => Promisable<void>;
 
 // @public
 export type TestCaseContext = {
@@ -71,7 +71,7 @@ export type TestCaseContext = {
     attach(data: Readable | Buffer | string, options: AttachmentOptions): Promise<void>;
     log(text: string): Promise<void>;
     link(url: string, title?: string): Promise<void>;
-    world: any;
+    world: World;
 };
 
 // @public
@@ -80,6 +80,12 @@ export function Then(text: string, fn: StepFunction): void;
 // @public
 export function When(text: string, fn: StepFunction): void;
 
+// @public
+export type World = any;
+
+// @public
+export function WorldCreator(creator: () => Promisable<World>, destroyer?: (world: World) => Promisable<void>): void;
+
 // (No @packageDocumentation comment for this package)
 
 ```

src/core/SupportCodeBuilder.spec.ts

@@ -7,7 +7,7 @@ describe('SupportCodeBuilder', () => {
     const builder = new SupportCodeBuilder(() => crypto.randomUUID())
     builder.registerStep('a {thing} happens', () => {}, {})
 
-    const library = builder.build()
+    const library = builder.toLibrary()
 
     expect(library.toEnvelopes().find((envelope) => envelope.undefinedParameterType)).to.deep.eq({
       undefinedParameterType: {
@@ -22,6 +22,6 @@ describe('SupportCodeBuilder', () => {
     // @ts-expect-error passing incorrect type to yield an error
     builder.registerStep(null, () => {}, {})
 
-    expect(() => builder.build()).to.throw()
+    expect(() => builder.toLibrary()).to.throw()
   })
 })

src/core/SupportCodeBuilder.ts

@@ -179,7 +179,7 @@ export class SupportCodeBuilder {
     })
   }
 
-  build(): SupportCodeLibrary {
+  toLibrary(): SupportCodeLibrary {
     return new SupportCodeLibrary(
       this.buildParameterTypes(),
       this.buildSteps(),

src/core/makeTestPlan.ts

@@ -28,7 +28,7 @@ export interface AssembledStep {
   id: string
   name: string
   always: boolean
-  prepare(): Runnable
+  prepare(thisArg?: unknown): Runnable
   toMessage(): TestStep
 }
 
@@ -72,9 +72,9 @@ function fromBeforeHooks(
       id: newId(),
       name: def.name ?? '',
       always: false,
-      prepare() {
+      prepare(thisArg) {
         return {
-          fn: def.fn,
+          fn: def.fn.bind(thisArg),
           args: [],
         }
       },
@@ -101,9 +101,9 @@ function fromAfterHooks(
         id: newId(),
         name: def.name ?? '',
         always: true,
-        prepare() {
+        prepare(thisArg) {
           return {
-            fn: def.fn,
+            fn: def.fn.bind(thisArg),
             args: [],
           }
         },
@@ -128,7 +128,7 @@ function fromPickleSteps(
       id: newId(),
       name: pickleStep.text,
       always: false,
-      prepare() {
+      prepare(thisArg) {
         if (matched.length < 1) {
           throw new UndefinedError(pickleStep.text)
         } else if (matched.length > 1) {
@@ -139,7 +139,7 @@ function fromPickleSteps(
         } else {
           const { def, args } = matched[0]
           // eslint-disable-next-line @typescript-eslint/no-explicit-any
-          const allArgs: Array<any> = args.map((arg) => arg.getValue(undefined))
+          const allArgs: Array<any> = args.map((arg) => arg.getValue(thisArg))
           if (pickleStep.argument?.docString) {
             allArgs.push(pickleStep.argument.docString.content)
           } else if (pickleStep.argument?.dataTable) {
@@ -152,7 +152,7 @@ function fromPickleSteps(
             )
           }
           return {
-            fn: def.fn,
+            fn: def.fn.bind(thisArg),
             args: allArgs,
           }
         }

src/index.ts

@@ -1,10 +1,35 @@
+import { Promisable } from 'type-fest'
+
 import { makeSourceReference } from './makeSourceReference.js'
 import { builder } from './runner/state.js'
-import { HookFunction, HookOptions, ParameterTypeOptions, StepFunction } from './types.js'
+import { HookFunction, HookOptions, ParameterTypeOptions, StepFunction, World } from './types.js'
 
 export * from './core/DataTable.js'
 export * from './types.js'
 
+/**
+ * Define a custom world creator and (optional) destroyer. These will be use to create and
+ * destroy each World instance. Both functions can either return a value, or promise that resolves
+ * to a value.
+ * @public
+ * @param creator - A function that creates and returns a custom World object
+ * @param destroyer - An optional function to clean up the World object after each test case
+ * @example CustomWorld(async () => \{
+ *   return \{ myCustomProperty: 'value' \}
+ * \}, async (world) => \{
+ *   // cleanup resources
+ * \})
+ */
+export function WorldCreator(
+  creator: () => Promisable<World>,
+  destroyer?: (world: World) => Promisable<void>
+) {
+  builder.registerWorldCreator(creator)
+  if (destroyer) {
+    builder.registerWorldDestroyer(destroyer)
+  }
+}
+
 /**
  * Define a custom parameter type for use in steps.
  * @public

src/runner/ContextTracker.ts

@@ -2,15 +2,15 @@ import { TestContext } from 'node:test'
 
 import { Envelope } from '@cucumber/messages'
 
-import { TestCaseContext } from '../types.js'
+import { TestCaseContext, World } from '../types.js'
 import { makeAttachment, makeLink, makeLog } from './makeAttachment.js'
 
 export class ContextTracker {
   outcomeKnown = false
 
   constructor(
     private readonly testCaseStartedId: string,
-    private readonly world: any, // eslint-disable-line @typescript-eslint/no-explicit-any
+    private readonly world: World,
     private readonly onMessage: (envelope: Envelope) => void
   ) {}
 

src/runner/ExtendedSupportCodeBuilder.ts

@@ -0,0 +1,27 @@
+import { Promisable } from 'type-fest'
+
+import { SupportCodeBuilder } from '../core/SupportCodeBuilder.js'
+import { makeId } from '../makeId.js'
+import { World } from '../types.js'
+import { WorldFactory } from './WorldFactory.js'
+
+export class ExtendedSupportCodeBuilder extends SupportCodeBuilder {
+  private worldCreator: () => Promisable<World> = () => ({})
+  private worldDestroyer: (world: World) => Promisable<void> = () => {}
+
+  constructor() {
+    super(makeId)
+  }
+
+  registerWorldCreator(creator: () => Promisable<World>) {
+    this.worldCreator = creator
+  }
+
+  registerWorldDestroyer(destroyer: (world: World) => Promisable<void>) {
+    this.worldDestroyer = destroyer
+  }
+
+  toWorldFactory() {
+    return new WorldFactory(this.worldCreator, this.worldDestroyer)
+  }
+}

src/runner/WorldFactory.ts

@@ -0,0 +1,18 @@
+import { Promisable } from 'type-fest'
+
+import { World } from '../types.js'
+
+export class WorldFactory {
+  constructor(
+    private readonly creator: () => Promisable<World>,
+    private readonly destroyer: (world: World) => Promisable<void>
+  ) {}
+
+  async create(): Promise<World> {
+    return this.creator()
+  }
+
+  async destroy(world: World): Promise<void> {
+    await this.destroyer(world)
+  }
+}

src/runner/index.ts

@@ -21,7 +21,7 @@ export function run({ source, gherkinDocument, pickles }: CompiledGherkin) {
     messages.push({ gherkinDocument })
     messages.push(...pickles.map((pickle) => ({ pickle })))
 
-    const library = await loadSupport()
+    const { library, worldFactory } = await loadSupport()
     messages.push(...library.toEnvelopes())
 
     const plan = makeTestPlan(makeId, pickles, library)
@@ -41,7 +41,7 @@ export function run({ source, gherkinDocument, pickles }: CompiledGherkin) {
           },
         })
 
-        const world = {}
+        const world = await worldFactory.create()
         const tracker = new ContextTracker(testCaseStartedId, world, (e) => messages.push(e))
 
         for (const step of item.steps) {
@@ -59,7 +59,7 @@ export function run({ source, gherkinDocument, pickles }: CompiledGherkin) {
             async (ctx2) => {
               let success = false
               try {
-                const { fn, args } = step.prepare()
+                const { fn, args } = step.prepare(world)
                 await fn(tracker.makeContext(ctx2, step.id), ...args)
                 success = true
               } finally {
@@ -80,6 +80,8 @@ export function run({ source, gherkinDocument, pickles }: CompiledGherkin) {
           })
         }
 
+        await worldFactory.destroy(world)
+
         messages.push({
           testCaseFinished: {
             testCaseStartedId: testCaseStartedId,

src/runner/loadSupport.ts

@@ -2,13 +2,15 @@ import { pathToFileURL } from 'node:url'
 
 import { globby } from 'globby'
 
-import { SupportCodeLibrary } from '../core/SupportCodeLibrary.js'
 import { builder } from './state.js'
 
-export async function loadSupport(): Promise<SupportCodeLibrary> {
+export async function loadSupport() {
   const paths = await globby('features/**/*.{cjs,js,mjs,cts,mts,ts}')
   for (const path of paths) {
     await import(pathToFileURL(path).toString())
   }
-  return builder.build()
+  return {
+    library: builder.toLibrary(),
+    worldFactory: builder.toWorldFactory(),
+  }
 }

src/runner/state.ts

@@ -1,8 +1,7 @@
-import { SupportCodeBuilder } from '../core/SupportCodeBuilder.js'
-import { makeId } from '../makeId.js'
+import { ExtendedSupportCodeBuilder } from './ExtendedSupportCodeBuilder.js'
 import { DiagnosticMessagesCollector, NoopMessagesCollector } from './MessagesCollector.js'
 
-export const builder = new SupportCodeBuilder(makeId)
+export const builder = new ExtendedSupportCodeBuilder()
 
 /*
 If no reporter is listening for messages, we provide

src/types.ts

@@ -3,6 +3,12 @@ import { TestContext } from 'node:test'
 
 import { Promisable } from 'type-fest'
 
+/**
+ * An object for sharing state between test steps.
+ * @public
+ */
+export type World = any // eslint-disable-line @typescript-eslint/no-explicit-any
+
 /**
  * Options for {@link TestCaseContext.attach}
  * @public
@@ -78,8 +84,7 @@ export type TestCaseContext = {
    * An object scoped only to this test case, that can be used to share state between
    * test steps.
    */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  world: any
+  world: World
 }
 
 /**
@@ -102,7 +107,7 @@ export type ParameterTypeOptions = {
    * @remarks
    * If not provided, the raw matched value(s) will be passed to the step function.
    */
-  transformer?: (...match: string[]) => unknown
+  transformer?: (this: World, ...match: string[]) => unknown
   /**
    * Whether this parameter type should be used when suggesting snippets for missing step
    * definitions.
@@ -140,7 +145,7 @@ export type HookOptions = {
  * Can optionally return a promise, which will duly be awaited. The actual returned/resolved value
  * is not read.
  */
-export type HookFunction = (context: TestCaseContext) => Promisable<void>
+export type HookFunction = (this: World, context: TestCaseContext) => Promisable<void>
 
 /**
  * A function to be executed as a step.
@@ -150,4 +155,4 @@ export type HookFunction = (context: TestCaseContext) => Promisable<void>
  * is not read.
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type StepFunction = (context: TestCaseContext, ...args: any) => Promisable<void>
+export type StepFunction = (this: World, context: TestCaseContext, ...args: any) => Promisable<void>