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

package/src/screenplay/interactions/Switch.ts

@@ -1,225 +1,169 @@
-import { Activity, Answerable, AnswersQuestions, Interaction, PerformsActivities, Task, UsesAbilities } from '@serenity-js/core';
+import { Activity, Actor, Answerable, AnswersQuestions, Interaction, Task, UsesAbilities } from '@serenity-js/core';
 
-import { BrowseTheWeb } from '../abilities';
-import { PageElement } from '../models';
+import { Switchable } from '../models';
 
 /**
- * @desc
- *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor}
- *  to switch to a different [frame](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/frame),
- *  [inline frame](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe),
- *  or browser window/tab.
- *
- * @example <caption>Lean Page Object describing a login form, embedded in an iframe</caption>
- *
- *  import { Target } from '@serenity-js/protractor';
- *  import { by } from 'protractor';
- *
- *  class LoginForm {
- *      static iframe           = Target.the('login form').located(by.tagName('iframe'));
- *      static usernameField    = Target.the('username field').located(by.css('[data-test="username"]'));
- *      static passwordField    = Target.the('password field').located(by.css('[data-test="password"]'));
- *      static submitButton     = Target.the('submit button').located(by.css(`button[type='submit']`));
- *  }
- *
- * @example <caption>Switch to an iframe and back</caption>
- *
- *  import { actorCalled } from '@serenity-js/core';
- *  import { BrowseTheWeb, Switch, Enter, Click } from '@serenity-js/protractor';
- *  import { protractor } from 'protractor';
- *
- *  actorCalled('Francesca')
- *      .whoCan(BrowseTheWeb.using(protractor.browser))
- *      .attemptsTo(
- *          Switch.toFrame(LoginForm.iframe),
- *
- *          Enter.theValue('francesca@example.org').into(LoginForm.usernameField),
- *          Enter.theValue('correct-horse-battery-staple').into(LoginForm.passwordField),
- *          Click.on(LoginForm.submitButton),
- *
- *          Switch.toParentFrame(),
- *      );
- *
- * @example <caption>Perform activities in the context of an iframe</caption>
+ * Instructs an {@apilink Actor|actor} who has the {@apilink Ability|ability} to {@apilink BrowseTheWeb}
+ * to switch the context for future activities to a {@apilink Switchable}, such as a {@apilink Page} or a {@apilink PageElement}.
  *
- *  import { actorCalled } from '@serenity-js/core';
- *  import { BrowseTheWeb, Switch, Enter, Click } from '@serenity-js/protractor';
- *  import { protractor } from 'protractor';
+ * Please note that when the {@apilink PageElement} implementing {@apilink Switchable} represents an {@apilink iframe},
+ * using {@apilink Switch} will result in switching the top-level browsing context to that {@apilink iframe}.
  *
- *  actorCalled('Francesca')
- *      .whoCan(BrowseTheWeb.using(protractor.browser))
- *      .attemptsTo(
- *          Switch.toFrame(LoginForm.iframe).and(
- *              Enter.theValue('francesca@example.org').into(LoginForm.usernameField),
- *              Enter.theValue('correct-horse-battery-staple').into(LoginForm.passwordField),
- *              Click.on(LoginForm.submitButton),
- *          ),
- *          // Note that Switch.toParentFrame() is invoked automatically
- *      );
+ * When the {@apilink PageElement} represents any other [HTMLElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement),
+ * using {@apilink Switch} sets [`HTMLElement#focus`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus)
+ * on the specified element. Assuming it can be focused.
  *
- * @example <caption>Switch to a new window/tab and back</caption>
+ * **Note:** The focused element is the element which will receive keyboard {@apilink Press} events by default.
  *
- *  import { actorCalled } from '@serenity-js/core';
- *  import { BrowseTheWeb, Switch, Close } from '@serenity-js/protractor';
- *  import { protractor } from 'protractor';
+ * ## Perform activities in the context of an iframe
  *
- *  actorCalled('Francesca')
- *      .whoCan(BrowseTheWeb.using(protractor.browser))
- *      .attemptsTo(
- *          Switch.toNewWindow(), // or: Switch.toWindow(...)
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { By, Click, Enter, PageElement, Switch } from '@serenity-js/web'
  *
- *          // perform some activities in the context of the new window
+ * // Lean Page Object describing a login form, embedded in an iframe
+ * class LoginForm {
+ *   static iframe = () =>
+ *     PageElement.located(By.css('iframe'))
+ *       .describedAs('login form')
  *
- *          Close.currentWindow(),
+ *   static usernameField = () =>
+ *     PageElement.located(By.css('[data-testid="username"]'))
+ *       .describedAs('username field')
  *
- *          Switch.toOriginalWindow(),
- *      );
+ *   static passwordField = () =>
+ *     PageElement.located(By.css('[data-testid="password"]'))
+ *       .describedAs('password field')
  *
- * @example <caption>Perform activities in the context of a different window/tab</caption>
- *
- *  import { actorCalled } from '@serenity-js/core';
- *  import { BrowseTheWeb, Switch, Close } from '@serenity-js/protractor';
- *  import { protractor } from 'protractor';
- *
- *  actorCalled('Francesca')
- *      .whoCan(BrowseTheWeb.using(protractor.browser))
- *      .attemptsTo(
- *          Switch.toNewWindow().and(
- *              // perform some activities in the context of the new window
- *
- *              Close.currentWindow()
- *          ),
- *
- *          // Note that Switch.toOriginalWindow() is invoked automatically
- *      );
+ *   static submitButton = () =>
+ *     PageElement.located(By.css('button[type="submit"]'))
+ *       .describedAs('submit button')
+ *  }
  *
- * @see {@link Close}
- * @see {@link BrowseTheWeb}
+ *  await actorCalled('Francesca')
+ *    .attemptsTo(
+ *      Switch.to(LoginForm.iframe).and(
+ *        Enter.theValue('francesca@example.org').into(LoginForm.usernameField()),
+ *        Enter.theValue('correct-horse-battery-staple').into(LoginForm.passwordField()),
+ *        Click.on(LoginForm.submitButton()),
+ *      )
+ *    )
+ * ```
+ *
+ * ## Perform activities in the context of another page
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Click, Enter, Switch } from '@serenity-js/web'
+ *
+ * await actorCalled('Francesca')
+ *   .whoCan(BrowseTheWebWithWebdriverIO.using(browser))
+ *   .attemptsTo(
+ *     Switch.to(Page.whichName(startsWith('popup'))).and(
+ *       // perform some activities in the context of the new window
+ *
+ *       // optionally, close the browser tab
+ *       Page.current().close(),
+ *     ),
+ *
+ *     // Note that switching back to the original page happens automatically
+ *     // after the last activity from the list finishes
+ *   )
+ * ```
+ *
+ * ## Perform activities in the context of a focused page element
+ *
+ * ```ts
+ * import { Ensure, equals } from '@serenity-js/assertions'
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Key, PageElement, Press, Switch, Value } from '@serenity-js/web'
+ *
+ * const inputField = () =>
+ *   PageElement.located(By.css('input'));
+ *
+ * await actorCalled('Francesca')
+ *   .whoCan(BrowseTheWebWithWebdriverIO.using(browser))
+ *   .attemptsTo(
+ *     Switch.to(inputField()).and(
+ *       Press.the('h', 'e', 'l', 'l', 'o'),
+ *       Press.the(Key.Tab),
+ *     ),
+ *     Ensure.that(Value.of(inputField()), equals('hello'))
+ *   )
+ * ```
+ *
+ * ## Learn more
+ *
+ * - {@apilink BrowseTheWeb}
+ * - {@apilink Switchable}
+ * - {@apilink SwitchableOrigin}
+ *
+ * @group Activities
  */
