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

package/lib/screenplay/questions/Note.d.ts

@@ -1,79 +0,0 @@
-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 declare class Note<Answer> extends Question<Promise<Answer>> {
-    private readonly topic;
-    private subject;
-    /**
-     * @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>;
-    /**
-     * @param {Question<Promise<Answer>> | Question<Answer> | string} topic
-     */
-    constructor(topic: Question<Promise<Answer>> | Question<Answer> | string);
-    /**
-     * @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>;
-    /**
-     * @desc
-     *  Changes the description of this question's subject.
-     *
-     * @param {string} subject
-     * @returns {Question<T>}
-     */
-    describedAs(subject: string): this;
-    toString(): string;
-}

package/lib/screenplay/questions/Note.js

@@ -1,96 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Note = void 0;
-const io_1 = require("../../io");
-const abilities_1 = require("../abilities");
-const Question_1 = require("../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}
- */
-class Note extends Question_1.Question {
-    /**
-     * @param {Question<Promise<Answer>> | Question<Answer> | string} topic
-     */
-    constructor(topic) {
-        super();
-        this.topic = topic;
-        this.subject = (0, io_1.formatted) `a note of ${topic}`;
-    }
-    /**
-     * @desc
-     *  Retrieves the previously recorded answer to a given {@link Question}
-     *
-     * @param {Question<Promise<A>> | Question<A> | string} topic
-     *
-     * @returns {Note<A>}
-     */
-    static of(topic) {
-        return new Note(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) {
-        return abilities_1.TakeNotes.as(actor).answerTo(this.topic);
-    }
-    /**
-     * @desc
-     *  Changes the description of this question's subject.
-     *
-     * @param {string} subject
-     * @returns {Question<T>}
-     */
-    describedAs(subject) {
-        this.subject = subject;
-        return this;
-    }
-    toString() {
-        return this.subject;
-    }
-}
-exports.Note = Note;
-//# sourceMappingURL=Note.js.map

package/lib/screenplay/questions/Note.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"Note.js","sourceRoot":"","sources":["../../../src/screenplay/questions/Note.ts"],"names":[],"mappings":";;;AAAA,iCAAqC;AACrC,4CAAyC;AAEzC,0CAAuC;AAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAa,IAAa,SAAQ,mBAAyB;IAgBvD;;OAEG;IACH,YAA6B,KAA4D;QACrF,KAAK,EAAE,CAAC;QADiB,UAAK,GAAL,KAAK,CAAuD;QAErF,IAAI,CAAC,OAAO,GAAG,IAAA,cAAS,EAAC,aAAc,KAAM,EAAE,CAAC;IACpD,CAAC;IAlBD;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,CAAI,KAAkD;QAC3D,OAAO,IAAI,IAAI,CAAI,KAAK,CAAC,CAAC;IAC9B,CAAC;IAUD;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,KAAuC;QAC9C,OAAO,qBAAS,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACpD,CAAC;IAED;;;;;;OAMG;IACH,WAAW,CAAC,OAAe;QACvB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,QAAQ;QACJ,OAAO,IAAI,CAAC,OAAO,CAAC;IACxB,CAAC;CACJ;AAvDD,oBAuDC"}

package/lib/stage/Clock.d.ts

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

package/lib/stage/Clock.js

@@ -1,23 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Clock = void 0;
-const model_1 = require("../model");
-/**
- * @desc A {@link Clock} tells the time.
- *
- * @example
- * const now: Timestamp = new Clock().now()
- */
-class Clock {
-    constructor(checkTime = () => new Date()) {
-        this.checkTime = checkTime;
-    }
-    /**
-     * @returns {Timestamp} current time
-     */
-    now() {
-        return new model_1.Timestamp(this.checkTime());
-    }
-}
-exports.Clock = Clock;
-//# sourceMappingURL=Clock.js.map

package/lib/stage/Clock.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"Clock.js","sourceRoot":"","sources":["../../src/stage/Clock.ts"],"names":[],"mappings":";;;AAAA,oCAAqC;AAErC;;;;;GAKG;AACH,MAAa,KAAK;IACd,YAA6B,YAAwB,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE;QAAxC,cAAS,GAAT,SAAS,CAA+B;IACrE,CAAC;IAED;;OAEG;IACH,GAAG;QACC,OAAO,IAAI,iBAAS,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;IAC3C,CAAC;CACJ;AAVD,sBAUC"}

package/src/SerenityConfig.ts

