@zohodesk/testinglibrary 0.0.42-n20-experimental → 0.0.44-n20-experimental

package/.github/styleGuides/POM_README.md

@@ -1,602 +0,0 @@
-# Page Object Model (POM) Structure Guide
-
-## Purpose
-
-This document describes the recommended structure, format, and creation rules for Page Object Model files used in this testing framework.
-
-> **Related guide:** Selector file structure, naming rules, and `dom-selectors/` conventions are documented separately in [DomSelectors_README.md](./DomSelectors_README.md).
-
-
-## What Each Folder Should Contain
-
-### `page-object-model/`
-
-Store reusable page factory functions and lightweight page access helpers here.
-
-Examples:
-
-- one file per major page or panel
-- one `index.js` barrel export file re-exporting all POMs in the module
-- methods for navigation, element access, and user actions
-
-> Full module folder hierarchy — see [Steps_README.md §1](./Steps_README.md#1-file--folder-structure).
-
-
-## Recommended POM Design
-
-This section describes what a well-structured POM should look like.
-
-Use it for design guidance such as class structure, method style, and separation of responsibilities.
-
-### 1. One factory function per page or panel
-
-Create one factory function for each meaningful UI surface. Factory functions are initialized with a shared context object.
-
-> Full context object shape with types — see [Steps_README.md §4](./Steps_README.md#4-context-destructuring).
-
-Each factory destructures only the properties it needs:
-
-```javascript
-TicketCommentsPanel({ page, i18N, actorContext })
-```
-
-Avoid passing the whole context object through to individual methods — destructure at the factory level.
-
-Examples:
-
-- `SetupHomePage`
-- `SetupMenuPanel`
-- `TicketDetailsPage`
-- `TicketCommentsPanel`
-
-Avoid putting unrelated flows in the same factory function.
-
-### 2. Expose meaningful methods
-
-Methods should represent business or UI actions.
-
-Good examples:
-
-- `openTicket(subject)`
-- `addComment(text)`
-- `deleteComment(text)`
-- `searchMenuPanel(keyword)`
-
-Avoid low-value names like:
-
-- `clickButton1()`
-- `fillField2()`
-
-### 3. Separate selectors from actions when needed
-
-Keep raw locator definitions in `dom-selectors/` and keep reusable interaction logic in the page object.
-
-Use this split:
-
-- `dom-selectors/` stores selector constants or selector helper functions — see [DomSelectors_README.md](./DomSelectors_README.md)
-- `page-object-model/` exposes business-friendly methods such as `openTicket()` and `addComment()`
-- step files should call page object methods instead of repeating selector details
-
-
-## Suggested POM File Format
-
-A page object file should usually contain:
-
-1. imports
-2. selector imports if needed
-3. factory function definition destructuring the required properties from the shared context object
-4. locator getter methods using `page` from the closure
-5. action methods using `i18N`, `getMetaInfo`, `cacheLayer`, `executionContext`, or `actorContext` as needed from the closure
-6. optional state access helpers
-7. named export
-
-Example:
-
-```javascript
-import { TicketSelectors } from '../dom-selectors/TicketSelectors';
-
-// Destructure only the context properties this POM needs
-const TicketCommentsPanel = ({ page, i18N, actorContext }) => {
-  const getCommentInput = () => page.locator(TicketSelectors.COMMENT_INPUT);
-
-  const getSaveCommentButton = () => page.locator(TicketSelectors.SAVE_COMMENT);
-
-  const addComment = async (commentText) => {
-    await getCommentInput().fill(commentText);
-    await getSaveCommentButton().click();
-  };
-
-  const getCommentLocator = async (commentKey) => page.getByText(await i18N(commentKey));
-
-  const getActorName = () => actorContext.name;
-
-  return { getCommentInput, getSaveCommentButton, addComment, getCommentLocator, getActorName };
-};
-
-export { TicketCommentsPanel };
-```
-
-## Rules for POM Creation
-
-Before creating a new POM file, check whether an existing POM in the same module can be reused or extended.
-
-
-### Rule 1: Place page objects inside the relevant module
-
-Keep module-specific page objects inside that module's `page-object-model/` folder.
-
-Example:
-
-```text
-test-slices/uat/modules/Ticket/page-object-model/TicketDetailsPage.js
-```
-
-### Rule 2: Match file names to responsibility
-
-Use file names that reflect the page or component responsibility.
-
-POM files must use PascalCase:
-
-- `TicketDetailsPage.js`
-- `TicketCommentsPanel.js`
-- `SetupHomePage.js`
-- `SetupPages.js`
-
-For selector file naming conventions, see [DomSelectors_README.md](./DomSelectors_README.md).
-
-### Rule 3: Use page objects for reusable UI logic only
-
-Move these into page objects:
-
-- navigation helpers
-- locator access
-- repeated button clicks
-- text input flows
-- reusable UI workflows
-- state access helpers
-
-Keep these out of page objects when possible:
-
-- feature wording
-- business rules
-- scenario decision-making
-- workflow orchestration across unrelated modules
-- test-specific branching based on expected business outcomes
-
-### Rule 4: Prefer stable selectors
-
-Prefer robust selectors — see [DomSelectors_README.md](./DomSelectors_README.md) for the full list of preferred selector types and rules on stable selector usage.
-
-When a page has multiple similar elements, scope the locator to the nearest stable parent container before locating the child element.
-
-Example:
-
-- good: find the comment composer first, then locate the save button inside it
-- weak: call `page.getByRole(...).first()` on the full page when multiple matching buttons may exist
-
-
-### Rule 5: Keep assertions outside POM
-
-Page object files must contain only UI interaction logic and state access helpers.
-
-POM files must not contain:
-
-- assertion helper imports
-- reusable validation logic
-- scenario outcome checks
-- methods that both read UI state and validate the result in the same place
-
-Preferred pattern:
-
-- good: the page object returns a locator, text, value, count, or state, and validation is performed in the step file or `assertions/`
-- weak: the page object clicks, reads UI state, and decides whether the scenario passed
-
-### Where to place assertions: `assertions/` vs step file vs POM
-
-Assertions can live in exactly two places — never in a POM:
-
-| Place it here | When |
-|---|---|
-| **Inline in the step definition** | The assertion is used in only **one** spec file, or is a simple one-liner (`Assertions.isElementVisible(elem)`) |
-| **`assertions/` module file** | The **same locator-read + assertion combination** appears in **2 or more different spec files** |
-| **POM file** | **Never** — POMs return locators/values; they do not validate |
-
-**Decision flow:**
-
-1. Write the assertion inline in the `Then` step.
-2. If you later find the same assertion needed in a second spec file, extract it into `assertions/<ModuleName>Assertions.js`.
-3. The assertion file receives a **locator or value** from a POM method — it never calls POM methods itself.
-4. If the assertion is a single Playwright `expect()` call with no POM interaction, keep it inline — extraction adds no value.
-
-**What belongs in an assertion file:**
-
-- A function that accepts a locator, value, or element and runs one or more `Assertions.*` / `expect()` calls.
-- Assertion files must not import POMs, must not perform clicks or navigation, and must not contain `Given`/`When`/`Then` steps.
-
-```javascript
-// assertions/ContractAssertions.js
-import Assertions from '../../_assertions/Assertions';
-
-const ContractAssertions = {
-  async verifyContractStatus(statusElement, expectedStatus) {
-    await Assertions.isElementVisible(statusElement);
-    await Assertions.isElementHaveText(statusElement, expectedStatus);
-  },
-};
-
-export default ContractAssertions;
-```
-
-```javascript
-// In a step file — uses POM to get the element, then passes to assertion
-Then('the contract status should be {string}', async ({ page, i18N }, status) => {
-    const detailView = ContractsDetailView({ page, i18N });
-    const statusElem = detailView.getStatusElement();
-    await ContractAssertions.verifyContractStatus(statusElem, status);
-});
-```
-
-
-### Rule 6: Return locators from getter methods
-
-When an element is reused multiple times, create getter methods.
-
-Getter methods (e.g., `getSearchInput()`) must return a **Playwright Locator** — not an awaited value. Do not `await` inside a getter. Action methods (e.g., `clickSave()`) are async and `await` Playwright actions internally.
-
-Example:
-
-- `getSearchInput()` — returns `page.locator(...)` (synchronous, returns Locator)
-- `getSetupMenu(menuName)` — returns `page.locator(...)` (synchronous, returns Locator)
-- `clickSave()` — async, awaits `click()` internally
-
-### Rule 7: Use async methods for UI actions
-
-Any method that interacts with the browser should be `async` and should `await` Playwright actions.
-
-### Rule 8: Keep methods focused
-
-A method should do one clear thing.
-
-Good:
-
-- `openSetupPage(moduleName)`
-- `clearSearchInput()`
-- `openTicketDetail(subject)`
-
-Avoid very large methods that perform unrelated actions.
-
-### Rule 9: Reuse shared helper files when useful
-
-A helper file can be used to create and return page object instances.
-
-Example pattern:
-
-- `SetupPages.js` returns `getHomePage(context)` and `getSetupMenuPanel(context)`, where `context` is the shared context object passed from the step file
-
-This is useful when multiple step files use the same objects.
-
-
-### Rule 10: No arbitrary waits
-
-Do not use hard waits or time-based delays in POM files.
-
-> Full waiting patterns, `networkidle` warnings, and DOM readiness guidance — see [Steps_README.md §10](./Steps_README.md#10-helper-functions--utilities).
-
-Key rule: use only explicit readiness checks (`element.waitFor()`, stable container visibility, or required network completion when it is part of the UI flow). Never use `page.waitForTimeout()`.
-
-### Rule 11: No static or hardcoded locators in POM files
-
-Do not define raw locator strings directly inside POM action methods.
-
-Required rule:
-
-- reusable selectors must live in `dom-selectors/` — see [DomSelectors_README.md](./DomSelectors_README.md)
-- dynamic selector patterns must be implemented as selector helper functions in `dom-selectors/`
-- POM files must import selectors instead of embedding raw locator strings
-
-Use text-based location only when there is no stable selector and the text is part of the intentional UI contract.
-
-### Rule 12: Design POMs for order-independent execution
-
-POM design must support order-independent execution.
-
-Do not rely on:
-
-- previously executed scenarios
-- cached mutable state shared across tests
-- data created implicitly by earlier scenarios
-
-Every scenario must prepare, create, or receive the state it needs explicitly.
-
-For random-order-safe automation:
-
-- never use `.first()` or `.last()` to resolve ambiguity
-- never rely on visual order
-- prefer unique ids, record ids, or returned API/UI identifiers
-
-If multiple records may share similar visible text, resolve the exact record through a stable identifier instead of choosing the first visible match.
-
-Better pattern example:
-
-```javascript
-import { TicketSelectors } from '../dom-selectors/TicketSelectors';
-
-const TicketListPage = ({ page }) => {
-  const getSubjectCell = (subject) =>
-    page.locator(ticketSelectors.SUBJECT_CELL).getByText(subject, { exact: true });
-
-  const getTicketIdBySubject = async (subject) => {
-    const subjectCell = getSubjectCell(subject);
-    await subjectCell.waitFor();
-    const dataId = await subjectCell.getAttribute('data-id');
-    return dataId?.replace('subject_', '');
-  };
-
-  const getTicketRowById = (ticketId) =>
-    page.locator(ticketSelectors.ticketRowById(ticketId));
-
-  const getTicketRow = async (subject) => {
-    const ticketId = await getTicketIdBySubject(subject);
-    return getTicketRowById(ticketId);
-  };
-
-  return { getSubjectCell, getTicketIdBySubject, getTicketRowById, getTicketRow };
-};
-```
-
-### Rule 13: Validate DOM readiness before any action
-
-Before clicking, filling, hovering, selecting, or submitting, validate that the UI is ready.
-
-`await element.waitFor()` defaults to `{ state: 'visible' }`. Always call it before `click()`, `fill()`, `hover()`, `selectOption()`, or `check()`. Use `{ state: 'hidden' }` only when waiting for an element to disappear. Use `{ state: 'attached' }` only when the element is expected to exist but may not yet be visible.
-
-Preferred sequence:
-
-1. locate a stable parent container or target element
-2. call `await element.waitFor()` to confirm readiness
-3. perform the action
-
-Do not perform actions against elements that may still be loading, hidden, detached, or stale.
-
-
-### Rule 14: File names must follow naming conventions
-
-File names must match the UI responsibility and use consistent naming.
-
-Required rules for POM files:
-
-- use descriptive PascalCase
-- file name should match the exported factory function name
-- prefer responsibility suffixes when applicable:
-  - `Page`
-  - `Panel`
-  - `Dialog`
-  - `Drawer`
-  - `Section`
-
-Recommended POM examples:
-
-- `ActivityListPage.js`
-- `ActivityDetailViewPage.js`
-- `AccountContractsPanel.js`
-
-Avoid names like:
-
-- `test.js`
-- `activityPOM.js`
-- `leftPanel.js`
-
-For selector file naming conventions, see [DomSelectors_README.md](./DomSelectors_README.md).
-
-> Rules 17 and 18 cover `dom-selectors/` file purity and selector duplication. See [DomSelectors_README.md](./DomSelectors_README.md).
-
-### Rule 15: Use factory functions initialized with a context object
-
-POMs must be defined as factory functions, not classes.
-
-Do not use `class`, `this`, `new`, `constructor`, or `prototype` in POM files. POMs must be plain functions that return plain objects.
-
-Factory functions accept a shared context object and destructure only the properties they need:
-
-```javascript
-// Destructure only what this POM uses
-const TicketDetailsPage = ({ page, i18N, getMetaInfo, actorContext }) => {
-  // All destructured properties are accessed via closure
-  return { ... };
-};
-```
-
-> Full context object shape with types — see [Steps_README.md §4](./Steps_README.md#4-context-destructuring).
-
-Required rules:
-
-- destructure only the properties the POM actually uses — do not accept and forward the full object
-- all destructured properties are accessed from the closure and never passed to individual methods
-- methods are returned as a plain object instead of relying on class instances
-- the factory is exported as a named export
-
-### Rule 16: Use barrel exports for local module POMs
-
-Each module must have an `index.js` file inside `page-object-model/` that re-exports all POMs in that module.
-
-> **Two barrels exist:** This barrel (`page-object-model/index.js`) re-exports only POM factory functions. The module root `index.js` (see [Steps_README.md §11](./Steps_README.md#11-barrel-exports-indexjs)) re-exports POMs, assertions, and utilities for cross-module use. Step files should import from the **module root barrel** (`'../index'`), not from `'../page-object-model/index'` directly.
-
-Required rules:
-
-- the POM barrel index must contain only named re-exports of POM factory functions
-- the module root `index.js` consumes this barrel and adds assertions and utilities
-
-Example barrel file:
-
-```javascript
-// page-object-model/index.js
-export { TicketDetailsPage } from './TicketDetailsPage';
-export { TicketCommentsPanel } from './TicketCommentsPanel';
-```
-
-Step files import from the module root barrel:
-
-```javascript
-import { TicketDetailsPage } from '../index';
-```
-
-### Rule 17: Use i18N for all user-facing strings
-
-All user-facing text matched in the UI must be resolved through `i18N`.
-
-**`i18N` is an async function** — always `await i18N('key')` before passing the result to a locator. Never write `i18N('key')` inline inside a Playwright locator call without awaiting first.
-
-**What counts as user-facing:** button labels, column headers, status values, error messages, placeholder text, tooltips, and menu items — any string a user can read in the UI.
-
-**What does NOT need i18N:** `data-test-id` values, `data-id` values, `id` attributes, `name` attributes, ARIA role names, CSS class names, and URL paths.
-
-Required rules:
-
-- destructure `i18N` from the shared context object in every POM factory that matches user-facing text
-- never hardcode translated strings directly in locator calls
-- use the `i18N` function as the single source for any text used in `getByText`, `getByLabel`, `getByPlaceholder`, or similar matchers
-
-Examples:
-
-- good: `page.getByText(await i18N('ticket.comments.save'))`
-- weak: `page.getByText('Save')`
-
-This ensures that tests remain valid across all supported locales.
-
-
-## POM Creation Workflow
-
-This section describes the order to follow when creating or updating a POM.
-
-It does not redefine the design rules. It shows how to apply them step by step.
-
-### Step 1: Identify the UI surface
-
-First, check whether a suitable POM already exists. Reuse or extend it if possible.
-
-Then decide whether the logic belongs to:
-
-- a full page
-- a side panel
-- a detail view
-- a reusable component
-
-### Step 2: Create the page object file
-
-Create or update the file under the module `page-object-model/` folder.
-
-### Step 3: Move selectors
-
-Create or update a `dom-selectors/` file and export selectors only when needed. Follow the conventions in [DomSelectors_README.md](./DomSelectors_README.md).
-
-### Step 4: Add clear action methods
-
-Implement or extend focused, business-friendly methods like:
-
-- `createTicket()`
-- `updateTicket()`
-- `addComment()`
-- `deleteComment()`
-
-### Step 5: Export from the barrel index
-
-Add the new POM as a named export in `page-object-model/index.js`.
-
-### Step 6: Use the page object from step files
-
-Import the page object from the module root barrel (`'../index'`) and call its methods.
-
-### Step 7: Add assertions outside the POM
-
-Write assertions in `assertions/` or in the step definition file, not in the page object.
-
-## Naming Recommendations
-
-### File names
-
-- use descriptive PascalCase names for POM files
-- use helper wrapper files only when they simplify usage
-
-### Factory function names
-
-- match the file name
-- keep names domain-specific
-
-Examples:
-
-- `TicketListPage`
-- `TicketDetailsPage`
-- `TicketCommentsPanel`
-
-### Method names
-
-Use verbs that describe intent:
-
-- `visitSetupHomePage()`
-- `selectModule(moduleName)`
-- `openTicket(subject)`
-- `updateComment(oldText, newText)`
-
-## Best Practices
-
-Use this section for quality guidance that improves readability and maintainability.
-
-- Keep page objects readable and small.
-- Prefer business-level actions over raw clicks in step files.
-- Let POM methods return locators, values, or state to callers instead of combining too many responsibilities.
-- Keep selectors centralized when they are shared.
-- Prefer unique ids, record ids, or returned UI identifiers over visual-order-based selection.
-- Use one module-local POM structure instead of a large global one.
-- Reuse existing page objects before creating new ones.
-- Add comments only when logic is not obvious.
-
-## Validation Checklist
-
-Before considering a POM ready, verify that:
-
-1. The file is placed under the correct module.
-2. The factory function name matches the page responsibility.
-3. Selectors are stable and readable — verified against [DomSelectors_README.md](./DomSelectors_README.md).
-4. Repeated locator logic is extracted into getters.
-5. Child elements are scoped under a stable parent container when needed.
-6. Reusable workflows are inside page methods.
-7. Step files use the page object instead of raw locator-heavy logic.
-8. Assertions are not placed in the page object by default.
-9. Shared assertions are extracted into `assertions/` when needed.
-10. No business logic is placed in the page object.
-11. No arbitrary waits are used.
-12. Raw hardcoded locators are not embedded repeatedly in action methods.
-13. DOM readiness is checked before each significant interaction.
-14. The implementation is safe for random scenario execution order.
-15. Scenario data is not stored in mutable global or environment state.
-16. Selectors are not duplicated — see [DomSelectors_README.md](./DomSelectors_README.md).
-17. Unused variables, imports, methods, and selectors are removed.
-18. POM file names follow PascalCase naming convention.
-19. Selector files remain pure — see [DomSelectors_README.md](./DomSelectors_README.md).
-20. Assertion files remain validation-only.
-21. Record selection does not depend on `.first()`, `.last()`, or visual order when a stable identifier is available.
-22. POMs are defined as factory functions that destructure only the context properties they need.
-23. All used context properties (`page`, `i18N`, `getMetaInfo`, `cacheLayer`, `context`, `executionContext`, `actorContext`) are accessed from the factory closure and not passed to individual methods.
-24. All user-facing strings are resolved through `i18N` and not hardcoded.
-25. Each module has an `index.js` barrel export in `page-object-model/`.
-26. Step files import POMs from the barrel index, not from deep file paths.
-
-
-For selector file references, see [DomSelectors_README.md](./DomSelectors_README.md).
-
-## Quick Checklist
-
-Use this section as a short working summary while creating or updating a POM.
-
-- Reuse an existing module POM when possible.
-- Keep the file in the correct `page-object-model/` folder.
-- Use one focused factory function per page or component.
-- Add reusable getters and clear action methods.
-- Keep validations outside the POM and step files thin.
-- Avoid hard waits and confirm DOM readiness before actions.
-- Remove unused or duplicated code before finishing.
-- Follow consistent PascalCase file naming for POMs.
-- Define POMs as factory functions that destructure only the context properties they need (`page`, `i18N`, `getMetaInfo`, `cacheLayer`, `context`, `executionContext`, `actorContext`).
-- Access all context properties from the factory closure, not as method-level parameters.
-- Use `i18N` for all user-facing strings in locators; never hardcode translated text.
-- Export all module POMs via `page-object-model/index.js` and import from the module root barrel (`'../index'`) in step files.