@serenity-js/protractor 2.32.4 → 3.0.0-rc.2

package/src/screenplay/questions/text/Text.ts

@@ -1,55 +0,0 @@
-import { MetaQuestion, Question } from '@serenity-js/core';
-import { ElementArrayFinder, ElementFinder } from 'protractor';
-
-import { TextOfMultipleElements } from './TextOfMultipleElements';
-import { TextOfSingleElement } from './TextOfSingleElement';
-
-/**
- * @desc
- *  Resolves to the visible (i.e. not hidden by CSS) `innerText` of:
- *  - a given {@link WebElement}, represented by {@link ElementFinder} or `Question<ElementFinder>`,
- *  - a group of {@link WebElement}s, represented by {@link ElementArrayFinder} or `Question<ElementArrayFinder>`.
- *
- *  The result includes the visible text of any sub-elements, without any leading or trailing whitespace.
- *
- * @public
- *
- * @extends {@serenity-js/core/lib/screenplay~Question}
- * @implements {@serenity-js/core/lib/screenplay/questions~MetaQuestion}
- */
-export class Text {
-
-    /**
-     * @desc
-     *  Retrieves text of a single {@link WebElement},
-     *  represented by {@link ElementFinder}
-     *  or `Question<ElementFinder>`.
-     *
-     * @param {Question<ElementFinder> | ElementFinder} target
-     * @returns {Question<Promise<string>> & MetaQuestion<Question<ElementFinder> | ElementFinder, Promise<string>>}
-     *
-     * @see {@link @serenity-js/core/lib/screenplay/questions~MetaQuestion}
-     */
-    static of(target: Question<ElementFinder> | ElementFinder):
-        Question<Promise<string>> & MetaQuestion<Question<ElementFinder> | ElementFinder, Promise<string>>  // eslint-disable-line @typescript-eslint/indent
-    {
-        return new TextOfSingleElement(target);
-    }
-
-    /**
-     * @desc
-     *  Retrieves text of a group of {@link WebElement}s,
-     *  represented by {@link ElementArrayFinder}
-     *  or `Question<ElementArrayFinder>`
-     *
-     * @param {Question<ElementArrayFinder> | ElementArrayFinder} target
-     * @returns {Question<Promise<string[]>> & MetaQuestion<Question<ElementFinder> | ElementFinder, Promise<string[]>>}
-     *
-     * @see {@link @serenity-js/core/lib/screenplay/questions~MetaQuestion}
-     */
-    static ofAll(target: Question<ElementArrayFinder> | ElementArrayFinder):
-        Question<Promise<string[]>> & MetaQuestion<Question<ElementFinder> | ElementFinder, Promise<string[]>>  // eslint-disable-line @typescript-eslint/indent
-    {
-        return new TextOfMultipleElements(target);
-    }
-}

package/src/screenplay/questions/text/TextOfMultipleElements.ts

@@ -1,40 +0,0 @@
-import { AnswersQuestions, MetaQuestion, Question, UsesAbilities } from '@serenity-js/core';
-import { ElementArrayFinder, ElementFinder } from 'protractor';
-
-import { withAnswerOf } from '../../withAnswerOf';
-import { TargetNestedElements } from '../targets';
-
-/**
- * @package
- */
-export class TextOfMultipleElements
-    extends Question<Promise<string[]>>
-    implements MetaQuestion<Question<ElementFinder> | ElementFinder, Promise<string[]>>
-{
-    constructor(protected readonly target: Question<ElementArrayFinder> | ElementArrayFinder) {
-        super(`the text of ${ target }`);
-    }
-
-    of(parent: Question<ElementFinder> | ElementFinder): Question<Promise<string[]>> {
-        return new TextOfMultipleElements(new TargetNestedElements(parent, this.target));
-    }
-
-    /**
-     * @desc
-     *  Makes the provided {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     *  answer this {@link @serenity-js/core/lib/screenplay~Question}.
-     *
-     * @param {AnswersQuestions & UsesAbilities} actor
-     * @returns {Promise<void>}
-     *
-     * @see {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     * @see {@link @serenity-js/core/lib/screenplay/actor~AnswersQuestions}
-     * @see {@link @serenity-js/core/lib/screenplay/actor~UsesAbilities}
-     */
-    answeredBy(actor: AnswersQuestions & UsesAbilities): Promise<string[]> {
-
-        // protractor ignores type definitions for the ElementArrayFinder, hence the `any`
-        // https://github.com/angular/protractor/blob/c3978ec166760ac07db01e700c4aaaa19d9b5c38/lib/element.ts#L92
-        return withAnswerOf(actor, this.target, eaf => Promise.resolve(eaf.getText() as any) as Promise<string[]>);
-    }
-}

