@serenity-js/core 2.33.1 → 3.0.0-rc.11

package/src/screenplay/questions/proxies/createQuestionProxy.ts

@@ -1,49 +0,0 @@
-/* eslint-disable @typescript-eslint/ban-types */
-import { formatted } from '../../../io';
-import { Answerable } from '../../Answerable';
-import { Question } from '../../Question';
-import { describePath } from './describePath';
-import { key } from './key';
-import { PropertyPathKey } from './PropertyPathKey';
-
-/**
- * @package
- */
-export type WithPropertiesAsQuestions<Original_Type> = {
-    [Key in keyof Original_Type]: Original_Type[Key] extends object
-        ? Question<Promise<Original_Type[Key]>> & WithPropertiesAsQuestions<Original_Type[Key]>
-        : Question<Promise<Original_Type[Key]>>
-}
-
-/**
- * @package
- */
-export function createQuestionProxy<Original_Type extends object>(subject: Answerable<Original_Type>, path: PropertyPathKey[] = []): WithPropertiesAsQuestions<Original_Type> {
-
-    const empty = {};
-
-    return new Proxy<Original_Type>(empty as any, {
-        get(target: unknown, name: PropertyPathKey) {
-
-            if (key(name).isOneOf<Question<any>>('answeredBy', 'describedAs', 'map', 'toString')) {
-
-                const question = Question.about(formatted `property ${ describePath(path) } of ${ subject }`, actor => {
-                    return actor.answer(subject).then(answer => {
-
-                        return path.reduce((subObject, keyName, index) => {
-                            if (keyName in subObject) {
-                                return subObject[keyName];
-                            }
-                            throw new Error(formatted `property ${ describePath(path.slice(0, index + 1)) } of ${ subject } doesn't exist`);
-                        }, answer);
-
-                    })
-                });
-
-                return question[name].bind(question);   // eslint-disable-line unicorn/prefer-prototype-methods
-            }
-
-            return createQuestionProxy(subject, path.concat(name));
-        }
-    }) as WithPropertiesAsQuestions<Original_Type>;
-}

package/src/screenplay/questions/proxies/describePath.ts

@@ -1,23 +0,0 @@
-import { PropertyPathKey } from './PropertyPathKey';
-
-/**
- * @package
- */
-export function describePath(parts: PropertyPathKey[]): string {
-    return parts.reduce(
-        (acc, segment) =>
-            acc.concat(
-                isNumber(segment)
-                    ? `[${ segment }]`
-                    : segment
-            ),
-        [],
-    ).join('.');
-}
-
-/**
- * @private
- */
-function isNumber(segment: PropertyPathKey): segment is number {
-    return Number.parseInt(String(segment), 10).toString() === segment;
-}

package/src/screenplay/questions/proxies/index.ts

@@ -1,2 +0,0 @@
-export * from './createMetaQuestionProxy';
-export * from './createQuestionProxy';

package/src/screenplay/questions/proxies/key.ts

@@ -1,14 +0,0 @@
-/* eslint-disable @typescript-eslint/ban-types,@typescript-eslint/explicit-module-boundary-types */
-import { PropertyPathKey } from './PropertyPathKey';
-
-/**
- * @package
- * @param {PropertyPathKey} keyName
- */
-export function key(keyName: PropertyPathKey) {
-    return {
-        isOneOf<T extends object = object>(...keys: Array<keyof T>) {
-            return !!~keys.indexOf(keyName as any);
-        }
-    }
-}

package/src/screenplay/tasks/Loop.ts

