seleniumgenic

Utilities to improve projects that utilize selenium-webdriver. Provides foundational classes for Page and Page Component Objects to help modularize and organize code which leads to improved readability, maintainability, and reusability. Also provides other utilities to aid in common tasks/scenarios.

Implemented in an un-opinionated way providing an easy to understand and use API.

Install

npm install -S seleniumgenic

Contents

• seleniumgenic
• Install
• Contents
• Usage
  • Component Objects
  • Page Objects
  • Put It Together
• Details
  • Component Objects
    • Import
    • Constructor
    • clear() => Promise
    • click() => Promise
    • contextClick() => Promise
    • createComponent(props) => Component
    • createComponents(props) => Promise<Array>
    • doubleClick() => Promise
    • dragAndDropTo(target) => Promise
    • getAttribute(attrName) => Promise<String|null>
    • getCssValue(property) => Promise<String|null>
    • getRect() => Promise<{height: Number, width: Number, x: Number, y: Number}>
    • getTagName() => Promise
    • getText(raw = false) => Promise
    • hoverClick() => Promise
    • isDisplayed() => Promise
    • isEnabled() => Promise
    • isPresent() => Promise
    • isSelected() => Promise
    • sendKeys(...args) => Promise
    • submit() => Promise
    • takeScreenshot() => Promise
    • waitUntilIsDisplayed(timeout = 10000) => Promise
    • waitUntilIsEnabled(timeout = 10000) => Promise
    • waitUntilIsPresent(timeout = 10000) => Promise
    • waitUntilIsSelected(timeout = 10000) => Promise
  • Page Objects
    • Import
    • Constructor
    • getTitle() => Promise
    • createComponent(props) => Component
    • createComponents(props) => Promise<Array>

Usage

Component Objects

// components/login-form.js
const { Component } = require('seleniumgenic');
const { By } = require('selenium');

class LoginForm extends Component {
    get UsernameInput() {
        return this.createComponent({
            by: By.id('username')
        });
    }

    get PasswordInput() {
        return this.createComponent({
            by: By.id('password')
        });
    }

    get LoginButton() {
        return this.createComponent({
            by: By.id('login')
        });
    }

    async login({ username, password }) {
        await this.UsernameInput.sendKeys(username);
        await this.PasswordInput.sendKeys(password);
        return this.LoginButton.click();
    }
}

module.exports = LoginForm;

Page Objects

// login-page.js
const { Page, Component } = require('seleniumgenic');
const LoginForm = require('./components/login-form');
const { By } = require('selenium-webdriver');

class LoginPage extends Page {
    get LoginForm() {
        return this.createComponent({
            by: By.className('login-panel'),
            componentClass: LoginForm
        });
    }

    get RegisterLink() {
        return this.createComponent({
            by: By.id('register')
        })
    }

    goTo() {
        return this._driver.get('url to login page');
    }
}

Put It Together

// main.js
require('chromedriver');
const { Builder } = require('selenium-webdriver');
const LoginPage = Require('./login-page');

(async function() {
    try {
        const driver = await new Builder().forBrowser('chrome').build();
        const LoginPage = new LoginPage({ driver });
        await LoginPage.goTo();
        await LoginPage.LoginForm.login({ username: 'joe', password: 'abcd1234' });
    } catch(err) {
        console.error(err);
    } finally {
        await driver.quit();
    }
})();

Details

seleniumgenic has zero dependencies. It just takes in a given Selenium WebDriver instance and works with it's API. Since the suites of core Selenium packages are constantly updating and only work with the latest versions of browsers, it will be the aim to keep seleniumgenic always working with the latest versions of the selenium-webdriver.

Component Objects

Component Objects represent individual or groups of elements on a page. Like with the example above, components could be the individual INPUT elements, or represent a Login form that might be reused on multiple pages in an application.

Import

const { Component } = require('seleniumgenic');

Constructor

Creates a Component instance. Takes a single props object as a parameter. Either a Selenium By or Selenium WebElement must be provided.

TIP: While Components can be created via the Constructor, it is highly recommended to make use of the createComponent(s) functions of Page and Component classes as they will take care of creating the Component instance with proper driver and scope properties as well as determining if the By or WebElement should be utilized.

Props

