@serenity-js/core 3.25.0 → 3.25.2

package/src/screenplay/Task.ts

@@ -4,8 +4,8 @@ import { Activity } from './Activity';
 import type { Answerable } from './Answerable';
 
 /**
- * **Tasks** model **{@apilink Activity|sequences of activities}**
- * and help you capture meaningful steps of an {@apilink Actor|actor} workflow
+ * **Tasks** model **[sequences of activities](https://serenity-js.org/api/core/class/Activity/)**
+ * and help you capture meaningful steps of an [actor](https://serenity-js.org/api/core/class/Actor/) workflow
  * in your domain.
  *
  * Typically, tasks correspond to higher-level, business domain-specific activities
@@ -13,20 +13,20 @@ import type { Answerable } from './Answerable';
  * However, higher-level tasks can and should be composed of lower-level tasks.
  * For example, a task to `SignUp` could be composed of tasks to `ProvideUsername` and `ProvidePassword`.
  *
- * The lowest-level tasks in your abstraction hierarchy should be composed of {@apilink Interaction|interactions}.
- * For example, a low-level task to `ProvideUsername` could be composed of an interaction to {@apilink Enter} the value
- * into a form field and {@apilink Press} the {@apilink Key.Enter}.
+ * The lowest-level tasks in your abstraction hierarchy should be composed of [interactions](https://serenity-js.org/api/core/class/Interaction/).
+ * For example, a low-level task to `ProvideUsername` could be composed of an interaction to [enter](https://serenity-js.org/api/web/class/Enter/) the value
+ * into a form field and [press](https://serenity-js.org/api/web/class/Press/) the [`Key.Enter`](https://serenity-js.org/api/web/class/Key/#Enter).
  *
- * Tasks 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 Question|Questions}.
+ * Tasks are the core building block of the [Screenplay Pattern](https://serenity-js.org/handbook/design/screenplay-pattern),
+ * along with [actors](https://serenity-js.org/api/core/class/Actor/), [abilities](https://serenity-js.org/api/core/class/Ability/), [interactions](https://serenity-js.org/api/core/class/Interaction/), and [questions](https://serenity-js.org/api/core/class/Question/).
  *
- * ![Screenplay Pattern](/images/design/serenity-js-screenplay-pattern.png)
+ * ![Screenplay Pattern](https://serenity-js.org/images/design/serenity-js-screenplay-pattern.png)
  *
  * Learn more about:
  * - [User-Centred Design: How a 50 year old technique became the key to scalable test automation](https://janmolak.com/user-centred-design-how-a-50-year-old-technique-became-the-key-to-scalable-test-automation-66a658a36555)
- * - {@apilink Actor|Actors}
- * - {@apilink Activity|Activities}
- * - {@apilink Interaction|Interactions}
+ * - [Actors](https://serenity-js.org/api/core/class/Actor/)
+ * - [Activities](https://serenity-js.org/api/core/class/Activity/)
+ * - [Interactions](https://serenity-js.org/api/core/class/Interaction/)
  *
  * ## Defining a task
  *
@@ -44,7 +44,7 @@ import type { Answerable } from './Answerable';
  *
  * ## Defining a not implemented task
  *
- * Note that calling {@apilink Task.where} method without providing the sequence of {@apilink Activity|activities}
+ * Note that calling [`Task.where`](https://serenity-js.org/api/core/class/Task/#where) method without providing the sequence of [activities](https://serenity-js.org/api/core/class/Activity/)
  * produces a Task that's marked as "pending" in the test report.
  *
  * This feature is useful when you want to quickly write down a task that will be needed in the scenario,
@@ -72,7 +72,7 @@ import type { Answerable } from './Answerable';
  * - specify origin city of "London"
  * - specify destination city of "New York"
  *
- * The easiest way to implement such task, and any custom Serenity/JS task for this matter, is to use the {@apilink Task.where} method to compose the lower-level activities:
+ * The easiest way to implement such task, and any custom Serenity/JS task for this matter, is to use the [`Task.where`](https://serenity-js.org/api/core/class/Task/#where) method to compose the lower-level activities:
  *
  * ```typescript
  * import { Task, the } from '@serenity-js/core'
@@ -94,9 +94,9 @@ import type { Answerable } from './Answerable';
  * - enter city name of `New York`
  * - pick the first suggested airport from the list
  *
- * Conveniently, [Serenity/JS modules](/handbook/about/architecture) provide low-level activities that
+ * Conveniently, [Serenity/JS modules](https://serenity-js.org/handbook/getting-started/architecture) provide low-level activities that
  * allow actors to interact with the various interfaces of the system under test.
- * For example, [Serenity/JS Web module](/api/web) ships with activities such as {@apilink Click} or {@apilink Enter},
+ * For example, [Serenity/JS Web module](https://serenity-js.org/api/web) ships with activities such as [`Click`](https://serenity-js.org/api/web/class/Click/) or [`Enter`](https://serenity-js.org/api/web/class/Enter/),
  * which we can incorporate into our task definitions just like any other activities:
  *
  * ```typescript
@@ -190,14 +190,14 @@ export abstract class Task extends Activity {
     }
 
     /**
-     * Instructs the provided {@apilink Actor} to perform this {@apilink Task}.
+     * Instructs the provided [`Actor`](https://serenity-js.org/api/core/class/Actor/) to perform this [`Task`](https://serenity-js.org/api/core/class/Task/).
      *
      * @param {PerformsActivities} actor
      *
      * #### Learn more
-     * - {@apilink Actor}
-     * - {@apilink PerformsActivities}
-     * - {@apilink Activity}
+     * - [`Actor`](https://serenity-js.org/api/core/class/Actor/)
+     * - [`PerformsActivities`](https://serenity-js.org/api/core/interface/PerformsActivities/)
+     * - [`Activity`](https://serenity-js.org/api/core/class/Activity/)
      */
     abstract performAs(actor: PerformsActivities): Promise<void>;
 }