package/src/screenplay/questions/text/TextOfSingleElement.ts

@@ -1,37 +0,0 @@
-import { AnswersQuestions, MetaQuestion, Question, UsesAbilities } from '@serenity-js/core';
-import { ElementFinder } from 'protractor';
-
-import { withAnswerOf } from '../../withAnswerOf';
-import { TargetNestedElement } from '../targets';
-
-/**
- * @package
- */
-export class TextOfSingleElement
-    extends Question<Promise<string>>
-    implements MetaQuestion<Question<ElementFinder> | ElementFinder, Promise<string>>
-{
-    constructor(protected readonly target: Question<ElementFinder> | ElementFinder) {
-        super(`the text of ${ target }`);
-    }
-
-    of(parent: Question<ElementFinder> | ElementFinder): Question<Promise<string>> {
-        return new TextOfSingleElement(new TargetNestedElement(parent, this.target));
-    }
-
-    /**
-     * @desc
-     *  Makes the provided {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     *  answer this {@link @serenity-js/core/lib/screenplay~Question}.
-     *
-     * @param {AnswersQuestions & UsesAbilities} actor
-     * @returns {Promise<void>}
-     *
-     * @see {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     * @see {@link @serenity-js/core/lib/screenplay/actor~AnswersQuestions}
-     * @see {@link @serenity-js/core/lib/screenplay/actor~UsesAbilities}
-     */
-    answeredBy(actor: AnswersQuestions & UsesAbilities): Promise<string> {
-        return withAnswerOf(actor, this.target, elf => elf.getText() as any);
-    }
-}

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

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

package/src/screenplay/withAnswerOf.ts

@@ -1,19 +0,0 @@
-import { AnswersQuestions, Question, UsesAbilities } from '@serenity-js/core';
-
-/**
- * @private
- * @param actor
- * @param maybeQuestion
- * @param fn
- */
-export function withAnswerOf<T, O>(
-    actor: AnswersQuestions & UsesAbilities,
-    maybeQuestion: Question<T> | T,
-    fn: (item: T) => O,
-): O {
-    const answer = Question.isAQuestion(maybeQuestion)
-        ? maybeQuestion.answeredBy(actor)
-        : maybeQuestion;
-
-    return fn(answer);
-}

package/src/stage/crew/index.ts

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

package/src/stage/crew/photographer/Photographer.ts

