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

package/src/screenplay/abilities/Ability.ts

@@ -0,0 +1,403 @@
+import { AbilityType } from './AbilityType';
+import { UsesAbilities } from './UsesAbilities';
+
+/**
+ * **Abilities** enable {@apilink Actor|actors}
+ * to perform {@apilink Interaction|interactions} with the system under test
+ * and answer {@apilink Question|questions} about its state.
+ *
+ * From the technical perspective, **abilities** act as **wrappers** around any **integration libraries** required
+ * to communicate with the external interfaces of system under test,
+ * such as {@apilink BrowseTheWeb|web browser drivers} or a {@apilink CallAnApi|HTTP client}.
+ * They also enable [portability](/handbook/design/portable-test-code)
+ * of your test code across such integration libraries.
+ *
+ * Abilities are the core building block of the [Screenplay Pattern](/handbook/design/screenplay-pattern),
+ * along with {@apilink Actor|Actors}, {@apilink Interaction|Interactions}, {@apilink Question|Questions}, and {@apilink Task|Tasks}.
+ *
+ * ![Screenplay Pattern](/images/design/serenity-js-screenplay-pattern.png)
+ *
+ * Learn more about:
+ * - {@apilink Actor|Actors}
+ * - {@apilink Cast|Configuring actors using Casts}
+ * - {@apilink Interaction|Interactions}
+ * - {@apilink Question|Questions}
+ * - [Web testing](/handbook/web-testing/)
+ * - [API testing](/handbook/api-testing/)
+ * - [Mobile testing](/handbook/mobile-testing/)
+ *
+ * ## Giving actors the abilities to interact
+ *
+ * Serenity/JS actors are capable of interacting with **any interface** of the system under test,
+ * be it a [web UI](/handbook/web-testing/), a [mobile app](/handbook/mobile-testing/), a [web service](/handbook/api-testing/),
+ * or {@apilink Ability|anything else} that a Node.js program can talk to.
+ * This flexibility is enabled by a mechanism called _**abilities**_
+ * and achieved without introducing any unnecessary dependencies to your code base thanks to the [modular architecture](/handbook/about/architecture) of Serenity/JS.
+ *
+ * :::tip Remember
+ * **Actors** have **abilities** that enable them to **perform interactions** and **answer questions**.
+ * :::
+ *
+ * From the technical perspective, an **ability** is an [adapter](https://en.wikipedia.org/wiki/Adapter_pattern)
+ * around an interface-specific integration library, such as a web browser driver, an HTTP client, a database client, and so on.
+ * You give an actor an ability, and it's the ability's responsibility to provide a consistent API around the integration library and deal with any of its quirks.
+ * Abilities **encapsulate integration libraries** and handle their {@apilink Initialisable|configuration and initialisation},
+ * the process of {@apilink Discardable|freeing up any resources} they hold,
+ * as well as managing any state associated with the library.
+ *
+ * ### Portable interactions with web interfaces
+ *
+ * To make your Serenity/JS actors interact with web interfaces,
+ * you call the [`Actor.whoCan`](/api/core/class/Actor#whoCan) method and give them an implementation of the ability to [`BrowseTheWeb`](/api/web/class/BrowseTheWeb),
+ * specific to your web integration tool of choice.
+ *
+ * Note how {@apilink BrowseTheWebWithPlaywright}, {@apilink BrowseTheWebWithWebdriverIO}, and {@apilink BrowseTheWebWithProtractor}
+ * all **extend** the base ability to {@apilink BrowseTheWeb}.
+ *
+ * #### Playwright Test
+ *
+ * ```typescript
+ * import { actorCalled } from '@serenity-js/core'
+ * import { BrowseTheWebWithPlaywright } from '@serenity-js/playwright'   // Serenity/JS integration module
+ * import { chromium } from 'playwright'
+ *
+ * const browser = await chromium.launch({ headless: true })              // integration library
+ *
+ * actorCalled('Trevor')                                                  // generic actor
+ *   .whoCan(BrowseTheWebWithPlaywright.using(browser))                   // tool-specific ability
+ * ```
+ *
+ * #### WebdriverIO
+ *
+ * ```typescript
+ * import { actorCalled } from '@serenity-js/core'
+ * import { BrowseTheWebWithWebdriverIO } from '@serenity-js/webdriverio' // Serenity/JS integration module
+ *
+ * actorCalled('Trevor')                                                  // generic actor
+ *   .whoCan(BrowseTheWebWithWebdriverIO.using(browser))                  // tool-specific ability
+ * ```
+ *
+ * #### Protractor
+ *
+ * ```typescript
+ * import { actorCalled } from '@serenity-js/core'
+ * import { BrowseTheWebWithProtractor } from '@serenity-js/protractor'   // Serenity/JS integration module
+ * import { protractor } from 'protractor'                                // integration library
+ *
+ * actorCalled('Trevor')                                                  // generic actor
+ *   .whoCan(BrowseTheWebWithProtractor.using(protractor.browser))        // tool-specific ability
+ * ```
+ *
+ * ### Retrieving an ability
+ *
+ * Use {@apilink Ability.as} to retrieve an ability in a custom {@apilink Interaction} or {@apilink Question} implementation.
+ *
+ * Here, `Ability` can be the integration library-specific class, for example {@apilink BrowseTheWebWithPlaywright},
+ * or its library-agnostic parent class, like {@apilink BrowseTheWeb}.
+ *
+ * To make your code portable across the various integration libraries, retrieve the ability
+ * using the library-agnostic parent class:
+ *
+ * ```typescript
+ * import { actorCalled } from '@serenity-js/core'
+ * import { BrowseTheWeb } from '@serenity-js/web' // Serenity/JS web module
+ *
+ * const actor    = actorCalled('Trevor')
+ * const ability  = await BrowseTheWeb.as(actor)   // retrieve implementation of BrowseTheWeb
+ * ```
+ *
+ * As you can already see, providing **encapsulation** and a **cleaner API** around the integration libraries are not the only reasons why you'd want to use the abilities.
+ *
+ * Another reason is that the Serenity/JS implementation of the Screenplay Pattern lets you **completely decouple the actor from the integration libraries**
+ * and make the abilities of the same type **interchangeable**.
+ * For example, [Serenity/JS web modules](/handbook/web-testing/serenity-js-web-modules) offer an abstraction that lets you switch between web integration libraries
+ * as vastly different as Selenium, WebdriverIO, or Playwright without having to change _anything whatsoever_ in your test scenarios.
+ *
+ * What this means is that your test code can become [portable and reusable across projects and teams](/handbook/design/portable-test-code),
+ * even if they don't use the same low-level integration tools. It also helps you to **avoid vendor lock-in**, as you can wrap any third-party integration library
+ * into an ability and swap it out for another implementation if you need to.
+ *
+ * However, Serenity/JS **doesn't prevent you** from using the integration libraries directly.
+ * When you need to, you can use a library-specific ability like {@apilink BrowseTheWebWithPlaywright}
+ * to trade portability for access to library-specific low-level methods:
+ *
+ * ```typescript
+ * import { actorCalled } from '@serenity-js/core'
+ * import { BrowseTheWebWithPlaywright, PlaywrightPage } from '@serenity-js/playwright'
+ *
+ * const actor          = actorCalled('Trevor')
+ * const ability        = await BrowseTheWebWithPlaywright.as(actor)
+ * const page           = (await ability.currentPage()) as PlaywrightPage;
+ * const playwrightPage = await page.nativePage();
+ * // use any Playwright-specific APIs on playwrightPage
+ * ```
+ *
+ * :::warning Using integration library-specific APIs reduces portability
+ * While Serenity/JS provides you with escape hatches and ways to access the low-level APIs of your integration libraries,
+ * doing so can reduce the portability of your code. Only do it when you have a good reason to trade portability for low-level access.
+ * :::
+ *
+ *
+ * ## Associating actors with data
+ *
+ * One more reason to use abilities is that abilities can also help you to **associate actors with data** they need to perform their activities.
+ * For example, a commonly used ability is one to [`TakeNotes`](/api/core/class/TakeNotes), which allows your actors to start the test scenario
+ * equipped with some data set, or record information about what they see in the test scenario so that they can act upon it later:
+ *
+ * ```typescript
+ * import { actorCalled, Notepad, TakeNotes } from '@serenity-js/core'
+ *
+ * interface MyNotes {
+ *   firstName: string;
+ *   lastName: string;
+ *   emailAddress: string;
+ * }
+ *
+ * await actorCalled('Trevor')
+ *   .whoCan(
+ *     TakeNotes.using(Notepad.with<MyNotes>({
+ *       firstName: 'Trevor',
+ *       lastName: 'Traveller',
+ *       emailAddress: 'Trevor.Traveller@example.org',
+ *     }))
+ *   )
+ * ```
+ *
+ * ## Actors with multiple abilities
+ *
+ * Of course, an actor can have **any number of abilities** they need to play their role.
+ * For example, it is quite common for an actor to be able to [`BrowseTheWeb`](/api/web/class/BrowseTheWeb), [`TakeNotes`](/api/core/class/TakeNotes), and [`CallAnApi`](/api/rest/class/CallAnApi):
+ *
+ * ```typescript
+ * import { actorCalled, Notepad, TakeNotes } from '@serenity-js/core'
+ * import { BrowseTheWebWithPlaywright } from '@serenity-js/playwright'
+ * import { CallAnApi } from '@serenity-js/rest'
+ * import { chromium } from 'playwright'
+ *
+ * const browser = await chromium.launch({ headless: true })
+ * const baseURL = 'https://example.org'
+ *
+ * interface MyNotes {
+ *   firstName: string;
+ *   lastName: string;
+ *   emailAddress: string;
+ * }
+ *
+ * await actorCalled('Trevor')
+ *   .whoCan(
+ *       BrowseTheWebWithPlaywright.using(browser, { baseURL }),
+ *       CallAnApi.at(`${ baseURL }/api`),
+ *       TakeNotes.using(Notepad.with<MyNotes>({
+ *           firstName: 'Trevor',
+ *           lastName: 'Traveller',
+ *           emailAddress: 'Trevor.Traveller@example.org',
+ *       }))
+ *   )
+ * ```
+ *
+ * ## Writing custom abilities
+ *
+ * If your system under test provides a type of interface that Serenity/JS doesn't support yet,
+ * you might want to implement a custom {@apilink Ability}, as well as {@apilink Interaction|interactions}
+ * and {@apilink Question|questions} to interact with it.
+ *
+ * The best way to start with that is for you to review the examples in the {@apilink Ability|Screenplay Pattern API docs},
+ * as well as the [Serenity/JS code base on GitHub](https://github.com/serenity-js/serenity-js/tree/main/packages).
+ * Also note that all the [Serenity/JS modules](/handbook/about/architecture)
+ * have their automated tests written in such a way to not only provide an **extremely high test coverage** for the framework itself,
+ * but to be **accessible** and act as a **reference implementation for you** to create your own integrations.
+ *
+ * If you believe that the custom integration you've developed could benefit the wider Serenity/JS community,
+ * please consider open-sourcing it yourself, or [contributing it](/contributing) to the main framework.
+ *
+ * [![Join Serenity/JS Community Chat](https://img.shields.io/badge/Chat-Serenity%2FJS%20Community-FBD30B?logo=matrix)](https://matrix.to/#/#serenity-js:gitter.im)
+ *
+ * ### Defining a custom ability to `MakePhoneCalls`
+ *
+ * ```ts
+ * import { Ability, actorCalled, Interaction } from '@serenity-js/core'
+ *
+ * class MakePhoneCalls extends Ability {
+ *
+ *   // A static method is typically used to inject a client of a given interface
+ *   // and instantiate the ability, for example:
+ *   //   actorCalled('Phil').whoCan(MakePhoneCalls.using(phone))
+ *   static using(phone: Phone) {
+ *     return new MakePhoneCalls(phone);
+ *   }
+ *
+ *   // Abilities can hold state, for example: the client of a given interface,
+ *   // additional configuration, or the result of the last interaction with a given interface.
+ *   protected constructor(private readonly phone: Phone) {
+ *   }
+ *
+ *   // Abilities expose methods that enable Interactions to call the system under test,
+ *   // and Questions to retrieve information about its state.
+ *   dial(phoneNumber: string): Promise<void> {
+ *     // ...
+ *   }
+ * }
+ * ```
+ *
+ * ### Defining a custom interaction using the custom ability
+ *
+ * ```ts
+ * // A custom interaction using the actor's ability:
+ * const Call = (phoneNumber: string) =>
+ *   Interaction.where(`#actor calls ${ phoneNumber }`, async actor => {
+ *     await MakePhoneCalls.as(actor).dial(phoneNumber)
+ *   })
+ * ```
+ *
+ * ### Using the custom ability and interaction in a test scenario
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ *
+ * await actorCalled('Connie')
+ *   .whoCan(MakePhoneCalls.using(phone))
+ *   .attemptsTo(
+ *     Call(phoneNumber)
+ *   )
+ * ```
+ *
+ * ## Using auto-initialisable and auto-discardable abilities
+ *
+ * Abilities that rely on resources that need to be initialised before they can be used,
+ * or discarded before the actor is dismissed can implement the {@apilink Initialisable}
+ * or {@apilink Discardable} interfaces, respectively.
+ *
+ * ### Defining a custom ability to `QueryPostgresDB`
+ *
+ * ```ts
+ * import {
+ *   Ability, actorCalled, Discardable, Initialisable, Question, UsesAbilities,
+ * } from '@serenity-js/core'
+ *
+ * // Some low-level interface-specific client we want the Actor to use,
+ * // for example a PostgreSQL database client:
+ * const { Client } = require('pg');
+ *
+ * // A custom Ability to give an Actor access to the low-level client:
+ * class QueryPostgresDB
+ *   extends Ability
+ *   implements Initialisable, Discardable
+ * {
+ *   constructor(private readonly client) {
+ *   }
+ *
+ *   // Invoked by Serenity/JS upon the first invocation of `actor.attemptsTo`
+ *   initialise(): Promise<void> | void {
+ *     return this.client.connect();
+ *   }
+ *
+ *   // Used to ensure that the Ability is not initialised more than once
+ *   isInitialised(): boolean {
+ *     return this.client._connected;
+ *   }
+ *
+ *   // Discards any resources the Ability uses when the Actor is dismissed,
+ *   // so when the Stage receives a SceneFinishes event for scenario-scoped actor,
+ *   // or TestRunFinishes for cross-scenario-scoped actors
+ *   discard(): Promise<void> | void {
+ *     return this.client.end();
+ *   }
+ *
+ *   // Any custom integration APIs the Ability, should make available to the Actor.
+ *   // Here, we want the ability to enable the actor to query the database.
+ *   query(query: string) {
+ *     return this.client.query(query);
+ *   }
+ *
+ *   // ... other custom integration APIs
+ * }
+ * ```
+ *
+ * ### Defining a custom question using the custom ability
+ *
+ * ```ts
+ * // A custom Question to allow the Actor query the database
+ * const CurrentDBUser = () =>
+ *   Question.about('current db user', actor =>
+ *     QueryPostgresDB.as(actor)
+ *       .query('SELECT current_user')
+ *       .then(result => result.rows[0].current_user)
+ *   );
+ * ```
+ *
+ * ### Using the custom ability and question in a test scenario
+ *
+ * ```ts
+ * // Example test scenario where the Actor uses the Ability to QueryPostgresDB
+ * // to assert on the username the connection has been established with
+ *
+ * import { describe, it } from 'mocha'
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Ensure, equals } from '@serenity-js/assertions'
+ *
+ * describe('Serenity/JS', () => {
+ *   it('can initialise and discard abilities automatically', () =>
+ *     actorCalled('Debbie')
+ *       .whoCan(new QueryPostgresDB(new Client()))
+ *       .attemptsTo(
+ *         Ensure.that(CurrentDBUser(), equals('jan'))
+ *       ))
+ * })
+ * ```
+ *
+ * ## Learn more
+ * - {@apilink AbilityType}
+ * - {@apilink Initialisable}
+ * - {@apilink Discardable}
+ * - {@apilink BrowseTheWeb}
+ * - {@apilink CallAnApi}
+ * - {@apilink TakeNotes}
+ *
+ * @group Screenplay Pattern
+ */
+export abstract class Ability {
+
+    /**
+     * Used to access an {@apilink Actor|actor's} {@apilink Ability|ability} of the given type
+     * from within the {@apilink Interaction} and {@apilink Question} classes.
+     *
+     * #### Retrieving an ability in an interaction definition
+     *
+     * ```ts
+     * import { Actor, Interaction } from '@serenity-js/core'
+     * import { BrowseTheWeb, Page } from '@serenity-js/web'
+     *
+     * export const ClearLocalStorage = () =>
+     *   Interaction.where(`#actor clears local storage`, async (actor: Actor) => {
+     *     const browseTheWeb: BrowseTheWeb = BrowseTheWeb.as(actor)    // retrieve an ability
+     *     const page: Page = await browseTheWeb.currentPage()
+     *     await page.executeScript(() => window.localStorage.clear())
+     *   })
+     * ```
+     *
+     * #### Retrieving an ability in a question definition
+     *
+     * ```ts
+     * import { Actor, Question } from '@serenity-js/core'
+     * import { BrowseTheWeb, Page } from '@serenity-js/web'
+     * import { CallAnApi } from '@serenity-js/rest'
+     *
+     * const LocalStorage = {
+     *   numberOfItems: () =>
+     *     Question.about<number>(`number of items in local storage`, async (actor: Actor) => {
+     *       const browseTheWeb: BrowseTheWeb = BrowseTheWeb.as(actor)    // retrieve an ability
+     *       const page: Page = await browseTheWeb.currentPage()
+     *       return page.executeScript(() => window.localStorage.length)
+     *     })
+     * }
+     * ```
+     *
+     * @param actor
+     */
+    static as<A extends Ability>(
+        this: AbilityType<A>,
+        actor: UsesAbilities
+    ): A {
+        return actor.abilityTo(this) as A;
+    }
+}