@@ -1,49 +0,0 @@
-import { OutputStream } from './io';
-import { Duration } from './model';
-import { Cast, StageCrewMember, StageCrewMemberBuilder } from './stage';
-
-/**
- * @interface
- *
- * @see {@link configure}
- */
-export abstract class SerenityConfig {
-    /**
-     * @desc
-     *  A {@link Cast} of {@link Actor}s to be used when {@link actorCalled}
-     *  and {@link actorInTheSpotlight} functions are called.
-     *
-     * @type {?Cast}
-     */
-    actors?:        Cast;
-
-    /**
-     * @desc
-     *  A list of {@link StageCrewMemberBuilder}s or {@link StageCrewMember}s
-     *  to be notified of {@link DomainEvent}s that occur during the scenario execution.
-     *
-     * @type {?Array<StageCrewMember | StageCrewMemberBuilder>}
-     */
-    crew?:          Array<StageCrewMember | StageCrewMemberBuilder>;
-
-    /**
-     * @desc
-     *  The maximum amount of time Serenity/JS should wait for any post-scenario
-     *  async operations to complete. Those include generating the screenshots,
-     *  saving reports to disk and so on. **Please note** that this is not
-     *  a scenario timeout, which should be configured in your test runner.
-     *
-     * @type {?Duration}
-     */
-    cueTimeout?:    Duration;
-
-    /**
-     * @desc
-     *  An output stream to be injected into {@link StageCrewMemberBuilder}s
-     *
-     *  Defaults to [`process.stdout`](https://nodejs.org/api/process.html#process_process_stdout).
-     *
-     * @type {?OutputStream}
-     */
-    outputStream?: OutputStream;
-}

package/src/errors/AssertionError.ts

@@ -1,20 +0,0 @@
-import { RuntimeError } from './RuntimeError';
-
-/**
- * @desc
- *  Thrown to indicate that an assertion has failed.
- *
- * @extends {RuntimeError}
- */
-export class AssertionError extends RuntimeError {
-
-    /**
-     * @param {string} message - Human-readable description of the error
-     * @param {unknown} expected - The value that was expected
-     * @param {unknown} actual - The value that was received instead of the expected one
-     * @param {Error} [cause] - The root cause of this {@link RuntimeError}, if any
-     */
-    constructor(message: string, public readonly expected: unknown, public readonly actual: unknown, cause?: Error) {
-        super(AssertionError, message, cause);
-    }
-}

package/src/errors/ConfigurationError.ts

@@ -1,18 +0,0 @@
-import { RuntimeError } from './RuntimeError';
-
-/**
- * @desc
- *  Thrown to indicate that a test framework or test suite configuration error occurs.
- *
- * @extends {RuntimeError}
- */
-export class ConfigurationError extends RuntimeError {
-
-    /**
-     * @param {string} message - Human-readable description of the error
-     * @param {Error} [cause] - The root cause of this {@link RuntimeError}, if any
-     */
-    constructor(message: string, cause?: Error) {
-        super(ConfigurationError, message, cause);
-    }
-}

package/src/errors/ImplementationPendingError.ts

@@ -1,33 +0,0 @@
-import { RuntimeError } from './RuntimeError';
-
-/**
- * @desc
- *  Thrown to indicate that the {@link Actor} attempted to perform
- *  a {@link Task} or {@link Interaction} that hasn't been implemented yet.
- *
- * @example <caption>A pending Task</caption>
- *  import { Task } from '@serenity-js/core';
- *
- *  // A pending Task is one that encapsulates no other activities
- *  const Authenticate = () =>
- *      Task.where(`#actor authenticates with the service up a test database` );
- *
- * @example <caption>A pending Interaction</caption>
- *  import { Interaction } from '@serenity-js/core';
- *
- *  // A pending Interaction is one that doesn't perform any action
- *  const DoubleClick = () =>
- *      Interaction.where(`#actor double-clicks`);
- *
- * @extends {RuntimeError}
- */
-export class ImplementationPendingError extends RuntimeError {
-
-    /**
-     * @param {string} message - Human-readable description of the error
-     * @param {Error} [cause] - The root cause of this {@link RuntimeError}, if any
-     */
-    constructor(message: string, cause?: Error) {
-        super(ImplementationPendingError, message, cause);
-    }
-}

package/src/errors/LogicError.ts

@@ -1,21 +0,0 @@
-import { RuntimeError } from './RuntimeError';
-
-/**
- * @desc
- *  Thrown to indicate that an {@link Interaction}, a {@link Task} or a test scenario
- *  can't be executed due to a logical error.
- *  For example, it's not possible to assert on the last HTTP Response if the request
- *  hasn't been performed yet.
- *
- * @extends {RuntimeError}
- */
-export class LogicError extends RuntimeError {
-
-    /**
-     * @param {string} message - Human-readable description of the error
-     * @param {Error} [cause] - The root cause of this {@link RuntimeError}, if any
-     */
-    constructor(message: string, cause?: Error) {
-        super(LogicError, message, cause);
-    }
-}

