Page Object API

Overview

Page objects provide an additional layer of abstraction for test case creation. Page objects are defined in modules and parsed into factory functions that create page object instances.

For an introduction to the Page Object Model in Nightwatch, refer to the Getting started guide.

Page object module

Name Type description
commands Array A list of objects containing functions to represent methods added to the page object instance.
elements Object | Array An object, or array of objects, of named element definitions to be used as element selectors within element commands called from the page object.
props Object | Function An object or a function returning an object representing a container for user variables. Props objects are copied directly into the props property of the page object instance.
sections Object An object of named sections definitions defining the sections within the page object.
url String | Function A url or function returning a url to be used in a url() command when the page's navigate() method is called.

Page object instance

Page object module definitions are used to define page object instances when their respective factory functions within the page reference of the standard command API is called.

const myPageObject = browser.page.MyPage(); // defined in MyPage.js module

Every time a factory function like MyPage above is called, a new instance of the page object is created.

Properties




Name Type description
api Object A reference providing access to the full Nightwatch command API, usually known as browser in test cases. This is used to access those commands that are not part of the subset of commands within the page object API.
elements Object A map of Element objects used by element selectors.
name string The name of the page object as defined by its module name (not including the extension). This is the same name used to access the page object factory from the page reference in the command API.
props Object A reference to props object assigned from the module definition.

Note: this will be the same props object for all instances of the page object if defined as an object instance within the page object module. If you wish for each props object to be unique, define props in the module as a function that would return a new props object for each new page object instance.
section Object A map of Sections objects defined for the page object. This will only contain sections within the page object module's root sections definition. Nested sections are accessible through their parent section's own section reference.
url string|Function The url value from the page object module, either a string or a function depending on how it was defined there.

Example

module.exports = {
  // can be string or function
  url: function () {
    return this.api.launchUrl;
  },
  elements: {
    // shorthand, specifies selector
    mySubmitButton: 'input[type=submit]'
    

    // full
    myTextInput: {
      selector: 'input[type=text]',
      locateStrategy: 'css selector'
    }
  },
  commands: [
    {
      myCustomPause: function () {
        this.api.pause(this.props.myPauseTime);
      }
    }
  ],
  // object version (best considered immutable)
  props: {
    myPauseTime: 1000
  },
  

  sections: {
    myFooterSection: {
      selector: '#my-footer',
      locateStrategy: 'css selector',
      elements: {
        myLogo: {
          selector: '.my-logo',
          locateStrategy: 'css selector'
        }
      },
      commands: [
        {
          myMoveToLogo: function () {
            this.moveToElement('@myLogo', this.props.myLogoX, this.props.myLogoY);
          }
        }
      ],
      // function version (recommended)
      props: function () {
        return {
          myLogoX: 10,
          myLogoY: 10
        };
      },
      sections: {
        // additional, nested sections
      }
    }
  }
};

Page Object Methods

.navigate()

Navigates to the resolved url defined for the page object using the command API's url() command. This command is generally used in place of the command API's url() when working with page objects because the url member of the page object is the user-defined url string or function and not the call used to navigate to a url.

Element Instances

Element instances encapsulate the definition used to handle element selectors. Generally you won't need to access them directly, instead referring to them using their @-prefixed names for selector arguments, but they are available through a page object or section's elements property.

Section Instances

For an introduction to creating sections, see the Define Sections guide page.

Page object section instances are accessed from the section property of a page object instance (note that this is the singular version of "section" whereas the plural version, "sections", was used in the module definition).

Sections are created automatically through the page object factory and are available directly as properties from the section reference.

const myPageObject = browser.page.MyPage();
const mySection = myPageObject.section.MySection; // from a `sections: {}` block in page object

Page Object Commands

For an introduction to writing page object custom commands, see the Writing page-specific commands guide page.



Name Type description
commands Array A list of objects containing functions to represent methods added to the page object instance.

Page object commands considerations

Page object commands in the module root commands are not available in child sections and section commands are not available in parent sections or the root page object.

  • Context: Page object command context (the value of this) is the page object (for sections it's the section instance);
  • Execution: Page object commands are not called from within the command queue. Code in a page object command is executed immediately when the function is called;
  • Chaining: Page object commands must return a value for chaining. This can be anything, but it's recommended you stick to this to allow your commands to be chained in the context of the page object instance.