@@ -1,108 +0,0 @@
-import { LogicError } from '@serenity-js/core';
-import { ActivityFinished, ActivityStarts, DomainEvent } from '@serenity-js/core/lib/events';
-import { Stage, StageCrewMember } from '@serenity-js/core/lib/stage';
-
-import { PhotoTakingStrategy } from './strategies';
-
-/**
- * @desc
- *  The Photographer is a {@link @serenity-js/core/lib/stage~StageCrewMember} who takes screenshots
- *  of the web browser the {@link @serenity-js/core/lib/screenplay/actor~Actor} in the spotlight is using.
- *
- * @example <caption>Assigning the Photographer to the Stage</caption>
- *
- * const { ArtifactArchiver } = require('@serenity-js/core');
- * const { Photographer, TakePhotosOfFailures } = require('@serenity-js/protractor');
- *
- * exports.config = {
- *
- *     serenity: {
- *         crew: [
- *             ArtifactArchiver.storingArtifactsAt('./target/site/serenity'),
- *             Photographer.whoWill(TakePhotosOfFailures),
- *         ]
- *     },
- *
- *     // ... rest of the config omitted for brevity
- * };
- *
- * @example <caption>Taking photos upon failures only</caption>
- *
- * const { Photographer, TakePhotosOfFailures } = require('@serenity-js/protractor');
- *
- * Photographer.whoWill(TakePhotosOfFailures)
- *
- * @example <caption>Taking photos of all the interactions</caption>
- *
- * const { Photographer, TakePhotosOfInteractions } = require('@serenity-js/protractor');
- *
- * Photographer.whoWill(TakePhotosOfInteractions)
- *
- * @example <caption>Taking photos before and after all the interactions</caption>
- *
- * const { Photographer, TakePhotosBeforeAndAfterInteractions } = require('@serenity-js/protractor');
- *
- * Photographer.whoWill(TakePhotosBeforeAndAfterInteractions)
- *
- * @see {@link @serenity-js/core/lib/stage~Stage}
- * @see {@link TakePhotosBeforeAndAfterInteractions}
- * @see {@link TakePhotosOfFailures}
- * @see {@link TakePhotosOfInteractions}
- */
-export class Photographer implements StageCrewMember {
-
-    /**
-     * @desc
-     *  Instantiates a new {@link Photographer} configured to take photos (screenshots)
-     *  as per the specified {@link PhotoTakingStrategy}.
-     *
-     * @param {Function} strategy - A no-arg constructor function that instantiates a {@link PhotoTakingStrategy}.
-     * @returns {StageCrewMember}
-     */
-    static whoWill(strategy: new () => PhotoTakingStrategy): StageCrewMember {
-        return new Photographer(new strategy());
-    }
-
-    /**
-     * @param {PhotoTakingStrategy} photoTakingStrategy
-     * @param {Stage} stage
-     */
-    constructor(
-        private readonly photoTakingStrategy: PhotoTakingStrategy,
-        private stage?: Stage,
-    ) {
-    }
-
-    /**
-     * @desc
-     *  Creates a new instance of this {@link StageCrewMember} and assigns it to a given {@link Stage}.
-     *
-     * @param {Stage} stage - An instance of a {@link Stage} this {@link StageCrewMember} will be assigned to
-     * @returns {StageCrewMember} - A new instance of this {@link StageCrewMember}
-     */
-    assignedTo(stage: Stage): StageCrewMember {
-        return new Photographer(this.photoTakingStrategy, stage);
-    }
-
-    /**
-     * @desc
-     *  Handles {@link DomainEvent} objects emitted by the {@link Stage}
-     *  this {@link StageCrewMember} is assigned to.
-     *
-     * @param {DomainEvent} event
-     * @returns {void}
-     */
-    notifyOf(event: DomainEvent): void {
-        if (! this.stage) {
-            throw new LogicError(`Photographer needs to be assigned to the Stage before it can be notified of any DomainEvents`);
-        }
-
-        if (! this.stage.theShowHasStarted()) {
-            return void 0;
-        }
-
-        if (event instanceof ActivityStarts || event instanceof ActivityFinished) {
-            this.photoTakingStrategy.considerTakingPhoto(event, this.stage);
-        }
-    }
-}

package/src/stage/crew/photographer/index.ts

@@ -1,2 +0,0 @@
-export * from './Photographer';
-export * from './strategies';

package/src/stage/crew/photographer/strategies/PhotoTakingStrategy.ts