-export class Switch {
+export class Switch extends Interaction {
 
     /**
-     * @desc
-     *  Switches the current [browsing context](https://w3c.github.io/webdriver/#dfn-current-browsing-context)
-     *  for future commands to a [frame](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/frame)
-     *  or an [inline frame](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe)
-     *  identified by its name, index or `Question<ElementFinder>`.
-     *
-     * @param {Answerable<ElementFinder | number | string>} targetOrIndex
+     * Instructs the {@apilink Actor}
+     * to switch the context for future activities to a {@apilink Switchable},
+     * such as a {@apilink Page} or a {@apilink PageElement}.
      *
-     * @returns {SwitchToFrame}
-     *
-     * @see {@link Switch.toParentFrame}
-     * @see {@link Switch.toDefaultContent}
-     * @see {@link Target}
+     * @param switchable
      */
-    static toFrame(targetOrIndex: Answerable<PageElement | number | string>): SwitchToFrame {
-        return new SwitchToFrame(targetOrIndex);
+    static to(switchable: Answerable<Switchable>): Switch {
+        return new Switch(switchable);
     }
 
-    /**
-     * @desc
-     *  Sets the current [browsing context](https://w3c.github.io/webdriver/#dfn-current-browsing-context)
-     *  for future commands to the parent of the current browsing context,
-     *  i.e. an `iframe` in which the current `iframe` is nested.
-     *
-     *  If the current context is the top-level browsing context, the context remains unchanged.
-     *
-     * @returns {@serenity-js/core/lib/screenplay~Interaction}
-     *
-     * @see {@link Switch.toFrame}
-     * @see https://w3c.github.io/webdriver/#switch-to-parent-frame
-     * @see https://w3c.github.io/webdriver/#dfn-current-browsing-context
-     */
-    static toParentFrame(): Interaction {
-        return new SwitchToParentFrame();
+    protected constructor(private readonly switchable: Answerable<Switchable>) {
+        super(`#actor switches to ${ switchable }`);
     }
 
     /**
-     * @desc
-     *  Switches the current [browsing context](https://w3c.github.io/webdriver/#dfn-current-browsing-context)
-     *  for future commands to the first frame on the page, or the main document
-     *  when a page contains [`iframe`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe)s.
-     *
-     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     * Instructs the {@apilink Actor}
+     * to switch the context for future activities to a {@apilink Switchable},
+     * such as a {@apilink Page} or a {@apilink PageElement},
+     * perform a sequence of `activities`, and then switch the context back.
      *
-     * @see {@link Switch.toFrame}
+     * @param activities
+     *  A sequence of activities to perform
      */
-    static toDefaultContent(): Interaction {
-        return new SwitchToDefaultContent();
-    }
-}
-
-/**
- * @package
- */
-class SwitchToFrame extends Interaction {
-    constructor(private readonly targetOrIndex: Answerable<PageElement | number | string>) {
-        super();
-    }
-
     and(...activities: Activity[]): Task {
-        return new SwitchToFrameAndPerformActivities(this.targetOrIndex, activities);
+        return new SwitchAndPerformActivities(this.switchable, activities);
     }
 
-    performAs(actor: UsesAbilities & AnswersQuestions): PromiseLike<void> {
-        return actor.answer(this.targetOrIndex)
-            .then((targetOrIndex: PageElement | number | string) => {
-                return BrowseTheWeb.as(actor).switchToFrame(targetOrIndex);
-            });
-    }
+    /**
+     * @inheritDoc
+     */
+    async performAs(actor: UsesAbilities & AnswersQuestions): Promise<void> {
+        const switchable = await actor.answer(this.switchable);
 
-    toString(): string {
-        return `#actor switches to frame: ${ this.targetOrIndex }`;
+        await switchable.switchTo();
     }
 }
 
 /**
  * @package
  */
-class SwitchToFrameAndPerformActivities extends Task {
+class SwitchAndPerformActivities extends Task {
     constructor(
-        private readonly targetOrIndex: Answerable<PageElement | number | string>,
+        private readonly switchable: Answerable<Switchable>,
         private readonly activities: Activity[]
     ) {
-        super();
+        super(`#actor switches to ${ switchable }`);
     }
 
-    performAs(actor: PerformsActivities): PromiseLike<void> {
-        return actor.attemptsTo(
-            new SwitchToFrame(this.targetOrIndex),
-            ...this.activities,
-            new SwitchToParentFrame()
-        )
-    }
+    /**
+     * @inheritDoc
+     */
+    async performAs(actor: Actor): Promise<void> {
 
-    toString(): string {
-        return `#actor switches to frame: ${ this.targetOrIndex }`;
-    }
-}
+        const switchable = await actor.answer(this.switchable);
 
-/**
- * @package
- */
-class SwitchToParentFrame extends Interaction {
-    performAs(actor: UsesAbilities & AnswersQuestions): PromiseLike<void> {
-        return BrowseTheWeb.as(actor).switchToParentFrame();
-    }
-
-    toString(): string {
-        return `#actor switches to parent frame`;
-    }
-}
+        const origin = await switchable.switchTo();
 
-/**
- * @package
- */
-class SwitchToDefaultContent extends Interaction {
-    performAs(actor: UsesAbilities & AnswersQuestions): PromiseLike<void> {
-        return BrowseTheWeb.as(actor).switchToDefaultContent();
-    }
+        await actor.attemptsTo(
+            ...this.activities,
+        )
 
-    toString(): string {
-        return `#actor switches to default content`;
+        await origin.switchBack();
     }
 }

package/src/screenplay/interactions/TakeScreenshot.ts

@@ -1,74 +1,58 @@
-import { Answerable, AnswersQuestions, CollectsArtifacts, Interaction, UsesAbilities } from '@serenity-js/core';
-import { formatted } from '@serenity-js/core/lib/io';
+import { Answerable, AnswersQuestions, CollectsArtifacts, d, Interaction, UsesAbilities } from '@serenity-js/core';
 import { Name, Photo } from '@serenity-js/core/lib/model';
 
 import { BrowseTheWeb } from '../abilities';
 
 /**
- * @desc
- *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor} to
- *  take a screenshot and emit an {@link @serenity-js/core/lib/model~Artifact},
- *  which can then be persisted by {@link @serenity-js/core/lib/stage/crew/artifact-archiver~ArtifactArchiver}
- *  and reported by [Serenity BDD reporter](/modules/serenity-bdd).
+ * Instructs an {@apilink Actor|actor} who has the {@apilink Ability|ability} to {@apilink BrowseTheWeb}
+ * to take a screenshot and emit an {@apilink Artifact},
+ * which can then be persisted by {@apilink ArtifactArchiver}
+ * and reported by [Serenity BDD reporter](/api/serenity-bdd).
  *
- * @example <caption>Clicking on an element</caption>
- *  import { actorCalled } from '@serenity-js/core';
- *  import { BrowseTheWeb, Navigate, TakeScreenshot } from '@serenity-js/protractor';
- *  import { protractor } from 'protractor';
+ * #### Taking a screenshot
  *
- *  actorCalled('Tania')
- *      .whoCan(BrowseTheWeb.using(protractor.browser))
- *      .attemptsTo(
- *          Navigate.to('/app'),
- *          TakeScreenshot.of('my app'),
- *      );
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core';
+ * import { Navigate, TakeScreenshot } from '@serenity-js/protractor';
  *
- * @see {@link BrowseTheWeb}
- * @see {@link @serenity-js/core/lib/screenplay/actor~CollectsArtifacts}
- * @see {@link @serenity-js/core/lib/model~Artifact}
- * @see {@link @serenity-js/core/lib/stage/crew/artifact-archiver~ArtifactArchiver}
+ * await actorCalled('Tania')
+ *   .attemptsTo(
+ *     Navigate.to('/app'),
+ *     TakeScreenshot.of('my app'),
+ *   )
+ * ```
  *
- * @extends {@serenity-js/core/lib/screenplay~Interaction}
+ * ## Learn more
+ *
+ * - {@apilink BrowseTheWeb}
+ * - {@apilink CollectsArtifacts}
+ * - {@apilink Artifact}
+ * - {@apilink ArtifactArchiver}
+ *
+ * @group Activities
  */
 export class TakeScreenshot extends Interaction {
 
     /**
-     * @desc
-     *  Instantiates this {@link @serenity-js/core/lib/screenplay~Interaction}.
+     * Instantiates this {@apilink Interaction}.
      *
-     * @param {Answerable<string>} name
-     *  The name to associate the screenshot with
-     *
-     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     * @param name
+     *  The name to give the emitted {@apilink Artifact}
      */
     static of(name: Answerable<string>): Interaction {
         return new TakeScreenshot(name);
     }
 
-    /**
-     * @param {Answerable<string>} name
-     *  The name to associate the screenshot with
-     */
-    constructor(private readonly name: Answerable<string>) {
-        super();
+    protected constructor(private readonly name: Answerable<string>) {
+        super(d`#actor takes a screenshot of ${ name }`);
     }
 
     /**
-     * @desc
-     *  Makes the provided {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     *  perform this {@link @serenity-js/core/lib/screenplay~Interaction}.
-     *
-     * @param {UsesAbilities & AnswersQuestions} actor
-     *  An {@link @serenity-js/core/lib/screenplay/actor~Actor} to perform this {@link @serenity-js/core/lib/screenplay~Interaction}
-     *
-     * @returns {PromiseLike<void>}
-     *
-     * @see {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     * @see {@link @serenity-js/core/lib/screenplay/actor~UsesAbilities}
-     * @see {@link @serenity-js/core/lib/screenplay/actor~AnswersQuestions}
+     * @inheritDoc
      */
     async performAs(actor: UsesAbilities & AnswersQuestions & CollectsArtifacts): Promise<void> {
-        const screenshot    = await BrowseTheWeb.as(actor).takeScreenshot();
+        const page          = await BrowseTheWeb.as(actor).currentPage();
+        const screenshot    = await page.takeScreenshot();
         const name          = await actor.answer(this.name);
 
         actor.collect(
@@ -76,14 +60,4 @@ export class TakeScreenshot extends Interaction {
             new Name(name),
         );
     }
-
-    /**
-     * @desc
-     *  Generates a description to be used when reporting this {@link @serenity-js/core/lib/screenplay~Activity}.
-     *
-     * @returns {string}
-     */
-    toString(): string {
-        return formatted `#actor takes a screenshot of ${this.name}`;
-    }
 }

package/src/screenplay/interactions/index.ts

@@ -5,12 +5,10 @@ export * from './Enter';
 export * from './ExecuteScript';
 export * from './Hover';
 export * from './Navigate';
+export * from './PageElementInteraction';
 export * from './Press';
-export * from './PressBuilder';
 export * from './RightClick';
 export * from './Scroll';
 export * from './Select';
-export * from './SelectBuilder';
 export * from './Switch';
 export * from './TakeScreenshot';
-export * from './Wait';

package/src/screenplay/models/BrowserCapabilities.ts

@@ -0,0 +1,26 @@
+/**
+ * Basic meta-data about the browser used in the test
+ *
+ * ## Learn more
+ *
+ * - {@apilink BrowseTheWeb.browserCapabilities}
+ *
+ * @group Models
+ */
+export interface BrowserCapabilities {
+
+    /**
+     * Name of the operating system platform the test is executed on, like `darwin`, `linux` or `windows`.
+     */
+    platformName?: string;
+
+    /**
+     * Name of the Web browser the test is executed in, like `chrome`, `firefox` or `safari`.
+     */
+    browserName?: string;
+
+    /**
+     * Version number of the browser the test is executed in.
+     */
+    browserVersion?: string;
+}

package/src/screenplay/models/BrowsingSession.ts

@@ -0,0 +1,115 @@
+import { CorrelationId } from '@serenity-js/core/lib/model';
+
+import { Page } from './Page';
+
+/**
+ * Represents the pages open in the current browsing context.
+ *
+ * You'll need to use this class directly only if you're planning to integrate Serenity/JS
+ * with a new Web integration tool.
+ *
+ * @group Models
+ */
+export abstract class BrowsingSession<Page_Type extends Page> {
+    protected currentBrowserPage: Page_Type;
+    protected readonly pages: Map<CorrelationId, Page_Type> = new Map<CorrelationId, Page_Type>();
+
+    async closePagesOtherThan(pageOfInterest: Page_Type): Promise<void> {
+        for (const page of await this.allPages()) {
+            if (! page.id.equals(pageOfInterest.id)) {
+                await page.close();
+                this.pages.delete(page.id);
+            }
+        }
+
+        await this.changeCurrentPageTo(pageOfInterest);
+    }
+
+    /**
+     * Opens a new browser page and associates it with a {@apilink Page} object.
+     */
+    protected abstract registerCurrentPage(): Promise<Page_Type>;
+
+    /**
+     * Returns a {@apilink Page} representing the currently active top-level browsing context.
+     */
+    async currentPage(): Promise<Page_Type> {
+        if (! this.currentBrowserPage || ! await this.currentBrowserPage.isPresent()) {
+            this.currentBrowserPage = await this.registerCurrentPage();
+        }
+
+        return this.currentBrowserPage;
+    }
+
+    /**
+     * Registers specified {@apilink Page|pages} to be managed by this {@apilink BrowsingSession}.
+     *
+     * @param pages
+     */
+    register(...pages: Page_Type[]): void {
+        for(const page of pages) {
+            this.pages.set(page.id, page);
+        }
+    }
+
+    /**
+     * Informs this {@apilink BrowsingSession} that it should no longer manage {@apilink Page|pages}
+     * identified by the given `pageIds`.
+     *
+     * @param pageIds
+     */
+    deregister(...pageIds: CorrelationId[]): void {
+        for(const pageId of pageIds) {
+            this.pages.delete(pageId);
+        }
+    }
+
+    /**
+     * Returns a {@apilink Page|pages} representing all the available
+     * top-level browsing context, e.g. all the open browser tabs.
+     */
+    async allPages(): Promise<Array<Page_Type>> {
+        return Array.from(this.pages.values()) as Page_Type[];
+    }
+
+    /**
+     * Returns the ids of any {@apilink Page|pages} this {@apilink BrowsingSession} is aware of.
+     */
+    registeredPageIds(): Array<CorrelationId> {
+        return Array.from(this.pages.keys());
+    }
+
+    /**
+     * Informs the {@apilink BrowsingSession} that the "current page" has changed to `page`.
+     *
+     * Please note that different Web integration tools have a different definition of what a "current page" is.
+     * For example, Selenium or WebdriverIO use a single "focused" window that a developer
+     * needs to explicitly "switch to" in their tests in order to interact with it.
+     * This is similar to how a regular user would interact with Web pages;
+     * switching from one tab to another, but not interacting with more than one
+     * window/tab simultaneously.
+     *
+     * Playwright and Puppeteer, on the other hand, don't have a concept of the "current" page at all, since they
+     * allow the developer to interact with multiple open tabs/windows at the same time.
+     *
+     * Web integration-specific implementations of this class should override this method to define
+     * how the concept of the "current page" should be interpreted by Serenity/JS.
+     *
+     * @param page
+     */
+    async changeCurrentPageTo(page: Page_Type): Promise<void> {
+        this.currentBrowserPage = page;
+    }
+
+    /**
+     * Closes all the pages available in this browsing context
+     */
+    async closeAllPages(): Promise<void> {
+        for (const page of this.pages.values()) {
+            await page.close();
+        }
+
+        this.pages.clear();
+        this.currentBrowserPage = undefined;
+    }
+}