@serenity-js/web 3.0.0-rc.8 → 3.0.0

package/lib/screenplay/abilities/BrowseTheWeb.d.ts

@@ -1,53 +1,96 @@
-import { Ability, Duration, UsesAbilities } from '@serenity-js/core';
-import { Key } from '../../input';
-import { Cookie, CookieData, Locator, ModalDialog, Page, PageElement, Selector } from '../models';
-import { BrowserCapabilities } from './BrowserCapabilities';
-export declare abstract class BrowseTheWeb<Native_Element_Type = any, Native_Root_Element_Type = unknown> implements Ability {
-    protected locators: Map<new (...args: unknown[]) => Selector, (selector: Selector) => Locator<Native_Element_Type, Native_Root_Element_Type>>;
+import { Ability } from '@serenity-js/core';
+import { BrowserCapabilities, BrowsingSession, Page } from '../models';
+/**
+ * The {@apilink Ability|ability} to `BrowseTheWeb` enables an {@apilink Actor|actor}
+ * to {@apilink Interaction|interact with} and {@apilink Question|retrieve information from} Web-based user interfaces.
+ *
+ * `BrowseTheWeb` wraps test integration tools such as [Playwright](/api/playwright),
+ * [Protractor](/api/protractor), or [WebdriverIO](/api/webdriverio),
+ * and together with Serenity/JS Web models, such as {@apilink Page} or {@apilink PageElement} - offers a standardised way
+ * to write Web-based tests following the Screenplay Pattern.
+ *
+ * The consistent and portable design of abstractions provided by the [`@serenity-js/web` module](/api/web)
+ * also helps to make your tests portable across the various test integration tools and helps to make your test
+ * code easier to reuse across projects and teams.
+ *
+ * ## Giving the actors an ability to `BrowseTheWeb`
+ *
+ * To give an {@apilink Actor|actor} an ability to `BrowseTheWeb`, provide the **integration tool-specific implementation**
+ * via {@apilink Actor.whoCan} in {@apilink Cast.prepare}, or via {@apilink Cast.where}.
+ *
+ * ```ts
+ * import { beforeEach } from 'mocha'
+ * import { engage, Actor, Cast } from '@serenity-js/core'
+ * import { BrowseTheWebWithPlaywright } from '@serenity-js/playwright'
+ * import { Browser, chromium } from 'playwright'
+ *
+ * beforeEach(async () => {
+ *   const browser = await chromium.launch({ headless: true })
+ *
+ *   engage(
+ *     BrowseTheWebWithPlaywright.using(browser),
+ *   )
+ * })
+ * ```
+ *
+ * ### Learn more
+ *
+ * To learn more about using Serenity/JS with your chosen test integration tool, follow their respective documentation:
+ *
+ * - {@apilink BrowseTheWebWithPlaywright}
+ * - {@apilink BrowseTheWebWithProtractor}
+ * - {@apilink BrowseTheWebWithWebdriverIO}
+ *
+ * ## Using the ability to `BrowseTheWeb`
+ *
+ * To use the ability to `BrowseTheWeb` in a custom {@apilink Interaction} or {@apilink Question}, use the **generic** method {@apilink BrowseTheWeb.as}
+ * to retrieve it.
+ *
+ * This generic method retrieves the integration tool-specific implementation of {@apilink BrowseTheWeb} present on the {@apilink Actor},
+ * such as {@apilink BrowseTheWebWithPlaywright} or {@apilink BrowseTheWebWethWebdriverIO}, using {@apilink Actor.abilityTo}.
+ *
+ * This decoupling mechanism helps to make your test code portable across test integration tools,
+ * since the only part of your test suite that needs to know about the test integration tool used are the actors.
+ * The rest of your test code, so {@apilink Task|tasks}, {@apilink Interaction|interactions}, and {@apilink Question|questions},
+ * remain fully agnostic of the underlying tool.
+ *
+ * ```ts
+ * import { BrowseTheWeb, Question } from '@serenity-js/web'
+ *
+ * const BrowserDetails = () =>
+ *  Question.about('browser details', async actor => {
+ *    const capabilities = await BrowseTheWeb.as(actor).browserCapabilities();
+ *    return ${ capabilities.browserName } ${ capabilities.browserVersion }`;
+ *  })
+ * ```
+ *
+ * **Pro tip:** Use the specific `BrowseTheWebWith<test integration tool name>` to give the actor the ability,
+ * and generic `BrowseTheWeb.as(actor)` to retrieve it.
+ *
+ * ### Learn more
+ *
+ * - {@apilink Ability}
+ * - {@apilink Actor.whoCan}
+ * - {@apilink Cast.where}
+ * - {@apilink Cast.prepare}
+ *
+ * @group Abilities
+ */
+export declare abstract class BrowseTheWeb<Native_Element_Type = any> extends Ability {
+    protected readonly session: BrowsingSession<Page<Native_Element_Type>>;
+    constructor(session: BrowsingSession<Page<Native_Element_Type>>);
     /**
-     * @desc
-     *  Used to access the Actor's ability to {@link BrowseTheWeb}
-     *  from within the {@link @serenity-js/core/lib/screenplay~Interaction} classes,
-     *  such as {@link Click}.
-     *
-     * @param {@serenity-js/core/lib/screenplay/actor~UsesAbilities} actor
-     * @return {BrowseTheWeb}
+     * Returns {@apilink BrowserCapabilities|basic meta-data} about the browser associated with this ability.
      */
-    static as<NET = any, NRET = unknown>(actor: UsesAbilities): BrowseTheWeb<NET, NRET>;
-    constructor(locators: Map<new (...args: unknown[]) => Selector, (selector: Selector) => Locator<Native_Element_Type, Native_Root_Element_Type>>);
-    abstract navigateTo(destination: string): Promise<void>;
-    abstract navigateBack(): Promise<void>;
-    abstract navigateForward(): Promise<void>;
-    abstract reloadPage(): Promise<void>;
-    abstract waitFor(duration: Duration): Promise<void>;
-    abstract waitUntil(condition: () => boolean | Promise<boolean>, timeout: Duration): Promise<void>;
-    locate(selector: Selector): Locator<Native_Element_Type, Native_Root_Element_Type>;
     abstract browserCapabilities(): Promise<BrowserCapabilities>;
-    abstract sendKeys(keys: Array<Key | string>): Promise<void>;
-    abstract executeScript<Result, InnerArguments extends any[]>(script: string | ((...parameters: InnerArguments) => Result), ...args: InnerArguments): Promise<Result>;
-    abstract executeAsyncScript<Result, Parameters extends any[]>(script: string | ((...args: [...parameters: Parameters, callback: (result: Result) => void]) => void), ...args: Parameters): Promise<Result>;
-    abstract lastScriptExecutionResult<R = any>(): R;
-    abstract takeScreenshot(): Promise<string>;
     /**
-     * @desc
-     *  Returns a {@link Page} representing the currently active top-level browsing context.
-     *
-     * @returns {Promise<Page>}
+     * Returns a {@apilink Page} representing the currently active browser tab.
      */
-    abstract currentPage(): Promise<Page>;
+    currentPage(): Promise<Page<Native_Element_Type>>;
     /**
-     * @desc
-     *  Returns an array of {@link Page} objects representing all the available
-     *  top-level browsing context, e.g. all the open browser tabs.
-     *
-     * @returns {Promise<Array<Page>>}
+     * Returns an array of {@apilink Page|pages} representing all the browser tabs
+     * available in the current {@apilink BrowsingSession}.
      */
-    abstract allPages(): Promise<Array<Page>>;
-    abstract cookie(name: string): Promise<Cookie>;
-    abstract setCookie(cookieData: CookieData): Promise<void>;
-    abstract deleteAllCookies(): Promise<void>;
-    abstract modalDialog(): Promise<ModalDialog>;
-    abstract switchToFrame(targetOrIndex: PageElement | number | string): Promise<void>;
-    abstract switchToParentFrame(): Promise<void>;
-    abstract switchToDefaultContent(): Promise<void>;
+    allPages(): Promise<Array<Page<Native_Element_Type>>>;
 }
+//# sourceMappingURL=BrowseTheWeb.d.ts.map

package/lib/screenplay/abilities/BrowseTheWeb.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrowseTheWeb.d.ts","sourceRoot":"","sources":["../../../src/screenplay/abilities/BrowseTheWeb.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAE5C,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2EG;AACH,8BAAsB,YAAY,CAAC,mBAAmB,GAAG,GAAG,CAAE,SAAQ,OAAO;IAE7D,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;gBAAnD,OAAO,EAAE,eAAe,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;IAIlF;;OAEG;IACH,QAAQ,CAAC,mBAAmB,IAAI,OAAO,CAAC,mBAAmB,CAAC;IAE5D;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;IAIvD;;;OAGG;IACH,QAAQ,IAAI,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC,CAAC;CAGxD"}

package/lib/screenplay/abilities/BrowseTheWeb.js

@@ -2,29 +2,99 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BrowseTheWeb = void 0;
 const core_1 = require("@serenity-js/core");
-class BrowseTheWeb {
-    constructor(locators) {
-        this.locators = locators;
+/**
+ * The {@apilink Ability|ability} to `BrowseTheWeb` enables an {@apilink Actor|actor}
+ * to {@apilink Interaction|interact with} and {@apilink Question|retrieve information from} Web-based user interfaces.
+ *
+ * `BrowseTheWeb` wraps test integration tools such as [Playwright](/api/playwright),
+ * [Protractor](/api/protractor), or [WebdriverIO](/api/webdriverio),
+ * and together with Serenity/JS Web models, such as {@apilink Page} or {@apilink PageElement} - offers a standardised way
+ * to write Web-based tests following the Screenplay Pattern.
+ *
+ * The consistent and portable design of abstractions provided by the [`@serenity-js/web` module](/api/web)
+ * also helps to make your tests portable across the various test integration tools and helps to make your test
+ * code easier to reuse across projects and teams.
+ *
+ * ## Giving the actors an ability to `BrowseTheWeb`
+ *
+ * To give an {@apilink Actor|actor} an ability to `BrowseTheWeb`, provide the **integration tool-specific implementation**
+ * via {@apilink Actor.whoCan} in {@apilink Cast.prepare}, or via {@apilink Cast.where}.
+ *
+ * ```ts
+ * import { beforeEach } from 'mocha'
+ * import { engage, Actor, Cast } from '@serenity-js/core'
+ * import { BrowseTheWebWithPlaywright } from '@serenity-js/playwright'
+ * import { Browser, chromium } from 'playwright'
+ *
+ * beforeEach(async () => {
+ *   const browser = await chromium.launch({ headless: true })
+ *
+ *   engage(
+ *     BrowseTheWebWithPlaywright.using(browser),
+ *   )
+ * })
+ * ```
+ *
+ * ### Learn more
+ *
+ * To learn more about using Serenity/JS with your chosen test integration tool, follow their respective documentation:
+ *
+ * - {@apilink BrowseTheWebWithPlaywright}
+ * - {@apilink BrowseTheWebWithProtractor}
+ * - {@apilink BrowseTheWebWithWebdriverIO}
+ *
+ * ## Using the ability to `BrowseTheWeb`
+ *
+ * To use the ability to `BrowseTheWeb` in a custom {@apilink Interaction} or {@apilink Question}, use the **generic** method {@apilink BrowseTheWeb.as}
+ * to retrieve it.
+ *
+ * This generic method retrieves the integration tool-specific implementation of {@apilink BrowseTheWeb} present on the {@apilink Actor},
+ * such as {@apilink BrowseTheWebWithPlaywright} or {@apilink BrowseTheWebWethWebdriverIO}, using {@apilink Actor.abilityTo}.
+ *
+ * This decoupling mechanism helps to make your test code portable across test integration tools,
+ * since the only part of your test suite that needs to know about the test integration tool used are the actors.
+ * The rest of your test code, so {@apilink Task|tasks}, {@apilink Interaction|interactions}, and {@apilink Question|questions},
+ * remain fully agnostic of the underlying tool.
+ *
+ * ```ts
+ * import { BrowseTheWeb, Question } from '@serenity-js/web'
+ *
+ * const BrowserDetails = () =>
+ *  Question.about('browser details', async actor => {
+ *    const capabilities = await BrowseTheWeb.as(actor).browserCapabilities();
+ *    return ${ capabilities.browserName } ${ capabilities.browserVersion }`;
+ *  })
+ * ```
+ *
+ * **Pro tip:** Use the specific `BrowseTheWebWith<test integration tool name>` to give the actor the ability,
+ * and generic `BrowseTheWeb.as(actor)` to retrieve it.
+ *
+ * ### Learn more
+ *
+ * - {@apilink Ability}
+ * - {@apilink Actor.whoCan}
+ * - {@apilink Cast.where}
+ * - {@apilink Cast.prepare}
+ *
+ * @group Abilities
+ */
+class BrowseTheWeb extends core_1.Ability {
+    constructor(session) {
+        super();
+        this.session = session;
     }
     /**
-     * @desc
-     *  Used to access the Actor's ability to {@link BrowseTheWeb}
-     *  from within the {@link @serenity-js/core/lib/screenplay~Interaction} classes,
-     *  such as {@link Click}.
-     *
-     * @param {@serenity-js/core/lib/screenplay/actor~UsesAbilities} actor
-     * @return {BrowseTheWeb}
+     * Returns a {@apilink Page} representing the currently active browser tab.
      */
-    static as(actor) {
-        return actor.abilityTo(BrowseTheWeb);
+    async currentPage() {
+        return this.session.currentPage();
     }
-    locate(selector) {
-        for (const [type, locatorFactory] of this.locators) {
-            if (selector instanceof type) {
-                return locatorFactory(selector);
-            }
-        }
-        throw new core_1.LogicError((0, core_1.f) `${selector} is not supported by ${this.constructor.name}`);
+    /**
+     * Returns an array of {@apilink Page|pages} representing all the browser tabs
+     * available in the current {@apilink BrowsingSession}.
+     */
+    allPages() {
+        return this.session.allPages();
     }
 }
 exports.BrowseTheWeb = BrowseTheWeb;

package/lib/screenplay/abilities/BrowseTheWeb.js.map

@@ -1 +1 @@
-{"version":3,"file":"BrowseTheWeb.js","sourceRoot":"","sources":["../../../src/screenplay/abilities/BrowseTheWeb.ts"],"names":[],"mappings":";;;AAAA,4CAAoF;AAMpF,MAAsB,YAAY;IAc9B,YACc,QAIT;QAJS,aAAQ,GAAR,QAAQ,CAIjB;IAEL,CAAC;IApBD;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,CAA4B,KAAoB;QACrD,OAAO,KAAK,CAAC,SAAS,CAAC,YAAY,CAA4B,CAAC;IACpE,CAAC;IAuBD,MAAM,CAAC,QAAkB;QACrB,KAAK,MAAM,CAAE,IAAI,EAAE,cAAc,CAAE,IAAI,IAAI,CAAC,QAAQ,EAAE;YAClD,IAAI,QAAQ,YAAY,IAAI,EAAE;gBAC1B,OAAO,cAAc,CAAC,QAAQ,CAAC,CAAC;aACnC;SACJ;QAED,MAAM,IAAI,iBAAU,CAAC,IAAA,QAAC,EAAC,GAAI,QAAS,wBAAyB,IAAI,CAAC,WAAW,CAAC,IAAK,EAAE,CAAC,CAAC;IAC3F,CAAC;CA+CJ;AA1FD,oCA0FC"}
+{"version":3,"file":"BrowseTheWeb.js","sourceRoot":"","sources":["../../../src/screenplay/abilities/BrowseTheWeb.ts"],"names":[],"mappings":";;;AAAA,4CAA4C;AAI5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2EG;AACH,MAAsB,YAAwC,SAAQ,cAAO;IAEzE,YAA+B,OAAmD;QAC9E,KAAK,EAAE,CAAC;QADmB,YAAO,GAAP,OAAO,CAA4C;IAElF,CAAC;IAOD;;OAEG;IACH,KAAK,CAAC,WAAW;QACb,OAAO,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;IACtC,CAAC;IAED;;;OAGG;IACH,QAAQ;QACJ,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;IACnC,CAAC;CACJ;AAzBD,oCAyBC"}

package/lib/screenplay/abilities/index.d.ts

@@ -1,2 +1,2 @@
-export * from './BrowserCapabilities';
 export * from './BrowseTheWeb';
+//# sourceMappingURL=index.d.ts.map

package/lib/screenplay/abilities/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/screenplay/abilities/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC"}

package/lib/screenplay/abilities/index.js

@@ -1,7 +1,11 @@
 "use strict";
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
-    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
 }) : (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     o[k2] = m[k];
@@ -10,6 +14,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./BrowserCapabilities"), exports);
 __exportStar(require("./BrowseTheWeb"), exports);
 //# sourceMappingURL=index.js.map

package/lib/screenplay/abilities/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/screenplay/abilities/index.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,wDAAsC;AACtC,iDAA+B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/screenplay/abilities/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,iDAA+B"}

package/lib/screenplay/index.d.ts

@@ -2,3 +2,4 @@ export * from './abilities';
 export * from './interactions';
 export * from './models';
 export * from './questions';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/screenplay/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC"}

package/lib/screenplay/index.js

@@ -1,7 +1,11 @@
 "use strict";
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
-    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
 }) : (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     o[k2] = m[k];

package/lib/screenplay/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/screenplay/index.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,8CAA4B;AAC5B,iDAA+B;AAC/B,2CAAyB;AACzB,8CAA4B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/screenplay/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,8CAA4B;AAC5B,iDAA+B;AAC/B,2CAAyB;AACzB,8CAA4B"}

package/lib/screenplay/interactions/Clear.d.ts

@@ -2,78 +2,73 @@ import { Answerable, AnswersQuestions, Interaction, UsesAbilities } from '@seren
 import { PageElement } from '../models';
 import { PageElementInteraction } from './PageElementInteraction';
 /**
- * @desc
- *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor} to
- *  clear the `value` of a [form `input`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input).
+ * Instructs an {@apilink Actor|actor} who has the {@apilink Ability|ability} to {@apilink BrowseTheWeb}
+ * to clear the `value` of a [form `input` field](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input).
  *
- * @example <caption>Example widget</caption>
- *  <form>
- *    <input type="text" name="example" id="example" />
- *  </form>
+ * ## Example widget
  *
- * @example <caption>Lean Page Object describing the widget</caption>
- *  import { by, Target } from '@serenity-js/webdriverio';
+ * ```html
+ * <form>
+ *   <input type="text" name="example" id="example" />
+ * </form>
+ * ```
  *
- *  class Form {
- *      static exampleInput = Target.the('example input')
- *          .located(by.id('example'));
- *  }
+ * ## Lean Page Object describing the widget
  *
- * @example <caption>Clearing the value of an input field</caption>
- *  import { actorCalled } from '@serenity-js/core';
- *  import { BrowseTheWeb, Clear, Enter, Value } from '@serenity-js/webdriverio';
- *  import { Ensure, equals } from '@serenity-js/assertions';
+ * ```ts
+ * import { By, PageElement } from '@serenity-js/web'
  *
- *  actorCalled('Inés')
- *      .whoCan(BrowseTheWeb.using(browser))
- *      .attemptsTo(
- *          Enter.theValue('Hello world!').into(Form.exampleInput),
- *          Ensure.that(Value.of(Form.exampleInput), equals('Hello world!')),
+ * const Form = {
+ *   exampleInput: () =>
+ *     PageElement.located(By.id('example'))
+ *      .describedAs('example input')
+ * }
+ * ```
  *
- *          Clear.theValueOf(Form.exampleInput),
- *          Ensure.that(Value.of(Form.exampleInput), equals('')),
- *      );
+ * ## Clearing the value of an input field
  *
- * @see {@link BrowseTheWeb}
- * @see {@link Enter}
- * @see {@link Value}
- * @see {@link Target}
- * @see {@link @serenity-js/assertions~Ensure}
- * @see {@link @serenity-js/assertions/lib/expectations~equals}
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Clear, Enter, Value } from '@serenity-js/web'
+ * import { Ensure, equals } from '@serenity-js/assertions'
  *
- * @extends {@serenity-js/core/lib/screenplay~Interaction}
+ * await actorCalled('Inés')
+ *   .whoCan(BrowseTheWeb.using(browser))
+ *   .attemptsTo(
+ *     Enter.theValue('Hello world!').into(Form.exampleInput()),
+ *     Ensure.that(Value.of(Form.exampleInput()), equals('Hello world!')),
+ *
+ *     Clear.theValueOf(Form.exampleInput()),
+ *     Ensure.that(Value.of(Form.exampleInput()), equals('')),
+ *   )
+ * ```
+ *
+ * ## Learn more
+ *
+ * - {@apilink BrowseTheWeb}
+ * - {@apilink Enter}
+ * - {@apilink Value}
+ * - {@apilink PageElement}
+ *
+ * @group Activities
  */
 export declare class Clear extends PageElementInteraction {
     private readonly field;
     /**
-     * @desc
-     *  Instantiates this {@link @serenity-js/core/lib/screenplay~Interaction}.
-     *
-     * @param {Answerable<PageElement>} field
-     *  The field to be cleared
+     * Instantiates an {@apilink Interaction|interaction}
+     * that instructs the {@apilink Actor|actor}
+     * to clear the value of an input `field`,
      *
-     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     * @param field
+     *  The field which value should be cleared
      */
     static theValueOf(field: Answerable<PageElement>): Interaction;
+    protected constructor(field: Answerable<PageElement>);
     /**
-     * @param {Answerable<PageElement>} field
-     *  The element to be clicked on
-     */
-    constructor(field: Answerable<PageElement>);
-    /**
-     * @desc
-     *  Makes the provided {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     *  perform this {@link @serenity-js/core/lib/screenplay~Interaction}.
-     *
-     * @param {UsesAbilities & AnswersQuestions} actor
-     *  An {@link @serenity-js/core/lib/screenplay/actor~Actor} to perform this {@link @serenity-js/core/lib/screenplay~Interaction}
-     *
-     * @returns {PromiseLike<void>}
-     *
-     * @see {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     * @see {@link @serenity-js/core/lib/screenplay/actor~UsesAbilities}
-     * @see {@link @serenity-js/core/lib/screenplay/actor~AnswersQuestions}
+     * @inheritDoc
      */
     performAs(actor: UsesAbilities & AnswersQuestions): Promise<void>;
+    private isClearable;
     private capitaliseFirstLetter;
 }
+//# sourceMappingURL=Clear.d.ts.map

package/lib/screenplay/interactions/Clear.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Clear.d.ts","sourceRoot":"","sources":["../../../src/screenplay/interactions/Clear.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAK,WAAW,EAAc,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAE5G,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,qBAAa,KAAM,SAAQ,sBAAsB;IAcvB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAZ5C;;;;;;;OAOG;IACH,MAAM,CAAC,UAAU,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,GAAG,WAAW;IAI9D,SAAS,aAA8B,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC;IAIrE;;OAEG;IACG,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;YAczD,WAAW;IAmBzB,OAAO,CAAC,qBAAqB;CAGhC"}

package/lib/screenplay/interactions/Clear.js

@@ -2,92 +2,99 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Clear = void 0;
 const core_1 = require("@serenity-js/core");
-const io_1 = require("@serenity-js/core/lib/io");
 const PageElementInteraction_1 = require("./PageElementInteraction");
 /**
- * @desc
- *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor} to
- *  clear the `value` of a [form `input`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input).
+ * Instructs an {@apilink Actor|actor} who has the {@apilink Ability|ability} to {@apilink BrowseTheWeb}
+ * to clear the `value` of a [form `input` field](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input).
  *
- * @example <caption>Example widget</caption>
- *  <form>
- *    <input type="text" name="example" id="example" />
- *  </form>
+ * ## Example widget
  *
- * @example <caption>Lean Page Object describing the widget</caption>
- *  import { by, Target } from '@serenity-js/webdriverio';
+ * ```html
+ * <form>
+ *   <input type="text" name="example" id="example" />
+ * </form>
+ * ```
  *
- *  class Form {
- *      static exampleInput = Target.the('example input')
- *          .located(by.id('example'));
- *  }
+ * ## Lean Page Object describing the widget
  *
- * @example <caption>Clearing the value of an input field</caption>
- *  import { actorCalled } from '@serenity-js/core';
- *  import { BrowseTheWeb, Clear, Enter, Value } from '@serenity-js/webdriverio';
- *  import { Ensure, equals } from '@serenity-js/assertions';
+ * ```ts
+ * import { By, PageElement } from '@serenity-js/web'
  *
- *  actorCalled('Inés')
- *      .whoCan(BrowseTheWeb.using(browser))
- *      .attemptsTo(
- *          Enter.theValue('Hello world!').into(Form.exampleInput),
- *          Ensure.that(Value.of(Form.exampleInput), equals('Hello world!')),
+ * const Form = {
+ *   exampleInput: () =>
+ *     PageElement.located(By.id('example'))
+ *      .describedAs('example input')
+ * }
+ * ```
  *
- *          Clear.theValueOf(Form.exampleInput),
- *          Ensure.that(Value.of(Form.exampleInput), equals('')),
- *      );
+ * ## Clearing the value of an input field
  *
- * @see {@link BrowseTheWeb}
- * @see {@link Enter}
- * @see {@link Value}
- * @see {@link Target}
- * @see {@link @serenity-js/assertions~Ensure}
- * @see {@link @serenity-js/assertions/lib/expectations~equals}
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Clear, Enter, Value } from '@serenity-js/web'
+ * import { Ensure, equals } from '@serenity-js/assertions'
  *
- * @extends {@serenity-js/core/lib/screenplay~Interaction}
+ * await actorCalled('Inés')
+ *   .whoCan(BrowseTheWeb.using(browser))
+ *   .attemptsTo(
+ *     Enter.theValue('Hello world!').into(Form.exampleInput()),
+ *     Ensure.that(Value.of(Form.exampleInput()), equals('Hello world!')),
+ *
+ *     Clear.theValueOf(Form.exampleInput()),
+ *     Ensure.that(Value.of(Form.exampleInput()), equals('')),
+ *   )
+ * ```
+ *
+ * ## Learn more
+ *
+ * - {@apilink BrowseTheWeb}
+ * - {@apilink Enter}
+ * - {@apilink Value}
+ * - {@apilink PageElement}
+ *
+ * @group Activities
  */
 class Clear extends PageElementInteraction_1.PageElementInteraction {
     /**
-     * @param {Answerable<PageElement>} field
-     *  The element to be clicked on
-     */
-    constructor(field) {
-        super((0, io_1.formatted) `#actor clears the value of ${field}`);
-        this.field = field;
-    }
-    /**
-     * @desc
-     *  Instantiates this {@link @serenity-js/core/lib/screenplay~Interaction}.
-     *
-     * @param {Answerable<PageElement>} field
-     *  The field to be cleared
+     * Instantiates an {@apilink Interaction|interaction}
+     * that instructs the {@apilink Actor|actor}
+     * to clear the value of an input `field`,
      *
-     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     * @param field
+     *  The field which value should be cleared
      */
     static theValueOf(field) {
         return new Clear(field);
     }
+    constructor(field) {
+        super((0, core_1.d) `#actor clears the value of ${field}`);
+        this.field = field;
+    }
     /**
-     * @desc
-     *  Makes the provided {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     *  perform this {@link @serenity-js/core/lib/screenplay~Interaction}.
-     *
-     * @param {UsesAbilities & AnswersQuestions} actor
-     *  An {@link @serenity-js/core/lib/screenplay/actor~Actor} to perform this {@link @serenity-js/core/lib/screenplay~Interaction}
-     *
-     * @returns {PromiseLike<void>}
-     *
-     * @see {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     * @see {@link @serenity-js/core/lib/screenplay/actor~UsesAbilities}
-     * @see {@link @serenity-js/core/lib/screenplay/actor~AnswersQuestions}
+     * @inheritDoc
      */
     async performAs(actor) {
         const element = await this.resolve(actor, this.field);
-        const value = await element.value();
-        if (value === null || value === undefined) {
-            throw new core_1.LogicError(this.capitaliseFirstLetter((0, io_1.formatted) `${this.field} doesn't seem to have a 'value' attribute that could be cleared.`));
+        const isClearable = await this.isClearable(element);
+        if (!isClearable) {
+            throw new core_1.LogicError(this.capitaliseFirstLetter((0, core_1.d) `${this.field} doesn't seem like an element that could be cleared.`));
+        }
+        await element.clearValue();
+    }
+    async isClearable(element) {
+        const contentEditable = await element.attribute('contenteditable');
+        const hasContentEditableAttribute = contentEditable !== null && contentEditable !== undefined && contentEditable !== 'false'; // true or empty string mean content is editable
+        if (hasContentEditableAttribute) {
+            return true;
+        }
+        try {
+            const value = await element.value();
+            const hasValueAttribute = value !== null && value !== undefined;
+            return hasValueAttribute;
+        }
+        catch {
+            return false;
         }
-        return element.clearValue();
     }
     capitaliseFirstLetter(text) {
         return text.charAt(0).toUpperCase() + text.slice(1);

package/lib/screenplay/interactions/Clear.js.map

@@ -1 +1 @@
-{"version":3,"file":"Clear.js","sourceRoot":"","sources":["../../../src/screenplay/interactions/Clear.ts"],"names":[],"mappings":";;;AAAA,4CAAyG;AACzG,iDAAqD;AAGrD,qEAAkE;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAa,KAAM,SAAQ,+CAAsB;IAe7C;;;OAGG;IACH,YAA6B,KAA8B;QACvD,KAAK,CAAC,IAAA,cAAS,EAAC,8BAA+B,KAAM,EAAE,CAAC,CAAC;QADhC,UAAK,GAAL,KAAK,CAAyB;IAE3D,CAAC;IAnBD;;;;;;;;OAQG;IACH,MAAM,CAAC,UAAU,CAAC,KAA8B;QAC5C,OAAO,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC;IAC5B,CAAC;IAUD;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,SAAS,CAAC,KAAuC;QACnD,MAAM,OAAO,GAAK,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;QACxD,MAAM,KAAK,GAAO,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC;QAExC,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,EAAE;YACvC,MAAM,IAAI,iBAAU,CAChB,IAAI,CAAC,qBAAqB,CAAC,IAAA,cAAS,EAAC,GAAI,IAAI,CAAC,KAAM,kEAAkE,CAAC,CAC1H,CAAC;SACL;QAED,OAAO,OAAO,CAAC,UAAU,EAAE,CAAC;IAChC,CAAC;IAEO,qBAAqB,CAAC,IAAY;QACtC,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACxD,CAAC;CACJ;AArDD,sBAqDC"}
+{"version":3,"file":"Clear.js","sourceRoot":"","sources":["../../../src/screenplay/interactions/Clear.ts"],"names":[],"mappings":";;;AAAA,4CAA4G;AAG5G,qEAAkE;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,MAAa,KAAM,SAAQ,+CAAsB;IAE7C;;;;;;;OAOG;IACH,MAAM,CAAC,UAAU,CAAC,KAA8B;QAC5C,OAAO,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC;IAC5B,CAAC;IAED,YAAuC,KAA8B;QACjE,KAAK,CAAC,IAAA,QAAC,EAAA,8BAA+B,KAAM,EAAE,CAAC,CAAC;QADb,UAAK,GAAL,KAAK,CAAyB;IAErE,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,SAAS,CAAC,KAAuC;QACnD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;QAEtD,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;QAEpD,IAAI,CAAC,WAAW,EAAE;YACd,MAAM,IAAI,iBAAU,CAChB,IAAI,CAAC,qBAAqB,CAAC,IAAA,QAAC,EAAA,GAAI,IAAI,CAAC,KAAM,sDAAsD,CAAC,CACrG,CAAC;SACL;QAED,MAAM,OAAO,CAAC,UAAU,EAAE,CAAC;IAC/B,CAAC;IAEO,KAAK,CAAC,WAAW,CAAC,OAAoB;QAC1C,MAAM,eAAe,GAAG,MAAM,OAAO,CAAC,SAAS,CAAC,iBAAiB,CAAC,CAAC;QACnE,MAAM,2BAA2B,GAAG,eAAe,KAAK,IAAI,IAAI,eAAe,KAAK,SAAS,IAAI,eAAe,KAAK,OAAO,CAAC,CAAE,gDAAgD;QAE/K,IAAI,2BAA2B,EAAE;YAC7B,OAAO,IAAI,CAAC;SACf;QAED,IAAI;YACA,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC;YACpC,MAAM,iBAAiB,GAAG,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,CAAC;YAEhE,OAAO,iBAAiB,CAAC;SAC5B;QACD,MAAM;YACF,OAAO,KAAK,CAAC;SAChB;IACL,CAAC;IAEO,qBAAqB,CAAC,IAAY;QACtC,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACxD,CAAC;CACJ;AAzDD,sBAyDC"}