@serenity-js/protractor 2.33.1 → 3.0.0-rc.11

package/lib/screenplay/abilities/{BrowseTheWeb.d.ts → BrowseTheWebWithProtractor.d.ts}

@@ -1,6 +1,8 @@
-import { Ability, UsesAbilities } from '@serenity-js/core';
-import { ActionSequence, ElementArrayFinder, ElementFinder, Locator, ProtractorBrowser } from 'protractor';
-import { AlertPromise, Capabilities, Navigation, Options, WebElement, WebElementPromise } from 'selenium-webdriver';
+import { Duration } from '@serenity-js/core';
+import { BrowserCapabilities, BrowseTheWeb, Cookie, CookieData, Frame, Key, ModalDialog, Page, Selector } from '@serenity-js/web';
+import { ElementFinder, ProtractorBrowser } from 'protractor';
+import { Capabilities } from 'selenium-webdriver';
+import { ProtractorNativeElementRoot } from '../models/locators';
 /**
  * @desc
  *  An {@link @serenity-js/core/lib/screenplay~Ability} that enables the {@link Actor} to interact with web front-ends using {@link protractor}.
@@ -30,38 +32,38 @@ import { AlertPromise, Capabilities, Navigation, Options, WebElement, WebElement
  * @implements {@serenity-js/core/lib/screenplay~Ability}
  * @see {@link @serenity-js/core/lib/screenplay/actor~Actor}
  */
