@serenity-js/web 3.0.0-rc.0

package/lib/screenplay/questions/Attribute.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Attribute = void 0;
+const core_1 = require("@serenity-js/core");
+const models_1 = require("../models");
+const ElementQuestion_1 = require("./ElementQuestion");
+/**
+ * @desc
+ *  Returns the value of the given HTML attribute of a given {@link WebElement},
+ *  represented by Answerable<{@link @wdio/types~Element}>
+ *
+ * @example <caption>Example widget</caption>
+ *  <ul id="shopping-list" data-items-left="2">
+ *    <li data-state="bought">Coffee<li>
+ *    <li data-state="buy">Honey<li>
+ *    <li data-state="buy">Chocolate<li>
+ *  </ul>
+ *
+ * @example <caption>Retrieve a HTML attribute of a given WebElement</caption>
+ *  import { actorCalled } from '@serenity-js/core';
+ *  import { Ensure, equals } from '@serenity-js/assertions';
+ *  import { Attribute, by, BrowseTheWeb, Target } from '@serenity-js/webdriverio';
+ *
+ *  const shoppingList = () =>
+ *      Target.the('shopping list').located(by.id('shopping-list'))
+ *
+ *  actorCalled('Lisa')
+ *      .whoCan(BrowseTheWeb.using(browser))
+ *      .attemptsTo(
+ *          Ensure.that(Attribute.called('data-items-left').of(shoppingList()), equals('2')),
+ *      )
+ *
+ * @example <caption>Find WebElements with a given attribute</caption>
+ *  import { actorCalled } from '@serenity-js/core';
+ *  import { Ensure, includes } from '@serenity-js/assertions';
+ *  import { Attribute, BrowseTheWeb, by, Target } from '@serenity-js/webdriverio';
+ *
+ *  class ShoppingList {
+ *      static items = () =>
+ *          Target.all('items')
+ *              .located(by.css('#shopping-list li'))
+ *
+ *      static outstandingItems = () =>
+ *          ShoppingList.items
+ *              .where(Attribute.called('data-state'), includes('buy'))
+ *  }
+ *
+ *  actorCalled('Lisa')
+ *      .whoCan(BrowseTheWeb.using(browser))
+ *      .attemptsTo(
+ *          Ensure.that(
+ *              Text.ofAll(ShoppingList.outstandingItems()),
+ *              equals([ 'Honey', 'Chocolate' ])
+ *          ),
+ *      )
+ *
+ * @extends {ElementQuestion}
+ * @implements {@serenity-js/core/lib/screenplay/questions~MetaQuestion}
+ */
+class Attribute extends ElementQuestion_1.ElementQuestion {
+    /**
+     * @param {Answerable<string>} name
+     * @param {@serenity-js/core/lib/screenplay~Answerable<Element>} [element]
+     */
+    constructor(name, element) {
+        super(`"${name}" attribute of ${element}`);
+        this.name = name;
+        this.element = element;
+    }
+    /**
+     * @param {Answerable<string>} name
+     * @returns {Attribute}
+     */
+    static called(name) {
+        return new Attribute(name);
+    }
+    /**
+     * @desc
+     *  Resolves to the value of a HTML attribute of the `target` element,
+     *  located in the context of a `parent` element.
+     *
+     * @param {Answerable<PageElement>} parent
+     * @returns {Question<Promise<string[]>>}
+     *
+     * @see {@link Target.all}
+     * @see {@link @serenity-js/core/lib/screenplay/questions~MetaQuestion}
+     */
+    of(parent) {
+        return new Attribute(this.name, this.element
+            ? models_1.PageElement.of(this.element, parent)
+            : parent);
+    }
+    async answeredBy(actor) {
+        if (!this.element) {
+            throw new core_1.LogicError(`Target not specified`); // todo: better error message?
+        }
+        const element = await actor.answer(this.element);
+        const name = await actor.answer(this.name);
+        return element.attribute(name);
+    }
+}
+exports.Attribute = Attribute;
+//# sourceMappingURL=Attribute.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Attribute.js","sourceRoot":"","sources":["../../../src/screenplay/questions/Attribute.ts"],"names":[],"mappings":";;;AAAA,4CAAoH;AAEpH,sCAAwC;AACxC,uDAAoD;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,MAAa,SACT,SAAQ,iCAAgC;IAWxC;;;OAGG;IACH,YACqB,IAAwB,EACxB,OAAiC;QAElD,KAAK,CAAC,IAAK,IAAK,kBAAmB,OAAQ,EAAE,CAAC,CAAC;QAH9B,SAAI,GAAJ,IAAI,CAAoB;QACxB,YAAO,GAAP,OAAO,CAA0B;IAGtD,CAAC;IAjBD;;;OAGG;IACH,MAAM,CAAC,MAAM,CAAC,IAAwB;QAClC,OAAO,IAAI,SAAS,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;IAaD;;;;;;;;;;OAUG;IACH,EAAE,CAAC,MAA+B;QAC9B,OAAO,IAAI,SAAS,CAChB,IAAI,CAAC,IAAI,EACT,IAAI,CAAC,OAAO;YACR,CAAC,CAAC,oBAAW,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC;YACtC,CAAC,CAAC,MAAM,CACf,CAAC;IACN,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,KAAuC;QACpD,IAAI,CAAE,IAAI,CAAC,OAAO,EAAE;YAChB,MAAM,IAAI,iBAAU,CAAC,sBAAsB,CAAC,CAAC,CAAG,8BAA8B;SACjF;QAED,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACjD,MAAM,IAAI,GAAM,MAAM,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAE9C,OAAO,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC;CACJ;AArDD,8BAqDC"}

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

