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

package/lib/instance.d.ts

@@ -1,86 +1,150 @@
-import { Actor } from './screenplay/actor';
+import { SerenityConfig } from './config';
+import { Actor } from './screenplay';
 import { Serenity } from './Serenity';
-import { SerenityConfig } from './SerenityConfig';
 import { Cast } from './stage';
+/**
+ * Serenity object is the root object of the Serenity/JS framework.
+ *
+ * @group Serenity
+ */
 export declare const serenity: Serenity;
 /**
- * @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.
+ * 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.
  *
- *  This function is an alias for {@link Serenity#configure}.
+ * This function is an alias for {@apilink Serenity.configure}.
  *
- * @param {SerenityConfig} config
- * @return {void}
+ * :::tip configure vs engage
+  * If you want to retain the configuration but reset the {@apilink Cast|cast of actors}, use {@apilink engage} instead.
+ * :::
  *
- * @see {@link Serenity#configure}
+ * @param config
+ *
+ * @group Serenity
  */
 export declare function 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}.
+ *
+ * This function is an alias for {@apilink Serenity.engage},
+ * 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,
+ * - [`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
+ *     );
+ *   }
+ * }
+ *
+ * engage(new Actors());
+ * ```
+ *
+ * ### Using with Mocha test runner
+ *
+ * ```ts
+ * import { beforeEach } from 'mocha'
+ *
+ * beforeEach(() => engage(new Actors()))
+ * ```
+ *
+ * ### Using with Jasmine test runner
+ *
+ * ```typescript
+ * import 'jasmine'
+ *
+ * describe('My feature', () => {
+ *   beforeEach(() => engage(new Actors()))
+ *
+ *
+ * })
+ * ```
+ *
+ * ### Using with Cucumber.js test runner
+ *
+ * Engage `Actors` [before](https://github.com/cucumber/cucumber-js/blob/main/docs/support_files/hooks.md)
+ * each test scenario:
  *
- *  This function is an alias for {@link Serenity#engage},
- *  which provides an alternative to calling {@link Actor#whoCan}
- *  directly in your tests and is typically invoked in a "before all"
- *  or "before each" hook of your test runner of choice.
+ * ```typescript
+ * import { Before } from '@cucumber/cucumber'
  *
- *  If your implementation of the {@link Cast} interface is stateless,
- *  you can invoke this function 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
+ * Before(() => engage(new Actors()))
+ * ```
  *
- *  However, if your {@link Cast} holds state that you want 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
+ * Engage `Actors` before scenarios with [specific tags](https://github.com/cucumber/cucumber-js/blob/main/docs/support_files/hooks.md#tagged-hooks):
  *
- * @example <caption>Engaging a cast of actors</caption>
- *  import { Actor, Cast } from '@serenity-js/core';
+ * ```typescript
+ * import { Before } from '@cucumber/cucumber'
  *
- *  class Actors implements Cast {
- *      prepare(actor: Actor) {
- *          return actor.whoCan(
- *              // ... abilities you'd like the Actor to have
- *          );
- *      }
- *  }
+ * Before('@web', () => engage(new Actors()))
+ * ```
  *
- * engage(new Actors();
+ * ### Using with Playwright Test runner
  *
- * @example <caption>Usage with Jasmine</caption>
- *  import 'jasmine';
+ * [Serenity/JS Playwright Test module](/api/playwright-test) will configure the cast on your behalf,
+ * so you don't need to call {@apilink engage}.
  *
- *  beforeEach(() => engage(new Actors()));
+ * ```ts
+ * import { describe, it, test } from '@serenity-js/playwright-test'
  *
- * @example <caption>Usage with Cucumber</caption>
- *  import { Before } from 'cucumber';
+ * describe('My feature', () => {
  *
- *  Before(() => engage(new Actors());
+ *   this.use({
+ *     actors: new Actors()
+ *   })
  *
- * @param {Cast} actors
- * @returns {void}
+ *   // test scenarios
  *
- * @see {@link Actor}
- * @see {@link Cast}
+ * })
+ * ```
  *
- * @see {@link Serenity#engage}
+ * ## Learn more
+ * - {@apilink Actor}
+ * - {@apilink Cast}
+ * - {@apilink Serenity.engage}
+ *
+ * @param actors
+ *
+ * @group Serenity
  */
 export declare function 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.
  *
- *  This method is an alias for {@link Serenity#theActorCalled}.
+ * This method is an alias for {@apilink Serenity.theActorCalled}.
  *
- * @example <caption>Usage with Jasmine</caption>
- *   import 'jasmine';
+ * ## Usage with Mocha
+ *
+ * ```typescript
+ *   import { describe, it } from 'mocha';
  *   import { actorCalled } from '@serenity-js/core';
  *
  *   describe('Feature', () => {
@@ -88,57 +152,83 @@ export declare function engage(actors: Cast): void;
  *      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
  *
- * @returns {Actor}
+ * ```typescript
+ * import { actorCalled } from '@serenity-js/core';
+ * import { Given } from '@cucumber/cucumber';
  *
- * @see {@link engage}
- * @see {@link Actor}
- * @see {@link Cast}
- * @see {@link Serenity#theActorCalled}
+ * Given(/(.*?) is a registered user/, (name: string) =>
+ *   actorCalled(name).attemptsTo(
+ *     // ... activities
+ *   ))
+ * ```
+ *
+ * ## Learn more
+ *
+ * - {@apilink engage}
+ * - {@apilink Actor}
+ * - {@apilink Cast}
+ * - {@apilink Serenity.theActorCalled}
+ *
+ * @param name
+ *  The name of the actor to instantiate or retrieve
+ *
+ * @group Actors
  */
 export declare function actorCalled(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 actorCalled}.
  *
- *  This function is particularly useful when automating Cucumber scenarios.
+ * This function is particularly useful when automating Cucumber scenarios.
  *
- *  This function is an alias for {@link Serenity#theActorInTheSpotlight}.
+ * This function is an alias for {@apilink Serenity.theActorInTheSpotlight}.
  *
- * @example <caption>Usage with Cucumber</caption>
- *   import { actorCalled } from '@serenity-js/core';
- *   import { Given, When } from 'cucumber';
+ * ## Usage with Cucumber
  *
- *   Given(/(.*?) is a registered user/, (name: string) =>
- *      actorCalled(name).attemptsTo(
- *              // ... activities
- *          ));
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core';
+ * import { Given, When } from '@cucumber/cucumber';
  *
- *   When(/(?:he|she|they) browse their recent orders/, () =>
- *      actorInTheSpotlight().attemptsTo(
- *              // ... activities
- *          ));
+ * Given(/(.*?) is a registered user/, (name: string) =>
+ *   actorCalled(name).attemptsTo(
+ *     // ... activities
+ *   ))
+ *
+ * When(/(?:he|she|they) browse their recent orders/, () =>
+ *   actorInTheSpotlight().attemptsTo(
+ *     // ... activities
+ *   ))
+ * ```
+ *
+ * ## Learn more
  *
- * @returns {Actor}
+ * - {@apilink engage}
+ * - {@apilink actorCalled}
+ * - {@apilink Actor}
+ * - {@apilink Cast}
  *
- * @see {@link engage}
- * @see {@link actorCalled}
- * @see {@link Actor}
- * @see {@link Cast}
+ * @group Actors
  */
 export declare function actorInTheSpotlight(): Actor;
+//# sourceMappingURL=instance.d.ts.map

package/lib/instance.d.ts.map

@@ -0,0 +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,EAAS,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAI/B;;;;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

@@ -1,94 +1,158 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.actorInTheSpotlight = exports.actorCalled = exports.engage = exports.configure = exports.serenity = void 0;
+const screenplay_1 = require("./screenplay");
 const Serenity_1 = require("./Serenity");
-const stage_1 = require("./stage");
-const clock = new stage_1.Clock();
+const clock = new screenplay_1.Clock();
+/**
+ * Serenity object is the root object of the Serenity/JS framework.
+ *
+ * @group Serenity
+ */
 exports.serenity = new Serenity_1.Serenity(clock);
 /**
- * @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.
+ * 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.
  *
- *  This function is an alias for {@link Serenity#configure}.
+ * This function is an alias for {@apilink Serenity.configure}.
  *
- * @param {SerenityConfig} config
- * @return {void}
+ * :::tip configure vs engage
+  * If you want to retain the configuration but reset the {@apilink Cast|cast of actors}, use {@apilink engage} instead.
+ * :::
  *
- * @see {@link Serenity#configure}
+ * @param config
+ *
+ * @group Serenity
  */
 function configure(config) {
     exports.serenity.configure(config);
 }
 exports.configure = configure;
 /**
- * @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}.
+ *
+ * This function is an alias for {@apilink Serenity.engage},
+ * 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,
+ * - [`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
+ *     );
+ *   }
+ * }
+ *
+ * engage(new Actors());
+ * ```
+ *
+ * ### Using with Mocha test runner
+ *
+ * ```ts
+ * import { beforeEach } from 'mocha'
+ *
+ * beforeEach(() => engage(new Actors()))
+ * ```
+ *
+ * ### Using with Jasmine test runner
+ *
+ * ```typescript
+ * import 'jasmine'
+ *
+ * describe('My feature', () => {
+ *   beforeEach(() => engage(new Actors()))
+ *
+ *
+ * })
+ * ```
+ *
+ * ### Using with Cucumber.js test runner
+ *
+ * Engage `Actors` [before](https://github.com/cucumber/cucumber-js/blob/main/docs/support_files/hooks.md)
+ * each test scenario:
  *
- *  This function is an alias for {@link Serenity#engage},
- *  which provides an alternative to calling {@link Actor#whoCan}
- *  directly in your tests and is typically invoked in a "before all"
- *  or "before each" hook of your test runner of choice.
+ * ```typescript
+ * import { Before } from '@cucumber/cucumber'
  *
- *  If your implementation of the {@link Cast} interface is stateless,
- *  you can invoke this function 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
+ * Before(() => engage(new Actors()))
+ * ```
  *
- *  However, if your {@link Cast} holds state that you want 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
+ * Engage `Actors` before scenarios with [specific tags](https://github.com/cucumber/cucumber-js/blob/main/docs/support_files/hooks.md#tagged-hooks):
  *
- * @example <caption>Engaging a cast of actors</caption>
- *  import { Actor, Cast } from '@serenity-js/core';
+ * ```typescript
+ * import { Before } from '@cucumber/cucumber'
  *
- *  class Actors implements Cast {
- *      prepare(actor: Actor) {
- *          return actor.whoCan(
- *              // ... abilities you'd like the Actor to have
- *          );
- *      }
- *  }
+ * Before('@web', () => engage(new Actors()))
+ * ```
  *
- * engage(new Actors();
+ * ### Using with Playwright Test runner
  *
- * @example <caption>Usage with Jasmine</caption>
- *  import 'jasmine';
+ * [Serenity/JS Playwright Test module](/api/playwright-test) will configure the cast on your behalf,
+ * so you don't need to call {@apilink engage}.
  *
- *  beforeEach(() => engage(new Actors()));
+ * ```ts
+ * import { describe, it, test } from '@serenity-js/playwright-test'
  *
- * @example <caption>Usage with Cucumber</caption>
- *  import { Before } from 'cucumber';
+ * describe('My feature', () => {
  *
- *  Before(() => engage(new Actors());
+ *   this.use({
+ *     actors: new Actors()
+ *   })
  *
- * @param {Cast} actors
- * @returns {void}
+ *   // test scenarios
  *
- * @see {@link Actor}
- * @see {@link Cast}
+ * })
+ * ```
  *
- * @see {@link Serenity#engage}
+ * ## Learn more
+ * - {@apilink Actor}
+ * - {@apilink Cast}
+ * - {@apilink Serenity.engage}
+ *
+ * @param actors
+ *
+ * @group Serenity
  */
 function engage(actors) {
     exports.serenity.engage(actors);
 }
 exports.engage = engage;
 /**
- * @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.
  *
- *  This method is an alias for {@link Serenity#theActorCalled}.
+ * This method is an alias for {@apilink Serenity.theActorCalled}.
  *
- * @example <caption>Usage with Jasmine</caption>
- *   import 'jasmine';
+ * ## Usage with Mocha
+ *
+ * ```typescript
+ *   import { describe, it } from 'mocha';
  *   import { actorCalled } from '@serenity-js/core';
  *
  *   describe('Feature', () => {
@@ -96,61 +160,86 @@ exports.engage = engage;
  *      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
  *
- * @returns {Actor}
+ * ```typescript
+ * import { actorCalled } from '@serenity-js/core';
+ * import { Given } from '@cucumber/cucumber';
  *
- * @see {@link engage}
- * @see {@link Actor}
- * @see {@link Cast}
- * @see {@link Serenity#theActorCalled}
+ * Given(/(.*?) is a registered user/, (name: string) =>
+ *   actorCalled(name).attemptsTo(
+ *     // ... activities
+ *   ))
+ * ```
+ *
+ * ## Learn more
+ *
+ * - {@apilink engage}
+ * - {@apilink Actor}
+ * - {@apilink Cast}
+ * - {@apilink Serenity.theActorCalled}
+ *
+ * @param name
+ *  The name of the actor to instantiate or retrieve
+ *
+ * @group Actors
  */
 function actorCalled(name) {
     return exports.serenity.theActorCalled(name);
 }
 exports.actorCalled = actorCalled;
 /**
- * @desc
- *  Retrieves an actor who was last instantiated or retrieved
- *  using {@link actorCalled}.
+ * Retrieves an actor who was last instantiated or retrieved
+ * using {@apilink actorCalled}.
  *
- *  This function is particularly useful when automating Cucumber scenarios.
+ * This function is particularly useful when automating Cucumber scenarios.
  *
- *  This function is an alias for {@link Serenity#theActorInTheSpotlight}.
+ * This function is an alias for {@apilink Serenity.theActorInTheSpotlight}.
  *
- * @example <caption>Usage with Cucumber</caption>
- *   import { actorCalled } from '@serenity-js/core';
- *   import { Given, When } from 'cucumber';
+ * ## Usage with Cucumber
  *
- *   Given(/(.*?) is a registered user/, (name: string) =>
- *      actorCalled(name).attemptsTo(
- *              // ... activities
- *          ));
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core';
+ * import { Given, When } from '@cucumber/cucumber';
  *
- *   When(/(?:he|she|they) browse their recent orders/, () =>
- *      actorInTheSpotlight().attemptsTo(
- *              // ... activities
- *          ));
+ * Given(/(.*?) is a registered user/, (name: string) =>
+ *   actorCalled(name).attemptsTo(
+ *     // ... activities
+ *   ))
+ *
+ * When(/(?:he|she|they) browse their recent orders/, () =>
+ *   actorInTheSpotlight().attemptsTo(
+ *     // ... activities
+ *   ))
+ * ```
+ *
+ * ## Learn more
  *
- * @returns {Actor}
+ * - {@apilink engage}
+ * - {@apilink actorCalled}
+ * - {@apilink Actor}
+ * - {@apilink Cast}
  *
- * @see {@link engage}
- * @see {@link actorCalled}
- * @see {@link Actor}
- * @see {@link Cast}
+ * @group Actors
  */
 function actorInTheSpotlight() {
     return exports.serenity.theActorInTheSpotlight();

package/lib/instance.js.map

@@ -1 +1 @@
-{"version":3,"file":"instance.js","sourceRoot":"","sources":["../src/instance.ts"],"names":[],"mappings":";;;AACA,yCAAsC;AAEtC,mCAAsC;AAEtC,MAAM,KAAK,GAAG,IAAI,aAAK,EAAE,CAAC;AAEb,QAAA,QAAQ,GAAG,IAAI,mBAAQ,CAAC,KAAK,CAAC,CAAC;AAE5C;;;;;;;;;;;;;GAaG;AACH,SAAgB,SAAS,CAAC,MAAsB;IAC5C,gBAAQ,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;AAC/B,CAAC;AAFD,8BAEC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,SAAgB,MAAM,CAAC,MAAY;IAC/B,gBAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AAC5B,CAAC;AAFD,wBAEC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,SAAgB,WAAW,CAAC,IAAY;IACpC,OAAO,gBAAQ,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;AACzC,CAAC;AAFD,kCAEC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;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":";;;AACA,6CAA4C;AAC5C,yCAAsC;AAGtC,MAAM,KAAK,GAAG,IAAI,kBAAK,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"}