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

package/lib/screenplay/questions/Note.js

@@ -1,6 +1,7 @@
 "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");
 /**
@@ -46,8 +47,9 @@ class Note extends Question_1.Question {
      * @param {Question<Promise<Answer>> | Question<Answer> | string} topic
      */
     constructor(topic) {
-        super(`a note of ${topic}`);
+        super();
         this.topic = topic;
+        this.subject = (0, io_1.formatted) `a note of ${topic}`;
     }
     /**
      * @desc
@@ -75,6 +77,20 @@ class Note extends Question_1.Question {
     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 +1 @@
-{"version":3,"file":"Note.js","sourceRoot":"","sources":["../../../src/screenplay/questions/Note.ts"],"names":[],"mappings":";;;AAAA,4CAAyC;AAEzC,0CAAuC;AAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAa,IAAa,SAAQ,mBAAyB;IAcvD;;OAEG;IACH,YAA6B,KAA4D;QACrF,KAAK,CAAC,aAAc,KAAM,EAAE,CAAC,CAAC;QADL,UAAK,GAAL,KAAK,CAAuD;IAEzF,CAAC;IAjBD;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,CAAI,KAAkD;QAC3D,OAAO,IAAI,IAAI,CAAI,KAAK,CAAC,CAAC;IAC9B,CAAC;IASD;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,KAAuC;QAC9C,OAAO,qBAAS,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACpD,CAAC;CACJ;AApCD,oBAoCC"}
+{"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/screenplay/questions/index.d.ts

@@ -2,9 +2,6 @@ export * from './Check';
 export * from './Expectation';
 export * from './expectations';
 export * from './List';
-export * from './mappings';
 export * from './MetaQuestion';
 export * from './Note';
-export { Property } from './Property';
 export * from './q';
-export * from './Transform';

package/lib/screenplay/questions/index.js

@@ -10,16 +10,11 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Property = void 0;
 __exportStar(require("./Check"), exports);
 __exportStar(require("./Expectation"), exports);
 __exportStar(require("./expectations"), exports);
 __exportStar(require("./List"), exports);
-__exportStar(require("./mappings"), exports);
 __exportStar(require("./MetaQuestion"), exports);
 __exportStar(require("./Note"), exports);
-var Property_1 = require("./Property");
-Object.defineProperty(exports, "Property", { enumerable: true, get: function () { return Property_1.Property; } });
 __exportStar(require("./q"), exports);
-__exportStar(require("./Transform"), exports);
 //# sourceMappingURL=index.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/screenplay/questions/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;AAAA,0CAAwB;AACxB,gDAA8B;AAC9B,iDAA+B;AAC/B,yCAAuB;AACvB,6CAA2B;AAC3B,iDAA+B;AAC/B,yCAAuB;AACvB,uCAAsC;AAA7B,oGAAA,QAAQ,OAAA;AACjB,sCAAoB;AACpB,8CAA4B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/screenplay/questions/index.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,0CAAwB;AACxB,gDAA8B;AAC9B,iDAA+B;AAC/B,yCAAuB;AACvB,iDAA+B;AAC/B,yCAAuB;AACvB,sCAAoB"}

package/lib/stage/index.d.ts

@@ -1,11 +1,9 @@
 export * from './Cast';
 export * from './Clock';
 export * from './crew';
-export * from './DressingRoom';
 export * from './ListensToDomainEvents';
 export * from './Stage';
 export * from './StageCrewMember';
 export * from './StageCrewMemberBuilder';
 export * from './StageCrewMemberBuilderDependencies';
 export * from './StageManager';
-export * from './WithStage';

package/lib/stage/index.js

@@ -13,12 +13,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./Cast"), exports);
 __exportStar(require("./Clock"), exports);
 __exportStar(require("./crew"), exports);
-__exportStar(require("./DressingRoom"), exports);
 __exportStar(require("./ListensToDomainEvents"), exports);
 __exportStar(require("./Stage"), exports);
 __exportStar(require("./StageCrewMember"), exports);
 __exportStar(require("./StageCrewMemberBuilder"), exports);
 __exportStar(require("./StageCrewMemberBuilderDependencies"), exports);
 __exportStar(require("./StageManager"), exports);
-__exportStar(require("./WithStage"), exports);
 //# sourceMappingURL=index.js.map

package/lib/stage/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/stage/index.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,yCAAuB;AACvB,0CAAwB;AACxB,yCAAuB;AACvB,iDAA+B;AAC/B,0DAAwC;AACxC,0CAAwB;AACxB,oDAAkC;AAClC,2DAAyC;AACzC,uEAAqD;AACrD,iDAA+B;AAC/B,8CAA4B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/stage/index.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,yCAAuB;AACvB,0CAAwB;AACxB,yCAAuB;AACvB,0DAAwC;AACxC,0CAAwB;AACxB,oDAAkC;AAClC,2DAAyC;AACzC,uEAAqD;AACrD,iDAA+B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serenity-js/core",
-  "version": "2.33.1",
+  "version": "3.0.0-rc.11",
   "description": "Serenity/JS Screenplay, reporting engine and core interfaces.",
   "author": {
     "name": "Jan Molak",
@@ -27,7 +27,7 @@
   ],
   "scripts": {
     "clean": "rimraf .nyc_output lib target",
-    "lint": "eslint --ext ts --config ../../.eslintrc.js .",
+    "lint": "eslint --ext ts --config ../../.eslintrc.yml .",
     "lint:fix": "npm run lint -- --fix",
     "test": "nyc --report-dir ../../target/coverage/core mocha --config ../../.mocharc.yml 'spec/**/*.spec.*'",
     "compile": "tsc --project tsconfig.json",