@@ -1,102 +0,0 @@
-import { Stage } from '@serenity-js/core';
-import {
-    ActivityFinished,
-    ActivityRelatedArtifactGenerated,
-    ActivityStarts,
-    AsyncOperationAttempted,
-    AsyncOperationCompleted,
-    AsyncOperationFailed,
-    DomainEvent,
-} from '@serenity-js/core/lib/events';
-import { CorrelationId, Description, Name, Photo } from '@serenity-js/core/lib/model';
-import { error as webdriver } from 'selenium-webdriver';
-
-import { BrowseTheWeb } from '../../../../screenplay';
-
-/**
- * @desc
- *  Configures the {@link Photographer} to take photos (a.k.a. screenshots)
- *  of the {@link @serenity-js/core/lib/screenplay~Activity} performed
- *  by the {@link @serenity-js/core/lib/screenplay/actor~Actor} in the spotlight
- *  under specific conditions.
- *
- * @abstract
- */
-export abstract class PhotoTakingStrategy {
-
-    /**
-     * @desc
-     *  Takes a photo of the web browser held by the {@link @serenity-js/core/lib/screenplay/actor~Actor} in the spotlight.
-     *
-     * @param {@serenity-js/core/lib/events~ActivityStarts | @serenity-js/core/lib/events~ActivityFinished} event
-     * @param {@serenity-js/core/lib/stage~Stage} stage - the Stage that holds reference to the Actor in the spotlight
-     * @returns void
-     *
-     * @see {@link @serenity-js/core/lib/stage~Stage#theActorInTheSpotlight}
-     */
-    considerTakingPhoto(event: ActivityStarts | ActivityFinished, stage: Stage): void {
-        if (this.shouldTakeAPhotoOf(event)) {
-            let browseTheWeb: BrowseTheWeb;
-
-            try {
-                browseTheWeb = BrowseTheWeb.as(stage.theActorInTheSpotlight());
-            } catch {
-                return void 0;
-            }
-
-            const
-                id              = CorrelationId.create(),
-                nameSuffix      = this.photoNameFor(event);
-
-            stage.announce(new AsyncOperationAttempted(
-                new Description(`[Photographer:${ this.constructor.name }] Taking screenshot of '${ nameSuffix }'...`),
-                id,
-            ));
-
-            Promise.all([
-                browseTheWeb.takeScreenshot(),
-                browseTheWeb.getCapabilities(),
-            ]).then(([ screenshot, capabilities ]) => {
-
-                const
-                    context   = [ capabilities.get('platform'), capabilities.get('browserName'), capabilities.get('version') ],
-                    photoName = this.combinedNameFrom(...context, nameSuffix);
-
-                stage.announce(new ActivityRelatedArtifactGenerated(
-                    event.sceneId,
-                    event.activityId,
-                    photoName,
-                    Photo.fromBase64(screenshot),
-                ));
-
-                stage.announce(new AsyncOperationCompleted(
-                    new Description(`[${ this.constructor.name }] Took screenshot of '${ nameSuffix }' on ${ context }`),
-                    id,
-                ));
-            }).catch(error => {
-                if (this.shouldIgnore(error)) {
-                    stage.announce(new AsyncOperationCompleted(
-                        new Description(`[${ this.constructor.name }] Aborted taking screenshot of '${ nameSuffix }' because of ${ error.constructor && error.constructor.name }`),
-                        id,
-                    ));
-                }
-                else {
-                    stage.announce(new AsyncOperationFailed(error, id));
-                }
-            });
-        }
-    }
-
-    protected abstract shouldTakeAPhotoOf(event: DomainEvent): boolean;
-
-    protected abstract photoNameFor(event: DomainEvent): string;
-
-    private combinedNameFrom(...parts: string[]): Name {
-        return new Name(parts.filter(v => !! v).join('-'));
-    }
-
-    private shouldIgnore(error: Error) {
-        return error instanceof webdriver.NoSuchSessionError
-            || error instanceof webdriver.UnexpectedAlertOpenError
-    }
-}

package/src/stage/crew/photographer/strategies/TakePhotosBeforeAndAfterInteractions.ts

