@serenity-js/web 3.24.1 → 3.25.1

package/src/screenplay/models/Locator.ts

@@ -7,14 +7,14 @@ import { RootLocator } from './RootLocator';
 import { ByCss, ById, ByTagName, type Selector } from './selectors';
 
 /**
- * {@apilink Locator} uses a {@apilink Selector} to locate a {@apilink PageElement} or {@apilink PageElements}
- * within the {@apilink Page}.
+ * [`Locator`](https://serenity-js.org/api/web/class/Locator/) uses a [`Selector`](https://serenity-js.org/api/web/class/Selector/) to locate a [`PageElement`](https://serenity-js.org/api/web/class/PageElement/) or [`PageElement`](https://serenity-js.org/api/web/class/PageElements/)
+ * within the [`Page`](https://serenity-js.org/api/web/class/Page/).
  *
  * ## Learn more
- * - {@apilink RootLocator}
- * - {@apilink Page.locate}
- * - {@apilink PageElement}
- * - {@apilink PageElements}
+ * - [`RootLocator`](https://serenity-js.org/api/web/class/RootLocator/)
+ * - [`Page.locate`](https://serenity-js.org/api/web/class/Page/#locate)
+ * - [`PageElement`](https://serenity-js.org/api/web/class/PageElement/)
+ * - [`PageElement`](https://serenity-js.org/api/web/class/PageElements/)
  *
  * @group Models
  */