package/src/screenplay/abilities/AbilityType.ts

@@ -0,0 +1,46 @@
+import { Ability } from './Ability';
+
+/**
+ * An interface describing the static access method that every {@apilink Ability} class
+ * needs to provide in order to be accessible from within the {@apilink Interaction|interactions}.
+ *
+ * #### Retrieving an ability from an interaction
+ *
+ * ```ts
+ * import { Ability, actorCalled, Interaction } from '@serenity-js/core';
+ *
+ * class MakePhoneCalls extends Ability {
+ *   static using(phone: Phone) {
+ *     return new MakePhoneCalls(phone);
+ *   }
+ *
+ *   protected constructor(private readonly phone: Phone) {
+ *   }
+ *
+ *   // some method that allows us to interact with the external interface of the system under test
+ *   dial(phoneNumber: string): Promise<void> {
+ *     // ...
+ *   }
+ * }
+ *
+ * const Call = (phoneNumber: string) =>
+ *   Interaction.where(`#actor calls ${ phoneNumber }`, async actor => {
+ *     await MakePhoneCalls.as(actor).dial(phoneNumber)
+ *   });
+ *
+ * await actorCalled('Connie')
+ *   .whoCan(MakePhoneCalls.using(phone))
+ *   .attemptsTo(
+ *     Call(phoneNumber),
+ *   )
+ * ```
+ *
+ * ## Learn more
+ * - {@apilink Ability}
+ * - {@apilink Actor}
+ * - {@apilink Interaction}
+ *
+ * @group Abilities
+ */
+export type AbilityType<A extends Ability> =
+    (abstract new (... args: any[]) => A);

