@serenity-js/core 3.0.0-rc.8 → 3.0.0

package/src/screenplay/actor/Actor.ts

@@ -1,243 +0,0 @@
-import { ConfigurationError, TestCompromisedError } from '../../errors';
-import { ActivityRelatedArtifactGenerated } from '../../events';
-import { Artifact, Name } from '../../model';
-import { Ability, AbilityType, Answerable, Discardable, Initialisable } from '../../screenplay';
-import { Stage } from '../../stage';
-import { TrackedActivity } from '../activities';
-import { Activity } from '../Activity';
-import { Question } from '../Question';
-import { AnswersQuestions } from './AnswersQuestions';
-import { CanHaveAbilities } from './CanHaveAbilities';
-import { CollectsArtifacts } from './CollectsArtifacts';
-import { PerformsActivities } from './PerformsActivities';
-import { UsesAbilities } from './UsesAbilities';
-
-export class Actor implements
-    PerformsActivities,
-    UsesAbilities,
-    CanHaveAbilities<Actor>,
-    AnswersQuestions,
-    CollectsArtifacts
-{
-    // todo: Actor should have execution strategies
-    // todo: the default one executes every activity
-    // todo: there could be a dry-run mode that default to skip strategy
-
-    constructor(
-        public readonly name: string,
-        private readonly stage: Stage,
-        private readonly abilities: Map<AbilityType<Ability>, Ability> = new Map<AbilityType<Ability>, Ability>(),
-    ) {
-    }
-
-    /**
-     * @desc
-     *  Retrieves actor's {@link Ability} to `doSomething`.
-     *
-     *  Please note that this method performs an [`instancepf`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/instanceof)
-     *  check against abilities given to this actor via {@link Actor#whoCan}. Please also note that {@link Actor#whoCan} performs
-     *  the same check when abilities are assigned to the actor to ensure the actor has at most one instance of a given ability type.
-     *
-     * @param doSomething
-     */
-    abilityTo<T extends Ability>(doSomething: AbilityType<T>): T {
-        const found = this.findAbilityTo(doSomething);
-
-        if (! found) {
-            throw new ConfigurationError(`${ this.name } can't ${ doSomething.name } yet. ` +
-                `Did you give them the ability to do so?`);
-        }
-
-        return found;
-    }
-
-    /**
-     * @desc
-     *  Instructs the actor to attempt to perform a number of activities
-     *  (see {@link Activity}, so either {@link Task}s or {@link Interaction}s)
-     *  one by one.
-     *
-     * @param {...activities: Activity[]} activities
-     * @return {Promise<void>}
-     */
-    attemptsTo(...activities: Activity[]): Promise<void> {
-        return activities
-            .map(activity => new TrackedActivity(activity, this.stage))
-            .reduce((previous: Promise<void>, current: Activity) => {
-                return previous
-                    // synchronise async operations like taking screenshots
-                    .then(() => this.stage.waitForNextCue())
-                    .then(() =>{
-                        /* todo: add an execution strategy */
-                        return current.performAs(this);
-                    });
-            }, this.initialiseAbilities());
-    }
-
-    /**
-     * @desc
-     *  Gives this Actor a list of abilities (see {@link Ability}) they can use
-     *  to interact with the system under test or the test environment.
-     *
-     * @param {...Ability[]} abilities
-     *  A vararg list of abilities to give the actor
-     *
-     * @returns {Actor}
-     *  The actor with newly gained abilities
-     *
-     * @throws {ConfigurationError}
-     *  Throws a ConfigurationError if the actor already has an ability of this type.
-     */
-    whoCan(...abilities: Ability[]): Actor {
-        abilities.forEach(ability => {
-            const abilityType = ability.constructor as AbilityType<Ability>;
-
-            const found = this.findAbilityTo(abilityType);
-
-            if (found) {
-                const description = found.constructor.name === abilityType.name
-                    ? found.constructor.name
-                    : `${ found.constructor.name } (which extends ${ abilityType.name })`
-
-                throw new ConfigurationError(`${ this.name } already has an ability to ${ description }, so you don't need to give it to them again.`);
-            }
-
-            this.abilities.set(ability.constructor as AbilityType<Ability>, ability);
-        });
-
-        return this;
-    }
-
-    /**
-     * @param {Answerable<T>} answerable - a Question<Promise<T>>, Question<T>, Promise<T> or T
-     * @returns {Promise<T>} The answer to the Answerable
-     */
-    answer<T>(answerable: Answerable<T>): Promise<T> {
-        function isAPromise<V>(v: Answerable<V>): v is Promise<V> {
-            return Object.prototype.hasOwnProperty.call(v, 'then');
-        }
-
-        function isDefined<V>(v: Answerable<V>) {
-            return ! (v === undefined || v === null);
-        }
-
-        if (isDefined(answerable) && isAPromise(answerable)) {
-            return answerable;
-        }
-
-        if (isDefined(answerable) && Question.isAQuestion(answerable)) {
-            return this.answer(answerable.answeredBy(this));
-        }
-
-        return Promise.resolve(answerable as T);
-    }
-
-    /**
-     * @desc
-     *  Announce collection of an {@link Artifact} so that it can be picked up by a {@link StageCrewMember}.
-     *
-     * @param {Artifact} artifact
-     * @param {?(string | Name)} name
-     *
-     * @returns {void}
-     */
-    collect(artifact: Artifact, name?: string | Name): void {
-        this.stage.announce(new ActivityRelatedArtifactGenerated(
-            this.stage.currentSceneId(),
-            this.stage.currentActivityId(),
-            this.nameFrom(name || new Name(artifact.constructor.name)),
-            artifact,
-            this.stage.currentTime(),
-        ));
-    }
-
-    /**
-     * @desc
-     *  Instructs the actor to invoke {@link Discardable#discard} method on any
-     *  {@link Discardable} {@link Ability} it's been configured with.
-     *
-     * @returns {Promise<void>}
-     */
-    dismiss(): Promise<void> {
-        return this.findAbilitiesOfType<Discardable>('discard')
-            .reduce(
-                (previous: Promise<void>, ability: (Discardable & Ability)) =>
-                    previous.then(() => ability.discard()),
-                Promise.resolve(void 0),
-            ) as Promise<void>;
-    }
-
-    /**
-     * @desc
-     *  Returns a human-readable, string representation of this Actor
-     *
-     * @returns {string}
-     */
-    toString(): string {
-        const abilities = Array.from(this.abilities.keys()).map(type => type.name);
-
-        return `Actor(name=${ this.name }, abilities=[${ abilities.join(', ') }])`;
-    }
-
-    /**
-     * @private
-     */
-    private initialiseAbilities(): Promise<void> {
-        return this.findAbilitiesOfType<Initialisable>('initialise', 'isInitialised')
-            .filter(ability => ! ability.isInitialised())
-            .reduce(
-                (previous: Promise<void>, ability: (Initialisable & Ability)) =>
-                    previous
-                        .then(() => ability.initialise())
-                        .catch(error => {
-                            throw new TestCompromisedError(`${ this.name } couldn't initialise the ability to ${ ability.constructor.name }`, error);
-                        }),
-                Promise.resolve(void 0),
-            )
-    }
-
-    /**
-     * @param {...string[]} methodNames
-     * @private
-     */
-    private findAbilitiesOfType<T>(...methodNames: Array<keyof T>): Array<Ability & T> {
-        const abilitiesFrom = (map: Map<AbilityType<Ability>, Ability>): Ability[] =>
-            Array.from(map.values());
-
-        const abilitiesWithDesiredMethods = (ability: Ability & T): boolean =>
-            methodNames.every(methodName => typeof(ability[methodName]) === 'function');
-
-        return abilitiesFrom(this.abilities)
-            .filter(abilitiesWithDesiredMethods) as Array<Ability & T>;
-    }
-
-    /**
-     * @param {string} doSomething
-     * @private
-     */
-    private findAbilityTo<T extends Ability>(doSomething: AbilityType<T>): T | undefined {
-        for (const [abilityType_, ability] of this.abilities) {
-            if (ability instanceof doSomething) {
-                return ability as T;
-            }
-        }
-
-        return undefined;
-    }
-
-    /**
-     * @desc
-     *  Instantiates a {@link Name} based on the string value of the parameter,
-     *  or returns the argument if it's already an instance of {@link Name}.
-     *
-     * @param {string | Name} maybeName
-     * @returns {Name}
-     *
-     * @private
-     */
-    private nameFrom(maybeName: string | Name): Name {
-        return typeof maybeName === 'string'
-            ? new Name(maybeName)
-            : maybeName;
-    }
-}