@@ -0,0 +1,93 @@
+import { Answerable, AnswersQuestions, MetaQuestion, Question, UsesAbilities } from '@serenity-js/core';
+import { PageElement } from '../models';
+import { ElementQuestion } from './ElementQuestion';
+/**
+ * @desc
+ *  Resolves to an array of [CSS classes](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes#attr-class)
+ *  of a given {@link WebElement}, represented by Answerable<{@link @wdio/types~Element}>.
+ *
+ * @example <caption>Example widget</caption>
+ *  <ul id="shopping-list" class="active favourite">
+ *    <li class="bought">Coffee<li>
+ *    <li class="buy">Honey<li>
+ *    <li class="buy">Chocolate<li>
+ *  </ul>
+ *
+ * @example <caption>Retrieve CSS classes of a given WebElement</caption>
+ *  import { actorCalled } from '@serenity-js/core';
+ *  import { Ensure, equals } from '@serenity-js/assertions';
+ *  import { BrowseTheWeb, by, CssClasses, Target } from '@serenity-js/webdriverio';
+ *
+ *  const shoppingList = () =>
+ *      Target.the('shopping list').located(by.id('shopping-list'))
+ *
+ *  actorCalled('Lisa')
+ *      .whoCan(BrowseTheWeb.using(browser))
+ *      .attemptsTo(
+ *          Ensure.that(CssClasses.of(shoppingList()), equals([ 'active', 'favourite' ])),
+ *      )
+ *
+ * @example <caption>Find WebElements with a given class</caption>
+ *  import { actorCalled } from '@serenity-js/core';
+ *  import { Ensure, contain } from '@serenity-js/assertions';
+ *  import { BrowseTheWeb, by, CssClasses, Target } from '@serenity-js/webdriverio';
+ *
+ *  class ShoppingList {
+ *      static items = () =>
+ *          Target.all('items')
+ *              .located(by.css('#shopping-list li'))
+ *
+ *      static outstandingItems = () =>
+ *          ShoppingList.items
+ *              .where(CssClasses, contain('buy'))
+ *  }
+ *
+ *  actorCalled('Lisa')
+ *      .whoCan(BrowseTheWeb.using(browser))
+ *      .attemptsTo(
+ *          Ensure.that(
+ *              Text.ofAll(ShoppingList.outstandingItems()),
+ *              equals([ 'Honey', 'Chocolate' ])
+ *          ),
+ *      )
+ *
+ * @extends {ElementQuestion}
+ * @implements {@serenity-js/core/lib/screenplay/questions~MetaQuestion}
+ */
+export declare class CssClasses extends ElementQuestion<Promise<string[]>> implements MetaQuestion<Answerable<PageElement>, Promise<string[]>> {
+    private readonly target;
+    /**
+     * @param {Question<PageElement> | PageElement} target
+     * @returns {CssClasses}
+     */
+    static of(target: Answerable<PageElement>): CssClasses;
+    /**
+     * @param {Question<PageElement> | PageElement} target
+     */
+    constructor(target: Answerable<PageElement>);
+    /**
+     * @desc
+     *  Resolves to an array of CSS classes of the `target` element,
+     *  located in the context of a `parent` element.
+     *
+     * @param {@serenity-js/core/lib/screenplay~Answerable<Element>} parent
+     * @returns {Question<Promise<string[]>>}
+     *
+     * @see {@link Target.all}
+     * @see {@link @serenity-js/core/lib/screenplay/questions~MetaQuestion}
+     */
+    of(parent: Answerable<PageElement>): Question<Promise<string[]>>;
+    /**
+     * @desc
+     *  Makes the provided {@link @serenity-js/core/lib/screenplay/actor~Actor}
+     *  answer this {@link @serenity-js/core/lib/screenplay~Question}.
+     *
+     * @param {AnswersQuestions & UsesAbilities} actor
+     * @returns {Promise<void>}
+     *
+     * @see {@link @serenity-js/core/lib/screenplay/actor~Actor}
+     * @see {@link @serenity-js/core/lib/screenplay/actor~AnswersQuestions}
+     * @see {@link @serenity-js/core/lib/screenplay/actor~UsesAbilities}
+     */
+    answeredBy(actor: AnswersQuestions & UsesAbilities): Promise<string[]>;
+}

