@serenity-js/core 3.41.2 → 3.42.0

package/esm/screenplay/notes/NotepadAdapter.js

@@ -0,0 +1,335 @@
+import { asyncMap } from '../../io/index.js';
+import { Interaction } from '../Interaction.js';
+import { Question } from '../Question.js';
+import { the } from '../questions/index.js';
+import { TakeNotes } from './TakeNotes.js';
+/**
+ * Serenity/JS Screenplay Pattern-style adapter for the [`Notepad`](https://serenity-js.org/api/core/class/Notepad/),
+ * that makes it easier for the [actors](https://serenity-js.org/api/core/class/Actor/) to access its APIs.
+ *
+ * See [`TakeNotes`](https://serenity-js.org/api/core/class/TakeNotes/), [`Notepad`](https://serenity-js.org/api/core/class/Notepad/) and [`notes`](https://serenity-js.org/api/core/function/notes/) for more examples.
+ *
+ * @group Notes
+ */
+export class NotepadAdapter {
+    /**
+     * Checks if a note identified by `subject` exists in the notepad.
+     *
+     * #### Learn more
+     * - [`Notepad.has`](https://serenity-js.org/api/core/class/Notepad/#has)}
+     *
+     * @param subject
+     *   A subject (name) that uniquely identifies a given note
+     *
+     * @returns
+     *  Question that resolves to `true` if the note exists, `false` otherwise
+     */
+    has(subject) {
+        return Question.about(`a note of ${String(subject)} exists`, actor => {
+            return TakeNotes.as(actor).notepad.has(subject);
+        });
+    }
+    /**
+     * Retrieves a note, identified by `subject`, from the notepad.
+     *
+     * #### Learn more
+     * - [`Notepad.get`](https://serenity-js.org/api/core/class/Notepad/#get)}
+     *
+     * @param subject
+     *   A subject (name) that uniquely identifies a given note
+     *
+     * @returns
+     *  The value of the previously recorded note.
+     *
+     * @throws
+     *  Throws a [`LogicError`](https://serenity-js.org/api/core/class/LogicError/) if the note with a given `subject`
+     *  has never been recorded.
+     */
+    get(subject) {
+        return Question.about(`a note of ${String(subject)}`, actor => {
+            return TakeNotes.as(actor).notepad.get(subject);
+        }).describedAs(Question.formattedValue());
+    }
+    /**
+     * Resolves a given `Answerable<value>` and stores it in the notepad,
+     * uniquely identified by its `subject`.
+     *
+     * **Pro tip:** calls to `set` can be chained and result in an accumulation
+     * of values to be recorded in the [`Notepad`](https://serenity-js.org/api/core/class/Notepad/).
+     * Those values are resolved and recorded when the [`Interaction`](https://serenity-js.org/api/core/class/Interaction/)
+     * returned by this method is performed by an [`Actor`](https://serenity-js.org/api/core/class/Actor/).
+     *
+     * If a note identified by a given `subject` is set multiple times,
+     * the last call wins.
+     *
+     * ```ts
+     *  import { actorCalled, notes, TakeNotes } from '@serenity-js/core'
+     *  import { Ensure, equals } from '@serenity-js/assertions'
+     *
+     *  interface MyNotes {
+     *      stringNote: string;
+     *      numberNote: number;
+     *  }
+     *
+     * await actorCalled('Alice')
+     *   .whoCan(TakeNotes.usingAnEmptyNotepad<MyNotes>());
+     *   .attemptsTo(
+     *
+     *     notes<MyNotes>()
+     *       .set('stringNote', 'example')
+     *       .set('numberNote', Promise.resolve(42))
+     *       .set('stringNote', 'another example'),
+     *
+     *     Ensure.equal(notes().toJSON(), {
+     *       firstNote: 'another example',
+     *       secondNote: 42,
+     *     })
+     * )
+     * ```
+     *
+     * #### Learn more
+     * - [`Notepad.set`](https://serenity-js.org/api/core/class/Notepad/#set)
+     *
+     * @param subject
+     *   A subject (name) that uniquely identifies a given note
+     *
+     * @param value
+     *  The value to record
+     */
+    set(subject, value) {
+        return new ChainableNoteSetter({ [subject]: value });
+    }
+    /**
+     * Removes the note identified by `subject` from the notepad.
+     *
+     * #### Using as an `Interaction`
+     *
+     * ```ts
+     * import { actorCalled, Check, Log, notes } from '@serenity-js/core'
+     * import { isPresent } from '@serenity-js/assertions'
+     *
+     * interface MyNotes {
+     *   myNote: string;
+     * }
+     *
+     * await actorCalled('Alice')
+     *   .whoCan(TakeNotes.using(Notepad.empty<MyNotes>()))
+     *   .attemptsTo(
+     *     notes<MyNotes>().set('myNote', 'example value'),
+     *
+     *     notes<MyNotes>().delete('myNote'),
+     *
+     *     Check.whether(notes<MyNotes>().get('myNote'), isPresent())
+     *       .andIfSo(
+     *         Log.the('myNote is present'),
+     *       )
+     *       .otherwise(
+     *         Log.the('myNote was deleted'),
+     *       )
+     *   )
+     *   // logs: myNote was deleted
+     * ```
+     *
+     * #### Using as a `Question`
+     *
+     * ```ts
+     * import { actorCalled, Check, Log, notes } from '@serenity-js/core'
+     * import { isTrue } from '@serenity-js/assertions'
+     *
+     * interface MyNotes {
+     *   myNote: string;
+     * }
+     *
+     * await actorCalled('Alice')
+     *   .whoCan(TakeNotes.using(Notepad.empty<MyNotes>()))
+     *   .attemptsTo(
+     *     notes<MyNotes>().set('myNote', 'example value'),
+     *
+     *     Check.whether(notes<MyNotes>().delete('myNote'), isTrue())
+     *       .andIfSo(
+     *         Log.the('myNote was deleted'),
+     *       )
+     *       .otherwise(
+     *         Log.the('myNote could not be deleted because it was not set'),
+     *       )
+     *   )
+     *   // logs: myNote was deleted
+     * ```
+     *
+     * #### Learn more
+     * - [`Notepad.delete`](https://serenity-js.org/api/core/class/Notepad/#delete)
+     *
+     * @param subject
+     *
+     * @returns
+     *  When used as a `Question`, resolves to `true` if the item in the Notepad object existed and has been removed,
+     *  `false` otherwise.
+     */
+    delete(subject) {
+        return Question.about(`#actor deletes a note of ${String(subject)}`, actor => {
+            return TakeNotes.as(actor).notepad.delete(subject);
+        });
+    }
+    /**
+     * Deletes all the notes stored in this notepad.
+     *
+     * ```ts
+     * import { actorCalled, notes } from '@serenity-js/core'
+     * import { isTrue } from '@serenity-js/assertions'
+     *
+     * interface MyNotes {
+     *   myNote: string;
+     * }
+     *
+     * await actorCalled('Alice')
+     *   .whoCan(TakeNotes.using(Notepad.empty<MyNotes>()))
+     *   .attemptsTo(
+     *     notes<MyNotes>().set('myNote', 'example value'),
+     *     Log.the(notes<MyNotes>().size()),   // emits 1
+     *     notes<MyNotes>().clear(),
+     *     Log.the(notes<MyNotes>().size()),   // emits 0
+     *   )
+     * ```
+     *
+     * #### Learn more
+     * - [`Notepad.clear`](https://serenity-js.org/api/core/class/Notepad/#clear)
+     */
+    clear() {
+        return Interaction.where(the `#actor clears ${new NumberOfNotes()} from their notepad`, actor => {
+            return TakeNotes.as(actor).notepad.clear();
+        });
+    }
+    /**
+     * Returns the number of notes stored in the notepad.
+     *
+     * ```ts
+     * import { actorCalled, notes } from '@serenity-js/core'
+     * import { isTrue } from '@serenity-js/assertions'
+     *
+     * interface MyNotes {
+     *   myNote: string;
+     * }
+     *
+     * await actorCalled('Alice')
+     *   .whoCan(TakeNotes.using(Notepad.empty<MyNotes>()))
+     *   .attemptsTo(
+     *     Log.the(notes<MyNotes>().size()),   // emits 0
+     *     notes<MyNotes>().set('myNote', 'example value'),
+     *     Log.the(notes<MyNotes>().size()),   // emits 1
+     *   )
+     * ```
+     *
+     * #### Learn more
+     * - [`Notepad.size`](https://serenity-js.org/api/core/class/Notepad/#size)
+     */
+    size() {
+        return Question.about(the `${new NumberOfNotes()}`, async (actor) => {
+            return TakeNotes.as(actor).notepad.size();
+        });
+    }
+    /**
+     * Produces a [`QuestionAdapter`](https://serenity-js.org/api/core/#QuestionAdapter) that resolves to a `JSONObject`
+     * representing the resolved notes stored in the notepad.
+     *
+     * Note that serialisation to JSON will simplify some data types that might not be serialisable by default,
+     * but are commonly used in data structures representing actor's notes.
+     * For example a [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) will be serialised as a regular JSON object, a [`Set`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set) will be serialised as [`Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array).
+     *
+     * Additionally, notepad assumes that the data structure you use it with does not contain cyclic references.
+     *
+     * To learn more about the serialisation mechanism used by the notepad, please refer to [TinyTypes documentation](https://jan-molak.github.io/tiny-types/).
+     *
+     * ```ts
+     * import { actorCalled, notes } from '@serenity-js/core'
+     *
+     * await actorCalled('Alice')
+     *   .whoCan(TakeNotes.using(Notepad.with({
+     *     aSet: new Set(['apples', 'bananas', 'cucumbers']),
+     *     aPromisedValue: Promise.resolve(42),
+     *     aString: 'example'
+     *   })))
+     *   .attemptsTo(
+     *     Log.the(notes().toJSON()),
+     *   )
+     *   // emits: {
+     *   //    aSet: ['apples', 'bananas', 'cucumbers']
+     *   //    aPromisedValue: 42,
+     *   //    aString: 'example',
+     *   // }
+     * ```
+     */
+    toJSON() {
+        return Question.about('notepad serialised to JSON', async (actor) => {
+            return TakeNotes.as(actor).notepad.toJSON();
+        });
+    }
+    /**
+     * @inheritDoc
+     */
+    toString() {
+        return 'notes';
+    }
+}
+/**
+ * @package
+ */
+class ChainableNoteSetter extends Interaction {
+    notes;
+    constructor(notes) {
+        super(new DescriptionOfNotes(notes));
+        this.notes = notes;
+    }
+    set(subject, value) {
+        return new ChainableNoteSetter({
+            ...this.notes,
+            [subject]: value,
+        });
+    }
+    async performAs(actor) {
+        const notepad = TakeNotes.as(actor).notepad;
+        for (const [subject, value] of Object.entries(this.notes)) {
+            const answer = await actor.answer(value);
+            notepad.set(subject, answer);
+        }
+    }
+}
+class DescriptionOfNotes extends Question {
+    notes;
+    options;
+    constructor(notes, options) {
+        super(`#actor takes notes: ${Object.keys(notes).join(', ')}`);
+        this.notes = notes;
+        this.options = options;
+    }
+    async answeredBy(actor) {
+        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) {
+        return this.answeredBy(actor);
+    }
+}
+class NumberOfNotes extends Question {
+    constructor() {
+        super('notes');
+    }
+    async answeredBy(actor) {
+        return TakeNotes.as(actor).notepad.size();
+    }
+    async describedBy(actor) {
+        const count = await this.answeredBy(actor);
+        return count === 1
+            ? '1 note'
+            : `${count} notes`;
+    }
+}
+//# sourceMappingURL=NotepadAdapter.js.map