package/src/screenplay/actor/AnswersQuestions.ts

@@ -1,11 +0,0 @@
-import { Answerable } from '../Answerable';
-
-/**
- * @desc
- *  Enables the {@link Actor} to answer a {@link Question} about the system under test
- *
- * @public
- */
-export interface AnswersQuestions {
-    answer<T>(knownUnknown: Answerable<T>): Promise<T>;
-}

package/src/screenplay/actor/CanHaveAbilities.ts

@@ -1,16 +0,0 @@
-import { Ability } from '../Ability';
-import { UsesAbilities } from './UsesAbilities';
-
-/**
- * @desc
- *  Enables the {@link Actor} to have an {@link Ability} or Abilities to perform some {@link Activity}.
- *
- * @public
- */
-export interface CanHaveAbilities<Returned_Type = UsesAbilities> {
-    /**
-     * @param {Ability[]} abilities
-     * @returns {Actor}
-     */
-    whoCan(...abilities: Ability[]): Returned_Type;
-}

package/src/screenplay/actor/CollectsArtifacts.ts

@@ -1,18 +0,0 @@
-import { Artifact, Name } from '../../model';
-
-/**
- * @desc
- *  Enables the {@link Actor} to collect {@link Artifact}s while the scenario is being executed
- *
- * @public
- */
-export interface CollectsArtifacts {
-    /**
-     * @desc
-     * Makes the {@link Actor} collect an {@link Artifact} so that it's included in the test report.
-     *
-     * @param {Artifact} artifact - The artifact to be collected, such as {@link JSONData}
-     * @param {Name} [name] - The name of the artifact to make it easy to recognise in the test report
-     */
-    collect(artifact: Artifact, name?: Name): void;
-}