package/src/screenplay/WithAnswerableProperties.ts

@@ -2,8 +2,8 @@ import type { Answerable } from './Answerable';
 import type { Question } from './Question';
 
 /**
- * Describes a plain JavaScript object with {@apilink Answerable} properties.
- * Typically, used in conjunction with {@apilink RecursivelyAnswered} and {@apilink Question.fromObject}.
+ * Describes a plain JavaScript object with [`Answerable`](https://serenity-js.org/api/core/#Answerable) properties.
+ * Typically, used in conjunction with [`RecursivelyAnswered`](https://serenity-js.org/api/core/#RecursivelyAnswered) and [`Question.fromObject`](https://serenity-js.org/api/core/class/Question/#fromObject).
  *
  * ```ts
  * import {

package/src/screenplay/abilities/Ability.ts

@@ -2,37 +2,38 @@ import type { AbilityType } from './AbilityType';
 import type { 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.
+ * **Abilities** enable [actors](https://serenity-js.org/api/core/class/Actor/)
+ * to perform [interactions](https://serenity-js.org/api/core/class/Interaction/) with the system under test
+ * and answer [questions](https://serenity-js.org/api/core/class/Question/) 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 an {@apilink CallAnApi|HTTP client}.
- * They also enable [portability](/handbook/design/portable-test-code)
+ * such as [web browser drivers](https://serenity-js.org/api/web/class/BrowseTheWeb/) or an [HTTP client](https://serenity-js.org/api/rest/class/CallAnApi/).
+ * They also enable [portability](https://serenity-js.org/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}.
+ * Abilities are the core building block of the [Screenplay Pattern](https://serenity-js.org/handbook/design/screenplay-pattern),
+ * along with [actors](https://serenity-js.org/api/core/class/Actor/), [interactions](https://serenity-js.org/api/core/class/Interaction/),
+ * [questions](https://serenity-js.org/api/core/class/Question/), and [tasks](https://serenity-js.org/api/core/class/Task/).
  *
- * ![Screenplay Pattern](/images/design/serenity-js-screenplay-pattern.png)
+ * ![Screenplay Pattern](https://serenity-js.org/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/)
+ * - [Actors](https://serenity-js.org/api/core/class/Actor/)
+ * - [Configuring actors using Casts](https://serenity-js.org/api/core/class/Cast/)
+ * - [Interactions](https://serenity-js.org/api/core/class/Interaction/)
+ * - [Questions](https://serenity-js.org/api/core/class/Question/)
+ * - [Web testing](https://serenity-js.org/handbook/web-testing/)
+ * - [API testing](https://serenity-js.org/handbook/api-testing/)
+ * - [Mobile testing](https://serenity-js.org/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.
+ * be it a [web UI](https://serenity-js.org/handbook/web-testing/), a [mobile app](https://serenity-js.org/handbook/mobile-testing/), a [web service](https://serenity-js.org/handbook/api-testing/),
+ * or [anything else](https://serenity-js.org/api/core/class/Ability/) 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.
+ * and achieved without introducing any unnecessary dependencies to your code base thanks to the [modular architecture](https://serenity-js.org/handbook/getting-started/architecture) of Serenity/JS.
  *
  * :::tip Remember
  * **Actors** have **abilities** that enable them to **perform interactions** and **answer questions**.
@@ -41,18 +42,18 @@ import type { UsesAbilities } from './UsesAbilities';
  * 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,
+ * Abilities **encapsulate integration libraries** and handle their [configuration and initialisation](https://serenity-js.org/api/core/interface/Initialisable/),
+ * the process of [freeing up any resources](https://serenity-js.org/api/core/interface/Discardable/) 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),
+ * you call the [`Actor.whoCan`](https://serenity-js.org/api/core/class/Actor#whoCan) method and give them an implementation of the ability to [`BrowseTheWeb`](https://serenity-js.org/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}.
+ * Note how [`BrowseTheWebWithPlaywright`](https://serenity-js.org/api/playwright/class/BrowseTheWebWithPlaywright/), [`BrowseTheWebWithWebdriverIO`](https://serenity-js.org/api/webdriverio/class/BrowseTheWebWithWebdriverIO/), and [`BrowseTheWebWithProtractor`](https://serenity-js.org/api/protractor/class/BrowseTheWebWithProtractor/)
+ * all **extend** the base ability to [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/).
  *
  * #### Playwright
  *
@@ -90,10 +91,10 @@ import type { UsesAbilities } from './UsesAbilities';
  *
  * ### Retrieving an ability
  *
- * Use {@apilink Ability.as} to retrieve an ability in a custom {@apilink Interaction} or {@apilink Question} implementation.
+ * Use [`PerformActivities`](https://serenity-js.org/api/core/class/PerformActivities/)} to retrieve an ability in a custom [`Interaction`](https://serenity-js.org/api/core/class/Interaction/) or [`Question`](https://serenity-js.org/api/core/class/Question/) implementation.
  *
- * Here, `Ability` can be the integration library-specific class, for example {@apilink BrowseTheWebWithPlaywright},
- * or its library-agnostic parent class, like {@apilink BrowseTheWeb}.
+ * Here, `Ability` can be the integration library-specific class, for example [`BrowseTheWebWithPlaywright`](https://serenity-js.org/api/playwright/class/BrowseTheWebWithPlaywright/),
+ * or its library-agnostic parent class, like [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/).
  *
  * To make your code portable across the various integration libraries, retrieve the ability
  * using the library-agnostic parent class:
@@ -110,15 +111,15 @@ import type { UsesAbilities } from './UsesAbilities';
  *
  * 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
+ * For example, [Serenity/JS web modules](https://serenity-js.org/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),
+ * What this means is that your test code can become [portable and reusable across projects and teams](https://serenity-js.org/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}
+ * When you need to, you can use a library-specific ability like [`BrowseTheWebWithPlaywright`](https://serenity-js.org/api/playwright/class/BrowseTheWebWithPlaywright/)
  * to trade portability for access to library-specific low-level methods:
  *
  * ```typescript
@@ -141,7 +142,7 @@ import type { UsesAbilities } from './UsesAbilities';
  * ## 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
+ * For example, a commonly used ability is one to [`TakeNotes`](https://serenity-js.org/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
@@ -166,7 +167,7 @@ import type { UsesAbilities } from './UsesAbilities';
  * ## 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):
+ * For example, it is quite common for an actor to be able to [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb), [`TakeNotes`](https://serenity-js.org/api/core/class/TakeNotes), and [`CallAnApi`](https://serenity-js.org/api/rest/class/CallAnApi):
  *
  * ```typescript
  * import { actorCalled, Notepad, TakeNotes } from '@serenity-js/core'
@@ -198,17 +199,17 @@ import type { UsesAbilities } from './UsesAbilities';
  * ## 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.
+ * you might want to implement a custom [`Ability`](https://serenity-js.org/api/core/class/Ability/), as well as [interactions](https://serenity-js.org/api/core/class/Interaction/)
+ * and [questions](https://serenity-js.org/api/core/class/Question/) 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},
+ * The best way to start with that is for you to review the examples in the [Screenplay Pattern API docs](https://serenity-js.org/api/core/class/Ability/),
  * 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)
+ * Also note that all the [Serenity/JS modules](https://serenity-js.org/handbook/getting-started/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.
+ * please consider open-sourcing it yourself, or [contributing it](https://serenity-js.org/community/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)
  *
@@ -266,8 +267,9 @@ import type { UsesAbilities } from './UsesAbilities';
  * ## 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.
+ * or discarded before the actor is dismissed can implement
+ * the [`Initialisable`](https://serenity-js.org/api/core/interface/Initialisable/)
+ * or [`Discardable`](https://serenity-js.org/api/core/interface/Discardable/) interfaces, respectively.
  *
  * ### Defining a custom ability to `QueryPostgresDB`
  *
@@ -348,20 +350,20 @@ import type { UsesAbilities } from './UsesAbilities';
  * ```
  *
  * ## Learn more
- * - {@apilink AbilityType}
- * - {@apilink Initialisable}
- * - {@apilink Discardable}
- * - {@apilink BrowseTheWeb}
- * - {@apilink CallAnApi}
- * - {@apilink TakeNotes}
+ * - [`AbilityType`](https://serenity-js.org/api/core/#AbilityType)
+ * - [`Initialisable`](https://serenity-js.org/api/core/interface/Initialisable/)
+ * - [`Discardable`](https://serenity-js.org/api/core/interface/Discardable/)
+ * - [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/)
+ * - [`CallAnApi`](https://serenity-js.org/api/rest/class/CallAnApi/)
+ * - [`TakeNotes`](https://serenity-js.org/api/core/class/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.
+     * Used to access an [actor's](https://serenity-js.org/api/core/class/Actor/) [ability](https://serenity-js.org/api/core/class/Ability/) of the given type
+     * from within the [`Interaction`](https://serenity-js.org/api/core/class/Interaction/) and [`Question`](https://serenity-js.org/api/core/class/Question/) classes.
      *
      * #### Retrieving an ability in an interaction definition
      *

package/src/screenplay/abilities/AbilityType.ts

@@ -1,8 +1,8 @@
 import type { 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}.
+ * An interface describing the static access method that every [`Ability`](https://serenity-js.org/api/core/class/Ability/) class
+ * needs to provide in order to be accessible from within the [interactions](https://serenity-js.org/api/core/class/Interaction/).
  *
  * #### Retrieving an ability from an interaction
  *
@@ -36,9 +36,9 @@ import type { Ability } from './Ability';
  * ```
  *
  * ## Learn more
- * - {@apilink Ability}
- * - {@apilink Actor}
- * - {@apilink Interaction}
+ * - [`Ability`](https://serenity-js.org/api/core/class/Ability/)
+ * - [`Actor`](https://serenity-js.org/api/core/class/Actor/)
+ * - [`Interaction`](https://serenity-js.org/api/core/class/Interaction/)
  *
  * @group Abilities
  */