package/src/errors/RuntimeError.ts

@@ -1,60 +0,0 @@
-/**
- * @desc
- *  Base class for custom errors that may occur during execution of a test scenario.
- *
- * @example <caption>Custom Error definition</caption>
- * import { RuntimeError } from '@serenity-js/core';
- *
- * export class CustomError extends RuntimeError {
- *   constructor(message: string, cause?: Error) {
- *       super(CustomError, message, cause);
- *   }
- * }
- *
- * @example <caption>Sync error handling</caption>
- * try {
- *     operationThatMightThrowAnError();
- * } catch(error) {
- *     // catch and re-throw
- *     throw new CustomError('operationThatMightThrowAnError has failed', error);
- * }
- *
- * @example <caption>Async error handling</caption>
- * operationThatMightRejectAPromise().catch(error => {
- *     // catch and re-throw
- *     throw new CustomError('operationThatMightThrowAnError has failed', error);
- * });
- *
- * @extends {Error}
- */
-export abstract class RuntimeError extends Error {
-
-    /**
-     * @param {Function} type - Constructor function used to instantiate a subclass of a RuntimeError
-     * @param {string} message - Human-readable description of the error
-     * @param {Error} [cause] - The root cause of this {@link RuntimeError}, if any
-     */
-    protected constructor(
-        type: new (...args: any[]) => RuntimeError,
-        message: string,
-        public readonly cause?: Error,
-    ) {
-        super(message);
-        Object.setPrototypeOf(this, type.prototype);
-        this.name = this.constructor.name;
-
-        Error.captureStackTrace(this, type);
-
-        if (cause) {
-            this.stack = `${ this.stack }\nCaused by: ${ cause.stack }`;
-        }
-    }
-
-    /**
-     * @desc
-     *  Human-readable description
-     */
-    toString(): string {
-        return `${ this.constructor.name }: ${ this.message }`;
-    }
-}

package/src/errors/TestCompromisedError.ts

@@ -1,30 +0,0 @@
-import { RuntimeError } from './RuntimeError';
-
-/**
- * @desc
- *  Thrown to indicate that the test can't be performed due to an issue with a downstream dependency.
- *  For example, it makes no sense to run a full-stack integration test if we already know that
- *  the database server is down.
- *
- * @example <caption>Throwing a TestCompromisedError from a custom Interaction</caption>
- *  import { Interaction } from '@serenity-js/core';
- *
- *  const SetUpTestDatabase = () =>
- *      Interaction.where(`#actor sets up a test database`, actor => {
- *          return SomeCustomDatabaseSpecificAbility.as(actor).setUpTestDatabase().catch(error => {
- *              throw new TestCompromisedError('Could not set up the test database', error);
- *          });
- *      });
- *
- * @extends {RuntimeError}
- */
-export class TestCompromisedError extends RuntimeError {
-
-    /**
-     * @param {string} message - Human-readable description of the error
-     * @param {Error} [cause] - The root cause of this {@link RuntimeError}, if any
-     */
-    constructor(message: string, cause?: Error) {
-        super(TestCompromisedError, message, cause);
-    }
-}

package/src/errors/UnknownError.ts

@@ -1,18 +0,0 @@
-import { RuntimeError } from './RuntimeError';
-
-/**
- * @desc
- *  Thrown to indicate that an unknown error has occurred.
- *
- * @extends {RuntimeError}
- */
-export class UnknownError extends RuntimeError {
-
-    /**
-     * @param {string} message - Human-readable description of the error
-     * @param {Error} [cause] - The root cause of this {@link RuntimeError}, if any
-     */
-    constructor(message: string, cause?: Error) {
-        super(UnknownError, message, cause);
-    }
-}

package/src/io/AssertionReportDiffer.ts

@@ -1,43 +0,0 @@
-import { Change, diffLines } from 'diff';
-
-export class AssertionReportDiffer {
-    constructor(private readonly mappers: AssertionReportDiffMappers) {
-    }
-
-    diff(expectedValue: string, actualValue: string): string {
-        const changes = diffLines(actualValue, expectedValue)
-            .map(change => this.markChanges(change));
-
-        return [
-            `Difference (${ this.mappers.expected('expected') }, ${ this.mappers.actual('actual') }):`,
-            '',
-            changes.length === 2
-                ? changes.join('\n')
-                : changes.join(''),
-        ].join('\n');
-    }
-
-    private markChanges(change: Change): string {
-
-        return change.added
-            ? this.eachLineOf(change.value, this.mappers.expected)
-            : (change.removed
-                ? this.eachLineOf(change.value, this.mappers.actual)
-                : this.eachLineOf(change.value, this.mappers.matching));
-    }
-
-    private eachLineOf(lines: string, mapper: (line: string) => string): string {
-        return lines.split('\n').map(
-            line =>
-                line.trim()
-                    ? mapper(line)
-                    : line
-        ).join('\n');
-    }
-}
-
-export interface AssertionReportDiffMappers {
-    expected:   (line: string) => string;
-    actual:     (line: string) => string;
-    matching:   (line: string) => string;
-}