package/src/screenplay/actor/PerformsActivities.ts

@@ -1,11 +0,0 @@
-import { Activity } from '../Activity';
-
-/**
- * @desc
- *  Enables the {@link Actor} to perform an {@link Activity}, such as a {@link Task} or an {@link Interaction}
- *
- * @public
- */
-export interface PerformsActivities {
-    attemptsTo(...tasks: Activity[]): Promise<void>;
-}

package/src/screenplay/actor/UsesAbilities.ts

@@ -1,20 +0,0 @@
-import { Ability } from '../Ability';
-import { AbilityType } from '../AbilityType';
-
-/**
- * @desc
- *  Enables the {@link Actor} to use an {@link Ability} to perform some {@link Activity}.
- *
- * @public
- */
-export interface UsesAbilities {
-
-    /**
-     * @desc
-     *  Grants access to the Actor's ability
-     *
-     * @param {AbilityType<T extends Ability>} doSomething
-     * @returns {T}
-     */
-    abilityTo<T extends Ability>(doSomething: AbilityType<T>): T;
-}

package/src/screenplay/actor/index.ts

@@ -1,6 +0,0 @@
-export * from './Actor';
-export * from './AnswersQuestions';
-export * from './CanHaveAbilities';
-export * from './CollectsArtifacts';
-export * from './PerformsActivities';
-export * from './UsesAbilities';

package/src/screenplay/interactions/Log.ts

@@ -1,81 +0,0 @@
-import { formatted } from '../../io';
-import { inspected } from '../../io/inspected';
-import { Name } from '../../model';
-import { LogEntry } from '../../model/artifacts';
-import { AnswersQuestions, CollectsArtifacts, UsesAbilities } from '../actor';
-import { Answerable } from '../Answerable';
-import { Interaction } from '../Interaction';
-
-/**
- * @desc
- *  Enables the {@link Actor} to log arbitrary static values and answers to {@link Question}s,
- *  so that they can be printed to the terminal by the [`ConsoleReporter`](/modules/console-reporter/)
- *  and attached to the HTML report by the [`SerenityBDDReporter`](/modules/serenity-bdd/).
- *
- * @example
- *  import { Log } from '@serenity-js/core';
- *  import { Website } from '@serenity-js/protractor';
- *
- *  actor.attemptsTo(
- *      Log.the('Current page', Website.title(), Website.url()),
- *  );
- *
- * @extends {Interaction}
- */
-export class Log extends Interaction {
-
-    /**
-     * @desc
-     *  Instantiates a new {@link Log} {@link Interaction}.
-     *
-     * @param {...items: any[]} items
-     *  The items to be logged
-     * @returns {Interaction}
-     */
-    static the(...items: Array<Answerable<any>>): Interaction {
-        return new Log(items);
-    }
-
-    /**
-     * @param {...items: any[]} items
-     *  The items to be logged
-     */
-    constructor(
-        private readonly items: Array<Answerable<any>>,
-    ) {
-        super();
-    }
-
-    /**
-     * @desc
-     *  Makes the provided {@link Actor}
-     *  perform this {@link Interaction}.
-     *
-     * @param {UsesAbilities & AnswersQuestions & CollectsArtifacts} actor
-     * @returns {Promise<void>}
-     *
-     * @see {@link Actor}
-     * @see {@link UsesAbilities}
-     * @see {@link AnswersQuestions}
-     * @see {@link CollectsArtifacts}
-     */
-    performAs(actor: UsesAbilities & AnswersQuestions & CollectsArtifacts): Promise<void> {
-        return Promise
-            .all(this.items.map(item => actor.answer(item)))
-            .then(items =>
-                items.forEach((item, i) =>
-                    actor.collect(LogEntry.fromJSON({ data: inspected(item) }), new Name(inspected(this.items[i]))),
-                ),
-            );
-    }
-
-    /**
-     * @desc
-     *  Generates a description to be used when reporting this {@link Activity}.
-     *
-     * @returns {string}
-     */
-    toString(): string {
-        return `#actor logs: ${ this.items.map(item => formatted`${ item }`).join(', ') }`;
-    }
-}

