node package manager

bby-page-objects

Best Buy Automation Page Objects

A general purpose page object framework for writing tests in webdriver.

Getting started with bby page objects

Installation

npm install bby-page-objects -g 
# or locally
npm install bby-page-objects --save
// during post-install it will ask to generate a config and install selenium with chrome/firefox adapters
 
// if you want to install and run selenium manually, do the following
// install selenium:
./node_modules/.bin/selenium-standalone install 
// run selenium by doing:
./node_modules/.bin/selenium-standalone start

Getting started

If you want to get started right away, you can require in the init bootstrap file bby-page-objects/init, that will startup selenium and configure webdriver for you. It exports a single function initPageObject(viewSize, logOutput) and returns a promise that resolves a page:

// this is a basic example of how to automate searching for headphones
var initPageObject = require('bby-page-objects/init')
 
initPageObject('l', true).then(function(page) {
    page.header
        .search('headphones')
        .pause(5000)
        .close()
})

BBY Page Objects comes with a cli tool that you can use to run your scripts, you can use it if you want to run your page object scripts with async/await support, here's what the script above would look like using the cli tool:

initPageObject('l', true)
    .then(async(page) => {
        await page.header.search('headphones')
        await browser.pause(5000).close()
    })

Then run the following command:

bby-page [your-file]

initPageObject API

  • viewSize: the viewSize of the page objects, defaults to true
  • outputLog: whether or not to output selenium logs, defaults to true

bby-page command line tool

bby-page is a CLI tool that is bundled with the page objects framework, it allows you to do the following things:

  • run page object scripts/files (with support for async/await)
  • generates a config file
  • opens the documentation server

Here's an example of how it works:

bby-page -f [your-file] # run a page object script
bby-page -d # start the documentation server
bby-page -g # generate a page object config file

Running the documentation server

It's highly recommended that you run the documentation server to get familiar with page objects, you can run the documentation server as follows:

bby-page -d
# open documentation server at: http://localhost:8888

Configuration

Open bby-page-objects.config.js and you can change the following settings:

Local Configuration (for development)

  • browser: browser can be either firefox, chrome, or phantomjs
  • baseUrl: the first url to initialize webdriver with
  • documentation : documentation server options, you shouldn't usually have to change this
    • baseUrl : the base url for the documentation server, defaults to http://localhost
    • port : the port for the documentation server, defaults to 8888
    • path : the path for the entry page on the documentation server, defaults to DOCS.md
    • openOnStart : opens the documentation server when you start the development environment defaults to true
  • autoReload: reloads the framework when page object models are changed, defaults to true (only applies during local development)

User Configuration

  • webdriver: webdriver options
    • host: hostname
    • port: port to run webdriver on
    • desiredCapabilities: list of webdriver capabilities
      • browserName: name of browser to use, can be chrome, firefox or phantomjs
  • browserPosition: position of where to start the browser at
  • baseUrl: the first url to initialize webdriver with
  • documentation : documentation server options, you shouldn't usually have to change this
    • baseUrl : the base url for the documentation server, defaults to http://localhost
    • port : the port for the documentation server, defaults to 8888
    • path : the path for the entry page on the documentation server, defaults to DOCS.md
    • openOnStart : opens the documentation server when you start the development environment defaults to true
  • phantomOpts: PhantomJS options, if using PhantomJS

Example configurations

Chrome

// personal config
module.exports = {
    webdriver: {
        host: 'localhost',
        port: 4444,
        desiredCapabilities: {
            browserName: "chrome" 
        }
    },
    browserPosition: "left", // left or right
    baseUrl: "http://www.bestbuy.com",
    documentation: {
        baseUrl: 'http://localhost:',
        port: 8888,
        path: 'DOCS.md',
        openOnStart: true
    },
    autoReload: true,
    phantomOpts: {}
}

Firefox

NOTE : to ensure that you can use the firefox selenium adapter https://ftp.mozilla.org/pub/firefox/releases/45.0/ and make sure to DISABLE UPDATES.

// personal config
module.exports = {
    webdriver: {
        host: 'localhost',
        port: 4444,
        desiredCapabilities: {
            seleniumProtocol: 'WebDriver',
            browserName: "firefox" 
        }
    },
    browserPosition: "left", // left or right
    baseUrl: "http://www.bestbuy.com",
    documentation: {
        baseUrl: 'http://localhost:',
        port: 8888,
        path: 'DOCS.md',
        openOnStart: true
    },
    autoReload: true,
    phantomOpts: {}
}

PhantomJS

// personal config, note that you can
// add phantomjs options via phantomOpts
module.exports = {
    webdriver: {
        host: 'localhost',
        port: 4444,
        desiredCapabilities: {
            browserName: "phantomjs" 
        }
    },
    browserPosition: "left", // left or right
    baseUrl: "http://www.bestbuy.com",
    documentation: {
        baseUrl: 'http://localhost:',
        port: 8888,
        path: 'DOCS.md',
        openOnStart: true
    },
    autoReload: true,
    phantomOpts: {}
}

Using the Framework as an es6 consumer

If you want to use the framework with an es6 consumer, you need to do the following:

// npm link the module locally and then:
import PageObjects from 'bby-page-objects/src/index';

Contributing and developing page objects

Before you get started with development run the following:

# after checking out the repo
npm install
npm run patch # patches sourcemap files
npm run selenium-install # installs local version of selenium
npm run gen-config # generate your personal config file

Real time page object model development

Real time page object model development is way to interact with your page models without writing tests first. It's kind of like a REPL for your page objects. It will automatically launch:

  • a selenium instance via webdriver
  • a devtool instance loaded with the page object framework
  • it also creates convenience globals to use in the console:
    • browser: the webdriver instance, you can any method defined at http://webdriver.io/api.html
    • reload(cacheUrl): close the current session and reload a new session, pass in cacheUrl as true/false to preserve your session
    • switchView(view): toggle between large and small view, pass in "l" or "s"
    • Page: the collection of all your defined page objects
    • help: display a table of methods/commands available

Writing page objects in dev mode

To speed up the process of writing page objects, you can run tests in a "dev" mode, this also allows you to access the page objects and experiment with them, run the following command to start up the test environment in dev mode:

npm start

It should launch an instance of devtool and a browser window for either chrome or firefox depending on your configuration.

Page objects

Page objects are the abstraction that helps you write the test without worrying about what the dom structure looks like. If you launched the test dev environment, you can access the documentation locally at http://localhost:8888 (although it should automatically open up a new window/tab with the documentation). To experiment and play around with page objects, you can simply type the variable Page. (with the dot) and you should see a list of available objects and methods.