Return messages in definition order

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]
+### Changed
+- Return messages in definition order ([#36](https://github.com/cucumber/javascript-core/pull/36))
 
 ## [0.8.1] - 2025-11-28
 ### Added

cucumber-core.api.md

@@ -12,6 +12,7 @@ import { GherkinDocument } from '@cucumber/messages';
 import { Hook } from '@cucumber/messages';
 import { IdGenerator } from '@cucumber/messages';
 import { NamingStrategy } from '@cucumber/query';
+import { ParameterType } from '@cucumber/messages';
 import parse from '@cucumber/tag-expressions';
 import { Pickle } from '@cucumber/messages';
 import { PickleDocString } from '@cucumber/messages';
@@ -84,16 +85,19 @@ export class DataTable {
 // @public
 export type DefinedParameterType = {
     id: string;
+    order: number;
     name: string;
     regularExpressions: ReadonlyArray<string>;
     preferForRegularExpressionMatch: boolean;
     useForSnippets: boolean;
     sourceReference: SourceReference;
+    toMessage(): ParameterType;
 };
 
 // @public
 export type DefinedStep = {
     id: string;
+    order: number;
     expression: {
         raw: string | RegExp;
         compiled: CucumberExpression | RegularExpression;
@@ -106,6 +110,7 @@ export type DefinedStep = {
 // @public
 export type DefinedTestCaseHook = {
     id: string;
+    order: number;
     name?: string;
     tags?: {
         raw: string;
@@ -119,6 +124,7 @@ export type DefinedTestCaseHook = {
 // @public
 export type DefinedTestRunHook = {
     id: string;
+    order: number;
     name?: string;
     fn: SupportCodeFunction;
     sourceReference: SourceReference;

src/AmbiguousError.spec.ts

@@ -21,6 +21,7 @@ describe('AmbiguousError', () => {
 
     const matches: ReadonlyArray<DefinedStep> = references.map((ref) => ({
       id: 'def-id',
+      order: 0,
       expression: {
         raw: 'text',
         compiled: {} as any,

src/SupportCodeBuilderImpl.ts

@@ -21,26 +21,28 @@ import {
   UndefinedParameterType,
 } from './types'
 
-type WithId<T> = { id: string } & T
+type Registered<T> = { id: string; order: number } & T
 
 /**
  * @internal
  */
 export class SupportCodeBuilderImpl implements SupportCodeBuilder {
   private readonly parameterTypeRegistry = new ParameterTypeRegistry()
   private readonly undefinedParameterTypes: Map<string, Set<string>> = new Map()
-  private readonly parameterTypes: Array<WithId<NewParameterType>> = []
-  private readonly steps: Array<WithId<NewStep>> = []
-  private readonly beforeHooks: Array<WithId<NewTestCaseHook>> = []
-  private readonly afterHooks: Array<WithId<NewTestCaseHook>> = []
-  private readonly beforeAllHooks: Array<WithId<NewTestRunHook>> = []
-  private readonly afterAllHooks: Array<WithId<NewTestRunHook>> = []
+  private readonly parameterTypes: Array<Registered<NewParameterType>> = []
+  private readonly steps: Array<Registered<NewStep>> = []
+  private readonly beforeHooks: Array<Registered<NewTestCaseHook>> = []
+  private readonly afterHooks: Array<Registered<NewTestCaseHook>> = []
+  private readonly beforeAllHooks: Array<Registered<NewTestRunHook>> = []
+  private readonly afterAllHooks: Array<Registered<NewTestRunHook>> = []
+  private sequence = 0
 
   constructor(private readonly newId: () => string) {}
 
   parameterType(options: NewParameterType) {
     this.parameterTypes.push({
       id: this.newId(),
+      order: this.sequence++,
       ...options,
     })
     return this
@@ -49,6 +51,7 @@ export class SupportCodeBuilderImpl implements SupportCodeBuilder {
   beforeHook(options: NewTestCaseHook) {
     this.beforeHooks.push({
       id: this.newId(),
+      order: this.sequence++,
       ...options,
     })
     return this
@@ -57,6 +60,7 @@ export class SupportCodeBuilderImpl implements SupportCodeBuilder {
   afterHook(options: NewTestCaseHook) {
     this.afterHooks.push({
       id: this.newId(),
+      order: this.sequence++,
       ...options,
     })
     return this
@@ -65,6 +69,7 @@ export class SupportCodeBuilderImpl implements SupportCodeBuilder {
   step(options: NewStep) {
     this.steps.push({
       id: this.newId(),
+      order: this.sequence++,
       ...options,
     })
     return this
@@ -73,6 +78,7 @@ export class SupportCodeBuilderImpl implements SupportCodeBuilder {
   beforeAllHook(options: NewTestRunHook) {
     this.beforeAllHooks.push({
       id: this.newId(),
+      order: this.sequence++,
       ...options,
     })
     return this
@@ -81,6 +87,7 @@ export class SupportCodeBuilderImpl implements SupportCodeBuilder {
   afterAllHook(options: NewTestRunHook) {
     this.afterAllHooks.push({
       id: this.newId(),
+      order: this.sequence++,
       ...options,
     })
     return this
@@ -99,25 +106,37 @@ export class SupportCodeBuilderImpl implements SupportCodeBuilder {
       this.parameterTypeRegistry.defineParameterType(parameterType)
       return {
         id: registered.id,
+        order: registered.order,
         name: registered.name,
         regularExpressions: [...parameterType.regexpStrings],
         preferForRegularExpressionMatch: parameterType.preferForRegexpMatch as boolean,
         useForSnippets: parameterType.useForSnippets as boolean,
         sourceReference: registered.sourceReference,
+        toMessage() {
+          return {
+            id: this.id,
+            name: this.name,
+            regularExpressions: this.regularExpressions,
+            preferForRegularExpressionMatch: this.preferForRegularExpressionMatch,
+            useForSnippets: this.useForSnippets,
+            sourceReference: this.sourceReference,
+          }
+        },
       }
     })
   }
 
   private buildSteps(): ReadonlyArray<DefinedStep> {
     return this.steps
-      .map(({ id, pattern, fn, sourceReference }) => {
+      .map(({ id, order, pattern, fn, sourceReference }) => {
         const compiled = this.compileExpression(pattern)
         if (!compiled) {
           return undefined
         }
         const source = this.extractPatternSource(pattern)
         return {
           id,
+          order,
           expression: {
             raw: pattern,
             compiled,
@@ -184,9 +203,10 @@ export class SupportCodeBuilderImpl implements SupportCodeBuilder {
   }
 
   private buildBeforeHooks(): ReadonlyArray<DefinedTestCaseHook> {
-    return this.beforeHooks.map(({ id, name, tags, fn, sourceReference }) => {
+    return this.beforeHooks.map(({ id, order, name, tags, fn, sourceReference }) => {
       return {
         id,
+        order,
         name,
         tags: tags
           ? {
@@ -210,9 +230,10 @@ export class SupportCodeBuilderImpl implements SupportCodeBuilder {
   }
 
   private buildAfterHooks(): ReadonlyArray<DefinedTestCaseHook> {
-    return this.afterHooks.map(({ id, name, tags, fn, sourceReference }) => {
+    return this.afterHooks.map(({ id, order, name, tags, fn, sourceReference }) => {
       return {
         id,
+        order,
         name,
         tags: tags
           ? {
@@ -236,9 +257,10 @@ export class SupportCodeBuilderImpl implements SupportCodeBuilder {
   }
 
   private buildBeforeAllHooks(): ReadonlyArray<DefinedTestRunHook> {
-    return this.beforeAllHooks.map(({ id, name, fn, sourceReference }) => {
+    return this.beforeAllHooks.map(({ id, order, name, fn, sourceReference }) => {
       return {
         id,
+        order,
         name,
         fn,
         sourceReference,
@@ -255,9 +277,10 @@ export class SupportCodeBuilderImpl implements SupportCodeBuilder {
   }
 
   private buildAfterAllHooks(): ReadonlyArray<DefinedTestRunHook> {
-    return this.afterAllHooks.map(({ id, name, fn, sourceReference }) => {
+    return this.afterAllHooks.map(({ id, order, name, fn, sourceReference }) => {
       return {
         id,
+        order,
         name,
         fn,
         sourceReference,

src/SupportCodeLibraryImpl.ts

@@ -1,5 +1,5 @@
 import { CucumberExpressionGenerator, ParameterTypeRegistry } from '@cucumber/cucumber-expressions'
-import { SourceReference } from '@cucumber/messages'
+import { Envelope, SourceReference } from '@cucumber/messages'
 
 import {
   DefinedParameterType,
@@ -11,6 +11,11 @@ import {
   UndefinedParameterType,
 } from './types'
 
+type OrderedEnvelope = {
+  order: number
+  envelope: Envelope
+}
+
 /**
  * @internal
  */
@@ -82,18 +87,50 @@ export class SupportCodeLibraryImpl implements SupportCodeLibrary {
   }
 
   toEnvelopes() {
+    const definedThings: ReadonlyArray<OrderedEnvelope> = [
+      ...this.parameterTypes.map((definedParameterType) => ({
+        order: definedParameterType.order,
+        envelope: {
+          parameterType: definedParameterType.toMessage(),
+        },
+      })),
+      ...this.steps.map((definedStep) => ({
+        order: definedStep.order,
+        envelope: {
+          stepDefinition: definedStep.toMessage(),
+        },
+      })),
+      ...this.beforeHooks.map((definedHook) => ({
+        order: definedHook.order,
+        envelope: {
+          hook: definedHook.toMessage(),
+        },
+      })),
+      ...this.afterHooks.map((definedHook) => ({
+        order: definedHook.order,
+        envelope: {
+          hook: definedHook.toMessage(),
+        },
+      })),
+      ...this.beforeAllHooks.map((definedHook) => ({
+        order: definedHook.order,
+        envelope: {
+          hook: definedHook.toMessage(),
+        },
+      })),
+      ...this.afterAllHooks.map((definedHook) => ({
+        order: definedHook.order,
+        envelope: {
+          hook: definedHook.toMessage(),
+        },
+      })),
+    ]
+
     return [
-      ...this.parameterTypes.map((parameterType) => ({ parameterType })),
-      ...this.steps
-        .map((definedStep) => definedStep.toMessage())
-        .map((stepDefinition) => ({ stepDefinition })),
-      ...this.undefinedParameterTypes.map((undefinedParameterType) => ({ undefinedParameterType })),
-      ...this.beforeHooks.map((definedHook) => definedHook.toMessage()).map((hook) => ({ hook })),
-      ...this.afterHooks.map((definedHook) => definedHook.toMessage()).map((hook) => ({ hook })),
-      ...this.beforeAllHooks
-        .map((definedHook) => definedHook.toMessage())
-        .map((hook) => ({ hook })),
-      ...this.afterAllHooks.map((definedHook) => definedHook.toMessage()).map((hook) => ({ hook })),
+      ...definedThings.toSorted((a, b) => a.order - b.order).map(({ envelope }) => envelope),
+      ...this.undefinedParameterTypes.map((undefinedParameterType) => ({
+        undefinedParameterType,
+      })),
     ]
   }
 }

src/buildSupportCode.spec.ts

@@ -1,5 +1,12 @@
 import { CucumberExpression, RegularExpression } from '@cucumber/cucumber-expressions'
-import { IdGenerator, StepDefinitionPatternType } from '@cucumber/messages'
+import {
+  Envelope,
+  Hook,
+  IdGenerator,
+  ParameterType,
+  StepDefinition,
+  StepDefinitionPatternType,
+} from '@cucumber/messages'
 import { expect } from 'chai'
 import sinon from 'sinon'
 
@@ -424,6 +431,58 @@ describe('buildSupportCode', () => {
     })
   })
 
+  describe('envelopes', () => {
+    it('should return envelopes in the same order the support code was registered', () => {
+      const library = buildSupportCode({ newId })
+        .afterHook({
+          name: 'teardown 2',
+          fn: sinon.stub(),
+          sourceReference: { uri: 'hooks.js', location: { line: 4, column: 1 } },
+        })
+        .afterAllHook({
+          name: 'big teardown',
+          fn: sinon.stub(),
+          sourceReference: { uri: 'hooks.js', location: { line: 2, column: 1 } },
+        })
+        .beforeAllHook({
+          name: 'big setup',
+          fn: sinon.stub(),
+          sourceReference: { uri: 'hooks.js', location: { line: 1, column: 1 } },
+        })
+        .beforeHook({
+          name: 'teardown 1',
+          fn: sinon.stub(),
+          sourceReference: { uri: 'hooks.js', location: { line: 3, column: 1 } },
+        })
+        .parameterType({
+          name: 'flight',
+          regexp: /([A-Z]{3})-([A-Z]{3})/,
+          /* c8 ignore next 3 */
+          transformer(from: string, to: string) {
+            return [from, to]
+          },
+          sourceReference: { uri: 'support.js', location: { line: 1, column: 1 } },
+        })
+        .step({
+          pattern: '{flight} has been delayed',
+          fn: sinon.stub(),
+          sourceReference: { uri: 'steps.js', location: { line: 1, column: 1 } },
+        })
+        .build()
+
+      const envelopes = library.toEnvelopes()
+
+      expect(
+        envelopes.flatMap((envelope) =>
+          Object.keys(envelope).map(
+            (key) =>
+              `${key}:${(envelope[key as keyof Envelope] as Hook | ParameterType | StepDefinition).id}`
+          )
+        )
+      ).to.deep.eq(['hook:0', 'hook:1', 'hook:2', 'hook:3', 'parameterType:4', 'stepDefinition:5'])
+    })
+  })
+
   describe('sources', () => {
     it('should return all source references from parameter types, steps, and hooks', () => {
       const library = buildSupportCode({ newId })