@@ -1,240 +0,0 @@
-import { formatted, Reducible } from '../../io';
-import { Activity } from '../Activity';
-import { AnswersQuestions, PerformsActivities, UsesAbilities } from '../actor';
-import { Answerable } from '../Answerable';
-import { Question } from '../Question';
-import { Task } from '../Task';
-
-/**
- * @desc
- *  Enables the {@link Actor} to iterate over a list of items produced by any {@link Answerable}.
- *
- *  You can think of `Loop` as a more sophisticated Screenplay-style equivalent of
- *  [`Array.forEach`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach).
- *  `Loop` is capable of working with both synchronous data structures,
- *  such as [`Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)
- *  and `Question<Array<T>>`,
- *  as well as asynchronous ones, so `Promise<Array<T>>` and `Question<Promise<Array<T>>>`.
- *
- *  Use {@link Loop.item} to access the current item being processed by {@link Loop}, and {@link Loop.index}
- *  to access the index of {@link Loop.item} in the list.
- *
- * @example <caption>Basic scenario - Iterating over a static list of items</caption>
- *  import { actorCalled, Loop, Log } from '@serenity-js/core';
- *
- *  actorCalled('Joe').attemptsTo(
- *      Loop.over([ 'apple', 'banana', 'candy' ]).to(
- *          Log.the('current element', Loop.item<string>()),
- *          Log.the('current index', Loop.index()),
- *      ),
- *  );
- *
- * @example <caption>API scenario - Iterating over items in an API response</caption>
- *
- *  import { actorCalled, Loop } from '@serenity-js/core';
- *  import { Send, GetRequest, CallAnApi, LastResponse } from '@serenity-js/rest';
- *  import { Ensure, property, isGreaterThan } from '@serenity-js/assertions';
- *
- *  interface TodoItem {
- *      userId: number;
- *      id: number;
- *      title: string;
- *      completed: boolean;
- *  }
- *
- *  actorCalled('Joe').whoCan(
- *      CallAnApi.at('https://jsonplaceholder.typicode.com')
- *  ).attemptsTo(
- *      Send.a(GetRequest.to('/todos')),
- *      Loop.over(LastResponse.body<TodoItem[]>()).to(
- *          Ensure.that(
- *              Loop.item<TodoItem>(),
- *              property('userId', isGreaterThan(0)),
- *          ),
- *      )
- *  );
- *
- * @example <caption>UI scenario - Example widget</caption>
- *  <nav>
- *      <div data-test="cookies">
- *          <label for="functional-cookies">
- *              <input type="checkbox" id="functional-cookies" />Allow functional cookies
- *          </label>
- *          <label for="performance-cookies">
- *              <input type="checkbox" id="performance-cookies" />Allow performance cookies
- *          </label>
- *          <label for="advertising-cookies">
- *              <input type="checkbox" id="advertising-cookies" />Allow advertising cookies
- *          </label>
- *      </div>
- *  </nav>
- *
- * @example <caption>UI scenario - Lean Page Object</caption>
- *  import { Target } from '@serenity-js/protractor';
- *  import { browser, by } from 'protractor';
- *
- *  class Cookies {
- *      static labels = Target.all('cookie options')
- *          .located(by.css('[data-test="cookies"]'));
- *
- *      static checkbox = Target.the('checkbox')
- *          .located(by.tagName('input')),
- *  }
- *
- * @example <caption>UI scenario - Performing the same set of activities with each element</caption>
- *  import { actorCalled, Loop } from '@serenity-js/core';
- *  import { Click, Text, isSelected } from '@serenity-js/protractor';
- *  import { Ensure, startsWith } from '@serenity-js/assertions';
- *  import { protractor } from 'protractor';
- *
- *  actorCalled('Joe')
- *      .whoCan(BrowseTheWeb.using(protractor.browser))
- *      .attemptsTo(
- *          Loop.over(Cookies.labels).to(
- *               Ensure.that(
- *                  Text.of(Loop.item<ElementFinder>()),
- *                  startsWith('Allow'),
- *              ),
- *
- *              Click.on(Loop.item<ElementFinder>()),
- *              Ensure.that(
- *                  Cookies.checkbox.of(Loop.item<ElementFinder>()),
- *                  isSelected(),
- *              ),
- *          ),
- *      );
- *
- * @extends {Task}
- *
- * @see {@link Loop.item}
- * @see {@link Loop.index}
- * @see {@link Question}
- */
-export class Loop<Item> extends Task {
-    private static currentItem: unknown = undefined;
-    private static currentIndex = 0;
-
-    /**
-     * @desc
-     *  Instantiates a {@link Task} to {@link Loop}
-     *  that enables the {@link Actor} to iterate over `items`
-     *  to perform some `activities`.
-     *
-     * @param {items: Answerable<ReducibleCollection>} items
-     * @returns {LoopBuilder}
-     */
-    static over<T>(items: Answerable<Reducible>): { to: (...activities: Activity[]) => Loop<T> } {
-        return {
-            to: (...activities: Activity[]) =>
-                new Loop<T>(items, activities)
-        }
-    }
-
-    /**
-     * @desc
-     *  Returns the current item being processed by {@link Loop.over}.
-     *
-     *  **Please note** that in order for the TypeScript transpiler to understand the exact `ExpectedType`
-     *  of the {@link Question} produced by this method you can optionally configure it with
-     *  a [_type variable_](https://www.typescriptlang.org/docs/handbook/generics.html).
-     *
-     *  For example, configuring the method with type variable of `string`, so `Loop.item<string>()`,
-     *  tells the transpiler that a `Question<string>` will be returned.
-     *
-     *  If the type variable is not configured, the transpiler assumes that returned type is a
-     *  `Question<any>`. This means that while your code could still work, you'd miss out
-     *  on checking provided by TypeScript.
-     *
-     * @returns {Question<ExpectedType>}
-     */
-    static item<ExpectedType = any>(): Question<ExpectedType> {
-        return Question.about<ExpectedType>(`current loop item`, actor =>
-            Loop.currentItem as ExpectedType,
-        );
-    }
-
-    /**
-     * @desc
-     *  Returns the index of current {@link Loop.item} in the `Answerable<Array>` given to {@link Loop.over}.
-     *
-     *  The index starts at `0`.
-     *
-     * @returns {Question<number>}
-     */
-    static index(): Question<number> {
-        return Question.about<number>(`current loop index`, actor =>
-            Loop.currentIndex,
-        );
-    }
-
-    /**
-     * @param {Answerable<Reducible>} items
-     * @param {Activity[]} activities
-     */
-    constructor(
-        private readonly items: Answerable<Reducible>,
-        private readonly activities: Activity[]
-    ) {
-        super();
-    }
-
-    /**
-     * @desc
-     *  Makes the provided {@link Actor}
-     *  perform this {@link Task}.
-     *
-     * @param {PerformsActivities & UsesAbilities & AnswersQuestions} actor
-     * @returns {Promise<void>}
-     *
-     * @see {@link Actor}
-     * @see {@link PerformsActivities}
-     * @see {@link UsesAbilities}
-     * @see {@link AnswersQuestions}
-     */
-    performAs(actor: PerformsActivities & UsesAbilities & AnswersQuestions): PromiseLike<void> | PromiseLike<any> {
-        return actor.answer(this.items)
-            .then(items =>
-                items.reduce((previous: Promise<void>, current: Item, index: number) => {
-                    return previous.then(() => {
-                        Loop.currentIndex = index;
-                        Loop.currentItem  = current;
-
-                        return actor.attemptsTo(
-                            ...this.activities
-                        );
-                    });
-                }, Promise.resolve(void 0))
-            );
-    }
-
-    /**
-     * @desc
-     *  Generates a description to be used when reporting this {@link Activity}.
-     *
-     * @returns {string}
-     */
-    toString(): string {
-        const description =  Array.isArray(this.items)
-            ? `a list of ${ this.items.length } item${ this.items.length !== 1 ? 's' : '' }`
-            : formatted `${ this.items }`;
-
-        return `#actor loops over ${ description }`;
-    }
-}
-
-/**
- * @typedef {Object} LoopBuilder
- * @property {function(...activities: Activity[]): Loop} to
- *
- * @example <caption>Basic scenario - Iterating over a static list of items</caption>
- *  import { actorCalled, Loop, Log } from '@serenity-js/core';
- *
- *  actorCalled('Joe').attemptsTo(
- *      Loop.over([ 'apple', 'banana', 'candy' ]).to(
- *          Log.the('current element', Loop.item<string>()),
- *      ),
- *  );
- *
- * @see {@link Loop}
- * @see {@link Loop.over}
- */

