@serenity-js/core 3.0.0-rc.9 → 3.0.1

package/src/screenplay/debugging/Debug.ts

@@ -0,0 +1,161 @@
+import { ErrorSerialiser } from '../../errors';
+import { d } from '../../io';
+import { stringified } from '../../io/stringified';
+import { LogEntry, Name } from '../../model';
+import { UsesAbilities } from '../abilities';
+import { Answerable } from '../Answerable';
+import { Answered } from '../Answered';
+import { CollectsArtifacts } from '../artifacts';
+import { Interaction } from '../Interaction';
+import { AnswersQuestions } from '../questions';
+import { DebuggingResult } from './DebuggingResult';
+
+/**
+ * Instructs the {@apilink Actor|actor} to evaluate and {@apilink Log|log} the provided {@apilink Answerable} values.
+ *
+ * Since this interaction **accepts a callback function** that receives the evaluated results,
+ * the best way to use it is while **running the test scenario via a Node.js debugger**.
+ * See the links below to learn how to do it in popular IDEs.
+ *
+ * ## Debugging Answerable values
+ *
+ * {@apilink Debug.values} accepts a callback function that receives an array of {@apilink DebuggingResult} objects,
+ * as well as the result of evaluating each provided {@apilink Answerable|answerable} with {@apilink Actor.answer}.
+ *
+ * ```typescript
+ * import { actorCalled, Debug } from '@serenity-js/core'
+ * import { Navigate, Page } from '@serenity-js/web'
+ *
+ * // Running the below through the Node.js debugger makes the actor resolve the provided values
+ * // and return them to the debugger function, where you can investigate their contents,
+ * // or inspect any Errors the evaluation has resulted with.
+ * await actorCalled('Debbie').attemptsTo(
+ *     Navigate.to('http://example.org'),
+ *     Debug.values((results, title, url) => {
+ *         // set a breakpoint here to view `results`, `title` and `url` in your IDE debugger
+ *     }, Page.current().title(), Page.current().url()), // accepts multiple values
+ * );
+ * ```
+ *
+ * ## Accessing Playwright Page
+ *
+ * [Playwright Test for VSCode](https://marketplace.visualstudio.com/items?itemName=ms-playwright.playwright)
+ * provides features that allow for [experimenting with web UI locators](https://marketplace.visualstudio.com/items?itemName=ms-playwright.playwright#tune-locators)
+ * while the test is paused at breakpoint.
+ *
+ * Since this functionality is specific to [Playwright](/api/playwright), you can use it by passing {@apilink PlaywrightPage.current|`PlaywrightPage.current().nativePage()`}
+ * to Serenity/JS {@apilink Debug.values}. Also make sure to name the evaluated value `page`, as this is the variable name that the Playwright VSCode extension expects.
+ *
+ * ```typescript
+ * import { actorCalled, Debug } from '@serenity-js/core'
+ * import { PlaywrightPage } from '@serenity-js/playwright'
+ *
+ * // Running the below through the Node.js debugger makes the actor resolve the provided values
+ * // and return them to the debugger function, where you can investigate their contents,
+ * // or inspect any Errors the evaluation has resulted with.
+ * await actorCalled('Debbie').attemptsTo(
+ *     Navigate.to('http://example.org'),
+ *     Debug.values((results, page) => {
+ *         // set a breakpoint here to use Playwright locator debugging features
+ *         page.locator('.example-css-class')
+ *         // note that you can change this selector while having the test paused at breakpoint
+ *     }, PlaywrightPage.current().nativePage()),
+ * );
+ * ```
+ *
+ * ## Learn more
+ * - [Node.js debugging - Getting started](https://nodejs.org/en/docs/guides/debugging-getting-started/)
+ * - [Node.js debugging in VS Code](https://code.visualstudio.com/docs/nodejs/nodejs-debugging)
+ * - [Running and debugging Node.js in WebStorm](https://www.jetbrains.com/help/webstorm/running-and-debugging-node-js.html)
+ * - [Playwright Test for VSCode](https://marketplace.visualstudio.com/items?itemName=ms-playwright.playwright)
+ *
+ * @group Activities
+ */
+export class Debug<Values extends Array<Answerable<unknown>>> extends Interaction {
+
+    /**
+     * Instructs the {@apilink Actor|actor} to evaluate the provided `values`,
+     * log the results, and then pass them to your `debuggerFunction`.
+     *
+     * To use this interaction, run your test scenario in the Node.js debugger
+     * and set a breakpoint inside the `debuggerFunction`.
+     *
+     * @param debuggerFunction
+     * @param values
+     */
+    static values<Values extends Array<Answerable<unknown>>>(debuggerFunction: (
+        results: { [ Index in keyof Values ]: DebuggingResult<Values[Index]> },
+        ...answers: { [ Index in keyof Values ]: Answered<Values[Index]> }
+    ) => Promise<void> | void, ...values: Values): Interaction {
+        /* istanbul ignore next can't test using a debugger in an automated test */
+        return new Debug<Values>(
+            `#actor debugs ${ values.length } values`,
+            debuggerFunction,
+            values
+        );
+    }
+
+    /**
+     * @param description
+     *  Description of this interaction
+     *
+     * @param debuggerFunction
+     *  Callback function to receive the results of debugging
+     *
+     * @param values
+     *  Value to be evaluated by the actor, and provided to debuggerFunction
+     */
+    protected constructor(
+        description: string,
+        private readonly debuggerFunction: (
+            debuggingResults: { [ Index in keyof Values ]: DebuggingResult<Values[Index]> },
+            ...args: { [ Index in keyof Values ]: Answered<Values[Index]> }
+        ) => Promise<void> | void,
+        private readonly values: Values,
+    ) {
+        super(description);
+    }
+
+    /**
+     * @inheritDoc
+     */
+    async performAs(actor: UsesAbilities & AnswersQuestions & CollectsArtifacts): Promise<void> {
+
+        const results = [] as { [ Index in keyof Values ]: DebuggingResult<Values[Index]> };
+
+        for (const value of this.values) {
+
+            const result: DebuggingResult<unknown> = {
+                description: d`${ value }`,
+                value: undefined,
+                error: undefined,
+            };
+
+            try {
+                result.value = await actor.answer(value);
+            }
+            catch (error) {
+                result.error = error;
+            }
+
+            actor.collect(
+                LogEntry.fromJSON({
+                    data: JSON.stringify({
+                        value: stringified(result.value),
+                        error: result.error
+                            ? ErrorSerialiser.serialise(result.error)
+                            : result.error
+                    }),
+                }),
+                new Name(result.description)
+            );
+
+            results.push(result);
+        }
+
+        this.debuggerFunction(
+            results,
+            ...results.map(result => result.value) as { [ Index in keyof Values ]: Answered<Values[Index]> }
+        );
+    }
+}