@@ -36,17 +36,18 @@
   "dependencies": {
     "cuid": "^2.1.8",
     "diff": "^5.0.0",
-    "error-stack-parser": "^2.0.6",
+    "error-stack-parser": "^2.0.7",
     "fast-glob": "^3.2.11",
     "filenamify": "^4.3.0",
     "graceful-fs": "^4.2.9",
     "moment": "^2.29.1",
     "semver": "^7.3.5",
+    "stackframe": "^1.2.0",
     "tiny-types": "^1.17.0",
     "upath": "^2.0.1"
   },
   "devDependencies": {
-    "@documentation/esdoc-template": "2.0.0",
+    "@documentation/esdoc-template": "3.0.0",
     "@types/chai": "^4.3.0",
     "@types/cuid": "^1.3.1",
     "@types/diff": "^5.0.2",
@@ -67,7 +68,7 @@
     "url": "https://github.com/serenity-js/serenity-js/issues"
   },
   "engines": {
-    "node": "^12 || ^14 || ^16",
+    "node": "^14 || ^16",
     "npm": "^6 || ^7 || ^8"
   },
   "nyc": {
@@ -92,5 +93,5 @@
     "cache": true,
     "all": true
   },
-  "gitHead": "c029cb6dde88fb0f034b8471ab93e0483c8b106d"
+  "gitHead": "0a232ce7ff21df56a9cc9e64859af5b0bce33b32"
 }

package/src/index.ts

@@ -1,6 +1,7 @@
 export * from './errors';
 export * from './instance';
-export { Duration } from './model';
+export { d, f, format } from './io';
+export { Duration, Timestamp } from './model';
 export * from './screenplay';
 export * from './Serenity';
 export { SerenityConfig } from './SerenityConfig';

package/src/io/ErrorSerialiser.ts

@@ -39,10 +39,14 @@ export class ErrorSerialiser {
     ];
 
     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: error.constructor.name || error.name }) as SerialisedError;
+        }, { name }) as SerialisedError;
 
         return stringify(serialisedError);
     }

package/src/io/ErrorStackParser.ts

@@ -1,4 +1,5 @@
 import * as parser from 'error-stack-parser';
