@serenity-js/web 3.0.0-rc.4 → 3.0.0-rc.5

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [3.0.0-rc.5](https://github.com/serenity-js/serenity-js/compare/v3.0.0-rc.4...v3.0.0-rc.5) (2022-01-07)
+
+
+### Features
+
+* **web:** support for advanced PageElement locator patterns ([c1ff8b7](https://github.com/serenity-js/serenity-js/commit/c1ff8b7539ebc1da8f79ea2b6d17bb01c42f443d)), closes [#1084](https://github.com/serenity-js/serenity-js/issues/1084)
+
+
+
+
+
 # [3.0.0-rc.4](https://github.com/serenity-js/serenity-js/compare/v3.0.0-rc.3...v3.0.0-rc.4) (2021-12-30)
 
 

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

@@ -1,8 +1,9 @@
 import { Ability, Duration, UsesAbilities } from '@serenity-js/core';
 import { Key } from '../../input';
-import { Cookie, CookieData, ModalDialog, NativeElementLocator, Page, PageElement, Selector } from '../models';
+import { Cookie, CookieData, Locator, ModalDialog, Page, PageElement, Selector } from '../models';
 import { BrowserCapabilities } from './BrowserCapabilities';
-export declare abstract class BrowseTheWeb<Native_Element_Type = any> implements Ability {
+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>>;
     /**
      * @desc
      *  Used to access the Actor's ability to {@link BrowseTheWeb}
@@ -12,16 +13,15 @@ export declare abstract class BrowseTheWeb<Native_Element_Type = any> implements
      * @param {@serenity-js/core/lib/screenplay/actor~UsesAbilities} actor
      * @return {BrowseTheWeb}
      */
-    static as(actor: UsesAbilities): BrowseTheWeb;
+    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>;
-    abstract locate<T>(selector: Selector<T>, locator?: NativeElementLocator<Native_Element_Type>): PageElement<Native_Element_Type>;
-    abstract locateAll<T>(selector: Selector<T>, locator?: NativeElementLocator<Native_Element_Type>): Promise<Array<PageElement<Native_Element_Type>>>;
-    abstract nativeElementLocator(): NativeElementLocator<Native_Element_Type>;
+    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>;

package/lib/screenplay/abilities/BrowseTheWeb.js

@@ -1,7 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BrowseTheWeb = void 0;
+const core_1 = require("@serenity-js/core");
+const f = (0, core_1.format)({ markQuestions: true });
 class BrowseTheWeb {
+    constructor(locators) {
+        this.locators = locators;
+    }
     /**
      * @desc
      *  Used to access the Actor's ability to {@link BrowseTheWeb}
@@ -14,6 +19,14 @@ class BrowseTheWeb {
     static as(actor) {
         return actor.abilityTo(BrowseTheWeb);
     }
+    locate(selector) {
+        for (const [type, locatorFactory] of this.locators) {
+            if (selector instanceof type) {
+                return locatorFactory(selector);
+            }
+        }
+        throw new core_1.LogicError(f `${selector} is not supported by ${this.constructor.name}`);
+    }
 }
 exports.BrowseTheWeb = BrowseTheWeb;
 //# sourceMappingURL=BrowseTheWeb.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"BrowseTheWeb.js","sourceRoot":"","sources":["../../../src/screenplay/abilities/BrowseTheWeb.ts"],"names":[],"mappings":";;;AAMA,MAAsB,YAAY;IAC9B;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,CAAC,KAAoB;QAC1B,OAAO,KAAK,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC;IACzC,CAAC;CA+DJ;AA3ED,oCA2EC"}
+{"version":3,"file":"BrowseTheWeb.js","sourceRoot":"","sources":["../../../src/screenplay/abilities/BrowseTheWeb.ts"],"names":[],"mappings":";;;AAAA,4CAAyF;AAMzF,MAAM,CAAC,GAAG,IAAA,aAAM,EAAC,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;AAE1C,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,CAAC,CAAC,GAAI,QAAS,wBAAyB,IAAI,CAAC,WAAW,CAAC,IAAK,EAAE,CAAC,CAAC;IAC3F,CAAC;CA+CJ;AA1FD,oCA0FC"}

package/lib/screenplay/interactions/Press.js

@@ -112,7 +112,6 @@ class PressKeyInField extends PageElementInteraction_1.PageElementInteraction {
         const field = await this.resolve(actor, this.field);
         const keys = await actor.answer(this.keys);
         // fix for protractor
-        // todo: should this wait on focus to occur?
         await abilities_1.BrowseTheWeb.as(actor).executeScript(
         /* istanbul ignore next */
         function focus(element) {

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

@@ -1 +1 @@
-{"version":3,"file":"Press.js","sourceRoot":"","sources":["../../../src/screenplay/interactions/Press.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Press.js","sourceRoot":"","sources":["../../../src/screenplay/interactions/Press.ts"],"names":[],"mappings":"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"}

package/lib/screenplay/models/Locator.d.ts

@@ -0,0 +1,14 @@
+import { PageElement } from './PageElement';
+import { Selector } from './selectors';
+export declare abstract class Locator<Native_Element_Type, Native_Root_Element_Type = any, Selector_Type extends Selector = Selector> {
+    protected readonly parentRoot: () => Promise<Native_Root_Element_Type> | Native_Root_Element_Type;
+    protected readonly selector: Selector_Type;
+    protected readonly locateElement: (root: Native_Root_Element_Type) => Promise<Native_Element_Type> | Native_Element_Type;
+    protected readonly locateAllElements: (root: Native_Root_Element_Type) => Promise<Array<Native_Element_Type>> | Array<Native_Element_Type>;
+    constructor(parentRoot: () => Promise<Native_Root_Element_Type> | Native_Root_Element_Type, selector: Selector_Type, locateElement: (root: Native_Root_Element_Type) => Promise<Native_Element_Type> | Native_Element_Type, locateAllElements: (root: Native_Root_Element_Type) => Promise<Array<Native_Element_Type>> | Array<Native_Element_Type>);
+    nativeElement(): Promise<Native_Element_Type>;
+    abstract of(parent: Locator<Native_Element_Type, Native_Root_Element_Type>): Locator<Native_Element_Type, Native_Root_Element_Type>;
+    abstract element(): PageElement<Native_Element_Type>;
+    abstract allElements(): Promise<Array<PageElement<Native_Element_Type>>>;
+    toString(): string;
+}

package/lib/screenplay/models/Locator.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Locator = void 0;
+class Locator {
+    constructor(parentRoot, selector, locateElement, locateAllElements) {
+        this.parentRoot = parentRoot;
+        this.selector = selector;
+        this.locateElement = locateElement;
+        this.locateAllElements = locateAllElements;
+    }
+    async nativeElement() {
+        return this.locateElement(await this.parentRoot());
+    }
+    toString() {
+        return this.selector.toString();
+    }
+}
+exports.Locator = Locator;
+//# sourceMappingURL=Locator.js.map

package/lib/screenplay/models/Locator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Locator.js","sourceRoot":"","sources":["../../../src/screenplay/models/Locator.ts"],"names":[],"mappings":";;;AAGA,MAAsB,OAAO;IACzB,YACuB,UAA8E,EAC9E,QAAuB,EACvB,aAAqG,EACrG,iBAAuH;QAHvH,eAAU,GAAV,UAAU,CAAoE;QAC9E,aAAQ,GAAR,QAAQ,CAAe;QACvB,kBAAa,GAAb,aAAa,CAAwF;QACrG,sBAAiB,GAAjB,iBAAiB,CAAsG;IAE9I,CAAC;IAEM,KAAK,CAAC,aAAa;QACtB,OAAO,IAAI,CAAC,aAAa,CAAC,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;IACvD,CAAC;IAOD,QAAQ;QACJ,OAAO,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC;IACpC,CAAC;CACJ;AArBD,0BAqBC"}

package/lib/screenplay/models/PageElement.d.ts

@@ -1,15 +1,13 @@
 import { Adapter, Answerable, Question } from '@serenity-js/core';
-import { NativeElementLocator } from './NativeElementLocator';
+import { Locator } from './Locator';
 import { Selector } from './selectors';
 export declare abstract class PageElement<Native_Element_Type = any> {
-    protected readonly selector: Selector<unknown>;
-    private readonly locator;
-    static located<NET, ST>(selector: Answerable<Selector<ST>>): Question<Promise<PageElement<NET>>> & Adapter<PageElement<NET>>;
+    readonly locator: Locator<Native_Element_Type>;
+    static located<NET>(selector: Answerable<Selector>): Question<Promise<PageElement<NET>>> & Adapter<PageElement<NET>>;
     static of<NET>(childElement: Answerable<PageElement<NET>>, parentElement: Answerable<PageElement<NET>>): Question<Promise<PageElement<NET>>> & Adapter<PageElement<NET>>;
-    constructor(selector: Selector<unknown>, locator: NativeElementLocator<Native_Element_Type>);
-    abstract of(parent: PageElement<Native_Element_Type>): PageElement<Native_Element_Type>;
+    constructor(locator: Locator<Native_Element_Type>);
+    abstract of(parentElement: PageElement<Native_Element_Type>): PageElement<Native_Element_Type>;
     nativeElement(): Promise<Native_Element_Type>;
-    nativeElementLocator(): NativeElementLocator<Native_Element_Type>;
     toString(): string;
     abstract enterValue(value: string | number | Array<string | number>): Promise<void>;
     abstract clearValue(): Promise<void>;

package/lib/screenplay/models/PageElement.js

@@ -2,19 +2,21 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PageElement = void 0;
 const core_1 = require("@serenity-js/core");
+const tiny_types_1 = require("tiny-types");
 const abilities_1 = require("../abilities");
 const d = (0, core_1.format)({ markQuestions: false });
 class PageElement {
-    constructor(selector, locator) {
-        this.selector = selector;
+    constructor(locator) {
         this.locator = locator;
+        (0, tiny_types_1.ensure)('native element locator', locator, (0, tiny_types_1.isDefined)());
     }
     static located(selector) {
         return core_1.Question.about(d `page element located ${selector}`, async (actor) => {
             const bySelector = await actor.answer(selector);
-            return abilities_1.BrowseTheWeb.as(actor).locate(bySelector);
+            return abilities_1.BrowseTheWeb.as(actor).locate(bySelector).element();
         });
     }
+    // todo: review usages and consider removing if not used
     static of(childElement, parentElement) {
         return core_1.Question.about(d `${childElement} of ${parentElement})`, async (actor) => {
             const child = await actor.answer(childElement);
@@ -23,18 +25,10 @@ class PageElement {
         });
     }
     async nativeElement() {
-        try {
-            return this.locator.locate(this.selector);
-        }
-        catch (error) {
-            throw new core_1.LogicError(`Couldn't find element`, error);
-        }
-    }
-    nativeElementLocator() {
-        return this.locator;
+        return this.locator.nativeElement();
     }
     toString() {
-        return `PageElement located ${this.selector}`;
+        return `PageElement located ${this.locator.toString()}`;
     }
 }
 exports.PageElement = PageElement;

package/lib/screenplay/models/PageElement.js.map

@@ -1 +1 @@
-{"version":3,"file":"PageElement.js","sourceRoot":"","sources":["../../../src/screenplay/models/PageElement.ts"],"names":[],"mappings":";;;AAAA,4CAAsF;AAEtF,4CAA4C;AAI5C,MAAM,CAAC,GAAG,IAAA,aAAM,EAAC,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC,CAAC;AAE3C,MAAsB,WAAW;IAkB7B,YACuB,QAA2B,EAC7B,OAAkD;QADhD,aAAQ,GAAR,QAAQ,CAAmB;QAC7B,YAAO,GAAP,OAAO,CAA2C;IAEvE,CAAC;IApBD,MAAM,CAAC,OAAO,CAAU,QAAkC;QACtD,OAAO,eAAQ,CAAC,KAAK,CAAC,CAAC,CAAA,wBAAyB,QAAS,EAAE,EAAE,KAAK,EAAC,KAAK,EAAC,EAAE;YACvE,MAAM,UAAU,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YAChD,OAAO,wBAAY,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,MAAM,CAAK,UAAU,CAAC,CAAC;QACzD,CAAC,CAAC,CAAC;IACP,CAAC;IAED,MAAM,CAAC,EAAE,CAAM,YAA0C,EAAE,aAA2C;QAClG,OAAO,eAAQ,CAAC,KAAK,CAAC,CAAC,CAAA,GAAI,YAAa,OAAQ,aAAc,GAAG,EAAE,KAAK,EAAC,KAAK,EAAC,EAAE;YAC7E,MAAM,KAAK,GAAO,MAAM,KAAK,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;YACnD,MAAM,MAAM,GAAM,MAAM,KAAK,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;YAEpD,OAAO,KAAK,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC;QAC5B,CAAC,CAAC,CAAC;IACP,CAAC;IAUD,KAAK,CAAC,aAAa;QACf,IAAI;YACA,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;SAC7C;QACD,OAAO,KAAK,EAAE;YACV,MAAM,IAAI,iBAAU,CAAC,uBAAuB,EAAE,KAAK,CAAC,CAAC;SACxD;IACL,CAAC;IAED,oBAAoB;QAChB,OAAO,IAAI,CAAC,OAAO,CAAC;IACxB,CAAC;IAED,QAAQ;QACJ,OAAO,uBAAwB,IAAI,CAAC,QAAS,EAAE,CAAA;IACnD,CAAC;CAoBJ;AA7DD,kCA6DC"}
+{"version":3,"file":"PageElement.js","sourceRoot":"","sources":["../../../src/screenplay/models/PageElement.ts"],"names":[],"mappings":";;;AAAA,4CAA0E;AAC1E,2CAA+C;AAE/C,4CAA4C;AAI5C,MAAM,CAAC,GAAG,IAAA,aAAM,EAAC,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC,CAAC;AAE3C,MAAsB,WAAW;IAmB7B,YAA4B,OAAqC;QAArC,YAAO,GAAP,OAAO,CAA8B;QAC7D,IAAA,mBAAM,EAAC,wBAAwB,EAAE,OAAO,EAAE,IAAA,sBAAS,GAAE,CAAC,CAAC;IAC3D,CAAC;IAnBD,MAAM,CAAC,OAAO,CAAM,QAA8B;QAC9C,OAAO,eAAQ,CAAC,KAAK,CAAC,CAAC,CAAA,wBAAyB,QAAS,EAAE,EAAE,KAAK,EAAC,KAAK,EAAC,EAAE;YACvE,MAAM,UAAU,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YAChD,OAAO,wBAAY,CAAC,EAAE,CAAM,KAAK,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,OAAO,EAAE,CAAC;QACpE,CAAC,CAAC,CAAC;IACP,CAAC;IAED,wDAAwD;IACxD,MAAM,CAAC,EAAE,CAAM,YAA0C,EAAE,aAA2C;QAClG,OAAO,eAAQ,CAAC,KAAK,CAAC,CAAC,CAAA,GAAI,YAAa,OAAQ,aAAc,GAAG,EAAE,KAAK,EAAC,KAAK,EAAC,EAAE;YAC7E,MAAM,KAAK,GAAO,MAAM,KAAK,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;YACnD,MAAM,MAAM,GAAM,MAAM,KAAK,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;YAEpD,OAAO,KAAK,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC;QAC5B,CAAC,CAAC,CAAC;IACP,CAAC;IAQD,KAAK,CAAC,aAAa;QACf,OAAO,IAAI,CAAC,OAAO,CAAC,aAAa,EAAE,CAAC;IACxC,CAAC;IAED,QAAQ;QACJ,OAAO,uBAAwB,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAG,EAAE,CAAC;IAC9D,CAAC;CAoBJ;AAnDD,kCAmDC"}

package/lib/screenplay/models/PageElements.d.ts

@@ -1,15 +1,13 @@
-import { Answerable, List } from '@serenity-js/core';
+import { Answerable, List, MetaQuestion, Question } from '@serenity-js/core';
+import { Locator } from './Locator';
 import { PageElement } from './PageElement';
 import { Selector } from './selectors';
-export declare class PageElements<Native_Element_Type = any> extends List<PageElement<Native_Element_Type>> {
-    protected readonly selector: Answerable<Selector<unknown>>;
-    private readonly parent?;
-    static located<NET, ST>(selector: Answerable<Selector<ST>>): PageElements<NET>;
+export declare class PageElements<Native_Element_Type = any> extends List<PageElement<Native_Element_Type>> implements MetaQuestion<Answerable<PageElement<Native_Element_Type>>, Promise<Array<PageElement<Native_Element_Type>>>> {
+    protected readonly locator: Question<Promise<Locator<Native_Element_Type>>>;
+    static located<NET>(selector: Answerable<Selector>): PageElements<NET>;
     /**
-     * @param {Answerable<Selector<unknown>>} selector
-     * @param {Answerable<PageElement>} [parent]
-     *  if not specified, browser root selector is used
+     * @param locator
      */
-    constructor(selector: Answerable<Selector<unknown>>, parent?: Answerable<PageElement>);
+    constructor(locator: Question<Promise<Locator<Native_Element_Type>>>);
     of(parent: Answerable<PageElement<Native_Element_Type>>): PageElements<Native_Element_Type>;
 }

package/lib/screenplay/models/PageElements.js

@@ -6,20 +6,17 @@ const abilities_1 = require("../abilities");
 const f = (0, core_1.format)({ markQuestions: true });
 class PageElements extends core_1.List {
     /**
-     * @param {Answerable<Selector<unknown>>} selector
-     * @param {Answerable<PageElement>} [parent]
-     *  if not specified, browser root selector is used
+     * @param locator
      */
-    constructor(selector, parent) {
-        super(new PageElementCollection(selector, parent));
-        this.selector = selector;
-        this.parent = parent;
+    constructor(locator) {
+        super(allElementsOf(locator));
+        this.locator = locator;
     }
     static located(selector) {
-        return new PageElements(selector);
+        return new PageElements(relativeToDocumentRoot(selector));
     }
     of(parent) {
-        return new PageElements(this.selector, parent)
+        return new PageElements(relativeToParent(this.locator, parent))
             .describedAs(`<<${this.toString()}>>` + f `.of(${parent})`);
     }
 }
@@ -27,24 +24,29 @@ exports.PageElements = PageElements;
 /**
  * @package
  */
-class PageElementCollection extends core_1.Question {
-    constructor(selector, parent) {
-        super();
-        this.selector = selector;
-        this.parent = parent;
-        this.subject = `page elements located ${selector.toString()}`;
-    }
-    async answeredBy(actor) {
-        const bySelector = await actor.answer(this.selector);
-        const parent = await actor.answer(this.parent);
-        return abilities_1.BrowseTheWeb.as(actor).locateAll(bySelector, parent ? parent.nativeElementLocator() : undefined);
-    }
-    describedAs(subject) {
-        this.subject = subject;
-        return this;
-    }
-    toString() {
-        return this.subject;
-    }
+function relativeToDocumentRoot(selector) {
+    return core_1.Question.about(selector.toString(), async (actor) => {
+        const bySelector = await actor.answer(selector);
+        return abilities_1.BrowseTheWeb.as(actor).locate(bySelector);
+    });
+}
+/**
+ * @package
+ */
+function relativeToParent(relativeLocator, parent) {
+    return core_1.Question.about(relativeLocator.toString() + f `.of${parent}`, async (actor) => {
+        const locator = await actor.answer(relativeLocator);
+        const parentElement = await actor.answer(parent);
+        return locator.of(parentElement.locator);
+    });
+}
+/**
+ * @package
+ */
+function allElementsOf(locator) {
+    return core_1.Question.about(`page elements located ${locator.toString()}`, async (actor) => {
+        const resolved = await actor.answer(locator);
+        return resolved.allElements();
+    });
 }
 //# sourceMappingURL=PageElements.js.map

package/lib/screenplay/models/PageElements.js.map

@@ -1 +1 @@
-{"version":3,"file":"PageElements.js","sourceRoot":"","sources":["../../../src/screenplay/models/PageElements.ts"],"names":[],"mappings":";;;AAAA,4CAAwG;AAExG,4CAA4C;AAI5C,MAAM,CAAC,GAAG,IAAA,aAAM,EAAC,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;AAE1C,MAAa,YACT,SAAQ,WAAsC;IAM9C;;;;OAIG;IACH,YACuB,QAAuC,EACzC,MAAgC;QAEjD,KAAK,CAAC,IAAI,qBAAqB,CAAsB,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC;QAHrD,aAAQ,GAAR,QAAQ,CAA+B;QACzC,WAAM,GAAN,MAAM,CAA0B;IAGrD,CAAC;IAdD,MAAM,CAAC,OAAO,CAAU,QAAkC;QACtD,OAAO,IAAI,YAAY,CAAC,QAAQ,CAAC,CAAC;IACtC,CAAC;IAcD,EAAE,CAAC,MAAoD;QACnD,OAAO,IAAI,YAAY,CAAsB,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC;aAC9D,WAAW,CAAC,KAAK,IAAI,CAAC,QAAQ,EAAE,IAAI,GAAG,CAAC,CAAA,OAAQ,MAAO,GAAG,CAAC,CAAC;IACrE,CAAC;CACJ;AAvBD,oCAuBC;AAED;;GAEG;AACH,MAAM,qBACF,SAAQ,eAA0D;IAGlE,YACqB,QAAuC,EACvC,MAAgC;QAEjD,KAAK,EAAE,CAAC;QAHS,aAAQ,GAAR,QAAQ,CAA+B;QACvC,WAAM,GAAN,MAAM,CAA0B;QAGjD,IAAI,CAAC,OAAO,GAAG,yBAA0B,QAAQ,CAAC,QAAQ,EAAG,EAAE,CAAC;IACpE,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,KAAuC;QACpD,MAAM,UAAU,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACrD,MAAM,MAAM,GAAO,MAAM,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAEnD,OAAO,wBAAY,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,SAAS,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,oBAAoB,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAC5G,CAAC;IAED,WAAW,CAAC,OAAe;QACvB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,QAAQ;QACJ,OAAO,IAAI,CAAC,OAAO,CAAC;IACxB,CAAC;CACJ"}
+{"version":3,"file":"PageElements.js","sourceRoot":"","sources":["../../../src/screenplay/models/PageElements.ts"],"names":[],"mappings":";;;AAAA,4CAAqF;AAErF,4CAA4C;AAK5C,MAAM,CAAC,GAAG,IAAA,aAAM,EAAC,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;AAE1C,MAAa,YACT,SAAQ,WAAsC;IAO9C;;OAEG;IACH,YAA+B,OAAwD;QACnF,KAAK,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC;QADH,YAAO,GAAP,OAAO,CAAiD;IAEvF,CAAC;IATD,MAAM,CAAC,OAAO,CAAM,QAA8B;QAC9C,OAAO,IAAI,YAAY,CAAC,sBAAsB,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC9D,CAAC;IASD,EAAE,CAAC,MAAoD;QACnD,OAAO,IAAI,YAAY,CAAsB,gBAAgB,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;aAC/E,WAAW,CAAC,KAAK,IAAI,CAAC,QAAQ,EAAE,IAAI,GAAG,CAAC,CAAA,OAAQ,MAAO,GAAG,CAAC,CAAC;IACrE,CAAC;CACJ;AAnBD,oCAmBC;AAED;;GAEG;AACH,SAAS,sBAAsB,CAAsB,QAA8B;IAC/E,OAAO,eAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAC,KAAK,EAAC,EAAE;QACrD,MAAM,UAAU,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAChD,OAAO,wBAAY,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IACrD,CAAC,CAAC,CAAC;AACP,CAAC;AAED;;GAEG;AACH,SAAS,gBAAgB,CAAsB,eAAyD,EAAE,MAAoD;IAC1J,OAAO,eAAQ,CAAC,KAAK,CAAC,eAAe,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAA,MAAO,MAAO,EAAE,EAAE,KAAK,EAAC,KAAK,EAAC,EAAE;QAChF,MAAM,OAAO,GAA6C,MAAM,KAAK,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC;QAC9F,MAAM,aAAa,GAAuC,MAAM,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAErF,OAAO,OAAO,CAAC,EAAE,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;IAC7C,CAAC,CAAC,CAAC;AACP,CAAC;AAED;;GAEG;AACH,SAAS,aAAa,CAAsB,OAAwD;IAChG,OAAO,eAAQ,CAAC,KAAK,CAAC,yBAA0B,OAAO,CAAC,QAAQ,EAAG,EAAE,EAAE,KAAK,EAAC,KAAK,EAAC,EAAE;QACjF,MAAM,QAAQ,GAAiC,MAAM,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC3E,OAAO,QAAQ,CAAC,WAAW,EAAE,CAAC;IAClC,CAAC,CAAC,CAAC;AACP,CAAC"}

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

@@ -1,9 +1,8 @@
 export * from './Cookie';
 export * from './CookieData';
+export * from './Locator';
 export * from './ModalDialog';
-export * from './NativeElementLocator';
 export * from './Page';
 export * from './PageElement';
 export * from './PageElements';
-export * from './PassThroughNativeElementLocator';
 export * from './selectors';

package/lib/screenplay/models/index.js

@@ -12,11 +12,10 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./Cookie"), exports);
 __exportStar(require("./CookieData"), exports);
+__exportStar(require("./Locator"), exports);
 __exportStar(require("./ModalDialog"), exports);
-__exportStar(require("./NativeElementLocator"), exports);
 __exportStar(require("./Page"), exports);
 __exportStar(require("./PageElement"), exports);
 __exportStar(require("./PageElements"), exports);
-__exportStar(require("./PassThroughNativeElementLocator"), exports);
 __exportStar(require("./selectors"), exports);
 //# sourceMappingURL=index.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/screenplay/models/index.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,2CAAyB;AACzB,+CAA6B;AAC7B,gDAA8B;AAC9B,yDAAuC;AACvC,yCAAuB;AACvB,gDAA8B;AAC9B,iDAA+B;AAC/B,oEAAkD;AAClD,8CAA4B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/screenplay/models/index.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,2CAAyB;AACzB,+CAA6B;AAC7B,4CAA0B;AAC1B,gDAA8B;AAC9B,yCAAuB;AACvB,gDAA8B;AAC9B,iDAA+B;AAC/B,8CAA4B"}

package/lib/screenplay/models/selectors/ByCss.d.ts

@@ -1,3 +1,5 @@
 import { Selector } from './Selector';
-export declare class ByCss extends Selector<string> {
+export declare class ByCss extends Selector {
+    readonly value: string;
+    constructor(value: string);
 }

package/lib/screenplay/models/selectors/ByCss.js

@@ -3,6 +3,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ByCss = void 0;
 const Selector_1 = require("./Selector");
 class ByCss extends Selector_1.Selector {
+    constructor(value) {
+        super();
+        this.value = value;
+    }
 }
 exports.ByCss = ByCss;
 //# sourceMappingURL=ByCss.js.map

package/lib/screenplay/models/selectors/ByCss.js.map

@@ -1 +1 @@
-{"version":3,"file":"ByCss.js","sourceRoot":"","sources":["../../../../src/screenplay/models/selectors/ByCss.ts"],"names":[],"mappings":";;;AAAA,yCAAsC;AAEtC,MAAa,KAAM,SAAQ,mBAAgB;CAC1C;AADD,sBACC"}
+{"version":3,"file":"ByCss.js","sourceRoot":"","sources":["../../../../src/screenplay/models/selectors/ByCss.ts"],"names":[],"mappings":";;;AAAA,yCAAsC;AAEtC,MAAa,KAAM,SAAQ,mBAAQ;IAC/B,YAA4B,KAAa;QACrC,KAAK,EAAE,CAAC;QADgB,UAAK,GAAL,KAAK,CAAQ;IAEzC,CAAC;CACJ;AAJD,sBAIC"}

package/lib/screenplay/models/selectors/ByCssContainingText.d.ts

@@ -1,5 +1,6 @@
 import { Selector } from './Selector';
-export declare class ByCssContainingText extends Selector<string> {
+export declare class ByCssContainingText extends Selector {
+    readonly value: string;
     readonly text: string;
-    constructor(selector: string, text: string);
+    constructor(value: string, text: string);
 }

package/lib/screenplay/models/selectors/ByCssContainingText.js

@@ -3,8 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ByCssContainingText = void 0;
 const Selector_1 = require("./Selector");
 class ByCssContainingText extends Selector_1.Selector {
-    constructor(selector, text) {
-        super(selector);
+    constructor(value, text) {
+        super();
+        this.value = value;
         this.text = text;
     }
 }

package/lib/screenplay/models/selectors/ByCssContainingText.js.map

@@ -1 +1 @@
-{"version":3,"file":"ByCssContainingText.js","sourceRoot":"","sources":["../../../../src/screenplay/models/selectors/ByCssContainingText.ts"],"names":[],"mappings":";;;AAAA,yCAAsC;AAEtC,MAAa,mBAAoB,SAAQ,mBAAgB;IACrD,YAAY,QAAgB,EAAkB,IAAY;QACtD,KAAK,CAAC,QAAQ,CAAC,CAAC;QAD0B,SAAI,GAAJ,IAAI,CAAQ;IAE1D,CAAC;CACJ;AAJD,kDAIC"}
+{"version":3,"file":"ByCssContainingText.js","sourceRoot":"","sources":["../../../../src/screenplay/models/selectors/ByCssContainingText.ts"],"names":[],"mappings":";;;AAAA,yCAAsC;AAEtC,MAAa,mBAAoB,SAAQ,mBAAQ;IAC7C,YAA4B,KAAa,EAAkB,IAAY;QACnE,KAAK,EAAE,CAAC;QADgB,UAAK,GAAL,KAAK,CAAQ;QAAkB,SAAI,GAAJ,IAAI,CAAQ;IAEvE,CAAC;CACJ;AAJD,kDAIC"}

package/lib/screenplay/models/selectors/ById.d.ts

@@ -1,3 +1,5 @@
 import { Selector } from './Selector';
-export declare class ById extends Selector<string> {
+export declare class ById extends Selector {
+    readonly value: string;
+    constructor(value: string);
 }

package/lib/screenplay/models/selectors/ById.js

@@ -3,6 +3,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ById = void 0;
 const Selector_1 = require("./Selector");
 class ById extends Selector_1.Selector {
+    constructor(value) {
+        super();
+        this.value = value;
+    }
 }
 exports.ById = ById;
 //# sourceMappingURL=ById.js.map

package/lib/screenplay/models/selectors/ById.js.map

@@ -1 +1 @@
-{"version":3,"file":"ById.js","sourceRoot":"","sources":["../../../../src/screenplay/models/selectors/ById.ts"],"names":[],"mappings":";;;AAAA,yCAAsC;AAEtC,MAAa,IAAK,SAAQ,mBAAgB;CACzC;AADD,oBACC"}
+{"version":3,"file":"ById.js","sourceRoot":"","sources":["../../../../src/screenplay/models/selectors/ById.ts"],"names":[],"mappings":";;;AAAA,yCAAsC;AAEtC,MAAa,IAAK,SAAQ,mBAAQ;IAC9B,YAA4B,KAAa;QACrC,KAAK,EAAE,CAAC;QADgB,UAAK,GAAL,KAAK,CAAQ;IAEzC,CAAC;CACJ;AAJD,oBAIC"}

package/lib/screenplay/models/selectors/ByTagName.d.ts

@@ -1,3 +1,5 @@
 import { Selector } from './Selector';
-export declare class ByTagName extends Selector<string> {
+export declare class ByTagName extends Selector {
+    readonly value: string;
+    constructor(value: string);
 }

package/lib/screenplay/models/selectors/ByTagName.js

@@ -3,6 +3,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ByTagName = void 0;
 const Selector_1 = require("./Selector");
 class ByTagName extends Selector_1.Selector {
+    constructor(value) {
+        super();
+        this.value = value;
+    }
 }
 exports.ByTagName = ByTagName;
 //# sourceMappingURL=ByTagName.js.map

package/lib/screenplay/models/selectors/ByTagName.js.map

@@ -1 +1 @@
-{"version":3,"file":"ByTagName.js","sourceRoot":"","sources":["../../../../src/screenplay/models/selectors/ByTagName.ts"],"names":[],"mappings":";;;AAAA,yCAAsC;AAEtC,MAAa,SAAU,SAAQ,mBAAgB;CAC9C;AADD,8BACC"}
+{"version":3,"file":"ByTagName.js","sourceRoot":"","sources":["../../../../src/screenplay/models/selectors/ByTagName.ts"],"names":[],"mappings":";;;AAAA,yCAAsC;AAEtC,MAAa,SAAU,SAAQ,mBAAQ;IACnC,YAA4B,KAAa;QACrC,KAAK,EAAE,CAAC;QADgB,UAAK,GAAL,KAAK,CAAQ;IAEzC,CAAC;CACJ;AAJD,8BAIC"}

package/lib/screenplay/models/selectors/ByXPath.d.ts

@@ -1,3 +1,5 @@
 import { Selector } from './Selector';
-export declare class ByXPath extends Selector<string> {
+export declare class ByXPath extends Selector {
+    readonly value: string;
+    constructor(value: string);
 }

package/lib/screenplay/models/selectors/ByXPath.js

@@ -3,6 +3,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ByXPath = void 0;
 const Selector_1 = require("./Selector");
 class ByXPath extends Selector_1.Selector {
+    constructor(value) {
+        super();
+        this.value = value;
+    }
 }
 exports.ByXPath = ByXPath;
 //# sourceMappingURL=ByXPath.js.map

package/lib/screenplay/models/selectors/ByXPath.js.map

@@ -1 +1 @@
-{"version":3,"file":"ByXPath.js","sourceRoot":"","sources":["../../../../src/screenplay/models/selectors/ByXPath.ts"],"names":[],"mappings":";;;AAAA,yCAAsC;AAEtC,MAAa,OAAQ,SAAQ,mBAAgB;CAC5C;AADD,0BACC"}
+{"version":3,"file":"ByXPath.js","sourceRoot":"","sources":["../../../../src/screenplay/models/selectors/ByXPath.ts"],"names":[],"mappings":";;;AAAA,yCAAsC;AAEtC,MAAa,OAAQ,SAAQ,mBAAQ;IACjC,YAA4B,KAAa;QACrC,KAAK,EAAE,CAAC;QADgB,UAAK,GAAL,KAAK,CAAQ;IAEzC,CAAC;CACJ;AAJD,0BAIC"}

package/lib/screenplay/models/selectors/Selector.d.ts

@@ -1,5 +1,3 @@
-export declare abstract class Selector<T> {
-    readonly value: T;
-    constructor(value: T);
+export declare abstract class Selector {
     toString(): string;
 }

package/lib/screenplay/models/selectors/Selector.js

@@ -4,10 +4,8 @@ exports.Selector = void 0;
 const core_1 = require("@serenity-js/core");
 const f = (0, core_1.format)({ markQuestions: true });
 class Selector {
-    constructor(value) {
-        this.value = value;
-    }
     toString() {
+        // todo: strip anything preceding "By", like "WebdriverIOByCss|
         const selectorDescription = this.constructor.name.replace(/([a-z]+)([A-Z])/g, '$1 $2').toLowerCase();
         const parametersDescription = Object.keys(this).map(field => f `${this[field]}`).join(', ');
         return `${selectorDescription} (${parametersDescription})`;

package/lib/screenplay/models/selectors/Selector.js.map

@@ -1 +1 @@
-{"version":3,"file":"Selector.js","sourceRoot":"","sources":["../../../../src/screenplay/models/selectors/Selector.ts"],"names":[],"mappings":";;;AAAA,4CAA2C;AAE3C,MAAM,CAAC,GAAG,IAAA,aAAM,EAAC,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;AAE1C,MAAsB,QAAQ;IAE1B,YAA4B,KAAQ;QAAR,UAAK,GAAL,KAAK,CAAG;IACpC,CAAC;IAED,QAAQ;QACJ,MAAM,mBAAmB,GAAK,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,kBAAkB,EAAE,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC;QACvG,MAAM,qBAAqB,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAA,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAE3F,OAAO,GAAI,mBAAoB,KAAM,qBAAsB,GAAG,CAAC;IACnE,CAAC;CACJ;AAXD,4BAWC"}
+{"version":3,"file":"Selector.js","sourceRoot":"","sources":["../../../../src/screenplay/models/selectors/Selector.ts"],"names":[],"mappings":";;;AAAA,4CAA2C;AAE3C,MAAM,CAAC,GAAG,IAAA,aAAM,EAAC,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;AAE1C,MAAsB,QAAQ;IAE1B,QAAQ;QACJ,+DAA+D;QAC/D,MAAM,mBAAmB,GAAK,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,kBAAkB,EAAE,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC;QACvG,MAAM,qBAAqB,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAA,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAE3F,OAAO,GAAI,mBAAoB,KAAM,qBAAsB,GAAG,CAAC;IACnE,CAAC;CACJ;AATD,4BASC"}

package/lib/screenplay/questions/Text.d.ts

@@ -1,5 +1,5 @@
 import { Adapter, Answerable, MetaQuestion, Question } from '@serenity-js/core';
-import { PageElement } from '../models';
+import { PageElement, PageElements } from '../models';
 /**
  * @desc
  *  Resolves to the visible (i.e. not hidden by CSS) `innerText` of:
@@ -93,5 +93,6 @@ export declare class Text {
      *
      * @see {@link @serenity-js/core/lib/screenplay/questions~MetaQuestion}
      */
+    static ofAll(elements: PageElements): Question<Promise<string[]>> & MetaQuestion<Answerable<PageElement>, Promise<string[]>> & Adapter<string[]>;
     static ofAll(elements: Answerable<PageElement[]>): Question<Promise<string[]>> & Adapter<string[]>;
 }

package/lib/screenplay/questions/Text.js

@@ -89,17 +89,10 @@ class Text {
     static of(element) {
         return (0, core_1.createAdapter)(new TextOfSingleElement(element));
     }
-    /**
-     * @desc
-     *  Retrieves text of a group of {@link WebElement}s,
-     *  represented by Answerable<{@link @wdio/types~ElementList}>
-     *
-     * @param {Answerable<PageElement[]>} elements
-     * @returns {Question<Promise<string[]>> & MetaQuestion<Answerable<PageElement>, Promise<string[]>>}
-     *
-     * @see {@link @serenity-js/core/lib/screenplay/questions~MetaQuestion}
-     */
     static ofAll(elements) {
+        if (elements instanceof models_1.PageElements) {
+            return (0, core_1.createAdapter)(new TextOfMultipleElements(elements));
+        }
         return core_1.Question.about(f `the text of ${elements}`, async (actor) => {
             const pageElements = await actor.answer(elements);
             return (0, io_1.asyncMap)(pageElements, element => element.text());
@@ -120,4 +113,17 @@ class TextOfSingleElement extends ElementQuestion_1.ElementQuestion {
         return element.text();
     }
 }
+class TextOfMultipleElements extends ElementQuestion_1.ElementQuestion {
+    constructor(elements) {
+        super(f `the text of ${elements}`);
+        this.elements = elements;
+    }
+    of(parent) {
+        return new TextOfMultipleElements(this.elements.of(parent));
+    }
+    async answeredBy(actor) {
+        const elements = await actor.answer(this.elements);
+        return (0, io_1.asyncMap)(elements, element => element.text());
+    }
+}
 //# sourceMappingURL=Text.js.map

package/lib/screenplay/questions/Text.js.map

@@ -1 +1 @@
-{"version":3,"file":"Text.js","sourceRoot":"","sources":["../../../src/screenplay/questions/Text.ts"],"names":[],"mappings":";;;AAAA,4CAAwI;AACxI,iDAAoD;AAEpD,sCAAwC;AACxC,uDAAoD;AAEpD,MAAM,CAAC,GAAG,IAAA,aAAM,EAAC,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AACH,MAAa,IAAI;IAEb;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,CAAC,OAAgC;QAKtC,OAAO,IAAA,oBAAa,EAChB,IAAI,mBAAmB,CAAC,OAAO,CAAC,CACnC,CAAC;IACN,CAAC;IAED;;;;;;;;;OASG;IACH,MAAM,CAAC,KAAK,CAAC,QAAmC;QAC5C,OAAO,eAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,eAAgB,QAAS,EAAE,EAAE,KAAK,EAAC,KAAK,EAAC,EAAE;YAE/D,MAAM,YAAY,GAAkB,MAAM,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YAEjE,OAAO,IAAA,aAAQ,EAAC,YAAY,EAAE,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;QAC7D,CAAC,CAAC,CAAA;IACN,CAAC;CACJ;AAxCD,oBAwCC;AAED,MAAM,mBACF,SAAQ,iCAAgC;IAGxC,YAA6B,OAAgC;QACzD,KAAK,CAAC,eAAgB,OAAQ,EAAE,CAAC,CAAC;QADT,YAAO,GAAP,OAAO,CAAyB;IAE7D,CAAC;IAED,EAAE,CAAC,MAA+B;QAC9B,OAAO,IAAI,mBAAmB,CAAC,oBAAW,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;IACzE,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,KAAuC;QACpD,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAEjD,OAAO,OAAO,CAAC,IAAI,EAAE,CAAC;IAC1B,CAAC;CACJ"}
+{"version":3,"file":"Text.js","sourceRoot":"","sources":["../../../src/screenplay/questions/Text.ts"],"names":[],"mappings":";;;AAAA,4CAAwI;AACxI,iDAAoD;AAEpD,sCAAsD;AACtD,uDAAoD;AAEpD,MAAM,CAAC,GAAG,IAAA,aAAM,EAAC,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AACH,MAAa,IAAI;IAEb;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,CAAC,OAAgC;QAKtC,OAAO,IAAA,oBAAa,EAChB,IAAI,mBAAmB,CAAC,OAAO,CAAC,CACnC,CAAC;IACN,CAAC;IAcD,MAAM,CAAC,KAAK,CAAC,QAAkD;QAC3D,IAAI,QAAQ,YAAY,qBAAY,EAAE;YAClC,OAAO,IAAA,oBAAa,EAChB,IAAI,sBAAsB,CAAC,QAAQ,CAAC,CACvC,CAAC;SACL;QAED,OAAO,eAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,eAAgB,QAAS,EAAE,EAAE,KAAK,EAAC,KAAK,EAAC,EAAE;YAC/D,MAAM,YAAY,GAAkB,MAAM,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YAEjE,OAAO,IAAA,aAAQ,EAAC,YAAY,EAAE,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;QAC7D,CAAC,CAAC,CAAC;IACP,CAAC;CACJ;AA/CD,oBA+CC;AAED,MAAM,mBACF,SAAQ,iCAAgC;IAGxC,YAA6B,OAAgC;QACzD,KAAK,CAAC,eAAgB,OAAQ,EAAE,CAAC,CAAC;QADT,YAAO,GAAP,OAAO,CAAyB;IAE7D,CAAC;IAED,EAAE,CAAC,MAA+B;QAC9B,OAAO,IAAI,mBAAmB,CAAC,oBAAW,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;IACzE,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,KAAuC;QACpD,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAEjD,OAAO,OAAO,CAAC,IAAI,EAAE,CAAC;IAC1B,CAAC;CACJ;AAED,MAAM,sBACF,SAAQ,iCAAkC;IAG1C,YAA6B,QAAsB;QAC/C,KAAK,CAAC,CAAC,CAAC,eAAgB,QAAS,EAAE,CAAC,CAAC;QADZ,aAAQ,GAAR,QAAQ,CAAc;IAEnD,CAAC;IAED,EAAE,CAAC,MAA+B;QAC9B,OAAO,IAAI,sBAAsB,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;IAChE,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,KAAuC;QACpD,MAAM,QAAQ,GAAkB,MAAM,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAElE,OAAO,IAAA,aAAQ,EAAC,QAAQ,EAAE,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IACzD,CAAC;CACJ"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serenity-js/web",
-  "version": "3.0.0-rc.4",
+  "version": "3.0.0-rc.5",
   "description": "Serenity/JS Screenplay Pattern APIs for the Web",
   "author": {
     "name": "Jan Molak",
@@ -46,8 +46,8 @@
     "npm": "^6 || ^7"
   },
   "dependencies": {
-    "@serenity-js/assertions": "3.0.0-rc.4",
-    "@serenity-js/core": "3.0.0-rc.4",
+    "@serenity-js/assertions": "3.0.0-rc.5",
+    "@serenity-js/core": "3.0.0-rc.5",
     "tiny-types": "^1.17.0"
   },
   "devDependencies": {
@@ -81,5 +81,5 @@
     "cache": true,
     "all": true
   },
-  "gitHead": "126a1cad42bcb1416ca68e62f54bf0d3eb3ea157"
+  "gitHead": "b63bb1465731d922fde0ade3b77ddebb96dbf990"
 }

package/src/screenplay/abilities/BrowseTheWeb.ts

@@ -1,10 +1,12 @@
-import { Ability, Duration, UsesAbilities } from '@serenity-js/core';
+import { Ability, Duration, format, LogicError, UsesAbilities } from '@serenity-js/core';
 
 import { Key } from '../../input';
-import { Cookie, CookieData, ModalDialog, NativeElementLocator, Page, PageElement, Selector } from '../models';
+import { Cookie, CookieData, Locator, ModalDialog, Page, PageElement, Selector } from '../models';
 import { BrowserCapabilities } from './BrowserCapabilities';
 
-export abstract class BrowseTheWeb<Native_Element_Type = any> implements Ability {
+const f = format({ markQuestions: true });
+
+export abstract class BrowseTheWeb<Native_Element_Type = any, Native_Root_Element_Type = unknown> implements Ability {
     /**
      * @desc
      *  Used to access the Actor's ability to {@link BrowseTheWeb}
@@ -14,8 +16,17 @@ export abstract class BrowseTheWeb<Native_Element_Type = any> implements Ability
      * @param {@serenity-js/core/lib/screenplay/actor~UsesAbilities} actor
      * @return {BrowseTheWeb}
      */
-    static as(actor: UsesAbilities): BrowseTheWeb {
-        return actor.abilityTo(BrowseTheWeb);
+    static as<NET = any, NRET = unknown>(actor: UsesAbilities): BrowseTheWeb<NET, NRET> {
+        return actor.abilityTo(BrowseTheWeb) as BrowseTheWeb<NET, NRET>;
+    }
+
+    constructor(
+        protected locators: Map<
+        new (...args: unknown[]) => Selector,
+        (selector: Selector) =>
+        Locator<Native_Element_Type, Native_Root_Element_Type>
+        >
+    ) {
     }
 
     abstract navigateTo(destination: string): Promise<void>;
@@ -30,9 +41,15 @@ export abstract class BrowseTheWeb<Native_Element_Type = any> implements Ability
 
     abstract waitUntil(condition: () => boolean | Promise<boolean>, timeout: Duration): Promise<void>;
 
-    abstract locate<T>(selector: Selector<T>, locator?: NativeElementLocator<Native_Element_Type>): PageElement<Native_Element_Type>;
-    abstract locateAll<T>(selector: Selector<T>, locator?: NativeElementLocator<Native_Element_Type>): Promise<Array<PageElement<Native_Element_Type>>>;
-    abstract nativeElementLocator(): NativeElementLocator<Native_Element_Type>;
+    locate(selector: Selector): Locator<Native_Element_Type, Native_Root_Element_Type> {
+        for (const [ type, locatorFactory ] of this.locators) {
+            if (selector instanceof type) {
+                return locatorFactory(selector);
+            }
+        }
+
+        throw new LogicError(f `${ selector } is not supported by ${ this.constructor.name }`);
+    }
 
     abstract browserCapabilities(): Promise<BrowserCapabilities>;
 

package/src/screenplay/interactions/Press.ts

@@ -121,7 +121,6 @@ class PressKeyInField extends PageElementInteraction {
         const keys  = await actor.answer(this.keys);
 
         // fix for protractor
-        // todo: should this wait on focus to occur?
         await BrowseTheWeb.as(actor).executeScript(
             /* istanbul ignore next */
             function focus(element: any) {

package/src/screenplay/models/Locator.ts

@@ -0,0 +1,25 @@
+import { PageElement } from './PageElement';
+import { Selector } from './selectors';
+
+export abstract class Locator<Native_Element_Type, Native_Root_Element_Type = any, Selector_Type extends Selector = Selector> {
+    constructor(
+        protected readonly parentRoot: () => Promise<Native_Root_Element_Type> | Native_Root_Element_Type,
+        protected readonly selector: Selector_Type,
+        protected readonly locateElement: (root: Native_Root_Element_Type) => Promise<Native_Element_Type> | Native_Element_Type,
+        protected readonly locateAllElements: (root: Native_Root_Element_Type) => Promise<Array<Native_Element_Type>> | Array<Native_Element_Type>,
+    ) {
+    }
+
+    public async nativeElement(): Promise<Native_Element_Type> {
+        return this.locateElement(await this.parentRoot());
+    }
+
+    abstract of(parent: Locator<Native_Element_Type, Native_Root_Element_Type>): Locator<Native_Element_Type, Native_Root_Element_Type>;
+
+    abstract element(): PageElement<Native_Element_Type>;
+    abstract allElements(): Promise<Array<PageElement<Native_Element_Type>>>;
+
+    toString(): string {
+        return this.selector.toString();
+    }
+}

package/src/screenplay/models/PageElement.ts

@@ -1,20 +1,22 @@
-import { Adapter, Answerable, format, LogicError, Question } from '@serenity-js/core';
+import { Adapter, Answerable, format, Question } from '@serenity-js/core';
+import { ensure, isDefined } from 'tiny-types';
 
 import { BrowseTheWeb } from '../abilities';
-import { NativeElementLocator } from './NativeElementLocator';
+import { Locator } from './Locator';
 import { Selector } from './selectors';
 
 const d = format({ markQuestions: false });
 
 export abstract class PageElement<Native_Element_Type = any> {
 
-    static located<NET, ST>(selector: Answerable<Selector<ST>>): Question<Promise<PageElement<NET>>> & Adapter<PageElement<NET>> {
+    static located<NET>(selector: Answerable<Selector>): Question<Promise<PageElement<NET>>> & Adapter<PageElement<NET>> {
         return Question.about(d`page element located ${ selector }`, async actor => {
             const bySelector = await actor.answer(selector);
-            return BrowseTheWeb.as(actor).locate<ST>(bySelector);
+            return BrowseTheWeb.as<NET>(actor).locate(bySelector).element();
         });
     }
 
+    // todo: review usages and consider removing if not used
     static of<NET>(childElement: Answerable<PageElement<NET>>, parentElement: Answerable<PageElement<NET>>): Question<Promise<PageElement<NET>>> & Adapter<PageElement<NET>> {
         return Question.about(d`${ childElement } of ${ parentElement })`, async actor => {
             const child     = await actor.answer(childElement);
@@ -24,29 +26,18 @@ export abstract class PageElement<Native_Element_Type = any> {
         });
     }
 
-    constructor(
-        protected readonly selector: Selector<unknown>,
-        private readonly locator: NativeElementLocator<Native_Element_Type>,
-    ) {
+    constructor(public readonly locator: Locator<Native_Element_Type>) {
+        ensure('native element locator', locator, isDefined());
     }
 
-    abstract of(parent: PageElement<Native_Element_Type>): PageElement<Native_Element_Type>;
+    abstract of(parentElement: PageElement<Native_Element_Type>): PageElement<Native_Element_Type>;
 
     async nativeElement(): Promise<Native_Element_Type> {
-        try {
-            return this.locator.locate(this.selector);
-        }
-        catch (error) {
-            throw new LogicError(`Couldn't find element`, error);
-        }
-    }
-
-    nativeElementLocator(): NativeElementLocator<Native_Element_Type> {
-        return this.locator;
+        return this.locator.nativeElement();
     }
 
     toString(): string {
-        return `PageElement located ${ this.selector }`
+        return `PageElement located ${ this.locator.toString() }`;
     }
 
     abstract enterValue(value: string | number | Array<string | number>): Promise<void>;

package/src/screenplay/models/PageElements.ts

@@ -1,6 +1,7 @@
-import { Answerable, AnswersQuestions, format, List, Question, UsesAbilities } from '@serenity-js/core';
+import { Answerable, format, List, MetaQuestion, Question } from '@serenity-js/core';
 
 import { BrowseTheWeb } from '../abilities';
+import { Locator } from './Locator';
 import { PageElement } from './PageElement';
 import { Selector } from './selectors';
 
@@ -8,25 +9,21 @@ const f = format({ markQuestions: true });
 
 export class PageElements<Native_Element_Type = any>
     extends List<PageElement<Native_Element_Type>>
+    implements MetaQuestion<Answerable<PageElement<Native_Element_Type>>, Promise<Array<PageElement<Native_Element_Type>>>>
 {
-    static located<NET, ST>(selector: Answerable<Selector<ST>>): PageElements<NET> {
-        return new PageElements(selector);
+    static located<NET>(selector: Answerable<Selector>): PageElements<NET> {
+        return new PageElements(relativeToDocumentRoot(selector));
     }
 
     /**
-     * @param {Answerable<Selector<unknown>>} selector
-     * @param {Answerable<PageElement>} [parent]
-     *  if not specified, browser root selector is used
+     * @param locator
      */
-    constructor(
-        protected readonly selector: Answerable<Selector<unknown>>,
-        private readonly parent?: Answerable<PageElement>
-    ) {
-        super(new PageElementCollection<Native_Element_Type>(selector, parent));
+    constructor(protected readonly locator: Question<Promise<Locator<Native_Element_Type>>>) {
+        super(allElementsOf(locator));
     }
 
     of(parent: Answerable<PageElement<Native_Element_Type>>): PageElements<Native_Element_Type> {
-        return new PageElements<Native_Element_Type>(this.selector, parent)
+        return new PageElements<Native_Element_Type>(relativeToParent(this.locator, parent))
             .describedAs(`<<${this.toString()}>>` + f`.of(${ parent })`);
     }
 }
@@ -34,31 +31,31 @@ export class PageElements<Native_Element_Type = any>
 /**
  * @package
  */
-class PageElementCollection<Native_Element_Type = any>
-    extends Question<Promise<Array<PageElement<Native_Element_Type>>>>
-{
-    private subject: string;
-    constructor(
-        private readonly selector: Answerable<Selector<unknown>>,
-        private readonly parent?: Answerable<PageElement>,
-    ) {
-        super();
-        this.subject = `page elements located ${ selector.toString() }`;
-    }
-
-    async answeredBy(actor: AnswersQuestions & UsesAbilities): Promise<Array<PageElement<Native_Element_Type>>> {
-        const bySelector = await actor.answer(this.selector);
-        const parent     = await actor.answer(this.parent);
+function relativeToDocumentRoot<Native_Element_Type>(selector: Answerable<Selector>): Question<Promise<Locator<Native_Element_Type>>> {
+    return Question.about(selector.toString(), async actor => {
+        const bySelector = await actor.answer(selector);
+        return BrowseTheWeb.as(actor).locate(bySelector);
+    });
+}
 
-        return BrowseTheWeb.as(actor).locateAll(bySelector, parent ? parent.nativeElementLocator() : undefined);
-    }
+/**
+ * @package
+ */
+function relativeToParent<Native_Element_Type>(relativeLocator: Answerable<Locator<Native_Element_Type>>, parent: Answerable<PageElement<Native_Element_Type>>): Question<Promise<Locator<Native_Element_Type>>> {
+    return Question.about(relativeLocator.toString() + f`.of${ parent }`, async actor => {
+        const locator: Locator<Native_Element_Type>             = await actor.answer(relativeLocator);
+        const parentElement: PageElement<Native_Element_Type>   = await actor.answer(parent);
 
-    describedAs(subject: string): this {
-        this.subject = subject;
-        return this;
-    }
+        return locator.of(parentElement.locator);
+    });
+}
 
-    toString(): string {
-        return this.subject;
-    }
+/**
+ * @package
+ */
+function allElementsOf<Native_Element_Type>(locator: Question<Promise<Locator<Native_Element_Type>>>): Question<Promise<Array<PageElement<Native_Element_Type>>>> {
+    return Question.about(`page elements located ${ locator.toString() }`, async actor => {
+        const resolved: Locator<Native_Element_Type> = await actor.answer(locator);
+        return resolved.allElements();
+    });
 }

package/src/screenplay/models/index.ts

@@ -1,9 +1,8 @@
 export * from './Cookie';
 export * from './CookieData';
+export * from './Locator';
 export * from './ModalDialog';
-export * from './NativeElementLocator';
 export * from './Page';
 export * from './PageElement';
 export * from './PageElements';
-export * from './PassThroughNativeElementLocator';
 export * from './selectors';

package/src/screenplay/models/selectors/ByCss.ts

@@ -1,4 +1,7 @@
 import { Selector } from './Selector';
 
-export class ByCss extends Selector<string> {
+export class ByCss extends Selector {
+    constructor(public readonly value: string) {
+        super();
+    }
 }

package/src/screenplay/models/selectors/ByCssContainingText.ts

@@ -1,7 +1,7 @@
 import { Selector } from './Selector';
 
-export class ByCssContainingText extends Selector<string> {
-    constructor(selector: string, public readonly text: string) {
-        super(selector);
+export class ByCssContainingText extends Selector {
+    constructor(public readonly value: string, public readonly text: string) {
+        super();
     }
 }

package/src/screenplay/models/selectors/ById.ts

@@ -1,4 +1,7 @@
 import { Selector } from './Selector';
 
-export class ById extends Selector<string> {
+export class ById extends Selector {
+    constructor(public readonly value: string) {
+        super();
+    }
 }

package/src/screenplay/models/selectors/ByTagName.ts

@@ -1,4 +1,7 @@
 import { Selector } from './Selector';
 
-export class ByTagName extends Selector<string> {
+export class ByTagName extends Selector {
+    constructor(public readonly value: string) {
+        super();
+    }
 }

package/src/screenplay/models/selectors/ByXPath.ts

@@ -1,4 +1,7 @@
 import { Selector } from './Selector';
 
-export class ByXPath extends Selector<string> {
+export class ByXPath extends Selector {
+    constructor(public readonly value: string) {
+        super();
+    }
 }

package/src/screenplay/models/selectors/Selector.ts

@@ -2,12 +2,10 @@ import { format } from '@serenity-js/core';
 
 const f = format({ markQuestions: true });
 
-export abstract class Selector<T> {
-
-    constructor(public readonly value: T) {
-    }
+export abstract class Selector {
 
     toString(): string {
+        // todo: strip anything preceding "By", like "WebdriverIOByCss|
         const selectorDescription   = this.constructor.name.replace(/([a-z]+)([A-Z])/g, '$1 $2').toLowerCase();
         const parametersDescription = Object.keys(this).map(field => f`${this[field]}`).join(', ');
 

package/src/screenplay/questions/Text.ts

@@ -1,7 +1,7 @@
 import { Adapter, Answerable, AnswersQuestions, createAdapter, format, MetaQuestion, Question, UsesAbilities } from '@serenity-js/core';
 import { asyncMap } from '@serenity-js/core/lib/io';
 
-import { PageElement } from '../models';
+import { PageElement, PageElements } from '../models';
 import { ElementQuestion } from './ElementQuestion';
 
 const f = format({ markQuestions: false });
@@ -107,13 +107,20 @@ export class Text {
      *
      * @see {@link @serenity-js/core/lib/screenplay/questions~MetaQuestion}
      */
-    static ofAll(elements: Answerable<PageElement[]>): Question<Promise<string[]>> & Adapter<string[]> {
-        return Question.about(f `the text of ${ elements }`, async actor => {
+    static ofAll(elements: PageElements): Question<Promise<string[]>> & MetaQuestion<Answerable<PageElement>, Promise<string[]>> & Adapter<string[]>
+    static ofAll(elements: Answerable<PageElement[]>): Question<Promise<string[]>> & Adapter<string[]>
+    static ofAll(elements: PageElements | Answerable<PageElement[]>): Question<Promise<string[]>> & Adapter<string[]> {
+        if (elements instanceof PageElements) {
+            return createAdapter<Promise<string[]>, ElementQuestion<Promise<string[]>> & MetaQuestion<Answerable<PageElement>, Promise<string[]>>>(
+                new TextOfMultipleElements(elements)
+            );
+        }
 
+        return Question.about(f `the text of ${ elements }`, async actor => {
             const pageElements: PageElement[] = await actor.answer(elements);
 
             return asyncMap(pageElements, element => element.text());
-        })
+        });
     }
 }
 
@@ -135,3 +142,22 @@ class TextOfSingleElement
         return element.text();
     }
 }
+
+class TextOfMultipleElements
+    extends ElementQuestion<Promise<string[]>>
+    implements MetaQuestion<Answerable<PageElement>, Promise<string[]>>
+{
+    constructor(private readonly elements: PageElements) {
+        super(f `the text of ${ elements }`);
+    }
+
+    of(parent: Answerable<PageElement>): Question<Promise<string[]>> {
+        return new TextOfMultipleElements(this.elements.of(parent));
+    }
+
+    async answeredBy(actor: AnswersQuestions & UsesAbilities): Promise<string[]> {
+        const elements: PageElement[] = await actor.answer(this.elements);
+
+        return asyncMap(elements, element => element.text());
+    }
+}

package/lib/screenplay/models/NativeElementLocator.d.ts

@@ -1,5 +0,0 @@
-import { Selector } from './selectors';
-export interface NativeElementLocator<Native_Element_Type> {
-    locate<T>(selector: Selector<T>): Promise<Native_Element_Type>;
-    locateAll<T>(selector: Selector<T>): Promise<Native_Element_Type[]>;
-}

package/lib/screenplay/models/NativeElementLocator.js

@@ -1,3 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=NativeElementLocator.js.map

package/lib/screenplay/models/NativeElementLocator.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"NativeElementLocator.js","sourceRoot":"","sources":["../../../src/screenplay/models/NativeElementLocator.ts"],"names":[],"mappings":""}

package/lib/screenplay/models/PassThroughNativeElementLocator.d.ts

@@ -1,9 +0,0 @@
-import { NativeElementLocator } from './NativeElementLocator';
-import { Selector } from './selectors';
-export declare class PassThroughNativeElementLocator<Native_Element_Type = any> implements NativeElementLocator<Native_Element_Type> {
-    private readonly locator;
-    private readonly element;
-    constructor(locator: NativeElementLocator<Native_Element_Type>, element: Native_Element_Type);
-    locate<T>(selector: Selector<T>): Promise<Native_Element_Type>;
-    locateAll<T>(selector: Selector<T>): Promise<Native_Element_Type[]>;
-}

package/lib/screenplay/models/PassThroughNativeElementLocator.js

@@ -1,17 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.PassThroughNativeElementLocator = void 0;
-class PassThroughNativeElementLocator {
-    constructor(locator, element) {
-        this.locator = locator;
-        this.element = element;
-    }
-    async locate(selector) {
-        return this.element;
-    }
-    locateAll(selector) {
-        return this.locator.locateAll(selector);
-    }
-}
-exports.PassThroughNativeElementLocator = PassThroughNativeElementLocator;
-//# sourceMappingURL=PassThroughNativeElementLocator.js.map

package/lib/screenplay/models/PassThroughNativeElementLocator.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"PassThroughNativeElementLocator.js","sourceRoot":"","sources":["../../../src/screenplay/models/PassThroughNativeElementLocator.ts"],"names":[],"mappings":";;;AAGA,MAAa,+BAA+B;IACxC,YACqB,OAAkD,EAClD,OAA4B;QAD5B,YAAO,GAAP,OAAO,CAA2C;QAClD,YAAO,GAAP,OAAO,CAAqB;IAEjD,CAAC;IAED,KAAK,CAAC,MAAM,CAAI,QAAqB;QACjC,OAAO,IAAI,CAAC,OAAO,CAAC;IACxB,CAAC;IAED,SAAS,CAAI,QAAqB;QAC9B,OAAO,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IAC5C,CAAC;CACJ;AAdD,0EAcC"}

package/src/screenplay/models/NativeElementLocator.ts

@@ -1,6 +0,0 @@
-import { Selector } from './selectors';
-
-export interface NativeElementLocator<Native_Element_Type> {
-    locate<T>(selector: Selector<T>): Promise<Native_Element_Type>;
-    locateAll<T>(selector: Selector<T>): Promise<Native_Element_Type[]>;
-}

package/src/screenplay/models/PassThroughNativeElementLocator.ts

@@ -1,18 +0,0 @@
-import { NativeElementLocator } from './NativeElementLocator';
-import { Selector } from './selectors';
-
-export class PassThroughNativeElementLocator<Native_Element_Type = any> implements NativeElementLocator<Native_Element_Type> {
-    constructor(
-        private readonly locator: NativeElementLocator<Native_Element_Type>,
-        private readonly element: Native_Element_Type
-    ) {
-    }
-
-    async locate<T>(selector: Selector<T>): Promise<Native_Element_Type> {
-        return this.element;
-    }
-
-    locateAll<T>(selector: Selector<T>): Promise<Native_Element_Type[]> {
-        return this.locator.locateAll(selector);
-    }
-}