package/src/screenplay/interactions/TakeNote.ts

@@ -1,107 +0,0 @@
-import { formatted } from '../../io';
-import { TakeNotes } from '../abilities';
-import { AnswersQuestions, UsesAbilities } from '../actor';
-import { Interaction } from '../Interaction';
-import { Question } from '../Question';
-
-/**
- * @desc
- *  Enables the {@link Actor} to remember an answer to a given {@link Question},
- *  and recall it later.
- *
- * @example <caption>Using default subject name based on the name of the question</caption>
- *  import { actorCalled, Note, TakeNote, TakeNotes } from '@serenity-js/core'
- *  import { BrowseTheWeb, Target, Text } from '@serenity-js/protractor'
- *  import { by, protractor } from 'protractor';
- *
- *  class Vouchers {
- *      static code             = Target.the('voucher code').located(by.id('voucher'));
- *      static appliedVoucher   = Target.the('voucher code').located(by.id('applied-voucher'));
- *  }
- *
- *  const actor = actorCalled('Noah').whoCan(
- *      TakeNotes.usingAnEmptyNotepad(),
- *      BrowseTheWeb.using(protractor.browser),
- *  );
- *
- *  actor.attemptsTo(
- *      TakeNote.of(Text.of(Vouchers.code)),
- *      // ... add the product to a basket, go to checkout, etc.
- *      Ensure.that(Text.of(Vouchers.appliedVoucher), equals(Note.of(Text.of(Vouchers.code)))),
- *  );
- *
- * @example <caption>Using custom subject name</caption>
- *  actor.attemptsTo(
- *      TakeNote.of(Text.of(Vouchers.code)).as('voucher code'),
- *      // ... add the product to a basket, go to checkout, etc.
- *      Ensure.that(Text.of(Vouchers.appliedVoucher), equals(Note.of('voucher code'))),
- *  );
- *
- * @see {@link Note}
- * @see {@link TakeNotes}
- *
- * @extends {Interaction}
- */
-export class TakeNote<Answer> extends Interaction {
-
-    /**
-     * @desc
-     *  Instructs the {@link Actor} to remember the answer to a given question
-     *
-     * @param {Question<Promise<A>> | Question<A>} question
-     *
-     * @returns {TakeNote<A>}
-     */
-    static of<A>(question: Question<Promise<A>> | Question<A>): TakeNote<A> {
-        return new TakeNote<A>(question);
-    }
-
-    /**
-     * @param {Question<Promise<Answer>> | Question<Answer>} question
-     * @param {string} subject
-     */
-    constructor(
-        private readonly question: Question<Promise<Answer>> | Question<Answer>,
-        private readonly subject: string = question.toString()
-    ) {
-        super();
-    }
-
-    /**
-     * @desc
-     *  Sets a custom subject name to remember the answer as.
-     *
-     * @param {string} subject
-     * @returns {TakeNote<Answer>}
-     */
-    as(subject: string): TakeNote<Answer> {
-        return new TakeNote<Answer>(this.question, subject);
-    }
-
-    /**
-     * @desc
-     *  Makes the provided {@link Actor}
-     *  perform this {@link Interaction}.
-     *
-     * @param {UsesAbilities & AnswersQuestions} actor
-     * @returns {Promise<void>}
-     *
-     * @see {@link Actor}
-     * @see {@link UsesAbilities}
-     * @see {@link AnswersQuestions}
-     */
-    performAs(actor: UsesAbilities & AnswersQuestions): PromiseLike<void> {
-        return actor.answer(this.question)
-            .then(answer => TakeNotes.as(actor).record(this.subject, answer));
-    }
-
-    /**
-     * @desc
-     *  Generates a description to be used when reporting this {@link Activity}.
-     *
-     * @returns {string}
-     */
-    toString(): string {
-        return formatted `#actor takes note of ${ this.subject }`;
-    }
-}