-export declare class BrowseTheWeb implements Ability {
+export declare class BrowseTheWebWithProtractor extends BrowseTheWeb<ElementFinder, ProtractorNativeElementRoot> {
     protected browser: ProtractorBrowser;
-    /**
-     * @private
-     */
-    private lastScriptExecutionSummary;
-    /**
-     * @private
-     */
-    private originalWindowHandle;
     /**
      * @desc
      *  Ability to interact with web front-ends using a given protractor browser instance.
      *
      * @param {ProtractorBrowser} browser
-     * @returns {BrowseTheWeb}
+     * @returns {BrowseTheWebWithProtractor}
      */
-    static using(browser: ProtractorBrowser): BrowseTheWeb;
+    static using(browser: ProtractorBrowser): BrowseTheWebWithProtractor;
     /**
-     * @desc
-     *  Used to access the Actor's ability to {@link BrowseTheWeb} from within the {@link Interaction} classes,
-     *  such as {@link Navigate}.
-     *
-     * @param {UsesAbilities} actor
-     * @return {BrowseTheWeb}
+     * @private
      */
-    static as(actor: UsesAbilities): BrowseTheWeb;
+    private lastScriptExecutionSummary;
     /**
      * @param {ProtractorBrowser} browser
      *  An instance of a protractor browser
      */
     constructor(browser: ProtractorBrowser);
+    browserCapabilities(): Promise<BrowserCapabilities>;
+    cookie(name: string): Promise<Cookie>;
+    setCookie(cookieData: CookieData): Promise<void>;
+    deleteAllCookies(): Promise<void>;
+    navigateTo(destination: string): Promise<void>;
+    navigateBack(): Promise<void>;
+    navigateForward(): Promise<void>;
+    reloadPage(): Promise<void>;
+    waitFor(duration: Duration): Promise<void>;
+    waitUntil(condition: () => boolean | Promise<boolean>, timeout: Duration): Promise<void>;
+    sendKeys(keys: (string | Key)[]): Promise<void>;
+    modalDialog(): Promise<ModalDialog>;
+    frame(bySelector: Selector): Promise<Frame>;
     /**
      * @desc
      *  Navigate to the given destination and loads mock modules before Angular.
@@ -75,157 +77,19 @@ export declare class BrowseTheWeb implements Ability {
     get(destination: string, timeoutInMillis?: number): Promise<void>;
     /**
      * @desc
-     *  Interface for navigating back and forth in the browser history.
-     *
-     *  @returns {Navigation}
-     */
-    navigate(): Navigation;
-    /**
-     * @desc
-     *  Interface for defining sequences of complex user interactions.
-     *  Each sequence will not be executed until `perform` is called.
-     *
-     * @returns {ActionSequence}
-     *
-     * @see https://www.selenium.dev/selenium/docs/api/javascript/module/selenium-webdriver/lib/actions.html
-     */
-    actions(): ActionSequence;
-    /**
-     * @desc
-     *  Interface for managing browser and driver state.
-     *
-     * @returns {Options}
+     *  Returns a {@link Page} representing the currently active top-level browsing context.
      *
-     * @see https://www.selenium.dev/selenium/docs/api/javascript/module/selenium-webdriver/lib/webdriver_exports_WebDriver.html#manage
+     * @returns {Promise<Page>}
      */
-    manage(): Options;
+    currentPage(): Promise<Page>;
     /**
      * @desc
-     *  Changes focus to the active modal dialog,
-     *  such as those opened by
-     *  [`Window.alert()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/alert),
-     *  [`Window.prompt()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/prompt), or
-     *  [`Window.confirm()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/confirm).
+     *  Returns an array of {@link Page} objects representing all the available
+     *  top-level browsing context, e.g. all the open browser tabs.
      *
-     * The returned promise will be rejected with an [`error.NoSuchAlertError`](https://www.selenium.dev/selenium/docs/api/javascript/module/selenium-webdriver/lib/error_exports_NoSuchAlertError.html)
-     * if there are no open alerts.
-     *
-     * @returns {AlertPromise}
-     *
-     * @see https://www.selenium.dev/selenium/docs/api/javascript/module/selenium-webdriver/lib/webdriver_exports_TargetLocator.html#alert
+     * @returns {Promise<Array<Page>>}
      */
-    alert(): AlertPromise;
-    /**
-     * @desc
-     *  Switches the focus to a [`frame`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/frame) or
-     *  [`iframe`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe) identified by `elementOrIndexOrName`,
-     *  which can be specified either as {@link selenium-webdriver~WebElement}, the name of the frame, or its index.
-     *
-     * @param {number | string | WebElement} elementOrIndexOrName
-     *
-     * @returns {Promise<void>}
-     */
-    switchToFrame(elementOrIndexOrName: number | string | WebElement | WebElementPromise): Promise<void>;
-    /**
-     * @desc
-     *  Switches the focus from any [`frame`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/frame) or
-     *  [`iframe`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe) back to its parent iframe.
-     *
-     * @returns {Promise<void>}
-     */
-    switchToParentFrame(): Promise<void>;
-    /**
-     * @desc
-     *  Switches the focus from any [`frame`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/frame)
-     *  or [`iframe`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe) back to default content,
-     *  a.k.a. "the main window".
-     *
-     * @returns {Promise<void>}
-     */
-    switchToDefaultContent(): Promise<void>;
-    /**
-     * @desc
-     *  Switches browser window/tab to the one identified by `nameOrHandleOrIndex`,
-     *  which can be specified as the name of the window to switch to, its handle, or numeric index.
-     *
-     * @param {string | number} nameOrHandleOrIndex
-     *
-     * @returns {Promise<void>}
-     */
-    switchToWindow(nameOrHandleOrIndex: string | number): Promise<void>;
-    /**
-     * @param {string} nameOrHandle
-     * @private
-     */
-    private switchToWindowByNameOrHandle;
-    /**
-     * @param {number} index
-     * @private
-     */
-    private switchToWindowByIndex;
-    /**
-     * @desc
-     *  Switches the window back to the original one that was used to call {@link get}.
-     *
-     * @returns {Promise<void>}
-     */
-    switchToOriginalWindow(): Promise<void>;
-    /**
-     * @desc
-     *  Returns the handle of the browser window last used to navigate to a URL.
-     *
-     * @returns {Promise<string>}
-     *  A window handle
-     *
-     * @see {@link get}
-     */
-    getOriginalWindowHandle(): Promise<string>;
-    /**
-     * @desc
-     *  Returns the current window handle.
-     *  Please note that the current handle changes with each browser window you {@link Switch} to.
-     *
-     * @returns {Promise<string>}
-     *  A window handle
-     *
-     * @see {@link get}
-     */
-    getCurrentWindowHandle(): Promise<string>;
-    /**
-     * @desc
-     *  Returns the handles of all the available windows.
-     *
-     *  Please note that while some browsers organise entries of this list in the same order
-     *  new windows have been spawned, other browsers order it alphabetically.
-     *  For this reason, you should not make any assumptions about how this list is ordered.
-     *
-     * @returns {Promise<string[]>}
-     *  A list of window handles
-     */
-    getAllWindowHandles(): Promise<string[]>;
-    /**
-     * @desc
-     *  Closes the currently active browser window/tab.
-     *
-     * @returns {Promise<void>}
-     */
-    closeCurrentWindow(): Promise<void>;
-    /**
-     * @desc
-     *  Locates a single element identified by the locator
-     *
-     * @param {Locator} locator
-     * @returns {ElementFinder}
-     */
-    locate(locator: Locator): ElementFinder;
-    /**
-     * @desc
-     *  Locates all elements identified by the locator
-     *
-     * @param {Locator} locator
-     * @returns {ElementArrayFinder}
-     */
-    locateAll(locator: Locator): ElementArrayFinder;
+    allPages(): Promise<Array<Page>>;
     /**
      * @desc
      * If set to false, Protractor will not wait for Angular $http and $timeout
@@ -286,7 +150,6 @@ export declare class BrowseTheWeb implements Ability {
      * @see https://www.protractortest.org/#/api?view=webdriver.WebDriver.prototype.executeScript
      * @see https://seleniumhq.github.io/selenium/docs/api/java/org/openqa/selenium/JavascriptExecutor.html#executeScript-java.lang.String-java.lang.Object...-
      *
-     * @param {string} description  - useful for debugging
      * @param {string | Function} script
      * @param {any[]} args
      *
@@ -294,10 +157,10 @@ export declare class BrowseTheWeb implements Ability {
      *
      * @see {@link BrowseTheWeb#getLastScriptExecutionResult}
      */
-    executeScript(description: string, script: string | Function, ...args: any[]): Promise<any>;
+    executeScript<Result, InnerArguments extends any[]>(script: string | ((...parameters: InnerArguments) => Result), ...args: InnerArguments): Promise<Result>;
     /**
      * @desc
-     *  A simplified version of {@link BrowseTheWeb#executeScript} that doesn't affect {@link LastScriptExecution.result()}.
+     *  A simplified version of {@link BrowseTheWebWithProtractor#executeScript} that doesn't affect {@link LastScriptExecution.result()}.
      *
      * @param {Function} fn
      * @param {Parameters<fn>} args
@@ -317,7 +180,7 @@ export declare class BrowseTheWeb implements Ability {
      *  Arrays and objects may also be used as script arguments as long as each item adheres
      *  to the types previously mentioned.
      *
-     *  Unlike executing synchronous JavaScript with {@link BrowseTheWeb#executeScript},
+     *  Unlike executing synchronous JavaScript with {@link BrowseTheWebWithProtractor#executeScript},
      *  scripts executed with this function must explicitly signal they are finished by invoking the provided callback.
      *
      *  This callback will always be injected into the executed function as the last argument,
@@ -357,7 +220,7 @@ export declare class BrowseTheWeb implements Ability {
      *
      * @see {@link BrowseTheWeb#getLastScriptExecutionResult}
      */
-    executeAsyncScript(script: string | Function, ...args: any[]): Promise<any>;
+    executeAsyncScript<Result, Parameters extends any[]>(script: string | ((...args: [...parameters: Parameters, callback: (result: Result) => void]) => void), ...args: Parameters): Promise<Result>;
     /**
      * @desc
      *  Schedule a command to take a screenshot. The driver makes a best effort to
@@ -371,22 +234,6 @@ export declare class BrowseTheWeb implements Ability {
      * @return {Promise<string>} A promise that will be resolved to a base64-encoded screenshot PNG
      */
     takeScreenshot(): Promise<string>;
-    /**
-     * @desc
-     *  Returns the title of the current page.
-     *
-     * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/title
-     *
-     * @returns {Promise<string>}
-     */
-    getTitle(): Promise<string>;
-    /**
-     * @desc
-     *  Returns the url of the current page.
-     *
-     * @returns {Promise<string>}
-     */
-    getCurrentUrl(): Promise<string>;
     /**
      * @desc
      *  Returns the  capabilities of the browser used in the current session.
@@ -397,7 +244,7 @@ export declare class BrowseTheWeb implements Ability {
      *
      * @returns {Promise<Capabilities>} The actual capabilities of this browser.
      */
-    getCapabilities(): Promise<Capabilities>;
+    capabilities(): Promise<Capabilities>;
     /**
      * @desc
      *  Pause the actor flow for a specified number of milliseconds.
@@ -417,12 +264,12 @@ export declare class BrowseTheWeb implements Ability {
     wait(condition: () => Promise<boolean>, timeoutInMillis: number): Promise<boolean>;
     /**
      * @desc
-     *  Returns the last result of calling {@link BrowseTheWeb#executeAsyncScript}
-     *  or {@link BrowseTheWeb#executeScript}
+     *  Returns the last result of calling {@link BrowseTheWebWithProtractor#executeAsyncScript}
+     *  or {@link BrowseTheWebWithProtractor#executeScript}
      *
      * @returns {any}
      */
-    getLastScriptExecutionResult(): any;
+    lastScriptExecutionResult(): any;
     /**
      * @desc
      *  Returns Protractor configuration parameter at `path`.