• driver: The current Selenium WebDriver instance. Required.
• by: The Selenium By that is used to locate the Component. If not provided, webElement must be provided.
• scope: The scope in which to use the By to locate the Component. Must be a WebDriver or Component. Optional, will default to the driver if not provided.
• webElement: The Selenium WebElement object that represents the Component. If not provided, by must be provided.

clear() => Promise

Clears the value if this Component represents an INPUT or TEXTAREA element.

click() => Promise

Clicks this Component.

contextClick() => Promise

Performs a context/right click on this Component.

createComponent(props) => Component

Convenience method for instantiating a Component within the scope of this Component.

props

• by: The Selenium By that is used to locate the Component. Required.
• componentClass: The class/type of Component that the Component should be created as. Optional, will default to Component class.

createComponents(props) => Promise<Array>

Creates an array of Components within the scope of this Component.

props

• by: The Selenium By that is used to locate the Components. Required.
• componentClass: The class/type of Component that the Components should be created as. Optional, will default to Component class.

doubleClick() => Promise

Performs a double left-click on this Component.

dragAndDropTo(target) => Promise

Performs a drag-and-drop of this Component to another Component.

• target: The Component that this Component is to be dropped on.

getAttribute(attrName) => Promise<String|null>

Gets the current value of the given attribute of this Component.

getCssValue(property) => Promise<String|null>

Gets the value of a CSS style of this Component.

getRect() => Promise<{height: Number, width: Number, x: Number, y: Number}>

Gets an object that describes this Component's location and size.

getTagName() => Promise

Gets the Components HTML tag name.

getText(raw = false) => Promise

Gets the text contained within this Component. The default is to get the text as it is visually displayed to the user. The 'raw' flag can be used to ge the text as it is provided to the HTML of the page.

• raw: Boolean, flag that indicates if the text should be retrieved in its raw form.

hoverClick() => Promise

Performs the actions of hovering the mouse over the Component and then left-clicking it. Great for Components that are not displayed or able to be interacted with unless the Component is hovered over first.

isDisplayed() => Promise

Gets a value indicating if the Component is currently displayed.

isEnabled() => Promise

Gets a value indicating if the Component is currently enabled.

isPresent() => Promise

Gets a value indicating if the Component is present (exists).

isSelected() => Promise

Gets a value indicating if the Component is currently selected.

sendKeys(...args) => Promise

Types a key sequence on the DOM element that this Component represents. See WebElement.sendKeys() for more details.

submit() => Promise

Submits the form that this Component is part of, or the form itself if this Component represents a FORM element.

takeScreenshot() => Promise

Takes a screenshot of visible area of this Component and returns the base-64 encoded PNG.

• scroll: Indicates if the Component should be scrolled into view to take the screenshot. Optional.

waitUntilIsDisplayed(timeout = 10000) => Promise

Waits until the Component is displayed.

• timeout: The max amount of time (ms) to wait for the condition to be true. Optional, default is 10000.

waitUntilIsEnabled(timeout = 10000) => Promise

Waits until the Component is enabled.

• timeout: The max amount of time (ms) to wait for the condition to be true. Optional, default is 10000.

waitUntilIsPresent(timeout = 10000) => Promise

Waits until the Component is present.

• timeout: The max amount of time (ms) to wait for the condition to be true. Optional, default is 10000.

waitUntilIsSelected(timeout = 10000) => Promise

Waits until the Component is selected.

• timeout: The max amount of time (ms) to wait for the condition to be true. Optional, default is 10000.

Page Objects

Page Objects represent individual pages of a Web Application and represent collections of Components.

Import

const { Page } = require('seleniumgenic');

Constructor

Creates a Page instance. Takes a single props object as a parameter.

Props

• driver: The current Selenium WebDriver instance. Required.

getTitle() => Promise

Gets the current page title.

createComponent(props) => Component

Convenience method for instantiating a Component within the scope of this Page.

props

• by: The Selenium By that is used to locate the Component. Required.
• componentClass: The class/type of Component that the Component should be created as. Optional, will default to Component class.

createComponents(props) => Promise<Array>

Creates an array of Components within the scope of this Page.

props

• by: The Selenium By that is used to locate the Components. Required.
• componentClass: The class/type of Component that the Components should be created as. Optional, will default to Component class.