package/src/screenplay/debugging/DebuggingResult.ts

@@ -0,0 +1,10 @@
+/**
+ * An interface describing debugging data received by the callback function passed to {@apilink Debug.values}.
+ *
+ * @group Activities
+ */
+export interface DebuggingResult<T> {
+    description: string;
+    value: T | undefined;
+    error: Error | undefined;
+}

package/src/screenplay/debugging/Log.ts

@@ -0,0 +1,68 @@
+import { d } from '../../io';
+import { stringified } from '../../io/stringified';
+import { LogEntry, Name } from '../../model';
+import { UsesAbilities } from '../abilities';
+import { Answerable } from '../Answerable';
+import { CollectsArtifacts } from '../artifacts';
+import { Interaction } from '../Interaction';
+import { AnswersQuestions } from '../questions';
+
+/**
+ * Instructs the {@apilink Actor} to {@apilink CollectsArtifacts|collect} arbitrary static values and answers to {@apilink Answerable|Answerables},
+ * so that they can be sent to the {@apilink StageCrewMember|StageCrewMembers}
+ * and printed to the terminal by the {@apilink ConsoleReporter}
+ * or attached to the HTML report by the {@apilink SerenityBDDReporter}.
+ *
+ * ## Logging static and `Answerable` values
+ *
+ * ```ts
+ * import { actorCalled, Log } from '@serenity-js/core'
+ * import { Page } from '@serenity-js/web'
+ *
+ * await actorCalled('Laura').attemptsTo(
+ *   Log.the('Current page', Page.current().title(), Page.current().url()),
+ * )
+ * ```
+ *
+ * @group Activities
+ */
+export class Log extends Interaction {
+
+    /**
+     * Instantiates a new {@apilink Interaction|interaction} to {@apilink Log}
+     *
+     * Note that this method accepts [variable number of arguments](https://www.typescriptlang.org/docs/handbook/functions.html#rest-parameters),
+     * so that you can easily log several values at the same time.
+     *
+     * @param items
+     *  The items to be logged
+     */
+    static the(...items: Array<Answerable<any>>): Interaction {
+        return new Log(items);
+    }
+
+    /**
+     * @param items
+     *  The items to be logged
+     */
+    protected constructor(
+        private readonly items: Array<Answerable<any>>,
+    ) {
+        super(`#actor logs: ${ items.map(item => d`${ item }`).join(', ') }`);
+    }
+
+    /**
+     * @inheritDoc
+     */
+    async performAs(actor: UsesAbilities & AnswersQuestions & CollectsArtifacts): Promise<void> {
+        for (const item of this.items) {
+
+            const data = await actor.answer(item);
+
+            actor.collect(
+                LogEntry.fromJSON({ data: stringified(data) }),
+                new Name(d`${ item }`)
+            );
+        }
+    }
+}

