NPM Version License Code Coverage JavaScript Style Guide

The purpose of test-automation is to provide some scaffolding on top of protractor to follow a Page Object pattern for Automated browser tests. The framework contains some classes to help structure and automate your tests. This is developed in parallel with the test-automation-starter kit as the framework the Docker implementation is built upon. The starter kit has more of a complete example than what is provided below. The intent of the project is to provide the necessary tools and a starting point to rapidly develop automated browser tests.



Install using npm:

npm install --save mocha protractor test-automation


The framework consists of two main classes: Fragment and Sequence.


A Fragment is the Page Object, a reusable group of HTML element references that can be tested. For instance, a top level navigation bar is a reusable group of HTML elements that could show up on many pages. It can be used as a shared Fragment component that can be associated with other Fragments. If you have unique content on the home page, you can make a home page Fragment that is associated with your navigation Fragment above. The purpose of a Fragment is for testing its elements and optionally performing actions against its elements.

Fragment provides basic testing functionality for getting/setting elements stored in a Map. It also provides some basic test methods to test any child fragments as well as check if the elements exist on the page. To perform more complex tests, extend the functionality of the class with additional test methods as needed. Don't forget to override testElements to call your new methods after calling await super.testElements() to run the provided test methods.

  • NOTE: Elements must be defined on a Fragment object before any tests can occur.
  • NOTE: Any additional action methods/classes will need to be added per use case, requests for common Actions are welcome. (element api, element.all api)


A Sequence defines the steps an automated browser test specification needs to perform. It is also responsible to setting the entry point to the test sequence. It provides a Fragment cache to reference for each step in the sequence that will need to be defined.

I've started out with some basics and will be adding more over time (and open to feature requests).


Click on the link in the header above to go to the API page.


Here is a simple example of an implementation using test-automation. When testing a larger site with many tests, you will want to consider some structure around your code. I've added a suggested minimal folder structure below. I have also created a starter kit that contains a more advanced test than below with additional support scripts and environment/execution specifics.


  • ./constants.js

    // Selectors
    export const IMG_SELECTOR = '#hplogo'
    // Fragments
    export const GOOGLE_FRAGMENT = Symbol('google fragment')
  • ./fragments/GoogleFragment.js

    import { IMG_SELECTOR } from '../constants'
    import { Fragment } from 'test-automation'
    export default class GoogleFragment extends Fragment {
      constructor(fragments) {
  • ./sequences/GoogleSequence.js

    import { GOOGLE_FRAGMENT } from '../constants'
    import { Sequence } from 'test-automation'
    import GoogleFragment from '../fragments/GoogleFragment'
    export default class GoogleSequence extends Sequence {
      constructor() {
        this.setFragment(GOOGLE_FRAGMENT, new GoogleFragment())
        this.setStep(() => this.getUrl('/'))
  • ./specs/google.spec.js

    import GoogleSequence from '../sequences/GoogleSequence'
    browser.ignoreSynchronization = true
    describe('google homepage img test', () => {
      let googleSequence
      before(() => {
        googleSequence = new GoogleSequence()
      it('expects img to exist on the google homepage', async () => {
        await googleSequence.runSequence()
      after(() => {
        googleSequence = null


  • ./conf/config.js

    exports.config = {
      directConnect: true,
      capabilities: {
        browserName: 'chrome',
        platform: 'ANY',
        version: ''
      baseUrl: 'https://www.google.com',
      framework: 'mocha',
      mochaOpts: {
        reporter: 'spec',
        timeout: 5000
      specs: ['../dist/**/*spec.js']
    • NOTE: This configuration was used to run protractor on Ubuntu 18.04 LTS.