@serenity-js/core 3.41.2 → 3.42.1

package/src/screenplay/abilities/Ability.ts

@@ -1,6 +1,6 @@
-import type { AbilityType } from './AbilityType';
-import type { SerialisedAbility } from './SerialisedAbility';
-import type { UsesAbilities } from './UsesAbilities';
+import type { AbilityType } from './AbilityType.js';
+import type { SerialisedAbility } from './SerialisedAbility.js';
+import type { UsesAbilities } from './UsesAbilities.js';
 
 /**
  * **Abilities** enable [actors](https://serenity-js.org/api/core/class/Actor/)
@@ -362,6 +362,53 @@ import type { UsesAbilities } from './UsesAbilities';
  */
 export abstract class Ability {
 
+    /**
+     * Symbol used to brand Ability instances for cross-module instanceof checks.
+     * This addresses the dual-package hazard where the same class loaded from
+     * both ESM and CJS creates distinct constructor functions.
+     */
+    private static readonly TYPE_BRAND = Symbol.for('@serenity-js/core/Ability');
+
+    /**
+     * Custom instanceof check that works across module boundaries.
+     * This addresses the dual-package hazard where the same class loaded from
+     * both ESM and CJS creates distinct constructor functions.
+     *
+     * The check walks up the prototype chain of the instance and compares
+     * constructor names, which remain consistent across module boundaries.
+     */
+    static [Symbol.hasInstance](instance: unknown): boolean {
+        if (instance === null || typeof instance !== 'object') {
+            return false;
+        }
+
+        // First, verify this is an Ability instance using the brand
+        if ((instance as any)[Ability.TYPE_BRAND] !== true) {
+            return false;
+        }
+
+        // When checking against the base Ability class, any branded instance qualifies
+        if (this.name === 'Ability') {
+            return true;
+        }
+
+        // For subclass checks, walk the prototype chain and compare by name
+        // This works across ESM/CJS boundaries where constructor references differ
+        let proto = Object.getPrototypeOf(instance);
+        while (proto !== null) {
+            if (proto.constructor?.name === this.name) {
+                return true;
+            }
+            proto = Object.getPrototypeOf(proto);
+        }
+
+        return false;
+    }
+
+    protected constructor() {
+        (this as any)[Ability.TYPE_BRAND] = true;
+    }
+
     /**
      * Used to access an [actor's](https://serenity-js.org/api/core/class/Actor/) [ability](https://serenity-js.org/api/core/class/Ability/) of the given type
      * from within the [`Interaction`](https://serenity-js.org/api/core/class/Interaction/) and [`Question`](https://serenity-js.org/api/core/class/Question/) classes.
@@ -441,7 +488,7 @@ export abstract class Ability {
      * ```
      */
     static abilityType(): AbilityType<Ability> {
-        return Ability.abilityTypeOf(this);
+        return Ability.abilityTypeOf(this as unknown as AbilityType<Ability>);
     }
 
     /**
@@ -473,8 +520,20 @@ export abstract class Ability {
     private static ancestorTypes(abilityType: AbilityType<Ability>, ancestors: Array<AbilityType<Ability>> = []): Array<AbilityType<Ability>> {
         const parentType = Object.getPrototypeOf(abilityType);
 
-        return ! parentType || parentType === Ability
+        return ! parentType || Ability.isAbilityClass(parentType)
             ? ancestors
             : this.ancestorTypes(parentType, [ parentType, ...ancestors ]);
     }
+
+    /**
+     * Checks if the given constructor is the Ability base class.
+     * Uses name comparison to work across ESM/CJS module boundaries
+     * where the same class loaded from different module systems
+     * creates distinct constructor functions.
+     */
+    private static isAbilityClass(constructor: unknown): boolean {
+        return typeof constructor === 'function'
+            && constructor.name === 'Ability'
+            && typeof (constructor as typeof Ability).abilityType === 'function';
+    }
 }

package/src/screenplay/abilities/AbilityType.ts