package/src/screenplay/abilities/CanHaveAbilities.ts

@@ -0,0 +1,20 @@
+import { Ability } from './Ability';
+import { UsesAbilities } from './UsesAbilities';
+
+/**
+ * Describes an {@apilink Actor} who can have an {@apilink Ability} to perform some {@apilink Activity}.
+ *
+ * ## Learn more
+ *
+ * - {@apilink Ability}
+ * - {@apilink Actor}
+ *
+ * @group Actors
+ */
+export interface CanHaveAbilities<Returned_Type = UsesAbilities> {
+
+    /**
+     * Assigns an {@apilink Ability} or several abilities to the {@apilink Actor}
+     */
+    whoCan(...abilities: Ability[]): Returned_Type;
+}

package/src/screenplay/abilities/Discardable.ts

@@ -1,14 +1,26 @@
 /**
- * @desc
- *  An interface to be implemented by any {@link Ability} that needs to free up
- *  the resources it uses.
+ * An interface to be implemented by any {@apilink Ability} that needs to free up
+ * the resources it uses, e.g. disconnect from a database.
  *
- *  This {@link discard} method is invoked directly by the {@link Actor}, and indirectly by {@link Stage}:
- *  - when {@link SceneFinishes}, for actors instantiated after {@link SceneStarts} - i.e. within a test scenario or in a "before each" hook
- *  - when {@link TestRunFinishes}, for actors instantiated before {@link SceneStarts} - i.e. in a "before all" hook
+ * This {@apilink Discardable.discard} method is invoked directly by the {@apilink Actor}, and indirectly by {@apilink Stage}:
+ * - when {@apilink SceneFinishes}, for actors instantiated after {@apilink SceneStarts} - e.g. within a test scenario or in a "before each" hook
+ * - when {@apilink TestRunFinishes}, for actors instantiated before {@apilink SceneStarts} - e.g. in a "before all" hook
  *
- * @public
+ * Note that events such as {@apilink SceneFinishes} and {@apilink TestRunFinishes} are emitted by Serenity/JS test runner adapters,
+ * such as `@serenity-js/cucumber`, `@serenity-js/mocha`, `@serenity-js/jasmine`, and so on.
+ * Consult their respective readmes to learn how to register them with your test runner of choice.
+ *
+ * ## Learn more
+ * - {@apilink Ability}
+ * - {@apilink AbilityType}
+ * - {@apilink Initialisable}
+ *
+ * @group Abilities
  */
 export interface Discardable {
+
+    /**
+     * Discards the resources associated with this ability.
+     */
     discard(): Promise<void> | void;
 }

