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

package/src/io/formatted.ts

@@ -1,20 +0,0 @@
-import { Answerable } from '../screenplay';
-import { format } from './format';
-
-/**
- * @desc
- *  A tag function returning a human-readable description of a template containing one or more {@link Answerable}s.
- *  This function is deprecated, please use {@link format} instead.
- *
- * @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#Tagged_template_literals
- *
- *
- * @deprecated
- *
- * @param {TemplateStringsArray} templates
- * @param {Array<Answerable<any>>} placeholders
- * @returns {string}
- */
-export function formatted(templates: TemplateStringsArray, ...placeholders: Array<Answerable<any>>): string {
-    return format({ markQuestions: false })(templates, ...placeholders);
-}

package/src/io/json/cycle.ts

@@ -1,177 +0,0 @@
-/* eslint-disable @typescript-eslint/no-unused-vars,unicorn/better-regex,unicorn/escape-case,no-useless-escape,no-control-regex,@typescript-eslint/explicit-module-boundary-types */
-
-export function stringify(value: unknown, replacer?: (this: any, key: string, value: any) => any, space?: string | number): string {
-    return JSON.stringify(decycle(value), replacer, space);
-}
-
-/**
- * @desc
- *  Converts a JavaScript Object Notation (JSON) string into an object.
- *  Supports objects with cyclic references.
- *
- * @param text A valid JSON string.
- * @param reviver A function that transforms the results. This function is called for each member of the object.
- *   If a member contains nested objects, the nested objects are transformed before the parent object is.
- */
-export function parse(text: string, reviver?: (this: any, key: string, value: any) => any) {
-    return retrocycle(JSON.parse(text, reviver));
-}
-
-/**
- * @desc
- *  Makes a deep copy of an object or array, assuring that there is at most
- *  one instance of each object or array in the resulting structure. The
- *  duplicate references (which might be forming cycles) are replaced with
- *  an object of the form:
- *
- *  ```
- *      {"$ref": PATH}
- *  ```
- *
- *  where the PATH is a JSONPath string that locates the first occurrence.
- *
- *  So,
- *  ```
- *      var a = [];
- *      a[0] = a;
- *      return JSON.stringify(decycle(a));
- *  ```
- *
- *  produces the string `[{"$ref":"$"}]`.
- *
- *  JSONPath is used to locate the unique object. $ indicates the top level of
- *  the object or array. [NUMBER] or [STRING] indicates a child element or property.
- *
- *  Based on work by Douglas Crockford
- *   https://github.com/jan-molak/JSON-js/blob/master/cycle.js
- *
- * @param {any} object
- *
- * @package
- */
-function decycle(object: any) {
-    const objects = new WeakMap<any, string>();     // object to path mappings
-
-    // The derez function recurses through the object, producing a deep copy
-    return (function derez(value, path) {
-
-        let old_path,   // The path of an earlier occurance of value
-            nu;         // The new object or array
-
-        if (
-            typeof value === 'object'
-            && value !== null
-            && !(value instanceof Boolean)
-            && !(value instanceof Date)
-            && !(value instanceof Number)
-            && !(value instanceof RegExp)
-            && !(value instanceof String)
-        ) {
-            // If the value is an object or array, look to see if we have already
-            // encountered it. If so, return a {"$ref":PATH} object.
-
-            old_path = objects.get(value);
-            if (old_path !== undefined) {
-                return { $ref: old_path };
-            }
-            // Otherwise, accumulate the unique value and its path.
-
-            objects.set(value, path);
-
-            // If it is an array, replicate the array.
-
-            if (Array.isArray(value)) {
-                nu = [];
-                value.forEach(function (element, i) {
-                    nu[i] = derez(element, path + '[' + i + ']');
-                });
-            } else {
-
-                // If it is an object, replicate the object.
-
-                nu = {};
-                Object.keys(value).forEach(function (name) {
-                    nu[name] = derez(
-                        value[name],
-                        path + '[' + JSON.stringify(name) + ']'
-                    );
-                });
-            }
-            return nu;
-        }
-        return value;
-    }(object, '$'));
-}
-
-/**
- * @desc
- *  Restore an object that was reduced by decycle. Members which values are
- *  objects of the form
- *  ```
- *       {$ref: PATH}
- *  ```
- *  are replaced with references to the value found by the PATH.
- *  This will restore cycles. The object will be MUTATED.
- *
- *  The eval function is used to locate the values described by a PATH. The
- *  root object is kept in a $ variable. A regular expression is used to
- *  assure that the PATH is extremely well formed. The regexp contains nested
- *  * quantifiers. That has been known to have extremely bad performance
- *  problems on some browsers for very long strings. A PATH is expected to be
- *  reasonably short. A PATH is allowed to belong to a very restricted subset of
- *  Goessner's JSONPath.
- *
- *  So,
- *  ```
- *       var s = '[{"$ref":"$"}]';
- *       return retrocycle(JSON.parse(s));
- *  ```
- *  produces an array containing a single element which is the array itself.
- *
- *  Based on work by Douglas Crockford
- *   https://github.com/jan-molak/JSON-js/blob/master/cycle.js
- *
- * @param {any} $
- *
- * @package
- */
-function retrocycle($: any) {
-    const px = /^\$(?:\[(?:\d+|"(?:[^\\"\u0000-\u001f]|\\(?:[\\"\/bfnrt]|u[0-9a-zA-Z]{4}))*")\])*$/;
-
-    (function rez(value) {
-
-        // The rez function walks recursively through the object looking for $ref
-        // properties. When it finds one that has a value that is a path, then it
-        // replaces the $ref object with a reference to the value that is found by
-        // the path.
-
-        if (value && typeof value === 'object') {
-            if (Array.isArray(value)) {
-                value.forEach(function (element, i) {
-                    if (typeof element === 'object' && element !== null) {
-                        const path = element.$ref;
-                        if (typeof path === 'string' && px.test(path)) {
-                            value[i] = eval(path);
-                        } else {
-                            rez(element);
-                        }
-                    }
-                });
-            } else {
-                Object.keys(value).forEach(function (name) {
-                    const item = value[name];
-                    if (typeof item === 'object' && item !== null) {
-                        const path = item.$ref;
-                        if (typeof path === 'string' && px.test(path)) {
-                            value[name] = eval(path);
-                        } else {
-                            rez(item);
-                        }
-                    }
-                });
-            }
-        }
-    }($));
-
-    return $;
-}

package/src/io/json/index.ts

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

package/src/model/artifacts/AssertionReport.ts

@@ -1,7 +0,0 @@
-import { JSONData } from './JSONData';
-
-export class AssertionReport extends JSONData {
-    static fromJSON(value: { expected: string, actual: string }): AssertionReport {
-        return new AssertionReport(Buffer.from(JSON.stringify(value, undefined, 0), 'utf8').toString('base64'));
-    }
-}

package/src/model/tags/ContextTag.ts

@@ -1,21 +0,0 @@
-import { Tag } from './Tag';
-
-/**
- * @desc There are a couple of common use-cases for contexts: running the same test in different browsers,
- * and running the same test on different operating systems.
- * If you use the name of a browser (e.g. “chrome”, “firefox”, “safari”, “ie”),
- * the context will be represented in the reports as the icon of the respective browsers.
- * If you provide an operating system (e.g. “linux”, “windows”, “mac”, “android”, “iphone”),
- * a similar icon will be used. If you use any other term for your context,
- * it will appear in text form in the test results lists, so it is better to keep context names relatively short.
- *
- * @access public
- * @deprecated
- */
-export class ContextTag extends Tag {
-    static readonly Type = 'context';
-
-    constructor(context: string) {
-        super(context, ContextTag.Type);
-    }
-}

package/src/screenplay/Ability.ts

@@ -1,100 +0,0 @@
-/**
- * @desc
- *  An Ability enables the {@link Actor} to interact with an external interface of the system under test.
- *  Technically speaking, it's a wrapper around a client of said interface.
- *
- * @example
- *  import { Ability, Actor, Interaction } from '@serenity-js/core';
- *
- *  class MakePhoneCalls implements Ability {
- *      static as(actor: UsesAbilities): MakesPhoneCalls {
- *          return actor.abilityTo(MakePhoneCalls);
- *      }
- *
- *      static using(phone: Phone) {
- *          return new MakePhoneCalls(phone);
- *      }
- *
- *      constructor(private readonly phone: Phone) {}
- *
- *      // some method that allows us to interact with the external interface of the system under test
- *      dial(phoneNumber: string) {
- *        // ...
- *      }
- *  }
- *
- *  const Connie = Actor.named('Connie').whoCan(MakePhoneCalls.using(phone));
- *
- *  const Call = (phoneNumber: string) => Interaction.where(`#actor calls ${ phoneNumber }`, actor =>
- *      MakePhoneCalls.as(actor).dial(phoneNumber);
- *  );
- *
- * @example <caption>Ability that's automatically initialised and discarded</caption>
- *  import {
- *      Ability, actorCalled, Discardable, Initialisable,
- *      Question, UsesAbilities
- *  } from '@serenity-js/core';
- *  import { Ensure, equals } from '@serenity-js/assertions';
- *
- *  // A low-level client we want the Actor to use, i.e. a database client:
- *  const { Client } = require('pg');
- *
- *  // A custom Ability to give an Actor access to the low-level client:
- *  class QueryPostgresDB implements Initialisable, Discardable, Ability {
- *     static as(actor: UsesAbilities) {
- *         return actor.abilityTo(QueryPostgresDB);
- *     }
- *
- *     constructor(private readonly client) {
- *     }
- *
- *     // invoked by Serenity/JS when actor.attemptsTo is first invoked
- *     initialise(): Promise<void> | void {
- *         return this.client.connect();
- *     }
- *
- *     // Helps to ensure that the Ability is not initialised more than once
- *     isInitialised(): boolean {
- *         return this.client._connected;
- *     }
- *
- *     // Discards any resources the Ability uses when the Actor is dismissed
- *     discard(): Promise<void> | void {
- *         return this.client.end();
- *     }
- *
- *     // Any custom integration APIs the custom Ability
- *     // should make available to the Actor.
- *     query(query: string) {
- *         return this.client.query(query);
- *     }
- *
- *     // ... other custom integration APIs
- *  }
- *
- *  // A custom Question to allow the Actor query the system
- *  const CurrentDBUser = () =>
- *      Question.about('current db user', actor =>
- *          QueryPostgresDB.as(actor)
- *              .query('SELECT current_user')
- *              .then(result => result.rows[0].current_user)
- *      );
- *
- *  // Example test scenario where the Actor uses an Ability to QueryPostgresDB
- *  // to assert on the username the connection has been established with
- *  describe('Serenity/JS', () => {
- *     it('can initialise and discard abilities automatically', () =>
- *         actorCalled('Debbie')
- *             .whoCan(new QueryPostgresDB(new Client()))
- *             .attemptsTo(
- *                 Ensure.that(CurrentDBUser(), equals('jan'))
- *             ));
- *  });
- *
- * @see {@link Initialisable}
- * @see {@link Discardable}
- *
- * @access public
- */
-export interface Ability {  // eslint-disable-line @typescript-eslint/no-empty-interface
-}

package/src/screenplay/AbilityType.ts

@@ -1,44 +0,0 @@
-import { Ability } from './Ability';
-import { UsesAbilities } from './actor';
-
-/**
- * @desc
- *  An interface describing the static access method that every {@link Ability} class
- *  needs to provide in order to be accessible from within an {@link Interaction}.
- */
-export interface AbilityType<A extends Ability> extends Function {
-
-    /**
-     * @desc
-     *  Retrieves the Ability in question from the {@link Actor}, provided that the {@link Actor} has it.
-     *
-     * @example
-     * import { Ability, Actor, Interface } from '@serenity-js/core';
-     *
-     * class MakePhoneCalls implements Ability {
-     *     static as(actor: UsesAbilities): MakesPhoneCalls {
-     *         return actor.abilityTo(MakePhoneCalls);
-     *     }
-     *
-     *     static using(phone: Phone) {
-     *         return new MakePhoneCalls(phone);
-     *     }
-     *
-     *     constructor(private readonly phone: Phone) {}
-     *
-     *     // some method that allows us to interact with the external interface of the system under test
-     *     dial(phoneNumber: string) {
-     *       // ...
-     *     }
-     * }
-     *
-     * const Connie = Actor.named('Connie').whoCan(MakePhoneCalls.using(phone));
-     *
-     * const Call = (phoneNumber: string) => Interaction.where(`#actor calls ${ phoneNumber }`, actor =>
-     *  MakePhoneCalls.as(actor).dial(phoneNumber);
-     * );
-     *
-     * @param {UsesAbilities} actor
-     */
-    as(actor: UsesAbilities): A;
-}

package/src/screenplay/abilities/TakeNotes.ts

@@ -1,216 +0,0 @@
-import { LogicError } from '../../errors';
-import { Ability } from '../Ability';
-import { AnswersQuestions, UsesAbilities } from '../actor';
-import { Question } from '../Question';
-import { Discardable } from './Discardable';
-
-/**
- * @desc
- *  Enables the {@link Actor} to {@link TakeNote} of an answer to a given {@link Question}
- *  and to retrieve their {@link Note} later.
- *
- * @see {@link Note}
- * @see {@link TakeNote}
- *
- * @abstract
- * @implements {Ability}
- */
-export abstract class TakeNotes implements Ability {
-
-    /**
-     * @desc
-     *  Instantiates an ability to {@link TakeNotes} that uses an empty notepad.
-     *
-     *  This method should be used when you need the {@link Actor} to {@link TakeNote}
-     *  of an answer to some {@link Question} and retrieve such {@link Note} later on in the same scenario,
-     *  but you don't need the {@link Actor}s to share their notes.
-     *
-     * @example
-     *  import { actorCalled, Log, Note, TakeNote, TakeNotes } from '@serenity-js/core'
-     *  import { BrowseTheWeb, Target, Text } from '@serenity-js/protractor'
-     *  import { by, protractor } from 'protractor';
-     *
-     *  const actor = actorCalled('Apisitt').whoCan(
-     *      TakeNotes.usingAnEmptyNotepad(),
-     *      CallAnApi.at('https://api.example.org'),
-     *  );
-     *
-     *  actor.attemptsTo(
-     *      Send.a(GetRequest.to('/customers')),
-     *      TakeNote.of(LastResponse.status()),     // remember the LastResponse.status()
-     *      // ... perform some other activities
-     *      Log.the(Note.of(LastResponse.body())),  // log it later, or pass to any other interaction
-     *  );
-     *
-     * @example
-     *  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)))),
-     *  );
-     *
-     * @returns {TakeNotes & Discardable}
-     */
-    static usingAnEmptyNotepad(): TakeNotes & Discardable {
-        return new TakeNotesUsingAnEmptyNotepad();
-    }
-
-    /**
-     * @desc
-     *  Instantiates an ability to {@link TakeNotes} that uses a notepad that can be shared amongst {@link Actor}s.
-     *
-     *  This method should be used when you need the {@link Actor}s to {@link TakeNote}s
-     *  of answers to some {@link Question}s, share those notes amongst themselves,
-     *  and retrieve such shared {@link Note}s later on in the same scenario.
-     *
-     * @example
-     *  import { actorCalled, Note, TakeNote, TakeNotes } from '@serenity-js/core'
-     *  import { ManageALocalServer, StartLocalTestServer, StopLocalTestServer } from '@serenity-js/local-server'
-     *  import { BrowseTheWeb } from '@serenity-js/protractor'
-     *
-     *  const server = http.createServer(function (request, response) {
-     *      response.setHeader('Connection', 'close');
-     *      response.end('Hello!');
-     *  });
-     *
-     *  const Adam = actorCalled('Adam').whoCan(
-     *      ManageALocalServer.using(server),
-     *      TakeNotes.usingASharedNotepad(),
-     *  );
-     *
-     *  const Becky = actorCalled('Becky').whoCan(
-     *      TakeNotes.usingASharedNotepad(),
-     *      BrowseTheWeb.using(protractor.browser),
-     *  );
-     *
-     *  Adam.attemptsTo(
-     *      StartLocalTestServer.onRandomPort(),
-     *      TakeNote.of(LocalServer.url()),
-     *  );
-     *
-     *  Becky.attemptsTo(
-     *      Navigate.to(Note.of(LocalServer.url())),
-     *      // perform some UI interactions
-     *  );
-     *
-     * @returns {TakeNotes}
-     */
-    static usingASharedNotepad(): TakeNotes {
-        return new TakeNotesUsingASharedNotepad();
-    }
-
-    /**
-     * @desc
-     *  Retrieves the {@link Ability} to {@link TakeNotes}
-     *  for a given {@link Actor} to be used in custom {@link Interaction}s.
-     *
-     * @see {@link Ability}
-     * @see {@link Interaction}
-     *
-     * @param {UsesAbilities & AnswersQuestions} actor
-     *
-     * @returns {TakeNotes}
-     */
-    static as(actor: UsesAbilities & AnswersQuestions): TakeNotes {
-        return actor.abilityTo(TakeNotes);
-    }
-
-    /**
-     * @desc
-     *  Instantiates the {@link Ability} to {@link TakeNotes}
-     *
-     * @param {Map<string, any>} notepad
-     */
-    protected constructor(protected readonly notepad: Map<string, any>) {
-    }
-
-    /**
-     * @desc
-     *  Records the answer to a given {@link Question}
-     *
-     * @param {Question<Promise<Answer>> | Question<Answer> | string} subject
-     *  Question or name to record the Answer as
-     *
-     * @param {Promise<Answer> | Answer} value
-     *  The Answer to record
-     *
-     * @returns {void}
-     */
-    record<Answer>(subject: Question<Promise<Answer>> | Question<Answer> | string, value: Promise<Answer> | Answer): void {
-        this.notepad.set(subject.toString(), value);
-    }
-
-    /**
-     * @desc
-     *  Recalls the answer to a given {@link Question}
-     *
-     * @param {Question<Promise<Answer>> | Question<Answer> | string} subject
-     *  Question or name the Answer was recorded as
-     *
-     * @returns {Promise<Answer>}
-     */
-    answerTo<Answer>(subject: Question<Promise<Answer>> | Question<Answer> | string): Promise<Answer> {
-        const key = subject.toString();
-
-        return ! this.notepad.has(key)
-            ? Promise.reject(new LogicError(`The answer to "${ key }" has never been recorded`))
-            : Promise.resolve(this.notepad.get(key));
-    }
-}
-
-/**
- * @package
- */
-class TakeNotesUsingAnEmptyNotepad extends TakeNotes implements Discardable {
-
-    /**
-     * @desc
-     *  Instantiates the {@link Ability} to {@link TakeNotes}
-     *
-     * @param {Map<string, any>} notepad
-     */
-    constructor() {
-        super(new Map<string, any>());
-    }
-
-    /**
-     * @desc
-     *  Enables the {@link Actor} to clear the notepad when the {@link SceneFinishes}.
-     *
-     * @returns {Promise<void> | void}
-     */
-    discard(): Promise<void> | void {
-        this.notepad.clear();
-    }
-}
-
-/**
- * @package
- */
-class TakeNotesUsingASharedNotepad extends TakeNotes {
-    private static sharedNotepad = new Map<string, any>();
-
-    /**
-     * @desc
-     *  Instantiates the {@link Ability} to {@link TakeNotes}
-     *
-     * @param {Map<string, any>} notepad
-     */
-    constructor() {
-        super(TakeNotesUsingASharedNotepad.sharedNotepad);
-    }
-}

package/src/screenplay/activities/ActivityDescriber.ts

@@ -1,20 +0,0 @@
-import { Name } from '../../model';
-import { Activity } from '../Activity';
-
-/** @package */
-export class ActivityDescriber {
-
-    describe(activity: Activity, actor: { name: string }): Name {
-        const template = activity.toString() !== ({}).toString()
-            ? activity.toString()
-            : `#actor performs ${ activity.constructor.name }`;
-
-        return new Name(
-            this.includeActorName(template, actor),
-        );
-    }
-
-    private includeActorName(template: string, actor: { name: string }) {
-        return template.replace('#actor', actor.name);
-    }
-}

package/src/screenplay/activities/OutcomeMatcher.ts

@@ -1,25 +0,0 @@
-import { match } from 'tiny-types';
-
-import { AssertionError, ImplementationPendingError, TestCompromisedError } from '../../errors';
-import {
-    ExecutionCompromised,
-    ExecutionFailedWithAssertionError,
-    ExecutionFailedWithError,
-    ImplementationPending,
-    ProblemIndication,
-} from '../../model';
-
-/** @package */
-export class OutcomeMatcher {
-    outcomeFor(error: Error | any): ProblemIndication {
-        return match<Error, ProblemIndication>(error)
-            .when(ImplementationPendingError, _ => new ImplementationPending(error))
-            .when(TestCompromisedError, _ => new ExecutionCompromised(error))
-            .when(AssertionError, _ => new ExecutionFailedWithAssertionError(error))
-            .when(Error, _ =>
-                /AssertionError/.test(error.constructor.name) // mocha
-                    ? new ExecutionFailedWithAssertionError(error)
-                    : new ExecutionFailedWithError(error))
-            .else(_ => new ExecutionFailedWithError(error));
-    }
-}

package/src/screenplay/activities/TrackedActivity.ts

@@ -1,50 +0,0 @@
-import { InteractionFinished, InteractionStarts, TaskFinished, TaskStarts } from '../../events';
-import { ActivityDetails, ExecutionSuccessful } from '../../model';
-import { Stage } from '../../stage';
-import { Activity } from '../Activity';
-import { AnswersQuestions, PerformsActivities, UsesAbilities } from '../actor';
-import { Interaction } from '../Interaction';
-import { ActivityDescriber } from './ActivityDescriber';
-import { OutcomeMatcher } from './OutcomeMatcher';
-
-/** @package */
-export class TrackedActivity implements Activity {
-
-    protected static readonly describer = new ActivityDescriber();
-    protected static readonly outcomes = new OutcomeMatcher();
-
-    constructor(
-        protected readonly activity: Activity,
-        protected readonly stage: Stage,
-    ) {
-    }
-
-    performAs(actor: (PerformsActivities | UsesAbilities | AnswersQuestions) & { name: string }): PromiseLike<void> {
-        const
-            sceneId = this.stage.currentSceneId(),
-            activityId = this.stage.assignNewActivityId(),
-            details = new ActivityDetails(TrackedActivity.describer.describe(this.activity, actor));
-
-        const [ activityStarts, activityFinished] = this.activity instanceof Interaction
-            ? [ InteractionStarts, InteractionFinished ]
-            : [ TaskStarts, TaskFinished ];
-
-        return Promise.resolve()
-            .then(() => this.stage.announce(new activityStarts(sceneId, activityId, details, this.stage.currentTime())))
-            .then(() => this.activity.performAs(actor))
-            .then(() => {
-                const outcome = new ExecutionSuccessful();
-                this.stage.announce(new activityFinished(sceneId, activityId, details, outcome, this.stage.currentTime()));
-            })
-            .catch(error => {
-                const outcome = TrackedActivity.outcomes.outcomeFor(error);
-                this.stage.announce(new activityFinished(sceneId, activityId, details, outcome, this.stage.currentTime()));
-
-                throw error;
-            });
-    }
-
-    toString(): string {
-        return this.activity.toString();
-    }
-}