@@ -1,5 +1,5 @@
-import type { Ability } from './Ability';
-import type { UsesAbilities } from './UsesAbilities';
+import type { Ability } from './Ability.js';
+import type { UsesAbilities } from './UsesAbilities.js';
 
 /**
  * An interface describing the static access method that every [`Ability`](https://serenity-js.org/api/core/class/Ability/) class

package/src/screenplay/abilities/AnswerQuestions.ts

@@ -1,9 +1,9 @@
-import { ValueInspector } from '../../io';
-import type { Answerable } from '../Answerable';
-import { Question } from '../Question';
-import type { AnswersQuestions } from '../questions';
-import { Ability } from './Ability';
-import type { UsesAbilities } from './UsesAbilities';
+import { ValueInspector } from '../../io/index.js';
+import type { Answerable } from '../Answerable.js';
+import { Question } from '../Question.js';
+import type { AnswersQuestions } from '../questions/index.js';
+import { Ability } from './Ability.js';
+import type { UsesAbilities } from './UsesAbilities.js';
 
 /**
  * This [`Ability`](https://serenity-js.org/api/core/class/Ability/) enables an [`Actor`](https://serenity-js.org/api/core/class/Actor/) to resolve the value of a given [`Answerable`](https://serenity-js.org/api/core/#Answerable).

package/src/screenplay/abilities/CanHaveAbilities.ts

@@ -1,5 +1,5 @@
-import type { Ability } from './Ability';
-import type { UsesAbilities } from './UsesAbilities';
+import type { Ability } from './Ability.js';
+import type { UsesAbilities } from './UsesAbilities.js';
 
 /**
  * Describes an [`Actor`](https://serenity-js.org/api/core/class/Actor/) who can have an [`Ability`](https://serenity-js.org/api/core/class/Ability/) to perform some [`Activity`](https://serenity-js.org/api/core/class/Activity/).

package/src/screenplay/abilities/PerformActivities.ts

@@ -1,10 +1,10 @@
 import { match } from 'tiny-types';
 
-import { AssertionError, ImplementationPendingError, TestCompromisedError } from '../../errors';
-import type { EmitsDomainEvents } from '../../events';
-import { InteractionFinished, InteractionStarts, TaskFinished, TaskStarts } from '../../events';
-import { type FileSystemLocation, ValueInspector } from '../../io';
-import { ExecutionSkipped, type Outcome } from '../../model';
+import { AssertionError, ImplementationPendingError, TestCompromisedError } from '../../errors/index.js';
+import type { EmitsDomainEvents } from '../../events/index.js';
+import { InteractionFinished, InteractionStarts, TaskFinished, TaskStarts } from '../../events/index.js';
+import { type FileSystemLocation, ValueInspector } from '../../io/index.js';
+import { ExecutionSkipped, type Outcome } from '../../model/index.js';
 import {
     ActivityDetails,
     ExecutionCompromised,
@@ -13,13 +13,13 @@ import {
     ExecutionSuccessful,
     ImplementationPending,
     Name
-} from '../../model';
-import type { PerformsActivities } from '../activities/PerformsActivities';
-import type { Activity } from '../Activity';
-import { Interaction } from '../Interaction';
-import type { AnswersQuestions } from '../questions';
-import { Ability } from './Ability';
-import type { UsesAbilities } from './UsesAbilities';
+} from '../../model/index.js';
+import type { PerformsActivities } from '../activities/PerformsActivities.js';
+import type { Activity } from '../Activity.js';
+import { Interaction } from '../Interaction.js';
+import type { AnswersQuestions } from '../questions/index.js';
+import { Ability } from './Ability.js';
+import type { UsesAbilities } from './UsesAbilities.js';
 
 /**
  * An [`Ability`](https://serenity-js.org/api/core/class/Ability/) that enables an [`Actor`](https://serenity-js.org/api/core/class/Actor/) to perform a given [`Activity`](https://serenity-js.org/api/core/class/Activity/).

package/src/screenplay/abilities/UsesAbilities.ts

@@ -1,5 +1,5 @@
-import type { Ability } from './Ability';
-import type { AbilityType } from './AbilityType';
+import type { Ability } from './Ability.js';
+import type { AbilityType } from './AbilityType.js';
 
 /**
  * Describes an [`Actor`](https://serenity-js.org/api/core/class/Actor/) who can use their [abilities](https://serenity-js.org/api/core/class/Ability/) to perform an [`Activity`](https://serenity-js.org/api/core/class/Activity/)

package/src/screenplay/abilities/index.ts

@@ -1,9 +1,9 @@
-export * from './Ability';
-export * from './AbilityType';
-export * from './AnswerQuestions';
-export * from './CanHaveAbilities';
-export * from './Discardable';
-export * from './Initialisable';
-export * from './PerformActivities';
-export * from './SerialisedAbility';
-export * from './UsesAbilities';
+export * from './Ability.js';
+export * from './AbilityType.js';
+export * from './AnswerQuestions.js';
+export * from './CanHaveAbilities.js';
+export * from './Discardable.js';
+export * from './Initialisable.js';
+export * from './PerformActivities.js';
+export * from './SerialisedAbility.js';
+export * from './UsesAbilities.js';

package/src/screenplay/activities/PerformsActivities.ts

@@ -1,4 +1,4 @@
-import type { Activity } from '../Activity';
+import type { Activity } from '../Activity.js';
 
 /**
  * Describes an [`Actor`](https://serenity-js.org/api/core/class/Actor/) who can perform a sequence of [activities](https://serenity-js.org/api/core/class/Activity/),

package/src/screenplay/activities/index.ts

@@ -1 +1 @@
-export * from './PerformsActivities';
+export * from './PerformsActivities.js';

package/src/screenplay/artifacts/CollectsArtifacts.ts

@@ -1,4 +1,4 @@
-import type { Artifact, Name } from '../../model';
+import type { Artifact, Name } from '../../model/index.js';
 
 /**
  * Describes an [`Actor`](https://serenity-js.org/api/core/class/Actor/) who can collect artifacts, such as photos or `JSON` data.,
@@ -19,8 +19,8 @@ export interface CollectsArtifacts {
      * ```ts
      * import fs from 'node:fs';
      * import { Answerable, Interaction, the } from '@serenity-js/core'
-     * import { Path } from '@serenity-js/core/lib/io'
-     * import { Name, TextData } from '@serenity-js/core/lib/model'
+     * import { Path } from '@serenity-js/core/io'
+     * import { Name, TextData } from '@serenity-js/core/model'
      *
      * export class Attach {
      *
@@ -50,7 +50,7 @@ export interface CollectsArtifacts {
      *
      * ```ts
      * import { actorCalled } from '@serenity-js/core'
-     * import { Path } from '@serenity-js/core/lib/io'
+     * import { Path } from '@serenity-js/core/io'
      *
      * actorCalled('Alice').attemptsTo(
      *   Attach.textData('some text', 'some name'),

package/src/screenplay/artifacts/index.ts

@@ -1 +1 @@
-export * from './CollectsArtifacts';
+export * from './CollectsArtifacts.js';

package/src/screenplay/debugging/Debug.ts

@@ -1,14 +1,14 @@
-import { ErrorSerialiser } from '../../errors';
-import { d } from '../../io';
-import { stringified } from '../../io/stringified';
-import { LogEntry, Name } from '../../model';
-import type { UsesAbilities } from '../abilities';
-import type { Answerable } from '../Answerable';
-import type { Answered } from '../Answered';
-import type { CollectsArtifacts } from '../artifacts';
-import { Interaction } from '../Interaction';
-import type { AnswersQuestions } from '../questions';
-import type { DebuggingResult } from './DebuggingResult';
+import { ErrorSerialiser } from '../../errors/index.js';
+import { d } from '../../io/index.js';
+import { stringified } from '../../io/stringified.js';
+import { LogEntry, Name } from '../../model/index.js';
+import type { UsesAbilities } from '../abilities/index.js';
+import type { Answerable } from '../Answerable.js';
+import type { Answered } from '../Answered.js';
+import type { CollectsArtifacts } from '../artifacts/index.js';
+import { Interaction } from '../Interaction.js';
+import type { AnswersQuestions } from '../questions/index.js';
+import type { DebuggingResult } from './DebuggingResult.js';
 
 /**
  * Instructs the [actor](https://serenity-js.org/api/core/class/Actor/) to evaluate and [log](https://serenity-js.org/api/core/class/Log/) the provided [answerable](https://serenity-js.org/api/core/#Answerable) values.

package/src/screenplay/debugging/Log.ts

@@ -1,11 +1,11 @@
-import { d } from '../../io';
-import { stringified } from '../../io/stringified';
-import { LogEntry, Name } from '../../model';
-import type { UsesAbilities } from '../abilities';
-import type { Answerable } from '../Answerable';
-import type { CollectsArtifacts } from '../artifacts';
-import { Interaction } from '../Interaction';
-import type { AnswersQuestions } from '../questions';
+import { d } from '../../io/index.js';
+import { stringified } from '../../io/stringified.js';
+import { LogEntry, Name } from '../../model/index.js';
+import type { UsesAbilities } from '../abilities/index.js';
+import type { Answerable } from '../Answerable.js';
+import type { CollectsArtifacts } from '../artifacts/index.js';
+import { Interaction } from '../Interaction.js';
+import type { AnswersQuestions } from '../questions/index.js';
 
 /**
  * Instructs the [`Actor`](https://serenity-js.org/api/core/class/Actor/)

package/src/screenplay/debugging/index.ts

@@ -1,3 +1,3 @@
-export * from './Debug';
-export * from './DebuggingResult';
-export * from './Log';
+export * from './Debug.js';
+export * from './DebuggingResult.js';
+export * from './Log.js';

package/src/screenplay/index.ts

@@ -1,18 +1,18 @@
-export * from './abilities';
-export * from './activities';
-export * from './Activity';
-export * from './Actor';
-export * from './Answerable';
-export * from './Answered';
-export * from './artifacts';    // todo: move artifacts from model package
-export * from './debugging';
-export * from './Interaction';
-export * from './notes';
-export * from './Optional';
-export * from './Question';
-export * from './questions';
-export * from './RecursivelyAnswered';
-export * from './SerialisedActor';
-export * from './Task';
-export * from './time';
-export * from './WithAnswerableProperties';
+export * from './abilities/index.js';
+export * from './activities/index.js';
+export * from './Activity.js';
+export * from './Actor.js';
+export * from './Answerable.js';
+export * from './Answered.js';
+export * from './artifacts/index.js';    // todo: move artifacts from model package
+export * from './debugging/index.js';
+export * from './Interaction.js';
+export * from './notes/index.js';
+export * from './Optional.js';
+export * from './Question.js';
+export * from './questions/index.js';
+export * from './RecursivelyAnswered.js';
+export * from './SerialisedActor.js';
+export * from './Task.js';
+export * from './time/index.js';
+export * from './WithAnswerableProperties.js';

package/src/screenplay/notes/ChainableSetter.ts

@@ -1,5 +1,5 @@
-import type { Answerable } from '../Answerable';
-import type { Interaction } from '../Interaction';
+import type { Answerable } from '../Answerable.js';
+import type { Interaction } from '../Interaction.js';
 
 /**
  * @group Notes

package/src/screenplay/notes/Notepad.ts

@@ -1,8 +1,8 @@
 import { TinyType } from 'tiny-types';
 
-import { LogicError } from '../../errors';
-import { d } from '../../io';
-import { NotepadAdapter } from './NotepadAdapter';
+import { LogicError } from '../../errors/index.js';
+import { d } from '../../io/index.js';
+import { NotepadAdapter } from './NotepadAdapter.js';
 
 /**
  * Stores notes recorded by an [`Actor`](https://serenity-js.org/api/core/class/Actor/).

package/src/screenplay/notes/NotepadAdapter.ts

@@ -1,15 +1,15 @@
 import type { JSONObject } from 'tiny-types';
 
-import { asyncMap } from '../../io';
-import type { UsesAbilities } from '../abilities';
-import type { Answerable } from '../Answerable';
-import { Interaction } from '../Interaction';
-import type { QuestionAdapter } from '../Question';
-import { Question } from '../Question';
-import type { AnswersQuestions, DescriptionFormattingOptions} from '../questions';
-import { the } from '../questions';
-import type { ChainableSetter } from './ChainableSetter';
-import { TakeNotes } from './TakeNotes';
+import { asyncMap } from '../../io/index.js';
+import type { UsesAbilities } from '../abilities/index.js';
+import type { Answerable } from '../Answerable.js';
+import { Interaction } from '../Interaction.js';
+import type { QuestionAdapter } from '../Question.js';
+import { Question } from '../Question.js';
+import type { AnswersQuestions, DescriptionFormattingOptions} from '../questions/index.js';
+import { the } from '../questions/index.js';
+import type { ChainableSetter } from './ChainableSetter.js';
+import { TakeNotes } from './TakeNotes.js';
 
 /**
  * Serenity/JS Screenplay Pattern-style adapter for the [`Notepad`](https://serenity-js.org/api/core/class/Notepad/),

package/src/screenplay/notes/TakeNotes.ts

@@ -1,5 +1,5 @@
-import { Ability, type SerialisedAbility } from '../abilities';
-import { Notepad } from './Notepad';
+import { Ability, type SerialisedAbility } from '../abilities/index.js';
+import { Notepad } from './Notepad.js';
 
 /**
  * An [`Ability`](https://serenity-js.org/api/core/class/Ability/) that enables an [`Actor`](https://serenity-js.org/api/core/class/Actor/) to remember information

package/src/screenplay/notes/index.ts

@@ -1,5 +1,5 @@
-export * from './ChainableSetter';
-export * from './Notepad';
-export * from './NotepadAdapter';
-export * from './notes';
-export * from './TakeNotes';
+export * from './ChainableSetter.js';
+export * from './Notepad.js';
+export * from './NotepadAdapter.js';
+export * from './notes.js';
+export * from './TakeNotes.js';

package/src/screenplay/notes/notes.ts

@@ -1,5 +1,5 @@
-import { Notepad } from './Notepad';
-import type { NotepadAdapter } from './NotepadAdapter';
+import { Notepad } from './Notepad.js';
+import type { NotepadAdapter } from './NotepadAdapter.js';
 
 /**
  * Alias for [`Notepad.notes`](https://serenity-js.org/api/core/class/Notepad/#notes).

package/src/screenplay/questions/AnswersQuestions.ts

@@ -1,4 +1,4 @@
-import type { Answerable } from '../Answerable';
+import type { Answerable } from '../Answerable.js';
 
 /**
  * Describes an [`Actor`](https://serenity-js.org/api/core/class/Actor/) who can answer a [`Question`](https://serenity-js.org/api/core/class/Question/) about the system under test.

package/src/screenplay/questions/ChainableMetaQuestion.ts

@@ -1,6 +1,6 @@
-import type { Answerable } from '../Answerable';
-import type { Question } from '../Question';
-import type { MetaQuestion } from './MetaQuestion';
+import type { Answerable } from '../Answerable.js';
+import type { Question } from '../Question.js';
+import type { MetaQuestion } from './MetaQuestion.js';
 
 /**
  * A chainable meta-question is a [`MetaQuestion`](https://serenity-js.org/api/core/interface/MetaQuestion/) that can be answered

package/src/screenplay/questions/Check.ts

@@ -1,11 +1,11 @@
-import { d } from '../../io';
-import type { PerformsActivities } from '../activities';
-import type { Activity } from '../Activity';
-import type { Answerable } from '../Answerable';
-import type { AnswersQuestions } from '../questions';
-import { Task } from '../Task';
-import type { Expectation } from './Expectation';
-import { ExpectationMet } from './expectations';
+import { d } from '../../io/index.js';
+import type { PerformsActivities } from '../activities/index.js';
+import type { Activity } from '../Activity.js';
+import type { Answerable } from '../Answerable.js';
+import type { AnswersQuestions } from '../questions/index.js';
+import { Task } from '../Task.js';
+import type { Expectation } from './Expectation.js';
+import { ExpectationMet } from './expectations/index.js';
 
 /**
  * A [flow control statement](https://en.wikipedia.org/wiki/Control_flow)

package/src/screenplay/questions/Describable.ts

@@ -1,7 +1,7 @@
-import { ValueInspector } from '../../io/reflection/ValueInspector';
-import type { UsesAbilities } from '../abilities/UsesAbilities';
-import type { Answerable } from '../Answerable';
-import type { AnswersQuestions } from './AnswersQuestions';
+import { ValueInspector } from '../../io/reflection/ValueInspector.js';
+import type { UsesAbilities } from '../abilities/UsesAbilities.js';
+import type { Answerable } from '../Answerable.js';
+import type { AnswersQuestions } from './AnswersQuestions.js';
 
 const descriptionField = Symbol('description');
 

package/src/screenplay/questions/Expectation.ts

@@ -1,12 +1,12 @@
 import type { JSONValue } from 'tiny-types';
 
-import { asyncMap, d } from '../../io';
-import { ExpectationDetails, ExpectationMet, ExpectationNotMet } from '../';
-import type { Answerable, AnswersQuestions, QuestionAdapter} from '../index';
-import { the } from '../index';
-import { Question } from '../Question';
-import { Describable } from '../questions';
-import type { ExpectationOutcome } from './expectations';
+import { asyncMap, d } from '../../io/index.js';
+import { ExpectationDetails, ExpectationMet, ExpectationNotMet } from '..//index.js';
+import type { Answerable, AnswersQuestions, QuestionAdapter} from '../index.js';
+import { the } from '../index.js';
+import { Question } from '../Question.js';
+import { Describable } from '../questions/index.js';
+import type { ExpectationOutcome } from './expectations/index.js';
 
 /**
  * @group Expectations

package/src/screenplay/questions/List.ts

@@ -1,14 +1,14 @@
-import { ListItemNotFoundError, LogicError } from '../../errors';
-import { d } from '../../io';
-import type { UsesAbilities } from '../abilities';
-import type { Actor } from '../Actor';
-import type { Answerable } from '../Answerable';
-import type { MetaQuestionAdapter, QuestionAdapter } from '../Question';
-import { Question } from '../Question';
-import type { AnswersQuestions, ChainableMetaQuestion, MetaQuestion } from '../questions';
-import { Task } from '../Task';
-import type { Expectation } from './Expectation';
-import { ExpectationMet } from './expectations';
+import { ListItemNotFoundError, LogicError } from '../../errors/index.js';
+import { d } from '../../io/index.js';
+import type { UsesAbilities } from '../abilities/index.js';
+import type { Actor } from '../Actor.js';
+import type { Answerable } from '../Answerable.js';
+import type { MetaQuestionAdapter, QuestionAdapter } from '../Question.js';
+import { Question } from '../Question.js';
+import type { AnswersQuestions, ChainableMetaQuestion, MetaQuestion } from '../questions/index.js';
+import { Task } from '../Task.js';
+import type { Expectation } from './Expectation.js';
+import { ExpectationMet } from './expectations/index.js';
 
 /**
  * Serenity/JS Screenplay Pattern-style wrapper around [`Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)

package/src/screenplay/questions/Masked.ts

@@ -1,5 +1,5 @@
-import { type Answerable } from '../Answerable';
-import { Question, type QuestionAdapter } from '../Question';
+import { type Answerable } from '../Answerable.js';
+import { Question, type QuestionAdapter } from '../Question.js';
 
 /**
  * This question masks sensitive data handled by the actors and prevents

package/src/screenplay/questions/MetaQuestion.ts

@@ -1,5 +1,5 @@
-import type { Answerable } from '../Answerable';
-import type { Question } from '../Question';
+import type { Answerable } from '../Answerable.js';
+import type { Question } from '../Question.js';
 
 /**
  * A meta-question is a [`Question`](https://serenity-js.org/api/core/class/Question/) that can be answered