@serenity-js/core 3.23.2 → 3.24.0

package/src/screenplay/Task.ts

@@ -1,6 +1,7 @@
 import { ImplementationPendingError } from '../errors';
 import type { PerformsActivities } from './activities';
 import { Activity } from './Activity';
+import type { Answerable } from './Answerable';
 
 /**
  * **Tasks** model **{@apilink Activity|sequences of activities}**
@@ -30,11 +31,11 @@ import { Activity } from './Activity';
  * ## Defining a task
  *
  * ```ts
- * import { Answerable, Task, d } from '@serenity-js/core'
+ * import { Answerable, Task, the } from '@serenity-js/core'
  * import { By, Click, Enter, PageElement, Press, Key } from '@serenity-js/web'
  *
  * const SignIn = (username: Answerable<string>, password: Answerable<string>) =>
- *   Task.where(d`#actor signs is as ${ username }`,
+ *   Task.where(the`#actor signs is as ${ username }`,
  *     Enter.theValue(username).into(PageElement.located(By.id('username'))),
  *     Enter.theValue(password).into(PageElement.located(By.id('password'))),
  *     Press.the(Key.Enter),
@@ -50,11 +51,11 @@ import { Activity } from './Activity';
  * but you're not yet sure what activities it will involve.
  *
  * ```ts
- * import { Task } from '@serenity-js/core'
+ * import { Task, the } from '@serenity-js/core'
  *
  * const SignUp = () =>
- *     Task.where(`#actor signs up for a newsletter`) // no activities provided
- *                                                    // => task marked as pending
+ *     Task.where(the`#actor signs up for a newsletter`) // no activities provided
+ *                                                       // => task marked as pending
  * ```
  *
  * ## Composing activities into tasks
@@ -74,10 +75,10 @@ import { Activity } from './Activity';
  * The easiest way to implement such task, and any custom Serenity/JS task for this matter, is to use the {@apilink Task.where} method to compose the lower-level activities:
  *
  * ```typescript
- * import { Task } from '@serenity-js/core'
+ * import { Task, the } from '@serenity-js/core'
  *
  * const findFlight = (originCity: string, destinationCity: string) =>
- *     Task.where(`#actors finds a flight from ${ originCity } to ${ destinationCity }`,   // task goal
+ *     Task.where(the`#actor finds a flight from ${ originCity } to ${ destinationCity }`,   // task goal
  *         specifyOriginCity(originCity),                                                  // activities
  *         specifyDestinationCity(originCity),
  *     )
@@ -99,20 +100,20 @@ import { Activity } from './Activity';
  * which we can incorporate into our task definitions just like any other activities:
  *
  * ```typescript
- * import { Task } from '@serenity-js/core'
+ * import { Task, the } from '@serenity-js/core'
  * import { Click, Enter, Key, Press } from '@serenity-js/web'
  *
  * import { FlightFinder } from './ui/flight-finder'
  *
  * const specifyOriginCity = (originCity: string) =>
- *     Task.where(`#actor specifies origin city of ${ originCity }`,
+ *     Task.where(the`#actor specifies origin city of ${ originCity }`,
  *         Click.on(FlightFinder.originAirport),
  *         Enter.theValue(originCity).into(FlightFinder.originAirport),
  *         Press.the(Key.ArrowDown, Key.Enter).into(FlightFinder.originAirport),
  *     )
  *
  * const specifyDestinationCity = (destinationCity: string) =>
- *     Task.where(`#actor specifies destination city of ${ destinationCity }`,
+ *     Task.where(the`#actor specifies destination city of ${ destinationCity }`,
  *         Click.on(FlightFinder.destinationAirport),
  *         Enter.theValue(destinationCity).into(FlightFinder.destinationAirport),
  *         Press.the(Key.ArrowDown, Key.Enter).into(FlightFinder.destinationAirport),
@@ -125,23 +126,23 @@ import { Activity } from './Activity';
  * by **extracting a parameterised task**, in this case called `specifyCity`:
  *
  * ```typescript
- * import { Task } from '@serenity-js/core'
+ * import { Task, the } from '@serenity-js/core'
  * import { Click, Enter, Key, PageElement, Press } from '@serenity-js/web'
  *
  * import { FlightFinder } from './ui/flight-finder'
  *
  * const specifyOriginCity = (originCity: string) =>
- *     Task.where(`#actor specifies origin city of ${ originCity }`,
+ *     Task.where(the`#actor specifies origin city of ${ originCity }`,
  *         specifyCity(originCity, FlightFinder.originAirport)
  *     )
  *
  * const specifyDestinationCity = (destinationCity: string) =>
- *     Task.where(`#actor specifies destination city of ${ destinationCity }`,
+ *     Task.where(the`#actor specifies destination city of ${ destinationCity }`,
  *         specifyCity(destinationCity, FlightFinder.destinationAirport),
  *     )
  *
  * const specifyCity = (cityName: string, widget: PageElement) =>
- *     Task.where(`#actor specifies city of ${ cityName } in ${ widget }`,
+ *     Task.where(the`#actor specifies city of ${ cityName } in ${ widget }`,
  *         Click.on(widget),
  *         Enter.theValue(cityName).into(widget),
  *         Press.the(Key.ArrowDown, Key.Enter).into(widget),
@@ -182,7 +183,7 @@ export abstract class Task extends Activity {
      * @param activities
      *  A sequence of lower-level activities that constitute this task
      */