package/src/screenplay/interactions/index.ts

@@ -1,2 +0,0 @@
-export * from './Log';
-export * from './TakeNote';

package/src/screenplay/questions/Note.ts

@@ -1,99 +0,0 @@
-import { formatted } from '../../io';
-import { TakeNotes } from '../abilities';
-import { AnswersQuestions, UsesAbilities } from '../actor';
-import { Question } from '../Question';
-
-/**
- * @desc
- *  Enables the {@link Actor} to recall an answer to a given {@link Question},
- *  recorded using {@link TakeNote}.
- *
- * @example <caption>Using default subject name based on the name of the question</caption>
- *  import { actorCalled, Note, TakeNote, TakeNotes } from '@serenity-js/core'
- *  import { BrowseTheWeb, Target, Text } from '@serenity-js/protractor'
- *  import { by, protractor } from 'protractor';
- *
- *  class Vouchers {
- *      static code             = Target.the('voucher code').located(by.id('voucher'));
- *      static appliedVoucher   = Target.the('voucher code').located(by.id('applied-voucher'));
- *  }
- *
- *  const actor = actorCalled('Noah').whoCan(
- *      TakeNotes.usingAnEmptyNotepad(),
- *      BrowseTheWeb.using(protractor.browser),
- *  );
- *
- *  actor.attemptsTo(
- *      TakeNote.of(Text.of(Vouchers.code)),
- *      // ... add the product to a basket, go to checkout, etc.
- *      Ensure.that(Text.of(Vouchers.appliedVoucher), equals(Note.of(Text.of(Vouchers.code)))),
- *  );
- *
- * @example <caption>Using custom subject name</caption>
- *  actor.attemptsTo(
- *      TakeNote.of(Text.of(Vouchers.code)).as('voucher code'),
- *      // ... add the product to a basket, go to checkout, etc.
- *      Ensure.that(Text.of(Vouchers.appliedVoucher), equals(Note.of('voucher code'))),
- *  );
- *
- * @see {@link TakeNote}
- * @see {@link TakeNotes}
- *
- * @extends {Question}
- */
-export class Note<Answer> extends Question<Promise<Answer>> {
-
-    private subject: string;
-
-    /**
-     * @desc
-     *  Retrieves the previously recorded answer to a given {@link Question}
-     *
-     * @param {Question<Promise<A>> | Question<A> | string} topic
-     *
-     * @returns {Note<A>}
-     */
-    static of<A>(topic: Question<Promise<A>> | Question<A> | string): Note<A> {
-        return new Note<A>(topic);
-    }
-
-    /**
-     * @param {Question<Promise<Answer>> | Question<Answer> | string} topic
-     */
-    constructor(private readonly topic: Question<Promise<Answer>> | Question<Answer> | string) {
-        super();
-        this.subject = formatted `a note of ${ topic }`;
-    }
-
-    /**
-     * @desc
-     *  Makes the provided {@link Actor}
-     *  answer this {@link Question}.
-     *
-     * @param {AnswersQuestions & UsesAbilities} actor
-     * @returns {Promise<Answer>}
-     *
-     * @see {@link Actor}
-     * @see {@link AnswersQuestions}
-     * @see {@link UsesAbilities}
-     */
-    answeredBy(actor: AnswersQuestions & UsesAbilities): Promise<Answer> {
-        return TakeNotes.as(actor).answerTo(this.topic);
-    }
-
-    /**
-     * @desc
-     *  Changes the description of this question's subject.
-     *
-     * @param {string} subject
-     * @returns {Question<T>}
-     */
-    describedAs(subject: string): this {
-        this.subject = subject;
-        return this;
-    }
-
-    toString(): string {
-        return this.subject;
-    }
-}

package/src/stage/Clock.ts

@@ -1,19 +0,0 @@
-import { Timestamp } from '../model';
-
-/**
- * @desc A {@link Clock} tells the time.
- *
- * @example
- * const now: Timestamp = new Clock().now()
- */
-export class Clock {
-    constructor(private readonly checkTime: () => Date = () => new Date()) {
-    }
-
-    /**
-     * @returns {Timestamp} current time
-     */
-    now(): Timestamp {
-        return new Timestamp(this.checkTime());
-    }
-}

package/tsconfig.eslint.json

@@ -1,10 +0,0 @@
-{
-  "extends": "./tsconfig",
-  "include": [
-    "src/**/*.ts",
-    "spec/**/*.ts"
-  ],
-  "exclude": [
-    "node_modules"
-  ]
-}