package/src/screenplay/tasks/index.ts

@@ -1 +0,0 @@
-export * from './Loop';

package/src/stage/DressingRoom.ts

@@ -1,53 +0,0 @@
-import { Ability, Actor } from '../screenplay';
-
-/**
- * @desc
- *  Prepares the {@link Actor} for the performance.
- *
- * @example <caption>A dressing room for actors interacting with a Web UI</caption>
- *
- *  import { serenity, Actor, DressingRoom } from '@serenity-js/core'
- *  import { BrowseTheWeb } from '@serenity-js/protractor'
- *  import { protractor } from 'protractor'
- *
- *  class UIActors implements DressingRoom {
- *      prepare(actor: Actor) {
- *          return actor.whoCan(BrowseTheWeb.using(protractor.browser));
- *      }
- *  }
- *
- *  const stage = serenity.callToStageFor(new UIActors());
- *
- * @see {@link Stage}
- * @see {@link Cast}
- * @interface
- *
- * @deprecated Please use the Cast instead
- */
-export abstract class DressingRoom {
-    /**
-     * @desc
-     *  Creates a generic `DressingRoom` implementation, where every actor
-     *  is given all the abilities specified when the method is called.
-     *
-     * @param {Ability[]} abilities
-     * @returns {DressingRoom}
-     */
-    static whereEveryoneCan(...abilities: Ability[]): DressingRoom {
-        return new GenericDressingRoom(abilities);
-    }
-
-    abstract prepare(actor: Actor): Actor;
-}
-
-/**
- * @package
- */
-class GenericDressingRoom implements DressingRoom {
-    constructor(private readonly abilities: Ability[]) {
-    }
-
-    prepare(actor: Actor): Actor {
-        return actor.whoCan(...this.abilities);
-    }
-}

