Implementation:Nightwatchjs Nightwatch Element And Section Configuration

Knowledge Sources	Nightwatch Nightwatch Page Object Elements
Domains	Testing, Page_Object_Model, Element_Mapping
Last Updated	2026-02-12 00:00 GMT

Overview

Configuration pattern for mapping named elements and hierarchical sections within Nightwatch.js page objects.

Description

Elements are defined as properties of the elements object in a page object module. Each element can be a simple string (CSS selector) or an object with selector, locateStrategy, and index properties. Sections are defined in the sections object, each with its own selector, elements, and optional nested sections and commands. Elements within sections are scoped to the section's parent selector.

Usage

Define elements and sections in every page object to create a maintainable selector catalog. Use the @ prefix to reference elements by name in commands and assertions.

Code Reference

Source Location

• Repository: nightwatch
• File: examples/pages/google/consent.js (lines 49-64)
• File: examples/pages/google/searchResults.js (lines 18-50)
• File: types/page-object.d.ts (lines 24-143, 275-323)

Signature

// Element definition
elements: {
  [name: string]: string | {
    selector: string,
    locateStrategy?: 'css selector' | 'xpath' | 'link text' | 'partial link text' | 'tag name',
    index?: number  // nth match, default 0
  }
}

// Section definition
sections: {
  [name: string]: {
    selector: string,
    locateStrategy?: string,
    elements: { [name: string]: string | ElementProperties },
    sections?: { [name: string]: SectionProperties },
    commands?: Array<Object> | Class
  }
}

Import

// Defined within a page object module - no separate import

I/O Contract

Inputs

Name	Type	Required	Description
selector	string	Yes	CSS or XPath selector for the element or section root
locateStrategy	string	No	Selector strategy: 'css selector' (default), 'xpath', 'link text', etc.
index	number	No	Which match to use when multiple elements match (default: 0)

Outputs

Name	Type	Description
@elementName	Element reference	Accessible via @ prefix in page object commands and assertions
page.section.sectionName	Section object	Section instance with its own elements, sections, and commands

Usage Examples

Elements with Different Strategies

module.exports = {
  elements: {
    // Simple CSS selector
    searchBar: 'textarea[name=q]',

    // Object with explicit strategy
    submitButton: {
      selector: 'input[value="Google Search"]'
    },

    // XPath selector
    heading: {
      selector: '//h1[contains(text(), "Welcome")]',
      locateStrategy: 'xpath'
    }
  }
};

Sections with Nested Elements

const createSectionFor = (text) => {
  return {
    selector: '//div[contains(.,"' + text + '")]',
    locateStrategy: 'xpath',
    elements: {
      turnOffButton: 'button[aria-label^="Turn off"]'
    }
  };
};

module.exports = {
  elements: {
    consentModal: 'form[action^="https://consent.google"]'
  },

  sections: {
    customizeSearch: createSectionFor('Search customization'),
    youtubeHistory: createSectionFor('YouTube History'),

    consentForm: {
      selector: 'form[action^="https://consent.google"]',
      elements: {
        submitButton: 'button'
      }
    }
  }
};

Related Pages

Implements Principle

• Principle:Nightwatchjs_Nightwatch_Element_And_Section_Mapping