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

package/README.md

@@ -1,18 +1,16 @@
 # Serenity/JS
 
-[Serenity/JS](https://serenity-js.org) is a framework designed to make acceptance and regression testing
-of modern full-stack applications faster, more collaborative and easier to scale.
+[![Follow Serenity/JS on LinkedIn](https://img.shields.io/badge/Follow-Serenity%2FJS%20-0077B5?logo=linkedin)](https://www.linkedin.com/company/serenity-js)
+[![Watch Serenity/JS on YouTube](https://img.shields.io/badge/Watch-@serenity--js-E62117?logo=youtube)](https://www.youtube.com/@serenity-js)
+[![Join Serenity/JS Community Chat](https://img.shields.io/badge/Chat-Serenity%2FJS%20Community-FBD30B?logo=matrix)](https://matrix.to/#/#serenity-js:gitter.im)
+[![Support Serenity/JS on GitHub](https://img.shields.io/badge/Support-@serenity--js-703EC8?logo=github)](https://matrix.to/#/#serenity-js:gitter.im)
 
-Visit [serenity-js.org](https://serenity-js.org/) for the [latest tutorials](https://serenity-js.org/handbook/)
-and [API docs](https://serenity-js.org/modules/), and follow [@SerenityJS](https://twitter.com/SerenityJS) and [@JanMolak](https://twitter.com/JanMolak) on Twitter for project updates.
+[Serenity/JS](https://serenity-js.org) is an innovative framework designed to make acceptance and regression testing
+of complex software systems faster, more collaborative and easier to scale.
 
-### Learning Serenity/JS
+To get started, check out the comprehensive [Serenity/JS Handbook](https://serenity-js.org/handbook), [API documentation](https://serenity-js.org/api/core), and [Serenity/JS project templates on GitHub](https://serenity-js.org/handbook/getting-started#serenityjs-project-templates). 
 
-To learn more about Serenity/JS, check out the video below, read the [tutorial](https://serenity-js.org/handbook/thinking-in-serenity-js/index.html), review the [examples](https://github.com/serenity-js/serenity-js/tree/master/examples), and create your own test suite with [Serenity/JS template projects](https://github.com/serenity-js).
-
-If you have any questions, join us on [Serenity/JS Community Chat](https://gitter.im/serenity-js/Lobby).
-
-[![Full-Stack Acceptance Testing with Serenity/JS and the Screenplay Pattern](https://img.youtube.com/vi/djPMf-n93Rw/0.jpg)](https://www.youtube.com/watch?v=djPMf-n93Rw)
+If you have any questions or just want to say hello, join the [Serenity/JS Community Chat](https://matrix.to/#/#serenity-js:gitter.im).
 
 ## Serenity/JS Core
 

package/lib/Serenity.d.ts

@@ -1,76 +1,113 @@
+import { SerenityConfig } from './config';
+import { ErrorOptions, RuntimeError } from './errors';
 import { DomainEvent } from './events';
-import { CorrelationId, Timestamp } from './model';
-import { Actor } from './screenplay/actor/Actor';
-import { SerenityConfig } from './SerenityConfig';
+import { Path } from './io';
+import { ActivityDetails, CorrelationId } from './model';
+import { Actor, Clock, Timestamp } from './screenplay';
 import { Cast } from './stage/Cast';
-import { Clock } from './stage/Clock';
+/**
+ * @group Serenity
+ */
 export declare class Serenity {
     private readonly clock;
     private static defaultCueTimeout;
+    private static defaultInteractionTimeout;
     private static defaultActors;
     private stage;
     private outputStream;
+    private readonly classLoader;
+    private readonly workingDirectory;
     /**
-     * @param {Clock} clock
+     * @param clock
      */
-    constructor(clock?: Clock);
+    constructor(clock?: Clock, cwd?: string);
     /**
-     * @desc
-     *  Configures Serenity/JS. Every call to this function
-     *  replaces the previous configuration provided,
-     *  so this function should called be exactly once
-     *  in your test suite.
-     *
-     * @param {SerenityConfig} config
-     * @return {void}
+     * Configures Serenity/JS. Every call to this function
+     * replaces the previous configuration provided,
+     * so this function should be called exactly once
+     * in your test suite.
+     *
+     * @param config
      */
     configure(config: SerenityConfig): void;
     /**
-     * @desc
-     *  Re-configures Serenity/JS with a new {@link Cast} of {@link Actor}s
-     *  you'd like to use in any subsequent call to {@link actorCalled}.
+     * Re-configures Serenity/JS with a new {@apilink Cast} of {@apilink Actor|actors}
+     * you want to use in any subsequent calls to {@apilink actorCalled}.
+     *
+     * For your convenience, use {@apilink engage} function instead,
+     * which provides an alternative to calling {@apilink Actor.whoCan} directly in your tests
+     * and is typically invoked in a "before all" or "before each" hook of your test runner of choice.
+     *
+     * If your implementation of the {@apilink Cast} interface is stateless,
+     * you can invoke this function just once before your entire test suite is executed, see
+     * - [`beforeAll`](https://jasmine.github.io/api/3.6/global.html#beforeAll) in Jasmine,
+     * - [`before`](https://mochajs.org/#hooks) in Mocha,
+     * - [`BeforeAll`](https://github.com/cucumber/cucumber-js/blob/master/docs/support_files/hooks.md#beforeall--afterall) in Cucumber.js
+     *
+     * However, if your {@apilink Cast} holds state that you want to reset before each scenario,
+     * it's better to invoke `engage` before each test using:
+     * - [`beforeEach`](https://jasmine.github.io/api/3.6/global.html#beforeEach) in Jasmine
+     * - [`beforeEach`](https://mochajs.org/#hooks) in Mocha,
+     * - [`Before`](https://github.com/cucumber/cucumber-js/blob/master/docs/support_files/hooks.md#hooks) in Cucumber.js
+     *
+     * ## Engaging a cast of actors
+     *
+     * ```ts
+     * import { Actor, Cast } from '@serenity-js/core';
+     *
+     * class Actors implements Cast {
+     *   prepare(actor: Actor) {
+     *     return actor.whoCan(
+     *       // ... abilities you'd like the Actor to have
+     *     );
+     *   }
+     * }
      *
-     *  This method provides an alternative to calling {@link Actor#whoCan}
-     *  directly in your tests and you'd typically us it in a "before each"
-     *  hook of your test runner of choice.
+     * engage(new Actors());
+     * ```
      *
-     * @example <caption>Engaging a cast of actors</caption>
-     *  import { Actor, Cast } from '@serenity-js/core';
+     * ### Using with Mocha test runner
      *
-     *  class Actors implements Cast {
-     *      prepare(actor: Actor) {
-     *          return actor.whoCan(
-     *              // ... abilities you'd like the Actor to have
-     *          );
-     *      }
-     *  }
+     * ```ts
+     * import { beforeEach } from 'mocha'
      *
-     * engage(new Actors();
+     * beforeEach(() => engage(new Actors()))
+     * ```
      *
-     * @example <caption>Usage with Jasmine</caption>
-     *  import 'jasmine';
+     * ### Using with Jasmine test runner
      *
-     *  beforeEach(() => engage(new Actors()));
+     * ```ts
+     * import 'jasmine'
      *
-     * @example <caption>Usage with Cucumber</caption>
-     *  import { Before } from 'cucumber';
+     * beforeEach(() => engage(new Actors()))
+     * ```
      *
-     *  Before(() => engage(new Actors());
+     * ### Using with Cucumber.js test runner
      *
-     * @param {Cast} actors
-     * @returns {void}
+     * ```ts
+     * import { Before } from '@cucumber/cucumber'
      *
-     * @see {@link Actor}
-     * @see {@link Cast}
+     * Before(() => engage(new Actors()))
+     * ```
+     *
+     * ## Learn more
+     * - {@apilink Actor}
+     * - {@apilink Cast}
+     * - {@apilink engage}
+     *
+     * @param actors
      */
     engage(actors: Cast): void;
     /**
-     * @desc
-     *  Instantiates or retrieves an actor {@link Actor}
-     *  called `name` if one has already been instantiated.
+     * Instantiates or retrieves an {@apilink Actor}
+     * called `name` if one has already been instantiated.
      *
-     * @example <caption>Usage with Jasmine</caption>
-     *   import 'jasmine';
+     * For your convenience, use {@apilink actorCalled} function instead.
+     *
+     * ## Usage with Mocha
+     *
+     * ```typescript
+     *   import { describe, it } from 'mocha';
      *   import { actorCalled } from '@serenity-js/core';
      *
      *   describe('Feature', () => {
@@ -78,64 +115,92 @@ export declare class Serenity {
      *      it('should have some behaviour', () =>
      *          actorCalled('James').attemptsTo(
      *              // ... activities
-     *          ));
-     *   });
+     *          ))
+     *   })
+     * ```
+     *
+     * ## Usage with Jasmine
      *
-     * @example <caption>Usage with Cucumber</caption>
+     * ```typescript
+     *   import 'jasmine';
      *   import { actorCalled } from '@serenity-js/core';
-     *   import { Given } from 'cucumber';
      *
-     *   Given(/(.*?) is a registered user/, (name: string) =>
-     *      actorCalled(name).attemptsTo(
+     *   describe('Feature', () => {
+     *
+     *      it('should have some behaviour', () =>
+     *          actorCalled('James').attemptsTo(
      *              // ... activities
-     *          ));
+     *          ))
+     *   })
+     * ```
      *
-     * @param {string} name
-     *  The name of the actor to instantiate or retrieve
+     * ## Usage with Cucumber
+     *
+     * ```typescript
+     * import { actorCalled } from '@serenity-js/core';
+     * import { Given } from '@cucumber/cucumber';
+     *
+     * Given(/(.*?) is a registered user/, (name: string) =>
+     *   actorCalled(name).attemptsTo(
+     *     // ... activities
+     *   ))
+     * ```
      *
-     * @returns {Actor}
+     * ## Learn more
      *
-     * @see {@link engage}
-     * @see {@link Actor}
-     * @see {@link Cast}
+     * - {@apilink engage}
+     * - {@apilink Actor}
+     * - {@apilink Cast}
+     * - {@apilink actorCalled}
+     *
+     * @param name
+     *  The name of the actor to instantiate or retrieve
      */
     theActorCalled(name: string): Actor;
     /**
-     * @desc
-     *  Retrieves an actor who was last instantiated or retrieved
-     *  using {@link actorCalled}.
+     * Retrieves an actor who was last instantiated or retrieved
+     * using {@apilink Serenity.theActorCalled}.
      *
-     *  This function is particularly useful when automating Cucumber scenarios.
+     * This function is particularly useful when automating Cucumber scenarios.
      *
-     * @example <caption>Usage with Cucumber</caption>
-     *   import { actorCalled } from '@serenity-js/core';
-     *   import { Given, When } from 'cucumber';
+     * For your convenience, use {@apilink actorInTheSpotlight} function instead.
      *
-     *   Given(/(.*?) is a registered user/, (name: string) =>
-     *      actorCalled(name).attemptsTo(
-     *              // ... activities
-     *          ));
+     * ## Usage with Cucumber
      *
-     *   When(/(?:he|she|they) browse their recent orders/, () =>
-     *      actorInTheSpotlight().attemptsTo(
-     *              // ... activities
-     *          ));
+     * ```ts
+     * import { actorCalled } from '@serenity-js/core';
+     * import { Given, When } from '@cucumber/cucumber';
+     *
+     * Given(/(.*?) is a registered user/, (name: string) =>
+     *   actorCalled(name).attemptsTo(
+     *     // ... activities
+     *   ))
+     *
+     * When(/(?:he|she|they) browse their recent orders/, () =>
+     *   actorInTheSpotlight().attemptsTo(
+     *     // ... activities
+     *   ))
+     * ```
      *
-     * @returns {Actor}
+     * ## Learn more
      *
-     * @see {@link engage}
-     * @see {@link actorCalled}
-     * @see {@link Actor}
-     * @see {@link Cast}
+     * - {@apilink engage}
+     * - {@apilink actorCalled}
+     * - {@apilink actorInTheSpotlight}
+     * - {@apilink Actor}
+     * - {@apilink Cast}
      */
     theActorInTheSpotlight(): Actor;
-    announce(event: DomainEvent): void;
+    announce(...events: Array<DomainEvent>): void;
     currentTime(): Timestamp;
     assignNewSceneId(): CorrelationId;
     currentSceneId(): CorrelationId;
-    assignNewActivityId(): CorrelationId;
+    assignNewActivityId(activityDetails: ActivityDetails): CorrelationId;
+    createError<RE extends RuntimeError>(errorType: new (...args: any[]) => RE, options: ErrorOptions): RE;
     /**
      * @package
      */
     waitForNextCue(): Promise<void>;
+    cwd(): Path;
 }
+//# sourceMappingURL=Serenity.d.ts.map

package/lib/Serenity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Serenity.d.ts","sourceRoot":"","sources":["../src/Serenity.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,EAAoC,YAAY,EAAqB,YAAY,EAAE,MAAM,UAAU,CAAC;AAC3G,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EAA6D,IAAI,EAAE,MAAM,MAAM,CAAC;AACvF,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACzD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAY,SAAS,EAAE,MAAM,cAAc,CAAC;AAEjE,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAKpC;;GAEG;AACH,qBAAa,QAAQ;IAeb,OAAO,CAAC,QAAQ,CAAC,KAAK;IAd1B,OAAO,CAAC,MAAM,CAAC,iBAAiB,CAAoC;IACpE,OAAO,CAAC,MAAM,CAAC,yBAAyB,CAA4B;IACpE,OAAO,CAAC,MAAM,CAAC,aAAa,CAA+B;IAE3D,OAAO,CAAC,KAAK,CAAQ;IACrB,OAAO,CAAC,YAAY,CAAiC;IAErD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAC1C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAO;IAExC;;OAEG;gBAEkB,KAAK,GAAE,KAAmB,EAC3C,GAAG,GAAE,MAAsB;IAkB/B;;;;;;;OAOG;IACH,SAAS,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI;IAoDvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkEG;IACH,MAAM,CAAC,MAAM,EAAE,IAAI,GAAG,IAAI;IAM1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAyDG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK;IAInC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACH,sBAAsB,IAAI,KAAK;IAI/B,QAAQ,CAAC,GAAG,MAAM,EAAE,KAAK,CAAC,WAAW,CAAC,GAAG,IAAI;IAI7C,WAAW,IAAI,SAAS;IAIxB,gBAAgB,IAAI,aAAa;IAIjC,cAAc,IAAI,aAAa;IAI/B,mBAAmB,CAAC,eAAe,EAAE,eAAe,GAAG,aAAa;IAIpE,WAAW,CAAC,EAAE,SAAS,YAAY,EAAE,SAAS,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,YAAY,GAAG,EAAE;IAItG;;OAEG;IACH,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IAI/B,GAAG,IAAI,IAAI;CAGd"}