package/src/screenplay/abilities/AnswerQuestions.ts

@@ -6,11 +6,11 @@ import { Ability } from './Ability';
 import type { UsesAbilities } from './UsesAbilities';
 
 /**
- * This {@apilink Ability} enables an {@apilink Actor} to resolve the value of a given {@apilink Answerable}.
+ * This [`Ability`](https://serenity-js.org/api/core/class/Ability/) enables an [`Actor`](https://serenity-js.org/api/core/class/Actor/) to resolve the value of a given [`Answerable`](https://serenity-js.org/api/core/#Answerable).
  *
- * {@apilink AnswerQuestions} is used internally by {@apilink Actor.answer}, and it is unlikely you'll ever need to use it directly in your code.
+ * `AnswerQuestions` is used internally by [`Actor.answer`](https://serenity-js.org/api/core/class/Actor/#answer), and it is unlikely you'll ever need to use it directly in your code.
  * That is, unless you're building a custom Serenity/JS extension and want to override the default behaviour of the framework,
- * in which case you should check out the [Contributor's Guide](/contributing).
+ * in which case you should check out the [Contributor's Guide](https://serenity-js.org/community/contributing/).
  *
  * @group Abilities
  */

package/src/screenplay/abilities/CanHaveAbilities.ts

@@ -2,19 +2,19 @@ import type { Ability } from './Ability';
 import type { UsesAbilities } from './UsesAbilities';
 
 /**
- * Describes an {@apilink Actor} who can have an {@apilink Ability} to perform some {@apilink Activity}.
+ * Describes an [`Actor`](https://serenity-js.org/api/core/class/Actor/) who can have an [`Ability`](https://serenity-js.org/api/core/class/Ability/) to perform some [`Activity`](https://serenity-js.org/api/core/class/Activity/).
  *
  * ## Learn more
  *
- * - {@apilink Ability}
- * - {@apilink Actor}
+ * - [`Ability`](https://serenity-js.org/api/core/class/Ability/)
+ * - [`Actor`](https://serenity-js.org/api/core/class/Actor/)
  *
  * @group Actors
  */
 export interface CanHaveAbilities<Returned_Type = UsesAbilities> {
 
     /**
-     * Assigns an {@apilink Ability} or several abilities to the {@apilink Actor}
+     * Assigns an [`Ability`](https://serenity-js.org/api/core/class/Ability/) or several abilities to the [`Actor`](https://serenity-js.org/api/core/class/Actor/)
      */
     whoCan(...abilities: Ability[]): Returned_Type;
 }

