Principle:Nightwatchjs Nightwatch Element And Section Mapping
| Knowledge Sources | |
|---|---|
| Domains | Testing, Page_Object_Model, Element_Mapping |
| Last Updated | 2026-02-12 00:00 GMT |
Overview
A hierarchical element cataloging pattern that maps named identifiers to DOM selectors, organized into flat elements and nested sections.
Description
Element and Section Mapping establishes the connection between human-readable names and actual DOM selectors within a page object. Elements are flat key-value pairs mapping a name to a selector. Sections are nested containers that scope element lookups to a parent DOM node, preventing selector collisions and modeling the page's visual hierarchy.
This separation allows tests to reference elements by semantic names (e.g., @searchBar) rather than brittle CSS selectors, and sections to group related elements (e.g., a navigation menu's links, a form's fields).
Usage
Use element mapping for every interactive element that tests need to reference. Use sections when elements are logically grouped under a parent container (e.g., modal dialogs, navigation bars, form fieldsets).
Theoretical Basis
Element mapping follows a two-tier addressing scheme:
- Flat elements: Accessible via @elementName alias directly on the page object
- Section elements: Accessible via page.section.sectionName then @elementName within that section scope
Sections support nesting: a section can contain sub-sections, creating a tree structure that mirrors the DOM hierarchy.