package/src/stage/WithStage.ts

@@ -1,52 +0,0 @@
-import { Stage } from './Stage';
-
-/**
- * @desc Makes the {@link Stage} object setup in your test runner configuration visible
- * to test steps or test scenarios.
- *
- * When using Cucumber, the {@link Stage} is typically set up using the Cucumber World Constructor.
- * When using Jasmine, the {@link Stage} is typically set up in the `beforeEach` step.
- *
- * @see https://github.com/cucumber/cucumber-js/blob/v5.0.1/docs/support_files/api_reference.md
- * @see https://github.com/cucumber/cucumber-js/blob/v5.0.1/docs/support_files/step_definitions.md
- * @see https://www.typescriptlang.org/docs/handbook/functions.html#this-parameters
- *
- * @example <caption>Usage with Cucumber.js</caption>
- * // features/support/configure_serenity.ts
- * import { WithStage } from '@serenity-js/core';
- * import { setWorldConstructor } from 'cucumber';
- *
- * setWorldConstructor(function (this: WithStage, { parameters }) {
- *   this.stage = serenity.callToStageFor(new SomeImplementationOfTheCastInterface());
- * });
- *
- * // features/step_definitions/some.steps.ts
- * import { WithStage } from '@serenity-js/cucumber';
- *
- * Given(/(.*?) is a registered customer/, function (this: WithStage, actorName: string) {
- *   return this.stage.actor(actorName).attemptsTo(
- *
- *   );
- * });
- *
- * @example <caption>Usage with Jasmine</caption>
- * // spec/some.spec.ts
- * import { serenity, WithStage } from '@serenity-js/core';
- *
- * describe('Using the Stage', () => {
- *   beforeEach(function (this: WithStage) {
- *     this.stage = serenity.callToStageFor(new SomeImplementationOfTheCastInterface());
- *   });
- *
- *   it('makes it easy to access the Actors', function(this: WithStage) {
- *     return this.stage.theActorCalled('Barry').attemptsTo(
- *       // tasks
- *     );
- *   })
- * });
- *
- * @deprecated Please use serenity.actor() and serenity.actorInTheSpotlight() instead
- */
-export interface WithStage {
-    stage: Stage;
-}