package/src/screenplay/abilities/Discardable.ts

@@ -1,19 +1,19 @@
 /**
- * An interface to be implemented by any {@apilink Ability} that needs to free up
+ * An interface to be implemented by any [`Ability`](https://serenity-js.org/api/core/class/Ability/) that needs to free up
  * the resources it uses, e.g. disconnect from a database.
  *
- * 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
+ * This [`Discardable.discard`](https://serenity-js.org/api/core/interface/Discardable/#discard) method is invoked directly by the [actor](https://serenity-js.org/api/core/class/Actor/), and indirectly by the [stage](https://serenity-js.org/api/core/class/Stage/):
+ * - when [SceneFinishes](https://serenity-js.org/api/core-events/class/SceneFinishes/), for actors instantiated after [SceneStarts](https://serenity-js.org/api/core-events/class/SceneStarts/) - e.g. within a test scenario or in a "before each" hook
+ * - when [`TestRunFinishes`](https://serenity-js.org/api/core-events/class/TestRunFinishes/), for actors instantiated before [SceneStarts](https://serenity-js.org/api/core-events/class/SceneStarts/) - e.g. in a "before all" hook
  *
- * Note that events such as {@apilink SceneFinishes} and {@apilink TestRunFinishes} are emitted by Serenity/JS test runner adapters,
+ * Note that events such as [SceneFinishes](https://serenity-js.org/api/core-events/class/SceneFinishes/) and [`TestRunFinishes`](https://serenity-js.org/api/core-events/class/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}
+ * - [`Ability`](https://serenity-js.org/api/core/class/Ability/)
+ * - [`AbilityType`](https://serenity-js.org/api/core/#AbilityType)
+ * - [`Initialisable`](https://serenity-js.org/api/core/interface/Initialisable/)
  *
  * @group Abilities
  */