package/lib/screenplay/questions/CssClasses.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CssClasses = void 0;
+const io_1 = require("@serenity-js/core/lib/io");
+const models_1 = require("../models");
+const ElementQuestion_1 = require("./ElementQuestion");
+/**
+ * @desc
+ *  Resolves to an array of [CSS classes](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes#attr-class)
+ *  of a given {@link WebElement}, represented by Answerable<{@link @wdio/types~Element}>.
+ *
+ * @example <caption>Example widget</caption>
+ *  <ul id="shopping-list" class="active favourite">
+ *    <li class="bought">Coffee<li>
+ *    <li class="buy">Honey<li>
+ *    <li class="buy">Chocolate<li>
+ *  </ul>
+ *
+ * @example <caption>Retrieve CSS classes of a given WebElement</caption>
+ *  import { actorCalled } from '@serenity-js/core';
+ *  import { Ensure, equals } from '@serenity-js/assertions';
+ *  import { BrowseTheWeb, by, CssClasses, Target } from '@serenity-js/webdriverio';
+ *
+ *  const shoppingList = () =>
+ *      Target.the('shopping list').located(by.id('shopping-list'))
+ *
+ *  actorCalled('Lisa')
+ *      .whoCan(BrowseTheWeb.using(browser))
+ *      .attemptsTo(
+ *          Ensure.that(CssClasses.of(shoppingList()), equals([ 'active', 'favourite' ])),
+ *      )
+ *
+ * @example <caption>Find WebElements with a given class</caption>
+ *  import { actorCalled } from '@serenity-js/core';
+ *  import { Ensure, contain } from '@serenity-js/assertions';
+ *  import { BrowseTheWeb, by, CssClasses, Target } from '@serenity-js/webdriverio';
+ *
+ *  class ShoppingList {
+ *      static items = () =>
+ *          Target.all('items')
+ *              .located(by.css('#shopping-list li'))
+ *
+ *      static outstandingItems = () =>
+ *          ShoppingList.items
+ *              .where(CssClasses, contain('buy'))
+ *  }
+ *
+ *  actorCalled('Lisa')
+ *      .whoCan(BrowseTheWeb.using(browser))
+ *      .attemptsTo(
+ *          Ensure.that(
+ *              Text.ofAll(ShoppingList.outstandingItems()),
+ *              equals([ 'Honey', 'Chocolate' ])
+ *          ),
+ *      )
+ *
+ * @extends {ElementQuestion}
+ * @implements {@serenity-js/core/lib/screenplay/questions~MetaQuestion}
+ */
+class CssClasses extends ElementQuestion_1.ElementQuestion {
+    /**
+     * @param {Question<PageElement> | PageElement} target
+     */
+    constructor(target) {
+        super((0, io_1.formatted) `CSS classes of ${target}`);
+        this.target = target;
+    }
+    /**
+     * @param {Question<PageElement> | PageElement} target
+     * @returns {CssClasses}
+     */
+    static of(target) {
+        return new CssClasses(target);
+    }
+    /**
+     * @desc
+     *  Resolves to an array of CSS classes of the `target` element,
+     *  located in the context of a `parent` element.
+     *
+     * @param {@serenity-js/core/lib/screenplay~Answerable<Element>} parent
+     * @returns {Question<Promise<string[]>>}
+     *
+     * @see {@link Target.all}
+     * @see {@link @serenity-js/core/lib/screenplay/questions~MetaQuestion}
+     */
+    of(parent) {
+        return new CssClasses(models_1.PageElement.of(this.target, parent));
+    }
+    /**
+     * @desc
+     *  Makes the provided {@link @serenity-js/core/lib/screenplay/actor~Actor}
+     *  answer this {@link @serenity-js/core/lib/screenplay~Question}.
+     *
+     * @param {AnswersQuestions & UsesAbilities} actor
+     * @returns {Promise<void>}
+     *
+     * @see {@link @serenity-js/core/lib/screenplay/actor~Actor}
+     * @see {@link @serenity-js/core/lib/screenplay/actor~AnswersQuestions}
+     * @see {@link @serenity-js/core/lib/screenplay/actor~UsesAbilities}
+     */
+    async answeredBy(actor) {
+        const element = await this.resolve(actor, this.target);
+        return element.attribute('class')
+            .then(attribute => attribute !== null && attribute !== void 0 ? attribute : '')
+            .then(attribute => attribute
+            .replace(/\s+/, ' ')
+            .trim()
+            .split(' ')
+            .filter(cssClass => !!cssClass));
+    }
+}
+exports.CssClasses = CssClasses;
+//# sourceMappingURL=CssClasses.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"CssClasses.js","sourceRoot":"","sources":["../../../src/screenplay/questions/CssClasses.ts"],"names":[],"mappings":";;;AACA,iDAAqD;AAErD,sCAAwC;AACxC,uDAAoD;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,MAAa,UACT,SAAQ,iCAAkC;IAW1C;;OAEG;IACH,YAA6B,MAA+B;QACxD,KAAK,CAAC,IAAA,cAAS,EAAC,kBAAmB,MAAM,EAAE,CAAC,CAAC;QADpB,WAAM,GAAN,MAAM,CAAyB;IAE5D,CAAC;IAbD;;;OAGG;IACH,MAAM,CAAC,EAAE,CAAC,MAA+B;QACrC,OAAO,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC;IAClC,CAAC;IASD;;;;;;;;;;OAUG;IACH,EAAE,CAAC,MAA+B;QAC9B,OAAO,IAAI,UAAU,CAAC,oBAAW,CAAC,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC/D,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,UAAU,CAAC,KAAuC;QACpD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QAEvD,OAAO,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC;aAC5B,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,SAAS,aAAT,SAAS,cAAT,SAAS,GAAI,EAAE,CAAC;aAClC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,SAAS;aACvB,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;aACnB,IAAI,EAAE;aACN,KAAK,CAAC,GAAG,CAAC;aACV,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAE,QAAQ,CAAC,CACnC,CAAC;IACV,CAAC;CACJ;AA1DD,gCA0DC"}

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