package/esm/screenplay/notes/NotepadAdapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"NotepadAdapter.js","sourceRoot":"","sources":["../../../src/screenplay/notes/NotepadAdapter.ts"],"names":[],"mappings":"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"}

package/esm/screenplay/notes/TakeNotes.d.ts

@@ -0,0 +1,250 @@
+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
+ * to be recalled during a test scenario.
+ *
+ * Under the hood, [`TakeNotes`](https://serenity-js.org/api/core/class/TakeNotes/) uses a [`Notepad`](https://serenity-js.org/api/core/class/Notepad/), which state
+ * can be populated both during initialisation or while the test scenario is executed.
+ * Populating the notepad when it's initialised can be useful to associate authentication credentials
+ * or personal details with a given actor, while dynamic recording of notes during a test scenario
+ * can be useful when the data to be recorded is not known upfront - for example when we want
+ * the actor to remember a JWT stored in the browser and then use it when sending API requests.
+ *
+ * **Pro tip:** [`TakeNotes`](https://serenity-js.org/api/core/class/TakeNotes/), [`Notepad`](https://serenity-js.org/api/core/class/Notepad/) and [`notes`](https://serenity-js.org/api/core/function/notes/) can be typed
+ * using [TypeScript generics](https://www.typescriptlang.org/docs/handbook/2/generics.html)
+ * to help you avoid typos when specifying note names.
+ *
+ * See [notes](https://serenity-js.org/api/core/function/notes) and [`Notepad`](https://serenity-js.org/api/core/class/Notepad/) for more usage examples.
+ *
+ * ## Remembering and retrieving a value
+ *
+ * ```ts
+ * import { actorCalled, Log, notes, TakeNotes } from '@serenity-js/core'
+ *
+ * await actorCalled('Leonard')
+ *   .whoCan(TakeNotes.usingAnEmptyNotepad())
+ *   .attemptsTo(
+ *     notes().set('my_note', 'some value'),
+ *     Log.the(notes().get('my_note')),
+ *     // emits 'some value'
+ *   )
+ * ```
+ *
+ * ## Using generics
+ *
+ * ```ts
+ *  import { actorCalled, Log, notes, TakeNotes } from '@serenity-js/core'
+ *
+ *  interface MyNotes {
+ *    personalDetails: {
+ *      firstName: string;
+ *      lastName: string;
+ *    }
+ *  }
+ *
+ * await actorCalled('Leonard')
+ *   .whoCan(TakeNotes.usingAnEmptyNotepad<MyNotes>())
+ *   .attemptsTo(
+ *     Log.the(notes<MyNotes>().has('personalDetails')),
+ *     // emits false
+ *
+ *     Log.the(notes<MyNotes>().get('personalDetails').isPresent()),
+ *     // emits false
+ *
+ *     notes<MyNotes>().set('personalDetails', { firstName: 'Leonard', lastName: 'McLaud' }),
+ *
+ *     Log.the(notes<MyNotes>().has('personalDetails')),
+ *     // emits true
+ *
+ *     Log.the(notes<MyNotes>().get('personalDetails').isPresent()),
+ *     // emits true
+ *
+ *     Log.the(notes().get('personalDetails').firstName),
+ *     // emits 'Leonard'
+ *
+ *     Log.the(notes().get('personalDetails').firstName.toLocaleUpperCase()),
+ *     // emits 'LEONARD'
+ *   )
+ * ```
+ *
+ * ## Populating the notepad with initial state
+ *
+ * ```ts
+ * import { actorCalled, Log, Note, Notepad, TakeNotes } from '@serenity-js/core'
+ *
+ * interface MyNotes {
+ *   firstName: string;
+ *   lastName: string;
+ * }
+ *
+ * await actorCalled('Leonard')
+ *   .whoCan(
+ *     TakeNotes.using(Notepad.with<MyNotes>({
+ *       firstName: 'Leonard',
+ *       lastName: 'McLaud',
+ *     }))
+ *   )
+ *   .attemptsTo(
+ *     notes<MyNotes>().set('lastName', 'Shelby'),
+ *     Log.the(notes().get('firstName')),
+ *     // emits 'Leonard'
+ *
+ *     Log.the(notes().get('lastName')),
+ *     // emits 'Shelby'
+ *   )
+ * ```
+ *
+ * ## Recording a dynamic note
+ *
+ * ```ts
+ * import { actorCalled, Log, Notepad, notes, TakeNotes } from '@serenity-js/core'
+ * import { By, Text, PageElement } from '@serenity-js/web'
+ * import { BrowseTheWebWithWebdriverIO } from '@serenity-js/webdriverio'
+ *
+ * interface OnlineShoppingNotes {
+ *   promoCode: string;
+ * }
+ *
+ * const promoCodeBanner = () =>
+ *   PageElement.located(By.css('[data-testid="promo-code"]'))
+ *     .describedAs('promo code');
+ *
+ * const promoCodeInput = () =>
+ *   PageElement.located(By.css('[data-testid="promo-code-input"]'))
+ *     .describedAs('promo code field');
+ *
+ * await actorCalled('Leonard')
+ *   .whoCan(
+ *     BrowseTheWebWithWebdriverIO.using(browser),
+ *     TakeNotes.using(Notepad.empty<OnlineShoppingNotes>())
+ *   )
+ *   .attemptsTo(
+ *     notes<OnlineShoppingNotes>().set('promoCode', Text.of(promoCode()),
+ *     // ...
+ *     Enter.theValue(notes<OnlineShoppingNotes>().get('promoCode'))
+ *       .into(promoCodeInput())
+ *   )
+ * ```
+ *
+ * ## Clearing a notepad before each test scenario (Mocha)
+ *
+ * ```ts
+ * import 'mocha';
+ *
+ * beforeEach(() =>
+ *   actorCalled('Leonard')
+ *     .attemptsTo(
+ *       notes().clear(),
+ *     ))
+ * ```
+ *
+ * ## Clearing a notepad before each test scenario (Cucumber)
+ *
+ * ```ts
+ * import { Before } from '@cucumber/cucumber'
+ *
+ * Before(() =>
+ *   actorCalled('Leonard')
+ *     .attemptsTo(
+ *       notes().clear(),
+ *     ));
+ * ```
+ *
+ * ## Importing notes from an API response
+ *
+ * ```ts
+ *  // given an example API:
+ *  //   GET /generate-test-user
+ *  // which returns:
+ *  //   { "first_name": "Leonard", "last_name": "Shelby" }
+ *
+ * import { actorCalled, Log, Notepad, notes, TakeNotes } from '@serenity-js/core'
+ * import { CallAnApi, GetRequest, Send } from '@serenity-js/rest'
+ *
+ * interface PersonalDetails {
+ *   first_name: string;
+ *   last_name: string;
+ * }
+ *
+ * interface MyNotes {
+ *   personalDetails?: PersonalDetails;
+ * }
+ *
+ * await actorCalled('Leonard')
+ *   .whoCan(
+ *     CallAnApi.at('https://api.example.org/'),
+ *     TakeNotes.using(Notepad.empty<MyNotes>())
+ *   )
+ *   .attemptsTo(
+ *      Send.a(GetRequest.to('/generate-test-user')),
+ *      notes<MyNotes>().set('personalDetails', LastResponse.body<PersonalDetails>()),
+ *
+ *      Log.the(notes<MyNotes>().get('personalDetails').first_name),    // emits 'Leonard'
+ *      Log.the(notes<MyNotes>().get('personalDetails').last_name),     // emits 'Shelby'
+ *   )
+ * ```
+ *
+ * ## Using the QuestionAdapter
+ *
+ * ```ts
+ * import { actorCalled, Log, Notepad, notes, TakeNotes } from '@serenity-js/core'
+ *
+ * interface AuthCredentials {
+ *   username?: string;
+ *   password?: string;
+ * }
+ *
+ * interface MyNotes {
+ *   auth: AuthCredentials;
+ * }
+ *
+ * await actorCalled('Leonard')
+ *   .whoCan(
+ *     TakeNotes.using(
+ *       Notepad.with<MyNotes>({     // typed initial state
+ *         auth: {
+ *           username: 'leonard@example.org',
+ *           password: 'SuperSecretP@ssword!',
+ *         }
+ *       })
+ *     )
+ *   )
+ *   .attemptsTo(
+ *     Log.the(
+ *       notes<MyNotes>()          // typed notes
+ *         .get('auth')            // returns QuestionAdapter<AuthCredentials>
+ *         .password               // returns QuestionAdapter<string>
+ *         .charAt(0)
+ *         .toLocaleLowerCase(),   // emits "s"
+ *     ),
+ *   )
+ * ```
+ *
+ * ## Learn more
+ *
+ * - [notes](https://serenity-js.org/api/core/function/notes)
+ * - [`Notepad`](https://serenity-js.org/api/core/class/Notepad/)
+ *
+ * @group Notes
+ */
+export declare class TakeNotes<Notes_Type extends Record<any, any>> extends Ability {
+    readonly notepad: Notepad<Notes_Type>;
+    /**
+     * Initialises an [`Ability`](https://serenity-js.org/api/core/class/Ability/) to [`TakeNotes`](https://serenity-js.org/api/core/class/TakeNotes/) with [`Notepad.empty`](https://serenity-js.org/api/core/class/Notepad/#empty).
+     */
+    static usingAnEmptyNotepad<N extends Record<any, any>>(): TakeNotes<N>;
+    /**
+     * Initialises an [`Ability`](https://serenity-js.org/api/core/class/Ability/) to [`TakeNotes`](https://serenity-js.org/api/core/class/TakeNotes/) using
+     * a [`Notepad.with`](https://serenity-js.org/api/core/class/Notepad/#with) some initial state.
+     *
+     * @param notepad
+     */
+    static using<N extends Record<any, any>>(notepad: Notepad<N>): TakeNotes<N>;
+    /**
+     * @param notepad
+     */
+    constructor(notepad: Notepad<Notes_Type>);
+    toJSON(): SerialisedAbility;
+}
+//# sourceMappingURL=TakeNotes.d.ts.map

package/esm/screenplay/notes/TakeNotes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TakeNotes.d.ts","sourceRoot":"","sources":["../../../src/screenplay/notes/TakeNotes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AACxE,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmOG;AACH,qBAAa,SAAS,CAAC,UAAU,SAAS,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAE,SAAQ,OAAO;aAsB3C,OAAO,EAAE,OAAO,CAAC,UAAU,CAAC;IApBxD;;OAEG;IACH,MAAM,CAAC,mBAAmB,CAAC,CAAC,SAAS,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC;IAItE;;;;;OAKG;IACH,MAAM,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC;IAI3E;;OAEG;gBACyB,OAAO,EAAE,OAAO,CAAC,UAAU,CAAC;IAIxD,MAAM,IAAI,iBAAiB;CAQ9B"}