+import StackFrame = require('stackframe');
 
 /**
  * @desc
@@ -9,7 +10,7 @@ import * as parser from 'error-stack-parser';
  * @package
  */
 export class ErrorStackParser {
-    parse(error: Error): parser.StackFrame[] {
+    parse(error: Error): StackFrame[] {
         return parser.parse(error);
     }
 }

package/src/io/asyncMap.ts

@@ -0,0 +1,18 @@
+/**
+ * @desc
+ *  Maps an Array<Item_Type> to an Array<Result_Type>, one element at a time.
+ *
+ * @param {Array<Item_Type>} items
+ * @param {function(item: Item_Type): Promise<Result_Type>} mappingFunction
+ */
+export function asyncMap<Item_Type, Result_Type>(items: Item_Type[], mappingFunction: (item: Item_Type) => Promise<Result_Type> | Result_Type): Promise<Result_Type[]> {
+    return items.reduce(
+        (previous, item) =>
+            previous.then(async (acc) => {
+                const result = await mappingFunction(item);
+
+                return acc.concat(result);
+            })
+        , Promise.resolve([])
+    );
+}

package/src/io/format.ts

@@ -0,0 +1,49 @@
+import { Answerable } from '../screenplay';
+import { inspected } from './inspected';
+
+/**
+ * @desc
+ *  A factory function returning a tag function that produces a human-readable description of a template containing one or more {@link Answerable}s.
+ *
+ * @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#Tagged_template_literals
+ *
+ * @example
+ *  import { format, Question } from '@serenity-js/core';
+ *
+ *  const someQuestion = () =>
+ *      Question.about('some question', actor => 'some value');
+ *
+ *  format({ markQuestions: true }) `actor answers ${ question() }`;
+ *  // returns: actor answers <<some question>>
+ *
+ *  format({ markQuestions: false }) `actor answers ${ question() }`;
+ *  // returns: actor answers <<some question>>
+ *
+ * @example <caption>Aliasing</caption>
+ *  import { format, Question } from '@serenity-js/core';
+ *
+ *  const f = format({ markQuestions: true });
+ *
+ *  const someQuestion = () =>
+ *      Question.about('some question', actor => 'some value');
+ *
+ *  f `actor answers ${ question() }`;
+ *  // produces: actor answers <<some question>>
+ *
+ * @param {object} config
+ *  - `markQuestions`: boolean - if set to true, descriptions of questions passed in as arguments will be surrounded with double angled brackets, i.e. `<<description>>`
+ * @returns {function(templates: TemplateStringsArray, placeholders: ...Array<Answerable<any>>): string}
+ */
+export function format(config: { markQuestions: boolean }): (templates: TemplateStringsArray, ...placeholders: Array<Answerable<any>>) => string {
+    return (templates: TemplateStringsArray, ...placeholders: Array<Answerable<any>>): string => {
+        return templates
+            .map((template, i) => i < placeholders.length
+                ? [ template, inspected(placeholders[i], { inline: true, markQuestions: config.markQuestions }) ]
+                : [ template ])
+            .reduce((acc, tuple) => acc.concat(tuple))
+            .join('');
+    }
+}
+
+export const f = format({ markQuestions: true });
+export const d = format({ markQuestions: false });

package/src/io/formatted.ts

@@ -1,28 +1,20 @@
-import { Answerable } from '../screenplay/Answerable';
-import { inspected } from './inspected';
+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 templates
-        .map((template, i) => i < placeholders.length
-            ? [ template, compacted(inspected(placeholders[i])) ]
-            : [ template ])
-        .reduce((acc, tuple) => acc.concat(tuple))
-        .join('');
-}
-
-/** @private */
-function compacted(multiline: string) {
-    return multiline
-        .replace(/\r?\n/g, ' ')
-        .replace(/\s+/g, ' ');
+    return format({ markQuestions: false })(templates, ...placeholders);
 }

package/src/io/index.ts

@@ -1,5 +1,5 @@
 export * from './AssertionReportDiffer';
-export * from './collections';
+export * from './asyncMap';
 export * from './commaSeparated';
 export * from './Config';
 export * from './ErrorSerialiser';
@@ -7,6 +7,7 @@ export * from './ErrorStackParser';
 export * from './FileFinder';
 export * from './FileSystem';
 export * from './FileSystemLocation';
+export * from './format';
 export * from './formatted';
 export * from './json';
 export * from './ModuleLoader';

package/src/io/inspected.ts

@@ -3,6 +3,11 @@ import { inspect } from 'util';
 import { Answerable } from '../screenplay/Answerable';
 import { Question } from '../screenplay/Question';
 
+interface InspectedConfig {
+    inline: boolean;
+    markQuestions?: boolean;
+}
+
 /**
  * @desc
  *  Provides a human-readable description of the {@link Answerable<T>}.
@@ -10,27 +15,29 @@ import { Question } from '../screenplay/Question';
  *
  * @public
  * @param {Answerable<any>} value
+ * @param config
+ *  - inline - Return a single-line string instead of the default potentially multi-line description
+ *  - markQuestions - Surround the description of async values, such as Promises and Questions with <<value>>
  * @return {string}
  */