@@ -1,28 +0,0 @@
-import { DomainEvent, InteractionFinished, InteractionStarts } from '@serenity-js/core/lib/events';
-
-import { PhotoTakingStrategy } from './PhotoTakingStrategy';
-
-/**
- * @desc
- *  Configures the {@link Photographer} to take photos (a.k.a. screenshots) both before and after
- *  every single {@link @serenity-js/core/lib/screenplay~Interaction} performed
- *  by the {@link @serenity-js/core/lib/screenplay/actor~Actor} in the spotlight.
- *
- *  *Please note* that this strategy will result in _a lot_ of screenshots being taken,
- *  which will seriously affect the performance of your tests.
- *  For this reason, it's best to use it only for debugging purposes.
- *
- * @extends {PhotoTakingStrategy}
- */
-export class TakePhotosBeforeAndAfterInteractions extends PhotoTakingStrategy {
-    protected shouldTakeAPhotoOf(event: DomainEvent): boolean {
-        return event instanceof InteractionStarts
-            || event instanceof InteractionFinished;
-    }
-
-    protected photoNameFor(event: InteractionStarts | InteractionFinished): string {
-        return event instanceof InteractionStarts
-            ? `Before ${ event.details.name.value }`
-            : `After ${ event.details.name.value }`;
-    }
-}

package/src/stage/crew/photographer/strategies/TakePhotosOfFailures.ts

@@ -1,26 +0,0 @@
-import { DomainEvent, InteractionFinished } from '@serenity-js/core/lib/events';
-import { ImplementationPending } from '@serenity-js/core/lib/model';
-
-import { PhotoTakingStrategy } from './PhotoTakingStrategy';
-
-/**
- * @desc
- *  Configures the {@link Photographer} to take photos (a.k.a. screenshots) when
- *  the {@link @serenity-js/core/lib/screenplay~Interaction} performed
- *  by the {@link @serenity-js/core/lib/screenplay/actor~Actor} in the spotlight results in an error.
- *
- *  This strategy works best when you are interested in the screenshots only when
- *  the a fails.
- *
- * @extends {PhotoTakingStrategy}
- */
-export class TakePhotosOfFailures extends PhotoTakingStrategy {
-    protected shouldTakeAPhotoOf(event: DomainEvent): boolean {
-        return event instanceof InteractionFinished
-            && event.outcome.isWorseThan(ImplementationPending);
-    }
-
-    protected photoNameFor(event: InteractionFinished): string {
-        return event.details.name.value;
-    }
-}

package/src/stage/crew/photographer/strategies/TakePhotosOfInteractions.ts

@@ -1,26 +0,0 @@
-import { DomainEvent, InteractionFinished } from '@serenity-js/core/lib/events';
-
-import { PhotoTakingStrategy } from './PhotoTakingStrategy';
-
-/**
- * @desc
- *  Configures the {@link Photographer} to take photos (a.k.a. screenshots) when
- *  the the {@link @serenity-js/core/lib/screenplay/actor~Actor} in the spotlight
- *  performs any {@link @serenity-js/core/lib/screenplay~Interaction}.
- *
- *  This strategy works best when you want the results of your automated tests
- *  to become comprehensive living documentation of your system.
- *
- *  *Please note* that taking screenshots affects the performance of your tests.
- *
- * @extends {PhotoTakingStrategy}
- */
-export class TakePhotosOfInteractions extends PhotoTakingStrategy {
-    protected shouldTakeAPhotoOf(event: DomainEvent): boolean {
-        return event instanceof InteractionFinished;
-    }
-
-    protected photoNameFor(event: InteractionFinished): string {
-        return event.details.name.value;
-    }
-}

package/src/stage/crew/photographer/strategies/index.ts

@@ -1,4 +0,0 @@
-export * from './PhotoTakingStrategy';
-export * from './TakePhotosBeforeAndAfterInteractions';
-export * from './TakePhotosOfFailures';
-export * from './TakePhotosOfInteractions';

package/src/stage/index.ts

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