@@ -50,10 +50,10 @@ export abstract class Locator<Native_Element_Type, Native_Selector_Type = any>
     abstract locate(child: Locator<Native_Element_Type>): Locator<Native_Element_Type>;
 
     /**
-     * Expresses {@apilink ByCss}, {@apilink ById}, or {@apilink ByTagName} as a {@apilink ByCss} selector.
+     * Expresses [`ByCss`](https://serenity-js.org/api/web/class/ByCss/), [`ById`](https://serenity-js.org/api/web/class/ById/), or [`ByTagName`](https://serenity-js.org/api/web/class/ByTagName/) as a [`ByCss`](https://serenity-js.org/api/web/class/ByCss/) selector.
      *
      * @throws LogicError
-     *  if the `selector` can't be expressed as {@apilink ByCss}
+     *  if the `selector` can't be expressed as [`ByCss`](https://serenity-js.org/api/web/class/ByCss/)
      *
      * @param selector
      * @protected

package/src/screenplay/models/Page.ts

@@ -123,17 +123,17 @@ import type { SwitchableOrigin } from './SwitchableOrigin';
  *
  * ## Learn more
  *
- * - {@apilink BrowseTheWeb}
- * - {@apilink PageElement}
- * - {@apilink Optional}
- * - {@apilink Switchable}
+ * - [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/)
+ * - [`PageElement`](https://serenity-js.org/api/web/class/PageElement/)
+ * - [`Optional`](https://serenity-js.org/api/core/interface/Optional/)
+ * - [`Switchable`](https://serenity-js.org/api/web/interface/Switchable/)
  *
  * @group Models
  */
 export abstract class Page<Native_Element_Type = any> implements Optional, Switchable {
 
     /**
-     * Creates a {@apilink QuestionAdapter} representing the currently active {@apilink Page}.
+     * Creates a [`QuestionAdapter`](https://serenity-js.org/api/core/#QuestionAdapter) representing the currently active [`Page`](https://serenity-js.org/api/web/class/Page/).
      */
     static current(): QuestionAdapter<Page> {
         return Question.about<Page>('current page', actor => {
@@ -142,8 +142,8 @@ export abstract class Page<Native_Element_Type = any> implements Optional, Switc
     }
 
     /**
-     * Creates a {@apilink QuestionAdapter} that resolves to a {@apilink Page} which {@apilink Page.name}
-     * meets the {@apilink Expectation|`expectation`}.
+     * Creates a [`QuestionAdapter`](https://serenity-js.org/api/core/#QuestionAdapter) that resolves to a [`Page`](https://serenity-js.org/api/web/class/Page/) which [`Page.name`](https://serenity-js.org/api/web/class/Page/#name)
+     * meets the [expectation](https://serenity-js.org/api/core/class/Expectation/).
      *
      * #### Switching to a page with the desired name
      *
@@ -172,8 +172,8 @@ export abstract class Page<Native_Element_Type = any> implements Optional, Switc
     }
 
     /**
-     * Creates a {@apilink QuestionAdapter} that resolves to a {@apilink Page} which {@apilink Page.title}
-     * meets the {@apilink Expectation|`expectation`}.
+     * Creates a [`QuestionAdapter`](https://serenity-js.org/api/core/#QuestionAdapter) that resolves to a [`Page`](https://serenity-js.org/api/web/class/Page/) which [`Page.title`](https://serenity-js.org/api/web/class/Page/#title)
+     * meets the [expectation](https://serenity-js.org/api/core/class/Expectation/).
      *
      * #### Switching to a page with the desired title
      *
@@ -202,8 +202,8 @@ export abstract class Page<Native_Element_Type = any> implements Optional, Switc
     }
 
     /**
-     * Creates a {@apilink QuestionAdapter} that resolves to a {@apilink Page} which {@apilink Page.url}
-     * meets the {@apilink Expectation|`expectation`}.
+     * Creates a [`QuestionAdapter`](https://serenity-js.org/api/core/#QuestionAdapter) that resolves to a [`Page`](https://serenity-js.org/api/web/class/Page/) which [`Page.url`](https://serenity-js.org/api/web/class/Page/#url)
+     * meets the [expectation](https://serenity-js.org/api/core/class/Expectation/).
      *
      * #### Switching to a page with the desired URL
      *
@@ -258,21 +258,21 @@ export abstract class Page<Native_Element_Type = any> implements Optional, Switc
     }
 
     /**
-     * Creates a {@apilink PageElement} wrapping a native element.
+     * Creates a [`PageElement`](https://serenity-js.org/api/web/class/PageElement/) wrapping a native element.
      *
      * @param nativeElement
      */
     abstract createPageElement(nativeElement: Native_Element_Type): PageElement<Native_Element_Type>;
 
     /**
-     * Creates a {@apilink PageElement}, retrieving an element located by {@apilink Selector}.
+     * Creates a [`PageElement`](https://serenity-js.org/api/web/class/PageElement/), retrieving an element located by [`Selector`](https://serenity-js.org/api/web/class/Selector/).
      *
      * @param selector
      */
     abstract locate(selector: Selector): PageElement<Native_Element_Type>;
 
     /**
-     * Creates {@apilink PageElements}, retrieving a collection of elements located by {@apilink Selector}.
+     * Creates [`PageElement`](https://serenity-js.org/api/web/class/PageElements/), retrieving a collection of elements located by [`Selector`](https://serenity-js.org/api/web/class/Selector/).
      *
      * @param selector
      */
@@ -296,7 +296,7 @@ export abstract class Page<Native_Element_Type = any> implements Optional, Switc
 
     /**
      * Causes the browser to traverse one step backward in the joint session history
-     * of the current {@apilink Page} (the current top-level browsing context).
+     * of the current [`Page`](https://serenity-js.org/api/web/class/Page/) (the current top-level browsing context).
      *
      * This is equivalent to pressing the back button in the browser UI,
      * or calling [`window.history.back`](https://developer.mozilla.org/en-US/docs/Web/API/History/back).
@@ -305,7 +305,7 @@ export abstract class Page<Native_Element_Type = any> implements Optional, Switc
 
     /**
      * Causes the browser to traverse one step forward in the joint session history
-     * of the current {@apilink Page} (the current top-level browsing context).
+     * of the current [`Page`](https://serenity-js.org/api/web/class/Page/) (the current top-level browsing context).
      *
      * This is equivalent to pressing the back button in the browser UI,
      * or calling [`window.history.forward`](https://developer.mozilla.org/en-US/docs/Web/API/History/forward).
@@ -313,12 +313,12 @@ export abstract class Page<Native_Element_Type = any> implements Optional, Switc
     abstract navigateForward(): Promise<void>;
 
     /**
-     * Causes the browser to reload the {@apilink Page} in the current top-level browsing context.
+     * Causes the browser to reload the [`Page`](https://serenity-js.org/api/web/class/Page/) in the current top-level browsing context.
      */
     abstract reload(): Promise<void>;
 
     /**
-     * Send a sequence of {@apilink Key} strokes to the active element.
+     * Send a sequence of [`Key`](https://serenity-js.org/api/web/class/Key/) strokes to the active element.
      *
      * @param keys
      *  Keys to enter
@@ -345,7 +345,7 @@ export abstract class Page<Native_Element_Type = any> implements Optional, Switc
      * If the script has a return value (i.e. if the script contains a `return` statement),
      * then the following steps will be taken for resolving this functions return value:
      *
-     * - For a {@apilink PageElement}, the value will resolve to a [HTMLElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement)
+     * - For a [`PageElement`](https://serenity-js.org/api/web/class/PageElement/), the value will resolve to a [HTMLElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement)
      * - `null` and `undefined` return values will resolve to `null`
      * - `boolean`, `number`, and `string` values will resolve as is
      * - Functions will resolve to their string representation
@@ -363,7 +363,7 @@ export abstract class Page<Native_Element_Type = any> implements Optional, Switc
      *
      * #### Learn more
      * - [Selenium WebDriver: JavaScript Executor](https://seleniumhq.github.io/selenium/docs/api/java/org/openqa/selenium/JavascriptExecutor.html#executeAsyncScript-java.lang.String-java.lang.Object...-)
-     * - {@apilink Page.lastScriptExecutionResult}
+     * - [`Page.lastScriptExecutionResult`](https://serenity-js.org/api/web/class/Page/#lastScriptExecutionResult)
      *
      * @param script
      * @param args
@@ -385,7 +385,7 @@ export abstract class Page<Native_Element_Type = any> implements Optional, Switc
      * Arrays and objects may also be used as script arguments as long as each item adheres
      * to the types previously mentioned.
      *
-     * Unlike executing synchronous JavaScript with {@apilink Page.executeScript},
+     * Unlike executing synchronous JavaScript with [`Page.executeScript`](https://serenity-js.org/api/web/class/Page/#executeScript),
      * scripts executed with this function must explicitly signal they are finished by invoking the provided callback.
      *
      * This callback will always be injected into the executed function as the last argument,
@@ -394,7 +394,7 @@ export abstract class Page<Native_Element_Type = any> implements Optional, Switc
      * The following steps will be taken for resolving this functions return value against
      * the first argument to the script's callback function:
      *
-     * - For a {@apilink PageElement}, the value will resolve to a [HTMLElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement)
+     * - For a [`PageElement`](https://serenity-js.org/api/web/class/PageElement/), the value will resolve to a [HTMLElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement)
      * - `null` and `undefined` return values will resolve to `null`
      * - `boolean`, `number`, and `string` values will resolve as is
      * - Functions will resolve to their string representation
@@ -423,7 +423,7 @@ export abstract class Page<Native_Element_Type = any> implements Optional, Switc
      *
      * #### Learn more
      * - [Selenium WebDriver: JavaScript Executor](https://seleniumhq.github.io/selenium/docs/api/java/org/openqa/selenium/JavascriptExecutor.html#executeAsyncScript-java.lang.String-java.lang.Object...-)
-     * - {@apilink Page.lastScriptExecutionResult}
+     * - [`Page.lastScriptExecutionResult`](https://serenity-js.org/api/web/class/Page/#lastScriptExecutionResult)
      *
      * @param script
      * @param args
@@ -434,15 +434,15 @@ export abstract class Page<Native_Element_Type = any> implements Optional, Switc
     ): Promise<Result>;
 
     /**
-     * Returns the last result of calling {@apilink Page.executeAsyncScript}
-     * or {@apilink Page.executeScript}
+     * Returns the last result of calling [`Page.executeAsyncScript`](https://serenity-js.org/api/web/class/Page/#executeAsyncScript)
+     * or [`Page.executeScript`](https://serenity-js.org/api/web/class/Page/#executeScript)
      */
     abstract lastScriptExecutionResult<R = any>(): R;
 
     /**
      * Take a screenshot of the top-level browsing context's viewport.
      *
-     * @throws {@apilink BrowserWindowClosedError}
+     * @throws [`BrowserWindowClosedError`](https://serenity-js.org/api/web/class/BrowserWindowClosedError/)
      *  When the page you're trying to take the screenshot of has already been closed
      *
      * @return
@@ -451,15 +451,15 @@ export abstract class Page<Native_Element_Type = any> implements Optional, Switc
     abstract takeScreenshot(): Promise<string>;
 
     /**
-     * Retrieves a cookie identified by `name` and visible to this {@apilink Page}.
+     * Retrieves a cookie identified by `name` and visible to this [`Page`](https://serenity-js.org/api/web/class/Page/).
      *
      * @param name
      */
     abstract cookie(name: string): Promise<Cookie>;
 
     /**
-     * Adds a single cookie with {@apilink CookieData} to the cookie store associated
-     * with the active {@apilink Page}'s address.
+     * Adds a single cookie with [`CookieData`](https://serenity-js.org/api/web/interface/CookieData/) to the cookie store associated
+     * with the active [`Page`](https://serenity-js.org/api/web/class/Page/)'s address.
      *
      * @param cookieData
      */
@@ -512,8 +512,8 @@ export abstract class Page<Native_Element_Type = any> implements Optional, Switc
      * to the previous context when needed.
      *
      * ## Learn more
-     * - {@apilink Switch}
-     * - {@apilink Switchable}
+     * - [`Switch`](https://serenity-js.org/api/web/class/Switch/)
+     * - [`Switchable`](https://serenity-js.org/api/web/interface/Switchable/)
      */
     async switchTo(): Promise<SwitchableOrigin> {
 
@@ -539,7 +539,7 @@ export abstract class Page<Native_Element_Type = any> implements Optional, Switc
     abstract closeOthers(): Promise<void>;
 
     /**
-     * Returns the {@apilink ModalDialogHandler} for the current {@apilink Page}.
+     * Returns the [`ModalDialogHandler`](https://serenity-js.org/api/web/class/ModalDialogHandler/) for the current [`Page`](https://serenity-js.org/api/web/class/Page/).
      */
     modalDialog(): ModalDialogHandler {
         return this.modalDialogHandler;

package/src/screenplay/models/PageElement.ts

@@ -1,4 +1,4 @@
-import type { Answerable, MetaQuestionAdapter, Optional } from '@serenity-js/core';
+import type { Answerable, MetaQuestion, MetaQuestionAdapter, Optional , QuestionAdapter} from '@serenity-js/core';
 import { Question, the } from '@serenity-js/core';
 import { ensure, isDefined } from 'tiny-types';
 
@@ -10,13 +10,13 @@ import type { Switchable } from './Switchable';
 import type { SwitchableOrigin } from './SwitchableOrigin';
 
 /**
- * Uses the {@apilink Actor|actor's} {@apilink Ability|ability} to {@apilink BrowseTheWeb} to identify
- * a single Web element located by {@apilink Selector}.
+ * Uses the [actor's](https://serenity-js.org/api/core/class/Actor/) [ability](https://serenity-js.org/api/core/class/Ability/) to [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/) to identify
+ * a single Web element located by [`Selector`](https://serenity-js.org/api/web/class/Selector/).
  *
  * ## Learn more
- * - [Page Element Query Language](/handbook/web-testing/page-element-query-language)
- * - {@apilink Optional}
- * - {@apilink Switchable}
+ * - [Page Element Query Language](https://serenity-js.org/handbook/web-testing/page-element-query-language)
+ * - [`Optional`](https://serenity-js.org/api/core/interface/Optional/)
+ * - [`Switchable`](https://serenity-js.org/api/web/interface/Switchable/)
  *
  * @group Models
  */
@@ -51,6 +51,38 @@ export abstract class PageElement<Native_Element_Type = any> implements Optional
         });
     }
 
+    /**
+     * A static method producing a [`MetaQuestion`](https://serenity-js.org/api/core/interface/MetaQuestion/) that can be used with [`PageElements.eachMappedTo`](https://serenity-js.org/api/web/class/PageElements/#eachMappedTo) method
+     * to extract the HTML of each element in a collection.
+     *
+     * #### Example
+     *
+     * ```typescript
+     * import { actorCalled, Log } from '@serenity-js/core'
+     * import { Navigate, PageElement, By, Text } from '@serenity-js/web'
+     * import { includes } from '@serenity-js/assertions'
+     *
+     * await actorCalled('Debbie').attemptsTo(
+     *   Navigate.to('https://serenity-js.org'),
+     *
+     *   Log.the(
+     *     PageElements.located(By.css('a'))
+     *       .where(Text, includes('modular'))
+     *       .eachMappedTo(PageElement.html())
+     *   ),
+     * )
+     * ```
+     */
+    static html<NET>(): MetaQuestion<PageElement<NET>, QuestionAdapter<string>> {
+        return {
+            of: (pageElement: Answerable<PageElement<NET>>) =>
+                Question.about(`outer HTML of ${pageElement}`, async actor => {
+                    const element = await actor.answer(pageElement);
+                    return element.html();
+                })
+        }
+    }
+
     constructor(public readonly locator: Locator<Native_Element_Type>) {
         ensure('native element locator', locator, isDefined());
     }
@@ -66,7 +98,7 @@ export abstract class PageElement<Native_Element_Type = any> implements Optional
 
     /**
      * Traverses the element and its parents, heading toward the document root,
-     * until it finds a parent {@apilink PageElement} that matches its associated CSS selector.
+     * until it finds a parent [`PageElement`](https://serenity-js.org/api/web/class/PageElement/) that matches its associated CSS selector.
      *
      * #### Example
      *
@@ -101,9 +133,9 @@ export abstract class PageElement<Native_Element_Type = any> implements Optional
      * :::info
      * This method relies on [Element: closest() API](https://developer.mozilla.org/en-US/docs/Web/API/Element/closest),
      * and so is only compatible with locating parent elements specified using the following CSS selectors:
-     * - {@apilink ByCss}
-     * - {@apilink ById}
-     * - {@apilink ByTagName}
+     * - [`ByCss`](https://serenity-js.org/api/web/class/ByCss/)
+     * - [`ById`](https://serenity-js.org/api/web/class/ById/)
+     * - [`ByTagName`](https://serenity-js.org/api/web/class/ByTagName/)
      * :::
      *
      * @param childElement
@@ -139,6 +171,27 @@ export abstract class PageElement<Native_Element_Type = any> implements Optional
     abstract text(): Promise<string>;
     abstract value(): Promise<string>;
 
+    /**
+     * An instance method that resolves to the value of the [`outerHTML`](https://developer.mozilla.org/en-US/docs/Web/API/Element/outerHTML) property
+     * of the underlying element.
+     *
+     * #### Example
+     *
+     * ```typescript
+     * import { actorCalled, Log } from '@serenity-js/core'
+     * import { Navigate, PageElement, By } from '@serenity-js/web'
+     *
+     * await actorCalled('Debbie').attemptsTo(
+     *   Navigate.to('https://serenity-js.org'),
+     *
+     *   Log.the(
+     *     PageElement.located(By.css('h1')).html()
+     *   ),
+     * )
+     * ```
+     */
+    abstract html(): Promise<string>;
+
     /**
      * When the element represents an [`iframe`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe),
      * calling this method switches the current browsing context to the given `iframe` context.
@@ -151,8 +204,8 @@ export abstract class PageElement<Native_Element_Type = any> implements Optional
      *  to the previous context if needed.
      *
      * #### Learn more
-     * - {@apilink Switch}
-     * - {@apilink Switchable}
+     * - [`Switch`](https://serenity-js.org/api/web/class/Switch/)
+     * - [`Switchable`](https://serenity-js.org/api/web/interface/Switchable/)
      */
     abstract switchTo(): Promise<SwitchableOrigin>;
 
@@ -179,7 +232,7 @@ export abstract class PageElement<Native_Element_Type = any> implements Optional
     abstract isEnabled(): Promise<boolean>;
 
     /**
-     * Returns a {@apilink Promise} that resolves to `true` when the element
+     * Returns a [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that resolves to `true` when the element
      * is present in the [Document Object Model (DOM)](https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model),
      * `false` otherwise.
      */

package/src/screenplay/models/PageElements.ts

@@ -6,15 +6,15 @@ import { PageElementsLocator } from './PageElementsLocator';
 import type { Selector } from './selectors';
 
 /**
- * Uses the {@apilink Actor|actor's} {@apilink Ability|ability} to {@apilink BrowseTheWeb} to identify
- * a group of Web elements located by {@apilink Selector}.
+ * Uses the [actor's](https://serenity-js.org/api/core/class/Actor/) [ability](https://serenity-js.org/api/core/class/Ability/) to [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/) to identify
+ * a group of Web elements located by [`Selector`](https://serenity-js.org/api/web/class/Selector/).
  *
  * ## Learn more
  *
- * - [Page Element Query Language](/handbook/web-testing/page-element-query-language)
- * - {@apilink MetaList}
- * - {@apilink List}
- * - {@apilink ChainableMetaQuestion}
+ * - [Page Element Query Language](https://serenity-js.org/handbook/web-testing/page-element-query-language)
+ * - [`Actor`](https://serenity-js.org/api/core/class/Actor/)}
+ * - [`List`](https://serenity-js.org/api/core/class/List/)
+ * - [`ChainableMetaQuestion`](https://serenity-js.org/api/core/interface/ChainableMetaQuestion/)
  *
  * @group Models
  */

package/src/screenplay/models/RootLocator.ts

@@ -3,14 +3,14 @@ import { inspectedObject } from '@serenity-js/core/lib/io';
 import * as util from 'util';   // eslint-disable-line unicorn/import-style
 
 /**
- * {@apilink RootLocator} represents the context in which {@apilink Locator} looks for {@apilink PageElement} or {@apilink PageElements}.
+ * [`RootLocator`](https://serenity-js.org/api/web/class/RootLocator/) represents the context in which [`Locator`](https://serenity-js.org/api/web/class/Locator/) looks for [`PageElement`](https://serenity-js.org/api/web/class/PageElement/) or [`PageElement`](https://serenity-js.org/api/web/class/PageElements/).
  * This context is either a parent element, or some representation of the top-level browsing context.
  *
  * ## Learn more
- * - {@apilink Locator}
- * - {@apilink Page.locate}
- * - {@apilink PageElement}
- * - {@apilink PageElements}
+ * - [`Locator`](https://serenity-js.org/api/web/class/Locator/)
+ * - [`Page.locate`](https://serenity-js.org/api/web/class/Page/#locate)
+ * - [`PageElement`](https://serenity-js.org/api/web/class/PageElement/)
+ * - [`PageElement`](https://serenity-js.org/api/web/class/PageElements/)
  *
  * @group Models
  */

package/src/screenplay/models/SelectOption.ts

@@ -6,10 +6,10 @@ import { TinyType } from 'tiny-types';
  *
  * ## Learn more
  *
- * - {@apilink Select}
- * - {@apilink Selected}
- * - {@apilink PageElement.selectOptions}
- * - {@apilink PageElement.selectedOptions}
+ * - [`Select`](https://serenity-js.org/api/web/class/Select/)
+ * - [`Selected`](https://serenity-js.org/api/web/class/Selected/)
+ * - [`PageElement.selectOptions`](https://serenity-js.org/api/web/class/PageElement/#selectOptions)
+ * - [`PageElement.selectedOptions`](https://serenity-js.org/api/web/class/PageElement/#selectedOptions)
  *
  * @group Models
  */

package/src/screenplay/models/Switchable.ts

@@ -2,14 +2,14 @@ import type { SwitchableOrigin } from './SwitchableOrigin';
 
 /**
  * Describes a Serenity/JS model object that can be switched _to_ and switched back _from_
- * using the {@apilink Task|task} to {@apilink Switch}.
+ * using the [task](https://serenity-js.org/api/core/class/Task/) to [`Switch`](https://serenity-js.org/api/web/class/Switch/).
  *
- * Examples of switchable models include a {@apilink Page} and {@apilink PageElement}.
+ * Examples of switchable models include a [`Page`](https://serenity-js.org/api/web/class/Page/) and [`PageElement`](https://serenity-js.org/api/web/class/PageElement/).
  *
  * ## Learn more
- * - {@apilink Page}
- * - {@apilink PageElement}
- * - {@apilink Switch}
+ * - [`Page`](https://serenity-js.org/api/web/class/Page/)
+ * - [`PageElement`](https://serenity-js.org/api/web/class/PageElement/)
+ * - [`Switch`](https://serenity-js.org/api/web/class/Switch/)
  *
  * @group Models
  */
@@ -17,7 +17,7 @@ export interface Switchable {
 
     /**
      * Switches the context to the object implementing this interface
-     * and returns {@apilink SwitchableOrigin} that allows for the context to be switched
+     * and returns [`SwitchableOrigin`](https://serenity-js.org/api/web/interface/SwitchableOrigin/) that allows for the context to be switched
      * back when needed.
      */
     switchTo(): Promise<SwitchableOrigin>;

package/src/screenplay/models/SwitchableOrigin.ts

@@ -1,18 +1,18 @@
 /**
- * Enables the {@apilink Task} to {@apilink Switch} to perform a sequence of activities
+ * Enables the [`Task`](https://serenity-js.org/api/core/class/Task/) to [`Switch`](https://serenity-js.org/api/web/class/Switch/) to perform a sequence of activities
  * and switch back to the original context afterwards.
  *
  * ## Learn more
  *
- * - {@apilink Switch}
- * - {@apilink Switchable}
+ * - [`Switch`](https://serenity-js.org/api/web/class/Switch/)
+ * - [`Switchable`](https://serenity-js.org/api/web/interface/Switchable/)
  *
  * @group Models
  */
 export interface SwitchableOrigin {
 
     /**
-     * Switches the context back to the original {@apilink Switchable}
+     * Switches the context back to the original [`Switchable`](https://serenity-js.org/api/web/interface/Switchable/)
      */
     switchBack(): Promise<void>;
 }

package/src/screenplay/models/dialogs/AbsentModalDialog.ts

@@ -4,10 +4,10 @@ import { ModalDialog } from './ModalDialog';
 
 /**
  * `AbsentModalDialog` is a [null object](https://en.wikipedia.org/wiki/Null_object_pattern)
- * representing a {@apilink ModalDialog} that hasn't appeared yet.
+ * representing a [`ModalDialog`](https://serenity-js.org/api/web/class/ModalDialog/) that hasn't appeared yet.
  *
  * ## Learn more
- * - {@apilink ModalDialog}
+ * - [`ModalDialog`](https://serenity-js.org/api/web/class/ModalDialog/)
  *
  * @group Models
  */

package/src/screenplay/models/dialogs/AcceptedModalDialog.ts

@@ -3,11 +3,11 @@ import { ensure, isDefined } from 'tiny-types';
 import { ModalDialog } from './ModalDialog';
 
 /**
- * `AcceptedModalDialog` represents a {@apilink ModalDialog} that has been accepted
- * via {@apilink ModalDialog.acceptNext}.
+ * `AcceptedModalDialog` represents a [`ModalDialog`](https://serenity-js.org/api/web/class/ModalDialog/) that has been accepted
+ * via [`ModalDialog.acceptNext`](https://serenity-js.org/api/web/class/ModalDialog/#acceptNext).
  *
  * ## Learn more
- * - {@apilink ModalDialog}
+ * - [`ModalDialog`](https://serenity-js.org/api/web/class/ModalDialog/)
  *
  * @group Models
  */

package/src/screenplay/models/dialogs/DismissedModalDialog.ts

@@ -3,11 +3,11 @@ import { ensure, isDefined } from 'tiny-types';
 import { ModalDialog } from './ModalDialog';
 
 /**
- * `DismissedModalDialog` represents a {@apilink ModalDialog} that has been dismissed
- * via {@apilink ModalDialog.dismissNext}.
+ * `DismissedModalDialog` represents a [`ModalDialog`](https://serenity-js.org/api/web/class/ModalDialog/) that has been dismissed
+ * via [`ModalDialog.dismissNext`](https://serenity-js.org/api/web/class/ModalDialog/#dismissNext).
  *
  * ## Learn more
- * - {@apilink ModalDialog}
+ * - [`ModalDialog`](https://serenity-js.org/api/web/class/ModalDialog/)
  *
  * @group Models
  */

package/src/screenplay/models/dialogs/ModalDialog.ts

@@ -14,7 +14,10 @@ import { Page } from '../Page';
  * consistent across the various Web integration tools (such as Playwright, Puppeteer,
  * WebdriverIO or Selenium), Serenity/JS works as follows:
  * - Serenity/JS dismisses any modal dialogs by default and stores their message so that it can be asserted on.
- * - This behaviour can be changed by invoking {@apilink ModalDialog.acceptNext}, {@apilink ModalDialog.acceptNextWithValue]], or [[ModalDialog.dismissNext} before the dialog is triggered, as per the below examples.
+ * - This behaviour can be changed by invoking [`ModalDialog.acceptNext`](https://serenity-js.org/api/web/class/ModalDialog/#acceptNext),
+ *   [`ModalDialog.acceptNextWithValue`](https://serenity-js.org/api/web/class/ModalDialog/#acceptNextWithValue),
+ *   or [`ModalDialog.dismissNext`](https://serenity-js.org/api/web/class/ModalDialog/#dismissNext)
+ *   before the dialog is triggered, as per the below examples.
  * - Serenity/JS also allows you to `Wait.until(ModalDialog, isPresent())` so that you can synchronise your tests
  *   with modal dialogs that appear after a delay.
  *
@@ -93,7 +96,7 @@ import { Page } from '../Page';
  * ```
  *
  * ## Learn more
- * - {@apilink Optional}
+ * - [`Optional`](https://serenity-js.org/api/core/interface/Optional/)
  *
  * @group Models
  */
@@ -126,7 +129,7 @@ export abstract class ModalDialog implements Optional {
     }
 
     /**
-     * Produces an {@apilink Interaction|interaction} that invokes {@apilink ModalDialog.acceptNext}.
+     * Produces an [interaction](https://serenity-js.org/api/core/class/Interaction/) that invokes [`ModalDialog.acceptNext`](https://serenity-js.org/api/web/class/ModalDialog/#acceptNext).
      */
     static acceptNext(): Interaction {
         return Page.current().modalDialog().acceptNext()
@@ -134,7 +137,7 @@ export abstract class ModalDialog implements Optional {
     }
 
     /**
-     * Produces an {@apilink Interaction|interaction} that invokes {@apilink ModalDialog.acceptNextWithValue}.
+     * Produces an [interaction](https://serenity-js.org/api/core/class/Interaction/) that invokes [`ModalDialog.acceptNextWithValue`](https://serenity-js.org/api/web/class/ModalDialog/#acceptNextWithValue).
      *
      * @param value
      */
@@ -144,7 +147,7 @@ export abstract class ModalDialog implements Optional {
     }
 
     /**
-     * Produces an {@apilink Interaction|interaction} that invokes {@apilink ModalDialog.dismissNext}.
+     * Produces an [interaction](https://serenity-js.org/api/core/class/Interaction/) that invokes [`ModalDialog.dismissNext`](https://serenity-js.org/api/web/class/ModalDialog/#dismissNext).
      */
     static dismissNext(): Interaction {
         return Page.current().modalDialog().dismissNext()
@@ -152,7 +155,7 @@ export abstract class ModalDialog implements Optional {
     }
 
     /**
-     * {@apilink QuestionAdapter} that resolves to {@apilink ModalDialog.message} for the current {@apilink Page}.
+     * [`QuestionAdapter`](https://serenity-js.org/api/core/#QuestionAdapter) that resolves to [`ModalDialog.message`](https://serenity-js.org/api/web/class/ModalDialog/#message) for the current [`Page`](https://serenity-js.org/api/web/class/Page/).
      */
     static lastDialogMessage(): QuestionAdapter<string> {
         return Page.current().modalDialog().last().message()
@@ -160,7 +163,7 @@ export abstract class ModalDialog implements Optional {
     }
 
     /**
-     * {@apilink QuestionAdapter} that resolves to {@apilink ModalDialog.state} for the current {@apilink Page}.
+     * [`QuestionAdapter`](https://serenity-js.org/api/core/#QuestionAdapter) that resolves to [`ModalDialog.state`](https://serenity-js.org/api/web/class/ModalDialog/#state) for the current [`Page`](https://serenity-js.org/api/web/class/Page/).
      */
     static lastDialogState(): QuestionAdapter<string> {
         return Page.current().modalDialog().last().state()
@@ -169,12 +172,12 @@ export abstract class ModalDialog implements Optional {
 
     /**
      * Returns the message of the last modal dialog handled,
-     * or rejects the promise with a {@apilink LogicError}
+     * or rejects the promise with a [`LogicError`](https://serenity-js.org/api/core/class/LogicError/)
      * when no modal dialogs have been observed yet.
      *
      * @returns
      *  Message of the last handled dialog, or a `Promise`
-     *  rejected with a {@apilink LogicError}
+     *  rejected with a [`LogicError`](https://serenity-js.org/api/core/class/LogicError/)
      *  when no dialog has been handled yet.
      */
     abstract message(): Promise<string>;