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

package/.github/styleGuides/POM_README.md

@@ -0,0 +1,602 @@
+# 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.