package/src/io/ErrorSerialiser.ts

@@ -1,78 +0,0 @@
-import { JSONObject } from 'tiny-types';
-
-import * as serenitySpecificErrors from '../errors';
-import { parse, stringify } from './json';
-
-/**
- *
- * @extends {tiny-types~JSONObject}
- * @public
- */
-export interface SerialisedError extends JSONObject {
-    /**
-     *  Name of the constructor function used to instantiate
-     *  the original {@link Error} object.
-     */
-    name:    string;
-
-    /**
-     *  Message of the original {@link Error} object
-     */
-    message: string;
-
-    /**
-     *  Stack trace of the original {@link Error} object
-     */
-    stack:   string;
-}
-
-export class ErrorSerialiser {
-    private static recognisedErrors = [
-        ...Object.keys(serenitySpecificErrors).map(key => serenitySpecificErrors[key]),
-        Error,
-        EvalError,
-        RangeError,
-        ReferenceError,
-        SyntaxError,
-        TypeError,
-        URIError,
-    ];
-
-    static serialise(error: Error): string {
-        const name = error && error.constructor && error.constructor.name
-            ? error.constructor.name
-            : error.name;
-
-        const serialisedError = Object.getOwnPropertyNames(error).reduce((serialised, key) => {
-            serialised[key] = error[key]
-            return serialised;
-        }, { name }) as SerialisedError;
-
-        return stringify(serialisedError);
-    }
-
-    static deserialise<E extends Error>(stringifiedError: string): E {
-        const serialisedError = parse(stringifiedError) as SerialisedError;
-
-        const constructor = ErrorSerialiser.recognisedErrors.find(errorType => errorType.name === serialisedError.name) || Error;
-        const deserialised = Object.create(constructor.prototype);
-        for (const property in serialisedError) {
-            if (Object.prototype.hasOwnProperty.call(serialisedError, property)) {
-                deserialised[property] = serialisedError[property];
-            }
-        }
-        return deserialised;
-    }
-
-    static deserialiseFromStackTrace(stack: string): Error {
-        const stackTracePattern = /^([^\s:]*Error).*?(?::\s)?(.*?)\n(^ +at.*)$/ms;
-
-        if (! stackTracePattern.test(stack)) {
-            return new Error(String(stack));
-        }
-
-        const [, name, message, callStack_ ] = stack.match(stackTracePattern);
-
-        return ErrorSerialiser.deserialise(stringify({ name, message: message.trim(), stack }));
-    }
-}

package/src/io/OutputStream.ts

@@ -1,16 +0,0 @@
-/**
- * @desc
- *  An output stream to be injected into {@link StageCrewMemberBuilder}s configured via {@link SerenityConfig#crew}.
- *
- * @interface
- *
- * @see {@link StageCrewMemberBuilder}
- * @see {@link Serenity#configure}
- * @see {@link SerenityConfig#crew}
- */
-export interface OutputStream {
-    /**
-     * @type {function(content: string): void}
-     */
-    write: (content: string) => void;
-}

package/src/io/TestRunnerAdapter.ts

@@ -1,50 +0,0 @@
-import { Outcome } from '../model';
-
-/**
- * @desc
- *  Describes an adapter needed to run a given type of tests programmatically
- *
- * @interface
- */
-export interface TestRunnerAdapter {
-
-    /**
-     * @desc
-     *  Loads test scenarios.
-     *
-     * @type {function(pathsToScenarios: string[]): Promise<void>}
-     */
-    load: (pathsToScenarios: string[]) => Promise<void>;
-
-    /**
-     * @desc
-     *  Returns the number of loaded scenarios
-     *
-     * @throws {LogicError}
-     *  If called before `load`
-     *
-     * @type {function(): number}
-     */
-    scenarioCount: () => number;
-
-    /**
-     * @desc
-     *  Runs loaded test scenarios.
-     *
-     * @throws {LogicError}
-     *  If called before `load`
-     *
-     * @abstract
-     * @type {function(): Promise<void>}
-     */
-    run: () => Promise<void>;
-
-    /**
-     * @desc
-     *  Scenario success threshold for this test runner.
-     *
-     * @abstract
-     * @type {Outcome | { Code: number }}
-     */
-    successThreshold: () => Outcome | { Code: number };
-}