@serenity-js/protractor 2.32.5 → 3.0.0-rc.3

package/CHANGELOG.md

@@ -3,6 +3,92 @@
 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.3](https://github.com/serenity-js/serenity-js/compare/v3.0.0-rc.2...v3.0.0-rc.3) (2021-12-29)
+
+
+### Bug Fixes
+
+* **core:** refactored Mappable so that it's easier to implement filters ([176e0cd](https://github.com/serenity-js/serenity-js/commit/176e0cd0303d63271477b2b7a8e7b0572dda99a0)), closes [#1074](https://github.com/serenity-js/serenity-js/issues/1074)
+* **deps:** updated tiny-types to 1.17.0 ([3187051](https://github.com/serenity-js/serenity-js/commit/3187051594158b4b450c82e851e417fd2ed21652))
+* **web:** refactored Selector and NativeElementLocator classes to simplify the implementation ([f0c8f11](https://github.com/serenity-js/serenity-js/commit/f0c8f113433958877d36f13d0bc7f355ea68d280))
+
+
+### Features
+
+* **web:** isVisible checks if the element is in viewport and not hidden behind other elements ([429040f](https://github.com/serenity-js/serenity-js/commit/429040fb32b04cd4bc7524100635203fd8128eb6))
+* **web:** re-introduced PageElements.where DSL and universal By selectors ([39fe0a1](https://github.com/serenity-js/serenity-js/commit/39fe0a10edf7f652e93911159e4a4689c36d6876)), closes [#1081](https://github.com/serenity-js/serenity-js/issues/1081)
+
+
+
+
+
+# [3.0.0-rc.2](https://github.com/serenity-js/serenity-js/compare/v3.0.0-rc.1...v3.0.0-rc.2) (2021-12-09)
+
+
+### Bug Fixes
+
+* **lerna:** corrected versions of internal deps ([582b922](https://github.com/serenity-js/serenity-js/commit/582b922dbade08e970cb796f15aca909f606c079))
+
+
+
+
+
+# [3.0.0-rc.1](https://github.com/serenity-js/serenity-js/compare/v3.0.0-rc.0...v3.0.0-rc.1) (2021-12-09)
+
+**Note:** Version bump only for package @serenity-js/protractor
+
+
+
+
+
+# [3.0.0-rc.0](https://github.com/serenity-js/serenity-js/compare/v2.32.5...v3.0.0-rc.0) (2021-12-08)
+
+
+### Bug Fixes
+
+* **core:** 3.0 RC ([469d54e](https://github.com/serenity-js/serenity-js/commit/469d54e4f81ef430566b93852e3174826f8ef672)), closes [#805](https://github.com/serenity-js/serenity-js/issues/805)
+* **core:** renamed "Model" type to "Adapter" to better reflect its purpose ([b4ea7a1](https://github.com/serenity-js/serenity-js/commit/b4ea7a100fac2c896990bf15cbc906de641196b8)), closes [#805](https://github.com/serenity-js/serenity-js/issues/805)
+* **protractor:** fixed the interaction to Switch ([762ca84](https://github.com/serenity-js/serenity-js/commit/762ca8406389a720d2ac6b8ab49b2519fbecfc21))
+* **protractor:** lastScriptExecution.result() returns undefined instead of null for void functions ([997d87a](https://github.com/serenity-js/serenity-js/commit/997d87af2d825bffd47c0a1b3dbeee8ce572e391))
+* **protractor:** modernised ProtractorParam to return a Screenplay Model ([43c2032](https://github.com/serenity-js/serenity-js/commit/43c2032e73c5e1ad3392396dec6fff476283833d))
+* **protractor:** removed interaction to ResizeBrowserWindow in favour of Page.setViewportSize() ([b8e471d](https://github.com/serenity-js/serenity-js/commit/b8e471dc92fe7d930895571ce0bcb99066eb2206))
+* **protractor:** replaced obsolete "Window", replaced by "Page" in @serenity-js/web ([a3442c4](https://github.com/serenity-js/serenity-js/commit/a3442c432082327f9081c269c02141c73b2e4eb3))
+* **web:** corrected timestamp rounding when retrieving the expiry date of a cookie ([d636965](https://github.com/serenity-js/serenity-js/commit/d63696586618cd701e703e33dd8b476efaac65b6))
+* **webdriverio:** separated UIElement.hoverOver from UIElement.scrollIntoView ([cf4ca2c](https://github.com/serenity-js/serenity-js/commit/cf4ca2c531e0f90f9a27917e322359c13bfbc6e6))
+* **web:** removed Cookie as it will be re-implemented ([cb3d081](https://github.com/serenity-js/serenity-js/commit/cb3d0813f9f0532bfe82be77fef0edec45e8ca3e))
+* **web:** removed window-specific APIs from BrowseTheWeb that got replaced by Page ([918f447](https://github.com/serenity-js/serenity-js/commit/918f447c1d8f326fbf5730f1aa61108045556212)), closes [#805](https://github.com/serenity-js/serenity-js/issues/805)
+* **web:** renamed Element and associated classes to PageElement to avoid name conflicts ([1e4204b](https://github.com/serenity-js/serenity-js/commit/1e4204b5507469e6574c87a6d84454e39e8a813e))
+* **web:** renamed PageElementList to PageElements to improve readability ([a9903a7](https://github.com/serenity-js/serenity-js/commit/a9903a7389b00106ef94d2bdb9f86a7fd04be541)), closes [#805](https://github.com/serenity-js/serenity-js/issues/805)
+* **web:** standardised getters across PageElement implementations ([336472b](https://github.com/serenity-js/serenity-js/commit/336472b1a6882412f6a88483e51266909a1d51d0))
+
+
+### Features
+
+* **core:** question.about produces "props" that proxy the methods of the underlying model ([f771872](https://github.com/serenity-js/serenity-js/commit/f771872c56b487e404002c3800fc8f3baaed804f))
+* **protractor:** compatibility with @serenity-js/web ([9df4db2](https://github.com/serenity-js/serenity-js/commit/9df4db27a6e0ae62bf0d0e679a170d4865041043)), closes [#805](https://github.com/serenity-js/serenity-js/issues/805)
+* **protractor:** removed Protractor-specific Target implementations in favour of @serenity-js/web ([5cfc7e5](https://github.com/serenity-js/serenity-js/commit/5cfc7e53c977ae919398d9102f43985f393992db))
+* **web:** a common way to run the tests for all the web adapters ([c7e584a](https://github.com/serenity-js/serenity-js/commit/c7e584a9bf288ebc7781affdb720097527e8ed3a))
+* **web:** added Page.viewportSize and Page.setViewportSize methods ([4cabbe2](https://github.com/serenity-js/serenity-js/commit/4cabbe21a7fbac3457c6a6ea3d4442a62c3f1f3c))
+* **web:** interaction to set a Cookie ([c056439](https://github.com/serenity-js/serenity-js/commit/c056439746a8f57c3edd937b8862f2babb70e94e)), closes [#805](https://github.com/serenity-js/serenity-js/issues/805)
+* **web:** interaction to setViewportSize of a Page ([dd7f180](https://github.com/serenity-js/serenity-js/commit/dd7f18057b857d2e69c19265888bfd5b15fda21b))
+* **web:** migrated Photographer from @serenity-js/protractor to @serenity-js/web ([4506dac](https://github.com/serenity-js/serenity-js/commit/4506dacebdf955c32c4eff17bf9982c8e45e2925)), closes [#805](https://github.com/serenity-js/serenity-js/issues/805)
+* **web:** ModalDialog available for both Protractor and WebdriverIO adapters ([ef3c566](https://github.com/serenity-js/serenity-js/commit/ef3c566aed12b52aa22c54058992d369172b8597)), closes [#805](https://github.com/serenity-js/serenity-js/issues/805)
+* **web:** page provides an abstraction around browser window ([2e70a3b](https://github.com/serenity-js/serenity-js/commit/2e70a3b6af2e8cc49255820e8a1aaffcc71b76a8))
+* **web:** Page.url() and Page.title() replace Website.url() and Website.title() ([49fe009](https://github.com/serenity-js/serenity-js/commit/49fe0094422ab53ec67d4ba303f80c33e382eebd)), closes [#805](https://github.com/serenity-js/serenity-js/issues/805)
+* **web:** removed Target in favour of PageElement ([69496c4](https://github.com/serenity-js/serenity-js/commit/69496c47c4a1ec7b92e7ab6c83da1559e926f28e)), closes [#805](https://github.com/serenity-js/serenity-js/issues/805)
+* **web:** support for switching browsing context ([a73a635](https://github.com/serenity-js/serenity-js/commit/a73a635f93183d67229acde78e74526564008869)), closes [#805](https://github.com/serenity-js/serenity-js/issues/805)
+* **web:** support for working with cookies ([39cde6d](https://github.com/serenity-js/serenity-js/commit/39cde6de7a36d27a8b1c596493efbec94900af6b)), closes [#805](https://github.com/serenity-js/serenity-js/issues/805)
+
+
+### BREAKING CHANGES
+
+* **core:** Introduced @serenity-js/web - a shared library for Serenity/JS Web integration
+modules such as @serenity-js/protractor and @serenity-js/webdriverio. Dropped support for Node 12.
+
+
+
+
+
 ## [2.32.5](https://github.com/serenity-js/serenity-js/compare/v2.32.4...v2.32.5) (2021-12-08)
 
 **Note:** Version bump only for package @serenity-js/protractor

package/lib/index.d.ts

@@ -1,3 +1 @@
-export * from './expectations';
 export * from './screenplay';
-export * from './stage';

package/lib/index.js

@@ -10,7 +10,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./expectations"), exports);
 __exportStar(require("./screenplay"), exports);
-__exportStar(require("./stage"), exports);
 //# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,iDAA+B;AAC/B,+CAA6B;AAC7B,0CAAwB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,+CAA6B"}

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, UsesAbilities } from '@serenity-js/core';
+import { BrowserCapabilities, BrowseTheWeb, Cookie, CookieData, Key, ModalDialog, NativeElementLocator, Page, PageElement, Selector } from '@serenity-js/web';
+import { ElementFinder, ProtractorBrowser } from 'protractor';
+import { Capabilities } from 'selenium-webdriver';
+import { ProtractorPageElement } from '../models';
 /**
  * @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,49 @@ 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> {
     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,
+     *  Used to access the Actor's ability to {@link BrowseTheWebWithProtractor} from within the {@link Interaction} classes,
      *  such as {@link Navigate}.
      *
      * @param {UsesAbilities} actor
-     * @return {BrowseTheWeb}
+     * @return {BrowseTheWebWithProtractor}
+     */
+    static as(actor: UsesAbilities): BrowseTheWebWithProtractor;
+    /**
+     * @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>;
+    locate<T>(selector: Selector<T>, locator?: NativeElementLocator<ElementFinder>): ProtractorPageElement;
+    locateAll<T>(selector: Selector<T>, locator?: NativeElementLocator<ElementFinder>): Promise<ProtractorPageElement[]>;
+    nativeElementLocator(): NativeElementLocator<ElementFinder>;
+    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>;
     /**
      * @desc
      *  Navigate to the given destination and loads mock modules before Angular.
@@ -73,48 +86,6 @@ export declare class BrowseTheWeb implements Ability {
      * @returns {Promise<void>}
      */
     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}
-     *
-     * @see https://www.selenium.dev/selenium/docs/api/javascript/module/selenium-webdriver/lib/webdriver_exports_WebDriver.html#manage
-     */
-    manage(): Options;
-    /**
-     * @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).
-     *
-     * 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
-     */
-    alert(): AlertPromise;
     /**
      * @desc
      *  Switches the focus to a [`frame`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/frame) or
@@ -125,7 +96,7 @@ export declare class BrowseTheWeb implements Ability {
      *
      * @returns {Promise<void>}
      */
-    switchToFrame(elementOrIndexOrName: number | string | WebElement | WebElementPromise): Promise<void>;
+    switchToFrame(elementOrIndexOrName: number | string | PageElement): Promise<void>;
     /**
      * @desc
      *  Switches the focus from any [`frame`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/frame) or
@@ -145,87 +116,19 @@ export declare class BrowseTheWeb implements Ability {
     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 a {@link Page} representing the currently active top-level browsing context.
      *
-     * @returns {Promise<void>}
-     */
-    switchToWindow(nameOrHandleOrIndex: string | number): Promise<void>;
-    /**
-     * @param {string} nameOrHandle
-     * @private
-     */
-    private switchToWindowByNameOrHandle;
-    /**
-     * @param {number} index
-     * @private
+     * @returns {Promise<Page>}
      */
-    private switchToWindowByIndex;
+    currentPage(): Promise<Page>;
     /**
      * @desc
-     *  Switches the window back to the original one that was used to call {@link get}.
+     *  Returns an array of {@link Page} objects representing all the available
+     *  top-level browsing context, e.g. all the open browser tabs.
      *
-     * @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}
+     * @returns {Promise<Array<Page>>}
      */
-    locateAll(locator: Locator): ElementArrayFinder;
+    allPages(): Promise<Array<Page>>;
     /**
      * @desc
      * If set to false, Protractor will not wait for Angular $http and $timeout
@@ -286,7 +189,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 +196,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 +219,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 +259,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 +273,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 +283,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 +303,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`.