-export function inspected(value: Answerable<any>): string {
+export function inspected(value: Answerable<any>, config?: InspectedConfig): string {
+
+    const { inline, markQuestions } = { inline: false, markQuestions: false, ...config };
+
     if (! isDefined(value)) {
         return inspect(value);
     }
 
     if (Array.isArray(value)) {
-        return [
-            '[',
-            value.map(item => `  ${ inspected(item) }`).join(',\n'),
-            ']',
-        ].join('\n');
+        return stringifiedArray(value, inline);
     }
 
     if (isAPromise(value)) {
-        return `a Promise`;
+        return markAs('Promise', true);
     }
 
     if (Question.isAQuestion(value)) {
-        return value.toString();
+        return markAs(value.toString(), markQuestions);
     }
 
     if (isADate(value)) {
@@ -45,15 +52,49 @@ export function inspected(value: Answerable<any>): string {
         return value.inspect();
     }
 
-    if (isANamedFunction(value)) {
-        return `${ value.name } property`;
+    if (isAFunction(value)) {
+        return hasName(value)
+            ? value.name
+            : markAs(`Function`, true);
     }
 
     if (! hasCustomInspectionFunction(value) && isPlainObject(value) && isSerialisableAsJSON(value)) {
-        return JSON.stringify(value, undefined, 4);
+        return stringifiedToJson(value, inline);
     }
 
-    return inspect(value, { breakLength: Number.POSITIVE_INFINITY, compact: true, sorted: false  });
+    return inspect(value, { breakLength: Number.POSITIVE_INFINITY, compact: inline ? 3 : false, sorted: false  });
+}
+
+function stringifiedToJson(value: any, inline: boolean): string {
+    const indentation = inline ? 0 : 4;
+
+    return JSON.stringify(value, undefined, indentation);
+}
+
+function stringifiedArray(value: any[], inline: boolean): string {
+    const indentation   = inline ? '' : '  ';
+    const separator     = inline ? ' ' : '\n';
+
+    const inspectedItem = (item: unknown, index: number) =>
+        [
+            indentation,
+            inspected(item, { inline, markQuestions: true }),
+            index < value.length - 1 ? ',' : ''
+        ].join('')
+
+    return [
+        '[',
+        ...value.map(inspectedItem),
+        ']',
+    ].join(separator);
+}
+
+function markAs(value: string, markValue: boolean): string {
+    const [left, right] = markValue && ! value.startsWith('<<')
+        ? [ '<<', '>>' ]
+        : ['', ''];
+
+    return [ left, value, right ].join('');
 }
 
 /**
@@ -111,7 +152,8 @@ function isADate(v: Answerable<any>): v is Date {
  * @param {Answerable<any>} v
  */
 function isAPromise<T>(v: Answerable<T>): v is Promise<T> {
-    return !! (v as any).then;
+    return typeof v === 'object'
+        && 'then' in v;
 }
 
 /**
@@ -121,8 +163,19 @@ function isAPromise<T>(v: Answerable<T>): v is Promise<T> {
  * @private
  * @param {Answerable<any>} v
  */
-function isANamedFunction(v: any): v is { name: string } {
-    return Object.prototype.toString.call(v) === '[object Function]' && (v as any).name !== '';
+function isAFunction(v: any): v is Function {       // eslint-disable-line @typescript-eslint/ban-types
+    return Object.prototype.toString.call(v) === '[object Function]';
+}
+
+/**
+ * @desc
+ *  Checks if the value is has a property called 'name' with a non-empty value.
+ *
+ * @private
+ * @param {Answerable<any>} v
+ */
+function hasName(v: any): v is { name: string } {
+    return typeof (v as any).name === 'string' && (v as any).name !== '';
 }
 
 /**

package/src/model/Timestamp.ts

@@ -8,7 +8,11 @@ export class Timestamp extends TinyType {
         return new Timestamp(new Date(ensure(Timestamp.name, v, isSerialisedISO8601Date())));
     }
 
-    static fromMillisecondTimestamp(v: number): Timestamp {
+    static fromTimestampInSeconds(v: number): Timestamp {
+        return Timestamp.fromTimestampInMilliseconds(v * 1000);
+    }
+
+    static fromTimestampInMilliseconds(v: number): Timestamp {
         return new Timestamp(moment(v).toDate());
     }
 
@@ -29,10 +33,14 @@ export class Timestamp extends TinyType {
         return new Timestamp(moment(this.value).subtract(duration.inMilliseconds(), 'ms').toDate());
     }
 
-    toMillisecondTimestamp(): number {
+    toMilliseconds(): number {
         return moment(this.value).valueOf();
     }
 
+    toSeconds(): number {
+        return moment(this.value).unix();
+    }
+
     toJSON(): string {
         return this.value.toJSON();
     }

package/src/screenplay/Optional.ts

@@ -0,0 +1,30 @@
+import { Answerable } from './Answerable';
+
+/**
+ * @desc
+ *  `Optional` is a container object, which holds a value that may or may not be "present",
+ *
+ *  The meaning of being "present" depends on the context and typically means a value that:
+ *  - is other than `null` or `undefined`
+ *  - is retrievable, so retrieving it doesn't throw any errors
+ *
+ *  Additionally, `Optional` can also have a context-specific meaning. For example, `Optional#isPresent()`:
+ *  - in the context of a `PageElement` means that the element exists in the DOM.
+ *  - in the context of a `ModalWindow` means that the modal window is open.
+ *  - in the case of a REST API response, `LastResponse.body().books[0].author.name.isPresent()`
+ *    will inform us if a given entry exists (so `books[0].author.name`),
+ *    and if all the links of the property chain leading to the entry of interest exist too
+ *    (so `books` is present, and so is `books[0]`, `books[0].author`, `books[0].author.name`).
+ *
+ * @public
+ */
+export interface Optional {
+    /**
+     * @desc
+     *  Returns an {@link Answerable} that resolves to `true` when the optional value
+     *  is present, `false` otherwise.
+     *
+     * @returns {Answerable<boolean>}
+     */
+    isPresent(): Answerable<boolean>;
+}