-    static where(description: string, ...activities: Activity[]): Task {
+    static where(description: Answerable<string>, ...activities: Activity[]): Task {
         return activities.length > 0
             ? new DynamicallyGeneratedTask(description, activities)
             : new NotImplementedTask(description);
@@ -205,7 +206,7 @@ export abstract class Task extends Activity {
  * @package
  */
 class DynamicallyGeneratedTask extends Task {
-    constructor(description: string, private activities: Activity[]) {
+    constructor(description: Answerable<string>, private activities: Activity[]) {
         super(description, Task.callerLocation(4));
     }
 
@@ -218,7 +219,7 @@ class DynamicallyGeneratedTask extends Task {
  * @package
  */
 class NotImplementedTask extends Task {
-    constructor(description: string) {
+    constructor(description: Answerable<string>) {
         super(description, Task.callerLocation(4));
     }
 

package/src/screenplay/abilities/Ability.ts

@@ -54,7 +54,7 @@ import type { UsesAbilities } from './UsesAbilities';
  * Note how {@apilink BrowseTheWebWithPlaywright}, {@apilink BrowseTheWebWithWebdriverIO}, and {@apilink BrowseTheWebWithProtractor}
  * all **extend** the base ability to {@apilink BrowseTheWeb}.
  *
- * #### Playwright Test
+ * #### Playwright
  *
  * ```typescript
  * import { actorCalled } from '@serenity-js/core'
@@ -63,7 +63,7 @@ import type { UsesAbilities } from './UsesAbilities';
  *
  * const browser = await chromium.launch({ headless: true })              // integration library
  *
- * actorCalled('Trevor')                                                  // generic actor
+ * await actorCalled('Trevor')                                            // generic actor
  *   .whoCan(BrowseTheWebWithPlaywright.using(browser))                   // tool-specific ability
  * ```
  *
@@ -73,7 +73,7 @@ import type { UsesAbilities } from './UsesAbilities';
  * import { actorCalled } from '@serenity-js/core'
  * import { BrowseTheWebWithWebdriverIO } from '@serenity-js/webdriverio' // Serenity/JS integration module
  *
- * actorCalled('Trevor')                                                  // generic actor
+ * await actorCalled('Trevor')                                            // generic actor
  *   .whoCan(BrowseTheWebWithWebdriverIO.using(browser))                  // tool-specific ability
  * ```
  *
@@ -84,7 +84,7 @@ import type { UsesAbilities } from './UsesAbilities';
  * import { BrowseTheWebWithProtractor } from '@serenity-js/protractor'   // Serenity/JS integration module
  * import { protractor } from 'protractor'                                // integration library
  *
- * actorCalled('Trevor')                                                  // generic actor
+ * await actorCalled('Trevor')                                            // generic actor
  *   .whoCan(BrowseTheWebWithProtractor.using(protractor.browser))        // tool-specific ability
  * ```
  *
@@ -242,9 +242,11 @@ import type { UsesAbilities } from './UsesAbilities';
  * ### Defining a custom interaction using the custom ability
  *
  * ```ts
+ * import { Answerable, Interaction, the } from '@serenity-js/core'
+ *
  * // A custom interaction using the actor's ability:
- * const Call = (phoneNumber: string) =>
- *   Interaction.where(`#actor calls ${ phoneNumber }`, async actor => {
+ * const Call = (phoneNumber: Answerable<string>) =>
+ *   Interaction.where(the`#actor calls ${ phoneNumber }`, async actor => {
  *     await MakePhoneCalls.as(actor).dial(phoneNumber)
  *   })
  * ```

package/src/screenplay/abilities/AbilityType.ts

@@ -7,7 +7,7 @@ import type { Ability } from './Ability';
  * #### Retrieving an ability from an interaction
  *
  * ```ts
- * import { Ability, actorCalled, Interaction } from '@serenity-js/core';
+ * import { Ability, Answerable, actorCalled, Interaction, the } from '@serenity-js/core';
  *
  * class MakePhoneCalls extends Ability {
  *   static using(phone: Phone) {
@@ -23,8 +23,8 @@ import type { Ability } from './Ability';
  *   }
  * }
  *
- * const Call = (phoneNumber: string) =>
- *   Interaction.where(`#actor calls ${ phoneNumber }`, async actor => {
+ * const Call = (phoneNumber: Answerable<string>) =>
+ *   Interaction.where(the`#actor calls ${ phoneNumber }`, async actor => {
  *     await MakePhoneCalls.as(actor).dial(phoneNumber)
  *   });
  *

package/src/screenplay/abilities/AnswerQuestions.ts

@@ -1,3 +1,4 @@
+import { ValueInspector } from '../../io';
 import type { Answerable } from '../Answerable';
 import { Question } from '../Question';
 import type { AnswersQuestions } from '../questions';
@@ -20,7 +21,7 @@ export class AnswerQuestions extends Ability {
 
     answer<T>(answerable: Answerable<T>): Promise<T> {
 
-        if (AnswerQuestions.isDefined(answerable) && AnswerQuestions.isAPromise(answerable)) {
+        if (AnswerQuestions.isDefined(answerable) && ValueInspector.isPromise(answerable)) {
             return answerable;
         }
 
@@ -31,10 +32,6 @@ export class AnswerQuestions extends Ability {
         return Promise.resolve(answerable as T);
     }
 
-    private static isAPromise<V>(v: Answerable<V>): v is Promise<V> {
-        return Object.prototype.hasOwnProperty.call(v, 'then');
-    }
-
     private static isDefined<V>(v: Answerable<V>) {
         return !(v === undefined || v === null);
     }

package/src/screenplay/abilities/PerformActivities.ts

@@ -1,12 +1,10 @@
 import { match } from 'tiny-types';
 
 import { AssertionError, ImplementationPendingError, TestCompromisedError } from '../../errors';
-import type { EmitsDomainEvents} from '../../events';
+import type { EmitsDomainEvents } from '../../events';
 import { InteractionFinished, InteractionStarts, TaskFinished, TaskStarts } from '../../events';
-import type {
-    Outcome,
-    ProblemIndication
-} from '../../model';
+import { type FileSystemLocation, ValueInspector } from '../../io';
+import type { Outcome, ProblemIndication } from '../../model';
 import {
     ActivityDetails,
     ExecutionCompromised,
@@ -19,7 +17,9 @@ import {
 import type { PerformsActivities } from '../activities/PerformsActivities';
 import type { Activity } from '../Activity';
 import { Interaction } from '../Interaction';
-import { Ability } from './index';
+import type { AnswersQuestions } from '../questions';
+import { Ability } from './Ability';
+import type { UsesAbilities } from './UsesAbilities';
 
 /**
  * An {@apilink Ability} that enables an {@apilink Actor} to perform a given {@apilink Activity}.
@@ -32,15 +32,15 @@ import { Ability } from './index';
  */
 export class PerformActivities extends Ability {
     constructor(
-        protected readonly actor: PerformsActivities & { name: string },
+        protected readonly actor: AnswersQuestions & UsesAbilities & PerformsActivities & { name: string },
         protected readonly stage: EmitsDomainEvents,
     ) {
         super();
     }
 
     async perform(activity: Activity): Promise<void> {
-        const sceneId = this.stage.currentSceneId();
-        const details = this.detailsOf(activity);
+        const sceneId    = this.stage.currentSceneId();
+        const details    = this.detailsOf(this.nameOf(activity), activity.instantiationLocation());
         const activityId = this.stage.assignNewActivityId(details);
 
         const [ activityStarts, activityFinished ] = activity instanceof Interaction
@@ -48,11 +48,28 @@ export class PerformActivities extends Ability {
             : [ TaskStarts, TaskFinished ];
 
         try {
-            this.stage.announce(new activityStarts(sceneId, activityId, details, this.stage.currentTime()))
+            this.stage.announce(
+                new activityStarts(
+                    sceneId,
+                    activityId,
+                    details,
+                    this.stage.currentTime()
+                )
+            );
 
             await activity.performAs(this.actor);
 
-            this.stage.announce(new activityFinished(sceneId, activityId, details, new ExecutionSuccessful(), this.stage.currentTime()));
+            const name = await activity.describedBy(this.actor);
+
+            this.stage.announce(
+                new activityFinished(
+                    sceneId,
+                    activityId,
+                    this.detailsOf(name, activity.instantiationLocation()),
+                    new ExecutionSuccessful(),
+                    this.stage.currentTime()
+                )
+            );
         }
         catch (error) {
             this.stage.announce(new activityFinished(sceneId, activityId, details, this.outcomeFor(error), this.stage.currentTime()));
@@ -74,18 +91,18 @@ export class PerformActivities extends Ability {
             .else(_ => new ExecutionFailedWithError(error));
     }
 
-    private detailsOf(activity: Activity): ActivityDetails {
+    private detailsOf(name: string, instantiationLocation: FileSystemLocation): ActivityDetails {
         return new ActivityDetails(
-            new Name(this.nameOf(activity)),
-            activity.instantiationLocation(),
+            new Name(name),
+            instantiationLocation,
         )
     }
 
     protected nameOf(activity: Activity): string {
-        const template = activity.toString() === ({}).toString()
-            ? `#actor performs ${ activity.constructor.name }`
-            : activity.toString();
+        const template = ValueInspector.hasItsOwnToString(activity)
+            ? activity.toString()
+            : `#actor performs ${ activity.constructor.name }`;
 
-        return template.replace('#actor', this.actor.name);
+        return template.replaceAll('#actor', this.actor.name);
     }
 }

package/src/screenplay/artifacts/CollectsArtifacts.ts

@@ -19,7 +19,7 @@ export interface CollectsArtifacts {
      *
      * ```ts
      * import * as fs from 'node:fs'
-     * import { Answerable, Interaction } from '@serenity-js/core'
+     * 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'
      *
@@ -36,7 +36,7 @@ export interface CollectsArtifacts {
      *     })
      *
      *   static textData = (contents: Answerable<string>, name?: string): Interaction =>
-     *     Interaction.where(`#actor attaches text data`, async actor => {
+     *     Interaction.where(the`#actor attaches text data`, async actor => {
      *       const data = await actor.answer(contents);
      *
      *       actor.collect(

package/src/screenplay/notes/NotepadAdapter.ts

@@ -1,12 +1,13 @@
 import type { JSONObject } from 'tiny-types';
 
-import { commaSeparated } from '../../io';
+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 } from '../questions';
+import type { AnswersQuestions, DescriptionFormattingOptions} from '../questions';
+import { the } from '../questions';
 import type { ChainableSetter } from './ChainableSetter';
 import { TakeNotes } from './TakeNotes';
 
@@ -57,7 +58,7 @@ export class NotepadAdapter<Notes extends Record<any, any>> implements Chainable
     get<Subject extends keyof Notes>(subject: Subject): QuestionAdapter<Notes[Subject]> {
         return Question.about(`a note of ${ String(subject) }`, actor => {
             return TakeNotes.as(actor).notepad.get(subject);
-        });
+        }).describedAs(Question.formattedValue());
     }
 
     /**
@@ -207,7 +208,7 @@ export class NotepadAdapter<Notes extends Record<any, any>> implements Chainable
      * - {@apilink Notepad.clear}
      */
     clear(): Interaction {
-        return Interaction.where('#actor clears their notepad', actor => {
+        return Interaction.where(the`#actor clears ${ new NumberOfNotes() } from their notepad`, actor => {
             return TakeNotes.as(actor).notepad.clear();
         });
     }
@@ -236,7 +237,7 @@ export class NotepadAdapter<Notes extends Record<any, any>> implements Chainable
      * - {@apilink Notepad.size}
      */
     size(): QuestionAdapter<number> {
-        return Question.about('number of notes', async actor => {
+        return Question.about(the`${ new NumberOfNotes() }`, async actor => {
             return TakeNotes.as(actor).notepad.size();
         });
     }
@@ -296,7 +297,7 @@ type NotesToSet<Notes extends Record<any, any>> = {
 class ChainableNoteSetter<Notes extends Record<any, any>> extends Interaction implements ChainableSetter<Notes> {
 
     constructor(private readonly notes: NotesToSet<Notes>) {
-        super(`#actor takes note of ${ commaSeparated(Object.keys(notes)) }`);
+        super(new DescriptionOfNotes(notes));
     }
 
     set<K extends keyof Notes>(subject: K, value: Answerable<Notes[K]>): ChainableSetter<Notes> & Interaction {
@@ -316,3 +317,53 @@ class ChainableNoteSetter<Notes extends Record<any, any>> extends Interaction im
         }
     }
 }
+
+class DescriptionOfNotes<Notes extends Record<any, any>>
+    extends Question<Promise<string>>
+{
+    constructor(
+        private readonly notes: NotesToSet<Notes>,
+        private readonly options?: DescriptionFormattingOptions,
+    ) {
+        super(`#actor takes notes: ${ Object.keys(notes).join(', ') }`);
+    }
+
+    async answeredBy(actor: AnswersQuestions & UsesAbilities & { name: string }): Promise<string> {
+        const noteNames = Object.keys(this.notes);
+        const maxWidth  = noteNames.reduce((max, name) => Math.max(max, name.length), 0);
+
+        const list = await asyncMap(noteNames, async noteName => {
+            const label = `${ noteName }:`.padEnd(maxWidth + 1);
+            const noteDescription = await actor.answer(Question.formattedValue(this.options).of(this.notes[noteName]));
+
+            return `- ${ label } ${ noteDescription }`
+        })
+
+        return [
+            `#actor takes notes:`,
+            ...list,
+        ].join('\n');
+    }
+
+    async describedBy(actor: AnswersQuestions & UsesAbilities & { name: string }): Promise<string> {
+        return this.answeredBy(actor);
+    }
+}
+
+class NumberOfNotes extends Question<Promise<number>> {
+    constructor() {
+        super('notes');
+    }
+
+    async answeredBy(actor: AnswersQuestions & UsesAbilities): Promise<number> {
+        return TakeNotes.as(actor).notepad.size();
+    }
+
+    async describedBy(actor: AnswersQuestions & UsesAbilities & { name: string }): Promise<string> {
+        const count = await this.answeredBy(actor);
+
+        return count === 1
+            ? '1 note'
+            : `${ count } notes`;
+    }
+}

package/src/screenplay/questions/Describable.ts

@@ -0,0 +1,48 @@
+import { ValueInspector } from '../../io/reflection/ValueInspector';
+import type { UsesAbilities } from '../abilities/UsesAbilities';
+import type { Answerable } from '../Answerable';
+import type { AnswersQuestions } from './AnswersQuestions';
+
+const descriptionField = Symbol('description');
+
+/**
+ * @group Questions
+ */
+export abstract class Describable {
+
+    private [descriptionField]: Answerable<string>;
+
+    protected constructor(description: Answerable<string>) {
+        this[descriptionField] = description;
+    }
+
+    /**
+     * Resolves the description of this object in the context of the provided `actor`.
+     *
+     * @param actor
+     */
+    async describedBy(actor: AnswersQuestions & UsesAbilities & { name: string }): Promise<string> {
+        const description = await actor.answer(this[descriptionField]);
+
+        return description.replaceAll('#actor', actor.name);
+    }
+
+    protected setDescription(description: Answerable<string>): void {
+        this[descriptionField] = description;
+    }
+
+    protected getDescription(): Answerable<string> {
+        return this[descriptionField];
+    }
+
+    /**
+     * Returns a human-readable description of this object.
+     */
+    toString(): string {
+        if (ValueInspector.isPromise(this[descriptionField])) {
+            return 'Promise';
+        }
+
+        return String(this[descriptionField]);
+    }
+}

package/src/screenplay/questions/DescriptionFormattingOptions.ts

@@ -0,0 +1,13 @@
+/**
+ * Configuration options for {@apilink Question.formattedValue} and
+ * the [`the`](/api/core/function/the/) function.
+ *
+ * @group Questions
+ */
+export interface DescriptionFormattingOptions {
+    /**
+     * The maximum length of the string representation of the value.
+     * String representations longer than this value will be truncated and appended with an ellipsis.
+     */
+    maxLength: number;
+}

package/src/screenplay/questions/Expectation.ts

@@ -1,8 +1,11 @@
 import type { JSONValue } from 'tiny-types';
 
 import { asyncMap, d } from '../../io';
-import type { Answerable, AnswersQuestions, QuestionAdapter } from '../';
-import { ExpectationDetails, ExpectationMet, ExpectationNotMet, Question } from '../';
+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';
 
 /**
@@ -19,7 +22,7 @@ type AnswerableArguments<Arguments extends Array<unknown>> = { [Index in keyof A
  *
  * @group Expectations
  */
-export class Expectation<Actual> {
+export class Expectation<Actual> extends Describable {
 
     /**
      * A factory method to that makes defining custom {@apilink Expectation|expectations} easier
@@ -108,13 +111,13 @@ export class Expectation<Actual> {
      */
     static define<Actual_Type, PredicateArguments extends Array<unknown>>(
         functionName: string,
-        relationship: ((...answerableArguments: AnswerableArguments<PredicateArguments>) => string) | string,
+        relationship: ((...answerableArguments: AnswerableArguments<PredicateArguments>) => Answerable<string>) | Answerable<string>,
         predicate: (actual: Actual_Type, ...predicateArguments: PredicateArguments) => Promise<boolean> | boolean,
     ): (...answerableArguments: AnswerableArguments<PredicateArguments>) => Expectation<Actual_Type>
     {
         return Object.defineProperty(function(...answerableArguments: AnswerableArguments<PredicateArguments>): Expectation<Actual_Type> {
-            const description = typeof relationship === 'function' ? relationship(...answerableArguments)
-                : (answerableArguments.length === 1 ? relationship.trim() + d` ${answerableArguments[0]}`
+            const description: Answerable<string> = typeof relationship === 'function' ? relationship(...answerableArguments)
+                : (answerableArguments.length === 1 ? the`${ { toString: () => relationship } } ${ answerableArguments[0] }`
                     : relationship);
 
             return new Expectation<Actual_Type>(
@@ -129,6 +132,8 @@ export class Expectation<Actual> {
 
                     const result    = await predicate(actual, ...predicateArguments as PredicateArguments);
 
+                    const descriptionText = await actor.answer(description);
+
                     const expectationDetails = ExpectationDetails.of(functionName, ...predicateArguments);
 
                     const expected = predicateArguments.length > 0
@@ -136,8 +141,8 @@ export class Expectation<Actual> {
                         : true;     // the only parameter-less expectations are boolean ones like `isPresent`, `isActive`, etc.
 
                     return result
-                        ? new ExpectationMet(description, expectationDetails, expected, actual)
-                        : new ExpectationNotMet(description, expectationDetails, expected, actual);
+                        ? new ExpectationMet(descriptionText, expectationDetails, expected, actual)
+                        : new ExpectationNotMet(descriptionText, expectationDetails, expected, actual);
                 }
             )
         }, 'name', {value: functionName, writable: false});
@@ -243,9 +248,10 @@ export class Expectation<Actual> {
 
     protected constructor(
         private readonly functionName: string,
-        private description: string,
+        description: Answerable<string>,
         private readonly predicate: Predicate<Actual>
     ) {
+        super(description);
     }
 
     /**
@@ -256,21 +262,15 @@ export class Expectation<Actual> {
      * @param actual
      */
     isMetFor(actual: Answerable<Actual>): QuestionAdapter<ExpectationOutcome> {
-        return Question.about(this.description, actor => this.predicate(actor, actual));
+        return Question.about(this.getDescription(), actor => this.predicate(actor, actual));
     }
 
     /**
      * @inheritDoc
      */
-    describedAs(subject: string): this {
-        this.description = subject;
-        return this;
-    }
+    describedAs(description: Answerable<string>): this {
+        super.setDescription(description);
 
-    /**
-     * @inheritDoc
-     */
-    toString(): string {
-        return this.description;
+        return this;
     }
 }