@@ -0,0 +1,34 @@
+import { Answerable, AnswersQuestions, Question } from '@serenity-js/core';
+import { PageElement, PageElements } from '../models';
+/**
+ * @desc
+ *  A base class for questions about {@link PageElement}s.
+ *
+ * @extends {@serenity-js/core/lib/screenplay~Question}
+ */
+export declare abstract class ElementQuestion<T> extends Question<T> {
+    protected subject: string;
+    constructor(subject: string);
+    /**
+     * @desc
+     *  Changes the description of this question's subject.
+     *
+     * @param {string} subject
+     * @returns {Question<T>}
+     */
+    describedAs(subject: string): this;
+    toString(): string;
+    /**
+     * @desc
+     *  Returns the resolved {@link PageElement}, or throws a {@link @serenity-js/core/lib/errors~LogicError}
+     *  if the element is `undefined`.
+     *
+     * @param {@serenity-js/core/lib/screenplay/actor~AnswersQuestions} actor
+     * @param {@serenity-js/core/lib/screenplay~Answerable<Element|ElementList>} element
+     *
+     * @returns {Promise<PageElement|PageElements>}
+     *
+     * @protected
+     */
+    protected resolve<T = PageElement | PageElements>(actor: AnswersQuestions, element: Answerable<T>): Promise<T>;
+}

