@serenity-js/core 3.0.0-rc.42 → 3.0.0-rc.43

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [3.0.0-rc.43](https://github.com/serenity-js/serenity-js/compare/v3.0.0-rc.42...v3.0.0-rc.43) (2023-03-10)
+
+
+### Bug Fixes
+
+* **core:** introduced Cast.where factory method to make it easier to generate custom casts of actors ([26637f1](https://github.com/serenity-js/serenity-js/commit/26637f10746bbd264ab73ab14b43eaf11dea5652)), closes [#1523](https://github.com/serenity-js/serenity-js/issues/1523)
+
+
+
+
+
 # [3.0.0-rc.42](https://github.com/serenity-js/serenity-js/compare/v3.0.0-rc.41...v3.0.0-rc.42) (2023-02-12)
 
 

package/README.md

@@ -1,5 +1,10 @@
 # Serenity/JS
 
+[![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)
+
 [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.
 
@@ -10,7 +15,7 @@ and [API docs](https://serenity-js.org/modules/), and follow [@SerenityJS](https
 
 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/main/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).
+If you have any questions, join us on the [Serenity/JS Community Chat](https://matrix.to/#/#serenity-js:gitter.im).
 
 [![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)
 

package/lib/errors/ErrorOptions.d.ts

@@ -1,5 +1,8 @@
 import { FileSystemLocation } from '../io';
 import { ExpectationDetails } from '../screenplay';
+/**
+ * @group Errors
+ */
 export interface ErrorOptions {
     message: string;
     location?: FileSystemLocation;

package/lib/errors/ErrorOptions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ErrorOptions.d.ts","sourceRoot":"","sources":["../../src/errors/ErrorOptions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,OAAO,CAAC;AAC3C,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAEnD,MAAM,WAAW,YAAY;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IAC9B,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC,IAAI,CAAC,EAAE;QACH,QAAQ,EAAE,OAAO,CAAC;QAClB,MAAM,EAAE,OAAO,CAAC;KACnB,CAAC;IACF,KAAK,CAAC,EAAE,KAAK,CAAC;CACjB"}
+{"version":3,"file":"ErrorOptions.d.ts","sourceRoot":"","sources":["../../src/errors/ErrorOptions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,OAAO,CAAC;AAC3C,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAEnD;;GAEG;AACH,MAAM,WAAW,YAAY;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IAC9B,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC,IAAI,CAAC,EAAE;QACH,QAAQ,EAAE,OAAO,CAAC;QAClB,MAAM,EAAE,OAAO,CAAC;KACnB,CAAC;IACF,KAAK,CAAC,EAAE,KAAK,CAAC;CACjB"}

package/lib/instance.d.ts

@@ -16,6 +16,10 @@ export declare const serenity: Serenity;
  *
  * This function is an alias for {@apilink Serenity.configure}.
  *
+ * :::tip configure vs engage
+  * If you want to retain the configuration but reset the {@apilink Cast|cast of actors}, use {@apilink engage} instead.
+ * :::
+ *
  * @param config
  *
  * @group Serenity
@@ -29,6 +33,12 @@ export declare function configure(config: SerenityConfig): void;
  * 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.
  *
+ * :::tip configure vs engage
+ * Calling {@apilink engage} replaces the currently configured {@apilink Cast|cast of actors},
+ * but doesn't affect any other configuration.
+ * If you want to reset the Serenity/JS configuration completely, use {@apilink configure} instead.
+ * :::
+ *
  * 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,
@@ -67,20 +77,54 @@ export declare function configure(config: SerenityConfig): void;
  *
  * ### Using with Jasmine test runner
  *
- * ```ts
+ * ```typescript
  * import 'jasmine'
  *
- * beforeEach(() => engage(new Actors()))
+ * describe('My feature', () => {
+ *   beforeEach(() => engage(new Actors()))
+ *
+ *
+ * })
  * ```
  *
  * ### Using with Cucumber.js test runner
  *
- * ```ts
+ * Engage `Actors` [before](https://github.com/cucumber/cucumber-js/blob/main/docs/support_files/hooks.md)
+ * each test scenario:
+ *
+ * ```typescript
  * import { Before } from '@cucumber/cucumber'
  *
  * Before(() => engage(new Actors()))
  * ```
  *
+ * Engage `Actors` before scenarios with [specific tags](https://github.com/cucumber/cucumber-js/blob/main/docs/support_files/hooks.md#tagged-hooks):
+ *
+ * ```typescript
+ * import { Before } from '@cucumber/cucumber'
+ *
+ * Before('@web', () => engage(new Actors()))
+ * ```
+ *
+ * ### Using with Playwright Test runner
+ *
+ * [Serenity/JS Playwright Test module](/api/playwright-test) will configure the cast on your behalf,
+ * so you don't need to call {@apilink engage}.
+ *
+ * ```ts
+ * import { describe, it, test } from '@serenity-js/playwright-test'
+ *
+ * describe('My feature', () => {
+ *
+ *   this.use({
+ *     actors: new Actors()
+ *   })
+ *
+ *   // test scenarios
+ *
+ * })
+ * ```
+ *
  * ## Learn more
  * - {@apilink Actor}
  * - {@apilink Cast}
@@ -88,7 +132,7 @@ export declare function configure(config: SerenityConfig): void;
  *
  * @param actors
  *
- * @group Stage
+ * @group Serenity
  */
 export declare function engage(actors: Cast): void;
 /**

package/lib/instance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"instance.d.ts","sourceRoot":"","sources":["../src/instance.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,IAAI,EAAS,MAAM,SAAS,CAAC;AAItC;;;;GAIG;AACH,eAAO,MAAM,QAAQ,UAAsB,CAAC;AAE5C;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAEtD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,IAAI,GAAG,IAAI,CAEzC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAE/C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,mBAAmB,IAAI,KAAK,CAE3C"}
+{"version":3,"file":"instance.d.ts","sourceRoot":"","sources":["../src/instance.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,IAAI,EAAS,MAAM,SAAS,CAAC;AAItC;;;;GAIG;AACH,eAAO,MAAM,QAAQ,UAAsB,CAAC;AAE5C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAEtD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4GG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,IAAI,GAAG,IAAI,CAEzC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAE/C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,mBAAmB,IAAI,KAAK,CAE3C"}

package/lib/instance.js

@@ -18,6 +18,10 @@ exports.serenity = new Serenity_1.Serenity(clock);
  *
  * This function is an alias for {@apilink Serenity.configure}.
  *
+ * :::tip configure vs engage
+  * If you want to retain the configuration but reset the {@apilink Cast|cast of actors}, use {@apilink engage} instead.
+ * :::
+ *
  * @param config
  *
  * @group Serenity
@@ -34,6 +38,12 @@ exports.configure = configure;
  * 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.
  *
+ * :::tip configure vs engage
+ * Calling {@apilink engage} replaces the currently configured {@apilink Cast|cast of actors},
+ * but doesn't affect any other configuration.
+ * If you want to reset the Serenity/JS configuration completely, use {@apilink configure} instead.
+ * :::
+ *
  * 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,
@@ -72,20 +82,54 @@ exports.configure = configure;
  *
  * ### Using with Jasmine test runner
  *
- * ```ts
+ * ```typescript
  * import 'jasmine'
  *
- * beforeEach(() => engage(new Actors()))
+ * describe('My feature', () => {
+ *   beforeEach(() => engage(new Actors()))
+ *
+ *
+ * })
  * ```
  *
  * ### Using with Cucumber.js test runner
  *
- * ```ts
+ * Engage `Actors` [before](https://github.com/cucumber/cucumber-js/blob/main/docs/support_files/hooks.md)
+ * each test scenario:
+ *
+ * ```typescript
  * import { Before } from '@cucumber/cucumber'
  *
  * Before(() => engage(new Actors()))
  * ```
  *
+ * Engage `Actors` before scenarios with [specific tags](https://github.com/cucumber/cucumber-js/blob/main/docs/support_files/hooks.md#tagged-hooks):
+ *
+ * ```typescript
+ * import { Before } from '@cucumber/cucumber'
+ *
+ * Before('@web', () => engage(new Actors()))
+ * ```
+ *
+ * ### Using with Playwright Test runner
+ *
+ * [Serenity/JS Playwright Test module](/api/playwright-test) will configure the cast on your behalf,
+ * so you don't need to call {@apilink engage}.
+ *
+ * ```ts
+ * import { describe, it, test } from '@serenity-js/playwright-test'
+ *
+ * describe('My feature', () => {
+ *
+ *   this.use({
+ *     actors: new Actors()
+ *   })
+ *
+ *   // test scenarios
+ *
+ * })
+ * ```
+ *
  * ## Learn more
  * - {@apilink Actor}
  * - {@apilink Cast}
@@ -93,7 +137,7 @@ exports.configure = configure;
  *
  * @param actors
  *
- * @group Stage
+ * @group Serenity
  */
 function engage(actors) {
     exports.serenity.engage(actors);

package/lib/instance.js.map

@@ -1 +1 @@
-{"version":3,"file":"instance.js","sourceRoot":"","sources":["../src/instance.ts"],"names":[],"mappings":";;;AAEA,yCAAsC;AACtC,mCAAsC;AAEtC,MAAM,KAAK,GAAG,IAAI,aAAK,EAAE,CAAC;AAE1B;;;;GAIG;AACU,QAAA,QAAQ,GAAG,IAAI,mBAAQ,CAAC,KAAK,CAAC,CAAC;AAE5C;;;;;;;;;;;GAWG;AACH,SAAgB,SAAS,CAAC,MAAsB;IAC5C,gBAAQ,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;AAC/B,CAAC;AAFD,8BAEC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AACH,SAAgB,MAAM,CAAC,MAAY;IAC/B,gBAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AAC5B,CAAC;AAFD,wBAEC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,SAAgB,WAAW,CAAC,IAAY;IACpC,OAAO,gBAAQ,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;AACzC,CAAC;AAFD,kCAEC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,SAAgB,mBAAmB;IAC/B,OAAO,gBAAQ,CAAC,sBAAsB,EAAE,CAAC;AAC7C,CAAC;AAFD,kDAEC"}
+{"version":3,"file":"instance.js","sourceRoot":"","sources":["../src/instance.ts"],"names":[],"mappings":";;;AAEA,yCAAsC;AACtC,mCAAsC;AAEtC,MAAM,KAAK,GAAG,IAAI,aAAK,EAAE,CAAC;AAE1B;;;;GAIG;AACU,QAAA,QAAQ,GAAG,IAAI,mBAAQ,CAAC,KAAK,CAAC,CAAC;AAE5C;;;;;;;;;;;;;;;GAeG;AACH,SAAgB,SAAS,CAAC,MAAsB;IAC5C,gBAAQ,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;AAC/B,CAAC;AAFD,8BAEC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4GG;AACH,SAAgB,MAAM,CAAC,MAAY;IAC/B,gBAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AAC5B,CAAC;AAFD,wBAEC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,SAAgB,WAAW,CAAC,IAAY;IACpC,OAAO,gBAAQ,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;AACzC,CAAC;AAFD,kCAEC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,SAAgB,mBAAmB;IAC/B,OAAO,gBAAQ,CAAC,sBAAsB,EAAE,CAAC;AAC7C,CAAC;AAFD,kDAEC"}

package/lib/screenplay/Activity.d.ts

@@ -3,15 +3,15 @@ import { UsesAbilities } from './abilities';
 import { PerformsActivities } from './activities';
 import { AnswersQuestions } from './questions';
 /**
- * Serenity/JS Screenplay Pattern `Activity` represents
- * a {@apilink Task} or an {@apilink Interaction} to be performed by an {@apilink Actor}.
+ * **Activities** represents {@apilink Task|tasks} and {@apilink Interaction|interactions} to be performed by an {@apilink Actor|actor}.
  *
- * ## Learn more
+ * Learn more about:
+ * - [Performing activities at multiple levels](/handbook/design/screenplay-pattern#performing-activities-at-multiple-levels)
  * - {@apilink Actor}
  * - {@apilink PerformsActivities}
  * - [Command design pattern on Wikipedia](https://en.wikipedia.org/wiki/Command_pattern)
  *
- * @group Activities
+ * @group Screenplay Pattern
  */
 export declare abstract class Activity {
     #private;

package/lib/screenplay/Activity.js

@@ -20,15 +20,15 @@ const path_1 = __importDefault(require("path"));
 const errors_1 = require("../errors");
 const io_1 = require("../io");
 /**
- * Serenity/JS Screenplay Pattern `Activity` represents
- * a {@apilink Task} or an {@apilink Interaction} to be performed by an {@apilink Actor}.
+ * **Activities** represents {@apilink Task|tasks} and {@apilink Interaction|interactions} to be performed by an {@apilink Actor|actor}.
  *
- * ## Learn more
+ * Learn more about:
+ * - [Performing activities at multiple levels](/handbook/design/screenplay-pattern#performing-activities-at-multiple-levels)
  * - {@apilink Actor}
  * - {@apilink PerformsActivities}
  * - [Command design pattern on Wikipedia](https://en.wikipedia.org/wiki/Command_pattern)
  *
- * @group Activities
+ * @group Screenplay Pattern
  */
 class Activity {
     constructor(description, location = Activity.callerLocation(5)) {

package/lib/screenplay/Actor.d.ts

@@ -7,15 +7,63 @@ import { Activity } from './Activity';
 import { CollectsArtifacts } from './artifacts';
 import { AnswersQuestions } from './questions';
 /**
- * Core element of the Screenplay Pattern,
- * an {@apilink Actor} represents a user or an external system interacting with the system under test.
+ * **Actors** represent **people** and **external systems** interacting with the system under test.
+ * Their role is to perform {@apilink Activity|activities} that demonstrate how to accomplish a given goal.
  *
- * ## Learn more
+ * Actors are the core building block of the [Screenplay Pattern](/handbook/design/screenplay-pattern),
+ * along with {@apilink Ability|Abilities}, {@apilink Interaction|Interactions}, {@apilink Task|Tasks}, and {@apilink Question|Questions}.
+ * Actors are also the first thing you see in a typical Serenity/JS test scenario.
  *
+ * ![Screenplay Pattern](/images/design/serenity-js-screenplay-pattern.png)
+ *
+ * Learn more about:
  * - {@apilink Cast}
  * - {@apilink Stage}
+ * - {@apilink Ability|Abilities}
+ * - {@apilink Activity|Activities}
+ * - {@apilink Interaction|Interactions}
+ * - {@apilink Task|Tasks}
+ * - {@apilink Question|Questions}
+ *
+ * ## Representing people and systems as actors
+ *
+ * To use a Serenity/JS {@apilink Actor}, all you need is to say their name:
+ *
+ * ```typescript
+ * import { actorCalled } from '@serenity-js/core'
+ *
+ * actorCalled('Alice')
+ * // returns: Actor
+ * ```
+ *
+ * Serenity/JS actors perform within the scope of a test scenario, so the first time you invoke {@apilink actorCalled},
+ * Serenity/JS instantiates a new actor from the default {@apilink Cast} of actors (or any custom cast you might have {@apilink configured|configured}).
+ * Any subsequent invocations of this function within the scope of the same test scenario retrieve the already instantiated actor, identified by their name.
+ *
+ * ```typescript
+ * import { actorCalled } from '@serenity-js/core'
+ *
+ * actorCalled('Alice')    // instantiates Alice
+ * actorCalled('Bob')      // instantiates Bob
+ * actorCalled('Alice')    // retrieves Alice, since she's already been instantiated
+ * ```
+ *
+ * Serenity/JS scenarios can involve as many or as few actors as you need to model the given business workflow.
+ * For example, you might want to use **multiple actors** in test scenarios that model how **different people** perform different parts of a larger business process, such as reviewing and approving a loan application.
+ * It is also quite common to introduce **supporting actors** to perform **administrative tasks**, like setting up test data and environment, or **audit tasks**, like checking the logs or messages emitted to a message queue
+ * by the system under test.
+ *
+ * :::info The Stan Lee naming convention
+ * Actor names can be much more than just simple identifiers like `Alice` or `Bob`. While you can give your actors any names you like, a good convention to follow is to give them
+ * names indicating the [personae](https://articles.uie.com/goodwin_interview/) they represent or the role they play in the system.
+ *
+ * Just like the characters in [Stan Lee](https://en.wikipedia.org/wiki/Stan_Lee) graphic novels,
+ * actors in Serenity/JS test scenarios are often given alliterate names as a mnemonic device.
+ * Names like "Adam the Admin", "Edna the Editor", "Trevor the Traveller", are far more memorable than a generic "UI user" or "API user".
+ * They're also much easier for people to associate with the context, constraints, and affordances of the given actor.
+ * :::
  *
- * @group Actors
+ * @group Screenplay Pattern
  */
 export declare class Actor implements PerformsActivities, UsesAbilities, CanHaveAbilities<Actor>, AnswersQuestions, CollectsArtifacts {
     readonly name: string;

package/lib/screenplay/Actor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Actor.d.ts","sourceRoot":"","sources":["../../src/screenplay/Actor.ts"],"names":[],"mappings":"AAKA,OAAO,EAEH,QAAQ,EAMR,IAAI,EAEP,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,UAAU,EAA2C,MAAM,eAAe,CAAC;AAC1G,OAAO,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AACjC,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C;;;;;;;;;;GAUG;AACH,qBAAa,KAAM,YACf,kBAAkB,EAClB,aAAa,EACb,gBAAgB,CAAC,KAAK,CAAC,EACvB,gBAAgB,EAChB,iBAAiB;aAGG,IAAI,EAAE,MAAM;IAC5B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS;gBAFV,IAAI,EAAE,MAAM,EACX,KAAK,EAAE,KAAK,EACZ,SAAS,GAAE,GAAG,CAAC,WAAW,CAAC,OAAO,CAAC,EAAE,OAAO,CAA4C;IAI7G;;;;;;;;;;OAUG;IACH,SAAS,CAAC,CAAC,SAAS,OAAO,EAAE,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC;IAqB5D;;;;;;OAMG;IACH,UAAU,CAAC,GAAG,UAAU,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAcpD;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,GAAG,SAAS,EAAE,OAAO,EAAE,GAAG,KAAK;IAMtC;;;;;;OAMG;IACH,MAAM,CAAC,CAAC,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAoBhD;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAUvD;;;OAGG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IASxB;;;;OAIG;IACH,QAAQ,IAAI,MAAM;IAMlB,OAAO,CAAC,mBAAmB;IAc3B,OAAO,CAAC,mBAAmB;IAW3B,OAAO,CAAC,aAAa;IAMrB,OAAO,CAAC,cAAc;IAUtB,OAAO,CAAC,iBAAiB;IASzB;;;;;OAKG;IACH,OAAO,CAAC,QAAQ;CAKnB"}
+{"version":3,"file":"Actor.d.ts","sourceRoot":"","sources":["../../src/screenplay/Actor.ts"],"names":[],"mappings":"AAKA,OAAO,EAEH,QAAQ,EAMR,IAAI,EAEP,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,UAAU,EAA2C,MAAM,eAAe,CAAC;AAC1G,OAAO,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AACjC,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,qBAAa,KAAM,YACf,kBAAkB,EAClB,aAAa,EACb,gBAAgB,CAAC,KAAK,CAAC,EACvB,gBAAgB,EAChB,iBAAiB;aAGG,IAAI,EAAE,MAAM;IAC5B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS;gBAFV,IAAI,EAAE,MAAM,EACX,KAAK,EAAE,KAAK,EACZ,SAAS,GAAE,GAAG,CAAC,WAAW,CAAC,OAAO,CAAC,EAAE,OAAO,CAA4C;IAI7G;;;;;;;;;;OAUG;IACH,SAAS,CAAC,CAAC,SAAS,OAAO,EAAE,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC;IAqB5D;;;;;;OAMG;IACH,UAAU,CAAC,GAAG,UAAU,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAcpD;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,GAAG,SAAS,EAAE,OAAO,EAAE,GAAG,KAAK;IAMtC;;;;;;OAMG;IACH,MAAM,CAAC,CAAC,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAoBhD;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAUvD;;;OAGG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IASxB;;;;OAIG;IACH,QAAQ,IAAI,MAAM;IAMlB,OAAO,CAAC,mBAAmB;IAc3B,OAAO,CAAC,mBAAmB;IAW3B,OAAO,CAAC,aAAa;IAMrB,OAAO,CAAC,cAAc;IAUtB,OAAO,CAAC,iBAAiB;IASzB;;;;;OAKG;IACH,OAAO,CAAC,QAAQ;CAKnB"}

package/lib/screenplay/Actor.js

@@ -10,15 +10,63 @@ const screenplay_1 = require("../screenplay");
 const Activity_1 = require("./Activity");
 const Question_1 = require("./Question");
 /**
- * Core element of the Screenplay Pattern,
- * an {@apilink Actor} represents a user or an external system interacting with the system under test.
+ * **Actors** represent **people** and **external systems** interacting with the system under test.
+ * Their role is to perform {@apilink Activity|activities} that demonstrate how to accomplish a given goal.
  *
- * ## Learn more
+ * Actors are the core building block of the [Screenplay Pattern](/handbook/design/screenplay-pattern),
+ * along with {@apilink Ability|Abilities}, {@apilink Interaction|Interactions}, {@apilink Task|Tasks}, and {@apilink Question|Questions}.
+ * Actors are also the first thing you see in a typical Serenity/JS test scenario.
  *
+ * ![Screenplay Pattern](/images/design/serenity-js-screenplay-pattern.png)
+ *
+ * Learn more about:
  * - {@apilink Cast}
  * - {@apilink Stage}
+ * - {@apilink Ability|Abilities}
+ * - {@apilink Activity|Activities}
+ * - {@apilink Interaction|Interactions}
+ * - {@apilink Task|Tasks}
+ * - {@apilink Question|Questions}
+ *
+ * ## Representing people and systems as actors
+ *
+ * To use a Serenity/JS {@apilink Actor}, all you need is to say their name:
+ *
+ * ```typescript
+ * import { actorCalled } from '@serenity-js/core'
+ *
+ * actorCalled('Alice')
+ * // returns: Actor
+ * ```
+ *
+ * Serenity/JS actors perform within the scope of a test scenario, so the first time you invoke {@apilink actorCalled},
+ * Serenity/JS instantiates a new actor from the default {@apilink Cast} of actors (or any custom cast you might have {@apilink configured|configured}).
+ * Any subsequent invocations of this function within the scope of the same test scenario retrieve the already instantiated actor, identified by their name.
+ *
+ * ```typescript
+ * import { actorCalled } from '@serenity-js/core'
+ *
+ * actorCalled('Alice')    // instantiates Alice
+ * actorCalled('Bob')      // instantiates Bob
+ * actorCalled('Alice')    // retrieves Alice, since she's already been instantiated
+ * ```
+ *
+ * Serenity/JS scenarios can involve as many or as few actors as you need to model the given business workflow.
+ * For example, you might want to use **multiple actors** in test scenarios that model how **different people** perform different parts of a larger business process, such as reviewing and approving a loan application.
+ * It is also quite common to introduce **supporting actors** to perform **administrative tasks**, like setting up test data and environment, or **audit tasks**, like checking the logs or messages emitted to a message queue
+ * by the system under test.
+ *
+ * :::info The Stan Lee naming convention
+ * Actor names can be much more than just simple identifiers like `Alice` or `Bob`. While you can give your actors any names you like, a good convention to follow is to give them
+ * names indicating the [personae](https://articles.uie.com/goodwin_interview/) they represent or the role they play in the system.
+ *
+ * Just like the characters in [Stan Lee](https://en.wikipedia.org/wiki/Stan_Lee) graphic novels,
+ * actors in Serenity/JS test scenarios are often given alliterate names as a mnemonic device.
+ * Names like "Adam the Admin", "Edna the Editor", "Trevor the Traveller", are far more memorable than a generic "UI user" or "API user".
+ * They're also much easier for people to associate with the context, constraints, and affordances of the given actor.
+ * :::
  *
- * @group Actors
+ * @group Screenplay Pattern
  */
 class Actor {
     constructor(name, stage, abilities = new Map()) {

package/lib/screenplay/Actor.js.map

@@ -1 +1 @@
-{"version":3,"file":"Actor.js","sourceRoot":"","sources":["../../src/screenplay/Actor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Actor.js","sourceRoot":"","sources":["../../src/screenplay/Actor.ts"],"names":[],"mappings":"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"}

package/lib/screenplay/Interaction.d.ts

@@ -3,13 +3,34 @@ import { Activity } from './Activity';
 import { CollectsArtifacts } from './artifacts';
 import { AnswersQuestions } from './questions';
 /**
- * Serenity/JS Screenplay Pattern `Interaction` is a low-level {@apilink Activity|activity} that directly
- * uses the {@apilink Actor|actor's} {@apilink Ability|ability} to interact
- * with the system under test.
+ * **Interactions** are low-level {@apilink Activity|activities} that encapsulate
+ * a handful of instructions for an {@apilink Actor|actor} on how to use their {@apilink Ability|abilities}
+ * to perform an individual interaction with the given interface of the system under test.
  *
- * Use the factory method `Interaction.where(description, interactionFunction)` to define custom interactions.
+ * :::tip Tasks or interactions?
+ * Because of their low-level nature, interactions are named using the vocabulary of the [solution domain](https://blog.mattwynne.net/2013/01/17/the-problem-with-solutions/),
+ * and represent an individual interaction with the given interface, e.g. {@apilink Click}, {@apilink Enter}, or {@apilink Send}.
  *
- * ## Defining a custom interaction
+ * Interactions follow the [Single Responsibility Principle](https://en.wikipedia.org/wiki/Single_responsibility_principle) which means that they do _one thing and one thing only_.
+ * If you're considering implementing an "interaction" that performs more than one logical activity, e.g. checks if the button is visible and then clicks on it if is,
+ * consider using separate interactions for separate responsibilities and then composing them using a {@apilink Task|task}.
+ * :::
+ *
+ * Interactions are the core building block of the [Screenplay Pattern](/handbook/design/screenplay-pattern),
+ * along with {@apilink Actor|Actors}, {@apilink Ability|Abilities}, {@apilink Question|Questions}, and {@apilink Task|Tasks}.
+ *
+ * ![Screenplay Pattern](/images/design/serenity-js-screenplay-pattern.png)
+ *
+ * Learn more about:
+ * - {@apilink Actors|Actor}
+ * - {@apilink Ability|Abilities}
+ * - {@apilink Activity|Activities}
+ *
+ * ## Writing a custom interaction
+ *
+ * [Serenity/JS modules](/handbook/about/architecture) ship with dozens of interactions to help you compose your test scenarios.
+ * However, if you need to interact with a non-standard interface, or want to create a flavour of a given interaction that behaves slightly differently than the built-in version,
+ * you can easily create your own implementations using the {@apilink Interaction.where} factory method.
  *
  * ```ts
  * import { Actor, Interaction } from '@serenity-js/core'
@@ -42,7 +63,7 @@ import { AnswersQuestions } from './questions';
  *   )
  * ```
  *
- * @group Activities
+ * @group Screenplay Pattern
  */
 export declare abstract class Interaction extends Activity {
     /**

package/lib/screenplay/Interaction.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Interaction.d.ts","sourceRoot":"","sources":["../../src/screenplay/Interaction.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,8BAAsB,WAAY,SAAQ,QAAQ;IAE9C;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,CACR,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,CAAC,KAAK,EAAE,aAAa,GAAG,gBAAgB,GAAG,iBAAiB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,GACnG,WAAW;IAId;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;CAC7E"}
+{"version":3,"file":"Interaction.d.ts","sourceRoot":"","sources":["../../src/screenplay/Interaction.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,8BAAsB,WAAY,SAAQ,QAAQ;IAE9C;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,CACR,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,CAAC,KAAK,EAAE,aAAa,GAAG,gBAAgB,GAAG,iBAAiB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,GACnG,WAAW;IAId;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;CAC7E"}

package/lib/screenplay/Interaction.js

@@ -3,13 +3,34 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Interaction = void 0;
 const Activity_1 = require("./Activity");
 /**
- * Serenity/JS Screenplay Pattern `Interaction` is a low-level {@apilink Activity|activity} that directly
- * uses the {@apilink Actor|actor's} {@apilink Ability|ability} to interact
- * with the system under test.
+ * **Interactions** are low-level {@apilink Activity|activities} that encapsulate
+ * a handful of instructions for an {@apilink Actor|actor} on how to use their {@apilink Ability|abilities}
+ * to perform an individual interaction with the given interface of the system under test.
  *
- * Use the factory method `Interaction.where(description, interactionFunction)` to define custom interactions.
+ * :::tip Tasks or interactions?
+ * Because of their low-level nature, interactions are named using the vocabulary of the [solution domain](https://blog.mattwynne.net/2013/01/17/the-problem-with-solutions/),
+ * and represent an individual interaction with the given interface, e.g. {@apilink Click}, {@apilink Enter}, or {@apilink Send}.
  *
- * ## Defining a custom interaction
+ * Interactions follow the [Single Responsibility Principle](https://en.wikipedia.org/wiki/Single_responsibility_principle) which means that they do _one thing and one thing only_.
+ * If you're considering implementing an "interaction" that performs more than one logical activity, e.g. checks if the button is visible and then clicks on it if is,
+ * consider using separate interactions for separate responsibilities and then composing them using a {@apilink Task|task}.
+ * :::
+ *
+ * Interactions are the core building block of the [Screenplay Pattern](/handbook/design/screenplay-pattern),
+ * along with {@apilink Actor|Actors}, {@apilink Ability|Abilities}, {@apilink Question|Questions}, and {@apilink Task|Tasks}.
+ *
+ * ![Screenplay Pattern](/images/design/serenity-js-screenplay-pattern.png)
+ *
+ * Learn more about:
+ * - {@apilink Actors|Actor}
+ * - {@apilink Ability|Abilities}
+ * - {@apilink Activity|Activities}
+ *
+ * ## Writing a custom interaction
+ *
+ * [Serenity/JS modules](/handbook/about/architecture) ship with dozens of interactions to help you compose your test scenarios.
+ * However, if you need to interact with a non-standard interface, or want to create a flavour of a given interaction that behaves slightly differently than the built-in version,
+ * you can easily create your own implementations using the {@apilink Interaction.where} factory method.
  *
  * ```ts
  * import { Actor, Interaction } from '@serenity-js/core'
@@ -42,7 +63,7 @@ const Activity_1 = require("./Activity");
  *   )
  * ```
  *
- * @group Activities
+ * @group Screenplay Pattern
  */
 class Interaction extends Activity_1.Activity {
     /**

package/lib/screenplay/Interaction.js.map

@@ -1 +1 @@
-{"version":3,"file":"Interaction.js","sourceRoot":"","sources":["../../src/screenplay/Interaction.ts"],"names":[],"mappings":";;;AACA,yCAAsC;AAItC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAsB,WAAY,SAAQ,mBAAQ;IAE9C;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,CACR,WAAmB,EACnB,WAAkG;QAElG,OAAO,IAAI,+BAA+B,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;IACzE,CAAC;CAcJ;AA5BD,kCA4BC;AAED;;GAEG;AACH,MAAM,+BAAgC,SAAQ,WAAW;IACrD,YACI,WAAmB,EACF,WAAkG;QAEnH,KAAK,CAAC,WAAW,EAAE,WAAW,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC;QAFjC,gBAAW,GAAX,WAAW,CAAuF;IAGvH,CAAC;IAED,SAAS,CAAC,KAA2D;QACjE,IAAI;YACA,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC;SACnD;QAAC,OAAO,KAAK,EAAE;YACZ,OAAO,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;SAChC;IACL,CAAC;CACJ"}
+{"version":3,"file":"Interaction.js","sourceRoot":"","sources":["../../src/screenplay/Interaction.ts"],"names":[],"mappings":";;;AACA,yCAAsC;AAItC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,MAAsB,WAAY,SAAQ,mBAAQ;IAE9C;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,CACR,WAAmB,EACnB,WAAkG;QAElG,OAAO,IAAI,+BAA+B,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;IACzE,CAAC;CAcJ;AA5BD,kCA4BC;AAED;;GAEG;AACH,MAAM,+BAAgC,SAAQ,WAAW;IACrD,YACI,WAAmB,EACF,WAAkG;QAEnH,KAAK,CAAC,WAAW,EAAE,WAAW,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC;QAFjC,gBAAW,GAAX,WAAW,CAAuF;IAGvH,CAAC;IAED,SAAS,CAAC,KAA2D;QACjE,IAAI;YACA,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC;SACnD;QAAC,OAAO,KAAK,EAAE;YACZ,OAAO,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;SAChC;IACL,CAAC;CACJ"}

package/lib/screenplay/Question.d.ts

@@ -8,8 +8,18 @@ import { AnswersQuestions } from './questions/AnswersQuestions';
 import { RecursivelyAnswered } from './RecursivelyAnswered';
 import { WithAnswerableProperties } from './WithAnswerableProperties';
 /**
- * Serenity/JS Screenplay Pattern `Question` describes how an {@apilink Actor}
- * should query the system under test or the test environment.
+ * **Questions** describe how {@apilink Actor|actors} should query the system under test or the test environment to retrieve some information.
+ *
+ * Questions are the core building block of the [Screenplay Pattern](/handbook/design/screenplay-pattern),
+ * along with {@apilink Actor|Actors}, {@apilink Ability|Abilities}, {@apilink Interaction|Interactions}, and {@apilink Task|Tasks}.
+ *
+ * ![Screenplay Pattern](/images/design/serenity-js-screenplay-pattern.png)
+ *
+ * Learn more about:
+ * - {@apilink Actor}
+ * - {@apilink Ability|Abilities}
+ * - {@apilink Interaction}
+ * - {@apilink QuestionAdapter}
  *
  * ## Implementing a basic custom Question
  *
@@ -27,7 +37,7 @@ import { WithAnswerableProperties } from './WithAnswerableProperties';
  *  )
  * ```
  *
- * ## Implementing a Question using an Ability
+ * ## Implementing a Question that uses an Ability
  *
  * Just like the {@apilink Interaction|interactions}, a {@apilink Question}
  * also can use {@apilink Actor|actor's} {@apilink Ability|abilities}.
@@ -90,14 +100,7 @@ import { WithAnswerableProperties } from './WithAnswerableProperties';
  *   );
  * ```
  *
- * ## Learn more
- *
- * - {@apilink Actor}
- * - {@apilink Interaction}
- * - {@apilink Ability}
- * - {@apilink QuestionAdapter}
- *
- * @group Questions
+ * @group Screenplay Pattern
  */
 export declare abstract class Question<T> {
     /**