package/src/screenplay/debugging/index.ts

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

package/src/screenplay/index.ts

@@ -1,12 +1,17 @@
 export * from './abilities';
-export * from './Ability';
-export * from './AbilityType';
+export * from './activities';
 export * from './Activity';
-export * from './actor';
+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 './interactions';
+export * from './notes';
 export * from './Optional';
 export * from './Question';
 export * from './questions';
+export * from './RecursivelyAnswered';
 export * from './Task';
+export * from './time';
+export * from './WithAnswerableProperties';

package/src/screenplay/notes/ChainableSetter.ts

@@ -0,0 +1,9 @@
+import { Answerable } from '../Answerable';
+import { Interaction } from '../Interaction';
+
+/**
+ * @group Notes
+ */
+export interface ChainableSetter<T extends Record<any, any>> {
+    set<K extends keyof T>(key: K, value: Answerable<T[K]>): ChainableSetter<T> & Interaction;
+}

package/src/screenplay/notes/Notepad.ts

@@ -0,0 +1,208 @@
+import { TinyType } from 'tiny-types';
+
+import { LogicError } from '../../errors';
+import { d } from '../../io';
+import { NotepadAdapter } from './NotepadAdapter';
+
+/**
+ * Stores notes recorded by an {@apilink Actor}.
+ *
+ * See {@apilink TakeNotes} and [notes](/api/core/function/notes) for more usage examples.
+ *
+ * ## Sharing a notepad between actors
+ *
+ * ```ts
+ * import { Actor, Cast, Notepad, TakeNotes } from '@serenity-js/core'
+ *
+ * interface MyNotes {
+ *   auth: {
+ *     username: string;
+ *     password: string;
+ *   }
+ * }
+ *
+ * export class Actors implements Cast {
+ *
+ *   // initialise a shared notepad when the Actors class is initialised
+ *   private readonly sharedNotepad = Notepad.with<MyNotes>({
+ *     auth: {
+ *       username: 'test-user',
+ *       password: 'SuperSecretP@ssword!',
+ *     }
+ *   });
+ *
+ *   prepare(actor: Actor): Actor {
+ *     switch (actor.name) {
+ *       case 'Alice':
+ *       case 'Bob':
+ *         // Alice and Bob will share their notepad
+ *         return actor.whoCan(TakeNotes.using(this.sharedNotepad));
+ *       default:
+ *         // other actors will get their own notepads
+ *         return actor.whoCan(TakeNotes.using(Notepad.empty<AuthCredentials>()));
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * ## Learn more
+ *
+ * - {@apilink TakeNotes}
+ * - [notes](/api/core/function/notes)
+ * - {@apilink Cast}
+ *
+ * @group Notes
+ */
+export class Notepad<Notes extends Record<any, any>> extends TinyType {
+
+    /**
+     * Instantiates a new empty Notepad.
+     */
+    static empty<N extends Record<any, any>>(): Notepad<N> {
+        return new Notepad<N>({} as N);
+    }
+
+    /**
+     * Instantiates a new Notepad with an initial state.
+     *
+     * ```ts
+     * import { actorCalled, Notepad, notes, TakeNotes } from '@serenity-js/core'
+     * import { Ensure, equals } from '@serenity-js/assertions'
+     *
+     * interface MyNotes {
+     *   personalDetails: {
+     *     firstName: string;
+     *     lastName: string;
+     *   }
+     * }
+     *
+     * actorCalled('Leonard')
+     *   .whoCan(
+     *     TakeNotes.using(
+     *       Notepad.with<MyNotes>({
+     *         personalDetails: {
+     *           firstName: 'Leonard',
+     *           lastName: 'McLaud',
+     *         }
+     *       })
+     *     )
+     *   )
+     *   .attemptsTo(
+     *     Ensure.that(
+     *       notes<MyNotes>().get('personalDetails').firstName,
+     *       equals('Leonard')
+     *     ),
+     *   )
+     * ```
+     *
+     * @param notes
+     */
+    static with<N extends Record<any, any>>(notes: N): Notepad<N> {
+        return new Notepad<N>(notes);
+    }
+
+    /**
+     * Creates a {@apilink QuestionAdapter} that simplifies access to the notes
+     * stored in this notepad. Allows the {@apilink Actor} to record, read, and remove notes.
+     *
+     * #### Learn more
+     * - [notes](/api/core/function/notes)
+     * - {@apilink TakeNotes}
+     * - {@apilink Notepad}
+     */
+    static notes<N extends Record<any, any>>(): NotepadAdapter<N> {
+        return new NotepadAdapter<N>();
+    }
+
+    /**
+     * Instantiates a {@apilink Notepad} with an initial state.
+     *
+     * @param recordedNotes
+     *  Initial state of the notepad
+     */
+    protected constructor(private readonly recordedNotes: Notes) {
+        super();
+    }
+
+    /**
+     * Checks if a note identified by `subject` exists in the notepad.
+     *
+     * @param subject
+     *   A subject (name) that uniquely identifies a given note
+     *
+     * @returns
+     *  `true` if the note exists, `false` otherwise
+     */
+    has<Subject extends keyof Notes>(subject: Subject): boolean {
+        return Object.prototype.hasOwnProperty.call(this.recordedNotes, subject);
+    }
+
+    /**
+     * Retrieves a note, identified by `subject`, from the notepad.
+     *
+     * @param subject
+     *   A subject (name) that uniquely identifies a given note
+     *
+     * @returns
+     *  The value of the previously recorded note.
+     *
+     * @throws {@apilink LogicError}
+     *  Throws a {@apilink LogicError} if the note with a given `subject`
+     *  has never been recorded.
+     */
+    get<Subject extends keyof Notes>(subject: Subject): Notes[Subject] {
+        if (! this.has(subject)) {
+            throw new LogicError(d`Note of ${ subject } cannot be retrieved because it's never been recorded`);
+        }
+
+        return this.recordedNotes[subject];
+    }
+
+    /**
+     * Stores a given `value` uniquely identified by `subject` in the notepad.
+     *
+     * @param subject
+     *  A subject (name) that uniquely identifies a given note
+     *
+     * @param value
+     *  The value to record.
+     */
+    set<Subject extends keyof Notes>(subject: Subject, value: Notes[Subject]): Notepad<Notes> {
+        this.recordedNotes[subject] = value;
+        return this;
+    }
+
+    /**
+     * Removes the note identified by `subject` from the notepad.
+     *
+     * @param subject
+     *
+     * @returns
+     *  `true` if the item in the Notepad object existed and has been removed,
+     *  `false` otherwise.
+     */
+    delete<Subject extends keyof Notes>(subject: Subject): boolean {
+        if (this.has(subject)) {
+            return delete this.recordedNotes[subject];
+        }
+        return false;
+    }
+
+    /**
+     * Deletes all the notes stored in this notepad.
+     */
+    clear(): void {
+        const keys = Object.keys(this.recordedNotes);
+
+        for (const key of keys) {
+            this.delete(key);
+        }
+    }
+
+    /**
+     * Returns the number of notes stored in the notepad.
+     */
+    size(): number {
+        return Object.keys(this.recordedNotes).length;
+    }
+}