package/lib/screenplay/questions/ElementQuestion.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ElementQuestion = void 0;
+const core_1 = require("@serenity-js/core");
+const io_1 = require("@serenity-js/core/lib/io");
+/**
+ * @desc
+ *  A base class for questions about {@link PageElement}s.
+ *
+ * @extends {@serenity-js/core/lib/screenplay~Question}
+ */
+// todo: remove
+class ElementQuestion extends core_1.Question {
+    constructor(subject) {
+        super();
+        this.subject = subject;
+    }
+    /**
+     * @desc
+     *  Changes the description of this question's subject.
+     *
+     * @param {string} subject
+     * @returns {Question<T>}
+     */
+    describedAs(subject) {
+        this.subject = subject;
+        return this;
+    }
+    toString() {
+        return this.subject;
+    }
+    /**
+     * @desc
+     *  Returns the resolved {@link PageElement}, or throws a {@link @serenity-js/core/lib/errors~LogicError}
+     *  if the element is `undefined`.
+     *
+     * @param {@serenity-js/core/lib/screenplay/actor~AnswersQuestions} actor
+     * @param {@serenity-js/core/lib/screenplay~Answerable<Element|ElementList>} element
+     *
+     * @returns {Promise<PageElement|PageElements>}
+     *
+     * @protected
+     */
+    async resolve(actor, element) {
+        const resolved = await actor.answer(element);
+        if (!resolved) {
+            throw new core_1.LogicError((0, io_1.formatted) `Couldn't find ${element}`);
+        }
+        return resolved;
+    }
+}
+exports.ElementQuestion = ElementQuestion;
+//# sourceMappingURL=ElementQuestion.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ElementQuestion.js","sourceRoot":"","sources":["../../../src/screenplay/questions/ElementQuestion.ts"],"names":[],"mappings":";;;AAAA,4CAAuF;AACvF,iDAAqD;AAIrD;;;;;GAKG;AACH,eAAe;AACf,MAAsB,eAClB,SAAQ,eAAW;IAEnB,YAAsB,OAAe;QACjC,KAAK,EAAE,CAAC;QADU,YAAO,GAAP,OAAO,CAAQ;IAErC,CAAC;IAED;;;;;;OAMG;IACH,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;IAED;;;;;;;;;;;OAWG;IACO,KAAK,CAAC,OAAO,CACnB,KAAuB,EACvB,OAAsB;QAEtB,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAE7C,IAAI,CAAE,QAAQ,EAAE;YACZ,MAAM,IAAI,iBAAU,CAAC,IAAA,cAAS,EAAC,iBAAkB,OAAQ,EAAE,CAAC,CAAC;SAChE;QAED,OAAO,QAAQ,CAAC;IACpB,CAAC;CACJ;AA/CD,0CA+CC"}

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

@@ -0,0 +1,14 @@
+import { Question } from '@serenity-js/core';
+/**
+ * @desc
+ *  Returns the result of last script executed via {@link ExecuteScript}
+ */
+export declare class LastScriptExecution {
+    /**
+     * @desc
+     *  Enables asserting on the result of a function executed via {@link ExecuteScript}.
+     *
+     * @returns {Question<R>}
+     */
+    static result<R>(): Question<R>;
+}