package/src/screenplay/abilities/Initialisable.ts

@@ -1,31 +1,32 @@
 /**
- * @desc
- *  An interface to be implemented by any {@link Ability} that needs to initialise
- *  the resources it uses (i.e. establish a database connection).
+ * An interface to be implemented by any {@apilink Ability} that needs to initialise
+ * the resources it uses, e.g. establish a database connection.
  *
- *  The {@link initialise} method is invoked when {@link Actor#attemptsTo} is called,
- *  but only when {@link isInitialised} returns false.
+ * The {@apilink Initialisable.initialise} method is invoked whenever {@apilink Actor.attemptsTo} method is called,
+ * but **only when** {@apilink Initialisable.isInitialised} returns false. This is to avoid initialising abilities more than once.
  *
- * @public
+ * ## Learn more
+ * - {@apilink Ability}
+ * - {@apilink AbilityType}
+ * - {@apilink Discardable}
+ *
+ * @group Abilities
  */
 export interface Initialisable {
 
     /**
-     * @desc
-     *  Initialises the ability. Invoked when {@link Actor#attemptsTo} is called,
-     *  but only when {@link isInitialised} returns false.
-     *
-     *  Make sure to implement {@link isInitialised} so that it returns `true`
-     *  when the ability has been successfully initialised.
+     * Initialises the ability. Invoked whenever {@apilink Actor.attemptsTo} method is called,
+     * but **only when** {@apilink Initialisable.isInitialised} returns false.
      *
-     * @returns {Promise<void> | void}
+     * Make sure to implement {@apilink Initialisable.isInitialised} so that it returns `true`
+     * when the ability has been successfully initialised.
      */
     initialise(): Promise<void> | void;
 
     /**
-     * @desc
-     *  Whether or not a given ability has been initialised already
-     *  and should not be initialised again.
+     * Should return `true` when all the resources that the given ability needs
+     * have been initialised. Should return `false` if the {@apilink Actor} should
+     * initialise them again when {@apilink Actor.attemptsTo} is called.
      *
      * @returns {boolean}
      */

package/src/screenplay/abilities/UsesAbilities.ts

@@ -0,0 +1,24 @@
+import { Ability } from './Ability';
+import { AbilityType } from './AbilityType';
+
+/**
+ * Describes an {@apilink Actor} who can use their {@apilink Ability|abilities} to perform an {@apilink Activity}
+ * or answer a {@apilink Question}.
+ *
+ * ## Learn more
+ *
+ * - {@apilink Ability}
+ * - {@apilink Actor}
+ *
+ * @group Actors
+ */
+export interface UsesAbilities {
+
+    /**
+     * Provides access to the {@apilink Actor|actor's} {@apilink Ability} to do something
+     *
+     * @param doSomething
+     *  The type of ability to look up, e.g. {@apilink BrowseTheWeb} or {@apilink CallAnApi}
+     */
+    abilityTo<T extends Ability>(doSomething: AbilityType<T>): T;
+}

package/src/screenplay/abilities/index.ts

@@ -1,3 +1,6 @@
+export * from './Ability';
+export * from './AbilityType';
+export * from './CanHaveAbilities';
 export * from './Discardable';
 export * from './Initialisable';
-export * from './TakeNotes';
+export * from './UsesAbilities';

package/src/screenplay/activities/PerformsActivities.ts

@@ -0,0 +1,21 @@
+import { Activity } from '../Activity';
+
+/**
+ * Describes an {@apilink Actor} who can perform a sequence of {@apilink Activity|Activities},
+ * such as {@apilink Task|tasks} or {@apilink Interaction|interactions}.
+ *
+ * ## Learn more
+ * - {@apilink Activity}
+ * - {@apilink Interaction}
+ * - {@apilink Task}
+ * - {@apilink Actor}
+ *
+ * @group Actors
+ */
+export interface PerformsActivities {
+
+    /**
+     * Makes the {@apilink Actor} attempt to perform a sequence of {@apilink Activity|Activities}.
+     */
+    attemptsTo: (...activities: Activity[]) => Promise<void>;
+}

package/src/screenplay/activities/index.ts

@@ -1 +1 @@
-export * from './TrackedActivity';
+export * from './PerformsActivities';

package/src/screenplay/artifacts/CollectsArtifacts.ts

@@ -0,0 +1,25 @@
+import { Artifact, Name } from '../../model';
+
+/**
+ * Describes an {@apilink Actor} who can collect {@apilink Artifact|Artifacts}, such as {@apilink Photo|Photos} or {@apilink JSONData},
+ * while the scenario is being executed
+ *
+ * ## Learn more
+ * - {@apilink Artifact}
+ * - {@apilink Actor}
+ *
+ * @group Actors
+ */
+export interface CollectsArtifacts {
+
+    /**
+     * Makes the {@apilink Actor} collect an {@apilink Artifact} so that it can be included in the test report.
+     *
+     * @param artifact
+     *  The artifact to be collected, such as {@apilink JSONData}
+     *
+     * @param name
+     *  The name of the artifact to make it easy to recognise in the test report
+     */
+    collect(artifact: Artifact, name?: Name): void;
+}

package/src/screenplay/artifacts/index.ts

@@ -0,0 +1 @@
+export * from './CollectsArtifacts';