package/src/screenplay/abilities/Initialisable.ts

@@ -1,32 +1,32 @@
 /**
- * An interface to be implemented by any {@apilink Ability} that needs to initialise
+ * An interface to be implemented by any [`Ability`](https://serenity-js.org/api/core/class/Ability/) that needs to initialise
  * the resources it uses, e.g. establish a database connection.
  *
- * 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.
+ * The [`Initialisable.initialise`](https://serenity-js.org/api/core/interface/Initialisable/#initialise) method is invoked whenever [`Actor.attemptsTo`](https://serenity-js.org/api/core/class/Actor/#attemptsTo) method is called,
+ * but **only when** [`Initialisable.isInitialised`](https://serenity-js.org/api/core/interface/Initialisable/#isInitialised) returns false. This is to avoid initialising abilities more than once.
  *
  * ## Learn more
- * - {@apilink Ability}
- * - {@apilink AbilityType}
- * - {@apilink Discardable}
+ * - [`Ability`](https://serenity-js.org/api/core/class/Ability/)
+ * - [`AbilityType`](https://serenity-js.org/api/core/#AbilityType)
+ * - [`Discardable`](https://serenity-js.org/api/core/interface/Discardable/)
  *
  * @group Abilities
  */
 export interface Initialisable {
 
     /**
-     * Initialises the ability. Invoked whenever {@apilink Actor.attemptsTo} method is called,
-     * but **only when** {@apilink Initialisable.isInitialised} returns false.
+     * Initialises the ability. Invoked whenever [`Actor.attemptsTo`](https://serenity-js.org/api/core/class/Actor/#attemptsTo) method is called,
+     * but **only when** [`Initialisable.isInitialised`](https://serenity-js.org/api/core/interface/Initialisable/#isInitialised) returns false.
      *
-     * Make sure to implement {@apilink Initialisable.isInitialised} so that it returns `true`
+     * Make sure to implement [`Initialisable.isInitialised`](https://serenity-js.org/api/core/interface/Initialisable/#isInitialised) so that it returns `true`
      * when the ability has been successfully initialised.
      */
     initialise(): Promise<void> | void;
 
     /**
      * 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.
+     * have been initialised. Should return `false` if the [`Actor`](https://serenity-js.org/api/core/class/Actor/) should
+     * initialise them again when [`Actor.attemptsTo`](https://serenity-js.org/api/core/class/Actor/#attemptsTo) is called.
      *
      * @returns {boolean}
      */

package/src/screenplay/abilities/PerformActivities.ts

@@ -22,11 +22,11 @@ import { Ability } from './Ability';
 import type { UsesAbilities } from './UsesAbilities';
 
 /**
- * An {@apilink Ability} that enables an {@apilink Actor} to perform a given {@apilink Activity}.
+ * An [`Ability`](https://serenity-js.org/api/core/class/Ability/) that enables an [`Actor`](https://serenity-js.org/api/core/class/Actor/) to perform a given [`Activity`](https://serenity-js.org/api/core/class/Activity/).
  *
- * {@apilink PerformActivities} is used internally by {@apilink Actor.perform}, and it is unlikely you'll ever need to use it directly in your code.
+ * [`PerformActivities`](https://serenity-js.org/api/core/class/PerformActivities/) is used internally by [`Actor.attemptsTo`](https://serenity-js.org/api/core/class/Actor/#attemptsTo), and it is unlikely you'll ever need to use it directly in your code.
  * That is, unless you're building a custom Serenity/JS extension and want to override the default behaviour of the framework,
- * in which case you should check out the [Contributor's Guide](/contributing).
+ * in which case you should check out the [Contributor's Guide](https://serenity-js.org/community/contributing).
  *
  * @group Abilities
  */

package/src/screenplay/abilities/UsesAbilities.ts

@@ -2,23 +2,23 @@ import type { Ability } from './Ability';
 import type { AbilityType } from './AbilityType';
 
 /**
- * Describes an {@apilink Actor} who can use their {@apilink Ability|abilities} to perform an {@apilink Activity}
- * or answer a {@apilink Question}.
+ * Describes an [`Actor`](https://serenity-js.org/api/core/class/Actor/) who can use their [abilities](https://serenity-js.org/api/core/class/Ability/) to perform an [`Activity`](https://serenity-js.org/api/core/class/Activity/)
+ * or answer a [`Question`](https://serenity-js.org/api/core/class/Question/).
  *
  * ## Learn more
  *
- * - {@apilink Ability}
- * - {@apilink Actor}
+ * - [`Ability`](https://serenity-js.org/api/core/class/Ability/)
+ * - [`Actor`](https://serenity-js.org/api/core/class/Actor/)
  *
  * @group Actors
  */
 export interface UsesAbilities {
 
     /**
-     * Provides access to the {@apilink Actor|actor's} {@apilink Ability} to do something
+     * Provides access to the [actor's](https://serenity-js.org/api/core/class/Actor/) [`Ability`](https://serenity-js.org/api/core/class/Ability/) to do something
      *
      * @param doSomething
-     *  The type of ability to look up, e.g. {@apilink BrowseTheWeb} or {@apilink CallAnApi}
+     *  The type of ability to look up, e.g. [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/) or [`CallAnApi`](https://serenity-js.org/api/rest/class/CallAnApi/)
      */
     abilityTo<T extends Ability>(doSomething: AbilityType<T>): T;
 }

package/src/screenplay/activities/PerformsActivities.ts

@@ -1,21 +1,21 @@
 import type { 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}.
+ * Describes an [`Actor`](https://serenity-js.org/api/core/class/Actor/) who can perform a sequence of [activities](https://serenity-js.org/api/core/class/Activity/),
+ * such as [tasks](https://serenity-js.org/api/core/class/Task/) or [interactions](https://serenity-js.org/api/core/class/Interaction/).
  *
  * ## Learn more
- * - {@apilink Activity}
- * - {@apilink Interaction}
- * - {@apilink Task}
- * - {@apilink Actor}
+ * - [`Activity`](https://serenity-js.org/api/core/class/Activity/)
+ * - [`Interaction`](https://serenity-js.org/api/core/class/Interaction/)
+ * - [`Task`](https://serenity-js.org/api/core/class/Task/)
+ * - [`Actor`](https://serenity-js.org/api/core/class/Actor/)
  *
  * @group Actors
  */
 export interface PerformsActivities {
 
     /**
-     * Makes the {@apilink Actor} attempt to perform a sequence of {@apilink Activity|Activities}.
+     * Makes the [`Actor`](https://serenity-js.org/api/core/class/Actor/) attempt to perform a sequence of [activities](https://serenity-js.org/api/core/class/Activity/).
      */
     attemptsTo: (...activities: Activity[]) => Promise<void>;
 }

package/src/screenplay/artifacts/CollectsArtifacts.ts

@@ -1,19 +1,18 @@
 import type { Artifact, Name } from '../../model';
 
 /**
- * Describes an {@apilink Actor} who can collect {@apilink Artifact|Artifacts}, such as {@apilink Photo|Photos} or {@apilink JSONData},
+ * Describes an [`Actor`](https://serenity-js.org/api/core/class/Actor/) who can collect artifacts, such as photos or `JSON` data.,
  * while the scenario is being executed
  *
  * ## Learn more
- * - {@apilink Artifact}
- * - {@apilink Actor}
+ * - [`Actor`](https://serenity-js.org/api/core/class/Actor/)
  *
  * @group Actors
  */
 export interface CollectsArtifacts {
 
     /**
-     * Makes the {@apilink Actor} collect an {@apilink Artifact} so that it can be included in the test report.
+     * Makes the [`Actor`](https://serenity-js.org/api/core/class/Actor/) collect an artifact so that it can be included in the test report.
      *
      * #### Implementing a custom interaction to attach artifacts
      *
@@ -70,7 +69,7 @@ export interface CollectsArtifacts {
      * ```
      *
      * @param artifact
-     *  The artifact to be collected, such as {@apilink JSONData}
+     *  The artifact to be collected, such as `JSON` data.
      *
      * @param name
      *  The name of the artifact to make it easy to recognise in the test report

package/src/screenplay/debugging/Debug.ts

@@ -11,7 +11,7 @@ import type { AnswersQuestions } from '../questions';
 import type { DebuggingResult } from './DebuggingResult';
 
 /**
- * Instructs the {@apilink Actor|actor} to evaluate and {@apilink Log|log} the provided {@apilink Answerable|answerable} values.
+ * Instructs the [actor](https://serenity-js.org/api/core/class/Actor/) to evaluate and [log](https://serenity-js.org/api/core/class/Log/) the provided [answerable](https://serenity-js.org/api/core/#Answerable) values.
  *
  * Since this interaction **accepts a callback function** that receives the evaluated results,
  * the best way to use it is while **running the test scenario via a Node.js debugger**.
@@ -19,8 +19,8 @@ import type { DebuggingResult } from './DebuggingResult';
  *
  * ## Debugging Answerable values
  *
- * {@apilink Debug.values} accepts a callback function that receives an array of {@apilink DebuggingResult} objects,
- * as well as the result of evaluating each provided {@apilink Answerable|answerable} with {@apilink Actor.answer}.
+ * [`Debug.values`](https://serenity-js.org/api/core/class/Debug/#values) accepts a callback function that receives an array of [`DebuggingResult`](https://serenity-js.org/api/core/interface/DebuggingResult/) objects,
+ * as well as the result of evaluating each provided [answerable](https://serenity-js.org/api/core/#Answerable) with [`Actor.answer`](https://serenity-js.org/api/core/class/Actor/#answer).
  *
  * ```typescript
  * import { actorCalled, Debug } from '@serenity-js/core'
@@ -43,8 +43,9 @@ import type { DebuggingResult } from './DebuggingResult';
  * provides features that allow for [experimenting with web UI locators](https://marketplace.visualstudio.com/items?itemName=ms-playwright.playwright#tune-locators)
  * while the test is paused at breakpoint.
  *
- * Since this functionality is specific to [Playwright](/api/playwright), you can use it by passing {@apilink PlaywrightPage.current|`PlaywrightPage.current().nativePage()`}
- * to Serenity/JS {@apilink Debug.values}. Also make sure to name the evaluated value `page`, as this is the variable name that the Playwright VSCode extension expects.
+ * Since this functionality is specific to [Playwright](https://serenity-js.org/api/playwright),
+ * you can use it by passing [`PlaywrightPage.current().nativePage()`](https://serenity-js.org/api/playwright/class/PlaywrightPage/#current)
+ * to Serenity/JS [`Debug.values`](https://serenity-js.org/api/core/class/Debug/#values). Also make sure to name the evaluated value `page`, as this is the variable name that the Playwright VSCode extension expects.
  *
  * ```typescript
  * import { actorCalled, Debug } from '@serenity-js/core'
@@ -74,7 +75,7 @@ import type { DebuggingResult } from './DebuggingResult';
 export class Debug<Values extends Array<Answerable<unknown>>> extends Interaction {
 
     /**
-     * Instructs the {@apilink Actor|actor} to evaluate the provided `values`,
+     * Instructs the [actor](https://serenity-js.org/api/core/class/Actor/) to evaluate the provided `values`,
      * log the results, and then pass them to your `debuggerFunction`.
      *
      * To use this interaction, run your test scenario in the Node.js debugger

package/src/screenplay/debugging/DebuggingResult.ts

@@ -1,5 +1,5 @@
 /**
- * An interface describing debugging data received by the callback function passed to {@apilink Debug.values}.
+ * An interface describing debugging data received by the callback function passed to [`Debug.values`](https://serenity-js.org/api/core/class/Debug/#values).
  *
  * @group Activities
  */