package/lib/screenplay/questions/LastScriptExecution.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LastScriptExecution = void 0;
+const core_1 = require("@serenity-js/core");
+const abilities_1 = require("../abilities");
+/**
+ * @desc
+ *  Returns the result of last script executed via {@link ExecuteScript}
+ */
+class LastScriptExecution {
+    /**
+     * @desc
+     *  Enables asserting on the result of a function executed via {@link ExecuteScript}.
+     *
+     * @returns {Question<R>}
+     */
+    static result() {
+        return core_1.Question.about(`last script execution result`, actor => abilities_1.BrowseTheWeb.as(actor).lastScriptExecutionResult());
+    }
+}
+exports.LastScriptExecution = LastScriptExecution;
+//# sourceMappingURL=LastScriptExecution.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"LastScriptExecution.js","sourceRoot":"","sources":["../../../src/screenplay/questions/LastScriptExecution.ts"],"names":[],"mappings":";;;AAAA,4CAA6C;AAE7C,4CAA4C;AAE5C;;;GAGG;AACH,MAAa,mBAAmB;IAE5B;;;;;OAKG;IACH,MAAM,CAAC,MAAM;QACT,OAAO,eAAQ,CAAC,KAAK,CAAC,8BAA8B,EAAE,KAAK,CAAC,EAAE,CAC1D,wBAAY,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,yBAAyB,EAAE,CAAC,CAAC;IAC5D,CAAC;CACJ;AAZD,kDAYC"}

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

@@ -0,0 +1,185 @@
+import { Answerable, Question } from '@serenity-js/core';
+import { PageElement } from '../models';
+/**
+ * @desc
+ *  Represents options and values selected in a
+ *  [HTML `<select>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select).
+ *
+ * @see {@link Select}
+ */
+export declare class Selected {
+    /**
+     * @desc
+     *  Represents the value of a single option selected in a
+     *  [HTML `<select>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select).
+     *
+     * @example <caption>Example widget</caption>
+     *  <select data-test='countries'>
+     *      <option value='UK'>United Kingdom</option>
+     *      <option value='PL'>Poland</option>
+     *      <option value='US'>United States</option>
+     *  </select>
+     *
+     * @example <caption>Lean Page Object</caption>
+     *  import { Target } from '@serenity-js/protractor';
+     *  import { browser, by } from 'protractor';
+     *
+     *  class Countries {
+     *      static dropdown = Target.the('countries dropdown')
+     *          .located(by.css('[data-test="countries"]'));
+     *  }
+     *
+     * @example <caption>Retrieving the selected value</caption>
+     *  import { actorCalled } from '@serenity-js/core';
+     *  import { Accept, BrowseTheWeb, Select, Selected } from '@serenity-js/protractor';
+     *  import { Ensure, equals } from '@serenity-js/assertions';
+     *  import { protractor } from 'protractor';
+     *
+     *  actorCalled('Nick')
+     *      .whoCan(BrowseTheWeb.using(protractor.browser))
+     *      .attemptsTo(
+     *          Select.value('UK').from(Countries.dropdown),
+     *          Ensure.that(Selected.valueOf(Countries.dropdown), equals('UK')),
+     *      );
+     *
+     * @param {Answerable<PageElement>} pageElement
+     *  A {@link PageElement} identifying the `<select>` element of interest
+     *
+     * @returns {Question<Promise<string>>}
+     *
+     * @see {@link Select.value}
+     */
+    static valueOf(pageElement: Answerable<PageElement>): Question<Promise<string>>;
+    /**
+     * @desc
+     *  Represents values of options selected in a
+     *  [HTML `<select multiple>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select#attr-multiple)
+     *
+     * @example <caption>Example widget</caption>
+     *  <select multiple data-test='countries'>
+     *      <option value='UK'>United Kingdom</option>
+     *      <option value='PL'>Poland</option>
+     *      <option value='US'>United States</option>
+     *  </select>
+     *
+     * @example <caption>Lean Page Object</caption>
+     *  import { Target } from '@serenity-js/protractor';
+     *  import { browser, by } from 'protractor';
+     *
+     *  class Countries {
+     *      static dropdown = Target.the('countries dropdown')
+     *          .located(by.css('[data-test="countries"]'));
+     *  }
+     *
+     * @example <caption>Retrieving the selected value</caption>
+     *  import { actorCalled } from '@serenity-js/core';
+     *  import { Accept, BrowseTheWeb, Select, Selected } from '@serenity-js/protractor';
+     *  import { Ensure, equals } from '@serenity-js/assertions';
+     *  import { protractor } from 'protractor';
+     *
+     *  actorCalled('Nick')
+     *      .whoCan(BrowseTheWeb.using(protractor.browser))
+     *      .attemptsTo(
+     *          Select.values('UK').from(Countries.dropdown),
+     *          Ensure.that(Selected.valuesOf(Countries.dropdown), equals([ 'UK' ])),
+     *      );
+     *
+     * @param {Answerable<PageElement>} pageElement
+     *  A {@link Target} identifying the `<select>` element of interest
+     *
+     * @returns {Question<Promise<string[]>>}
+     *
+     * @see {@link Select.values}
+     */
+    static valuesOf(pageElement: Answerable<PageElement>): Question<Promise<string[]>>;
+    /**
+     * @desc
+     *  Represents a single option selected in a
+     *  [HTML `<select>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select#attr-multiple)
+     *
+     * @example <caption>Example widget</caption>
+     *  <select data-test='countries'>
+     *      <option value='UK'>United Kingdom</option>
+     *      <option value='PL'>Poland</option>
+     *      <option value='US'>United States</option>
+     *  </select>
+     *
+     * @example <caption>Lean Page Object</caption>
+     *  import { Target } from '@serenity-js/protractor';
+     *  import { browser, by } from 'protractor';
+     *
+     *  class Countries {
+     *      static dropdown = Target.the('countries dropdown')
+     *          .located(by.css('[data-test="countries"]'));
+     *  }
+     *
+     * @example <caption>Retrieving the selected value</caption>
+     *  import { actorCalled } from '@serenity-js/core';
+     *  import { Accept, BrowseTheWeb, Select, Selected } from '@serenity-js/protractor';
+     *  import { Ensure, equals } from '@serenity-js/assertions';
+     *  import { protractor } from 'protractor';
+     *
+     *  actorCalled('Nick')
+     *      .whoCan(BrowseTheWeb.using(protractor.browser))
+     *      .attemptsTo(
+     *          Select.option('Poland').from(Countries.dropdown),
+     *          Ensure.that(
+     *              Selected.optionIn(Countries.dropdown),
+     *              equals('Poland')
+     *          ),
+     *      );
+     *
+     * @param {Answerable<PageElement>} pageElement
+     *  A {@link Target} identifying the `<select>` element of interest
+     *
+     * @returns {Question<Promise<string>>}
+     *
+     * @see {@link Select.option}
+     */
+    static optionIn(pageElement: Answerable<PageElement>): Question<Promise<string>>;
+    /**
+     * @desc
+     *  Represents options selected in a
+     *  [HTML `<select multiple>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select#attr-multiple)
+     *
+     * @example <caption>Example widget</caption>
+     *  <select multiple data-test='countries'>
+     *      <option value='UK'>United Kingdom</option>
+     *      <option value='PL'>Poland</option>
+     *      <option value='US'>United States</option>
+     *  </select>
+     *
+     * @example <caption>Lean Page Object</caption>
+     *  import { Target } from '@serenity-js/protractor';
+     *  import { browser, by } from 'protractor';
+     *
+     *  class Countries {
+     *      static dropdown = Target.the('countries dropdown')
+     *          .located(by.css('[data-test="countries"]'));
+     *  }
+     *
+     * @example <caption>Retrieving the selected value</caption>
+     *  import { actorCalled } from '@serenity-js/core';
+     *  import { Accept, BrowseTheWeb, Select, Selected } from '@serenity-js/protractor';
+     *  import { Ensure, equals } from '@serenity-js/assertions';
+     *  import { protractor } from 'protractor';
+     *
+     *  actorCalled('Nick')
+     *      .whoCan(BrowseTheWeb.using(protractor.browser))
+     *      .attemptsTo(
+     *          Select.options('Poland', 'United States').from(Countries.dropdown),
+     *          Ensure.that(
+     *              Selected.optionsIn(Countries.dropdown),
+     *              equals([ 'Poland', 'United States' ])
+     *          ),
+     *      );
+     *
+     * @param {Answerable<PageElement>} pageElement
+     *  A {@link Target} identifying the `<select>` element of interest
+     *
+     * @returns {Question<Promise<string[]>>}
+     *
+     * @see {@link Select.options}
+     */
+    static optionsIn(pageElement: Answerable<PageElement>): Question<Promise<string[]>>;
+}