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

package/.github/copilot-instructions.md

@@ -1,95 +0,0 @@
-# Copilot Instructions — Desk Client App Test Automation
-
-## Project Overview
-
-This is a **BDD test automation** project for Zoho Desk using **Playwright** and a custom Cucumber-based framework (`@zohodesk/testinglibrary`). Tests live under `jsapps/supportapp/test-slices/uat/modules/`.
-
-## Core Framework
-
-- **Library**: `@zohodesk/testinglibrary` — provides `createBdd()` which returns `{ Given, When, Then, And }`
-- **All steps are async**: every browser interaction must be `await`ed
-- **Page automation**: Playwright `page` object from context
-
-## Module Folder Structure (Mandatory)
-
-Every module must follow this hierarchy:
-
-```
-modules/
-  <ModuleName>/
-    index.js                        # Barrel exports for the module
-    steps/
-      <FeatureName>.spec.js         # Step definitions
-    feature-files/
-      <FeatureName>.feature         # Gherkin scenarios
-    data-generators/
-      generators.json               # Test data
-    page-object-model/
-      <PageName>.js                 # Page objects (factory functions)
-      index.js                      # POM barrel re-exports
-    assertions/
-      <ModuleName>Assertions.js     # Module-specific assertions
-    dom-selectors/
-      <moduleName>Selectors.js      # Centralized selector constants
-    utils/
-      <moduleName>Utils.js          # Helper functions
-```
-
-## File Naming Conventions
-
-| Artifact          | Convention          | Example                      |
-|-------------------|---------------------|------------------------------|
-| Module folders    | PascalCase          | `Ticket/`, `CustomModule/`   |
-| Spec files        | PascalCase `.spec.js` | `SetupNavigation.spec.js`  |
-| Feature files     | PascalCase `.feature` | `TicketsCRUD.feature`      |
-| POM files         | PascalCase `.js`    | `TicketDetailView.js`        |
-| Assertion files   | PascalCase + `Assertions` | `SetupAssertions.js`   |
-| Selector files    | PascalCase + `Selectors`  | `TicketSelectors.js`   |
-| Utility files     | PascalCase + `Utils` | `TicketUtils.js`            |
-| Barrel files      | `index.js`          | `index.js`                   |
-
-## Step Definition Rules
-
-1. **Import pattern**: Always start with `import { createBdd } from '@zohodesk/testinglibrary'`
-2. **Import order**: framework → cross-module → local POM (via barrel) → assertions → constants → BDD destructuring
-3. **Given/When/Then separation**: Given = setup, When = action, Then = assertion only
-4. **No branching logic** (`if/else`, `switch`, ternary) inside step bodies — delegates to POM
-5. **Use `{string}` parameters** for dynamic values
-6. **Context destructuring**: only destructure what you use (`page`, `i18N`, `getMetaInfo`, `cacheLayer`, `context`, `executionContext`, `actorContext`)
-7. **Then steps are assertions only** — no clicks, fills, or navigation
-8. **No hardcoded English strings** — use `i18N()` (async function, always await)
-9. **No hardcoded locators** in step files — all DOM access via POM methods
-10. **Use `cacheLayer`** for data sharing between steps (not globals or `process.env`)
-
-## POM Rules
-
-1. **Factory functions only** — no classes, `this`, `new`, or `constructor`
-2. **One factory per page/panel** — destructure only needed context properties
-3. **Keep assertions outside POM** — POMs return locators/values, never validate
-4. **Import selectors from `dom-selectors/`** — no raw locators in POM methods
-5. **Validate DOM readiness** with `waitFor()` before every action
-6. **Use `i18N`** for all user-facing strings
-7. **No arbitrary waits** — never use `page.waitForTimeout()`
-8. **Export via barrel** — `page-object-model/index.js` re-exports all POMs
-
-## Selector Rules
-
-1. **Pure constants only** — no Playwright actions, assertions, or business logic
-2. **SCREAMING_SNAKE_CASE** for static selectors, **camelCase** for builder helpers
-3. **Prefer stable selectors**: `data-test-id` > `data-id` > `id` > `name` > ARIA > labels
-4. **No duplication** of selector strings
-5. **Step files never import selectors directly** — always access via POM
-
-## Assertion Rules
-
-1. **Use `Assertions` library** from `../../_assertions/Assertions`
-2. **Module-specific assertions** in `assertions/<ModuleName>Assertions.js` when reused across 2+ spec files
-3. **No assertions in POM files** — assertion files receive locators/values from POMs
-4. **Prefer Playwright auto-waiting assertions** over plain JS comparison
-
-## Style Guides
-
-Detailed rules are in `.github/styleGuides/`:
-- `Steps_README.md` — step definition patterns
-- `POM_README.md` — page object model patterns
-- `DomSelectors_README.md` — selector file patterns

package/.github/instructions/assertions.instructions.md

@@ -1,36 +0,0 @@
----
-applyTo: "**/test-slices/**/assertions/*.js"
----
-
-# Assertions Layer
-
-Module-level assertion files contain reusable validation helpers built by composing methods from the central `Assertion.js` library.
-
-## File Pattern
-
-```javascript
-// assertions/TicketAssertions.js
-import Assertions from '../../_assertions/Assertions';
-
-const TicketAssertions = {
-  async verifyTicketSubject(subjectElem, expectedSubject) {
-    await Assertions.isElementVisible(subjectElem);
-    await Assertions.isElementHaveText(subjectElem, expectedSubject);
-  },
-
-  async verifyCommentAuthored(authorElem, expectedName) {
-    await Assertions.isElementVisible(authorElem);
-    await Assertions.isElementContainText(authorElem, expectedName);
-  },
-};
-
-export default TicketAssertions;
-```
-
-## Strict Rules
-
-  - **No Actions:** Assertion files must never click, fill, or navigate.
-
-  - **No POM Imports:** Assertion files must never import POMs. They receive locators as arguments.
-
-  - **Central First:** Always prefer Assertions.* over raw expect().

package/.github/instructions/dom-selectors.instructions.md

@@ -1,33 +0,0 @@
----
-applyTo: "**/test-slices/**/dom-selectors/*.js"
----
-
-# Dom Selectors Layer
-
-Selector files are the single source of truth for all raw locator strings. Nothing else.
-
-## File Format
-
-```javascript
-// dom-selectors/TicketSelectors.js
-
-export const TicketSelectors = {
-  // Static — SCREAMING_SNAKE_CASE
-  COMMENT_INPUT: '[data-test-id="comment-input"]',
-  SAVE_COMMENT: '[data-test-id="save-comment-btn"]',
-  TICKET_ROW: '[data-id^="ticket_"]',
-
-  // Dynamic builder — camelCase arrow function
-  ticketRowById: (ticketId) => `[data-id="table_${ticketId}"]`,
-  ticketsByStatus: (status) => `[data-test-id="ticket-${status}"]`,
-};
-```
-
-## Rules
-
-- **Pure constants only** — no Playwright actions, assertions, waits, or business logic
-- **SCREAMING_SNAKE_CASE** for static selector keys
-- **camelCase** for dynamic builder helper functions
-- **No duplication** of selector strings
-- **Prefer stable selectors**: `data-test-id` > `data-id` > `id` > `name` > ARIA > labels
-- **Step files never import selectors** — only POMs consume these files

package/.github/instructions/pom-files.instructions.md

@@ -1,48 +0,0 @@
----
-applyTo: "**/test-slices/**/page-object-model/*.js"
----
-
-# Page Object Model Layer
-
-POM files contain all reusable UI interaction logic. Each file exports a single **factory function** (never a class).
-
-## Factory Function Pattern
-
-```javascript
-import { MySelectors } from '../dom-selectors/MySelectors';
-
-const MyPagePOM = ({ page, i18N, getMetaInfo }) => {
-  // Getter — synchronous, returns Locator
-  const getSubmitButton = () => page.locator(MySelectors.SUBMIT_BTN);
-
-  // Action — async, waitFor() before every interaction
-  const clickSubmit = async () => {
-    const btn = getSubmitButton();
-    await btn.waitFor();
-    await btn.click();
-  };
-
-  // i18N usage
-  const getElementByLabel = async (labelKey) => {
-    const label = await i18N(labelKey);
-    return page.getByText(label, { exact: true });
-  };
-
-  return { getSubmitButton, clickSubmit, getElementByLabel };
-};
-
-export { MyPagePOM };
-```
-
-## Rules
-
-- **Factory functions only** — no classes, `this`, `new`, `constructor`
-- **Destructure only needed context** from `({ page, i18N, getMetaInfo, cacheLayer, executionContext, actorContext })`
-- **Import selectors** from `../dom-selectors/` — no raw locator strings
-- **Getter methods** return Playwright Locators (synchronous, no `await`)
-- **Action methods** are async with `await` on Playwright actions
-- **DOM readiness**: call `element.waitFor()` before every action
-- **Use `await i18N('key')`** for all user-facing strings
-- **No assertions** — POMs return locators/values, never validate
-- **No `page.waitForTimeout()`** — use element-based waits only
-- **No `.first()` or `.last()`** for ambiguity — use unique identifiers

package/.github/instructions/step-definitions.instructions.md

@@ -1,44 +0,0 @@
----
-applyTo: "**/test-slices/**/steps/*.spec.js"
----
-
-# Step Definitions Layer
-
-BDD step definition files live in each module's `steps/` folder. They are the **thin wiring layer** between Gherkin feature files and POM factory functions.
-
-## Standard File Structure
-
-```javascript
-import { createBdd } from '@zohodesk/testinglibrary';
-import { XyzPOM, AbcPOM } from '../index';
-import Assertions from '../../_assertions/Assertions';
-
-const { Given, When, Then } = createBdd();
-
-Given('the user is in {string} department', async ({ page, i18N }, department) => {
-  // navigation / precondition only
-});
-
-When('the user clicks {string} button', async ({ page, i18N }, buttonLabel) => {
-  const pom = XyzPOM({ page, i18N });
-  await pom.clickButton(buttonLabel);
-});
-
-Then('the {string} element should be visible', async ({ page, i18N }, label) => {
-  const pom = XyzPOM({ page, i18N });
-  const elem = await pom.getElement(label);
-  await Assertions.isElementVisible(elem);
-});
-```
-
-## Step Rules
-
-- **Given** = setup only (navigation, preconditions)
-- **When** = user actions only (clicks, fills, submissions)
-- **Then** = assertions ONLY (no clicks, fills, navigation)
-- **No branching** (`if/else`, `switch`, ternary) in step bodies — delegate to POM
-- Use `{string}` for dynamic values
-- Destructure only needed context properties
-- Use `await i18N('key')` for all user-facing strings
-- Use `cacheLayer` for sharing data between steps
-- All DOM access via POM methods — no raw selectors

package/.github/styleGuides/DomSelectors_README.md

@@ -1,72 +0,0 @@
-# DOM Selectors Structure Guide
-
-## Purpose
-
-
-This document describes the strict rules and naming conventions for selector files used in the `dom-selectors/` folder of each test module. Selector files are the **single source of truth** for all raw locator strings.
-
----
-
-## What `dom-selectors/` Should Contain
-
-Store selector constants and selector builder helpers here.
-
-Examples:
-
-- one file per major page, panel, or UI responsibility
-- grouped selector constants exported as a single object
-- selector builder helpers for dynamic locators
-
-This keeps selector updates centralized and prevents raw locator strings from spreading across POM files and step files.
-
----
-
-## 1. Naming Conventions (Strict)
-
-To ensure consistency across the framework, you must strictly adhere to these casing rules:
-
-* **Files:** Must use **PascalCase** and end in `Selectors.js` (e.g., `TicketSelectors.js`).
-* **Exported Object:** Must match the file name exactly in **PascalCase** (e.g., `export const TicketSelectors`).
-* **Static Keys:** Must use **SCREAMING_SNAKE_CASE** (e.g., `COMMENT_INPUT: '[data-test-id="comment"]'`).
-* **Dynamic Builder Functions:** Must use **camelCase** (e.g., `ticketRowById: (id) => ...`).
-
----
-
-## 2. The Selector Priority Hierarchy (For UI Inspection)
-
-When capturing live selectors (e.g., via Playwright MCP) or writing new ones, you MUST prefer stable identifiers in this exact order:
-
-1. `data-test-id` (Highest Priority)
-2. `data-id`
-3. `id`
-4. `name`
-5. ARIA roles
-6. Labels / Placeholders (Lowest acceptable)
-
-**Absolutely Forbidden Selectors:**
-
-  - Deep, brittle CSS chains (`div > div > span > ul > li > a`).
-  - Index-based locators (`nth-child`, `.first()`, `.last()`) when a stable identifier is available.
-  - Selectors tied to text content that changes across locales/translations.
-
----
-
-## 3. Architectural Isolation Rules
-
-* **Rule 1: Keep it Pure.** Selector files must ONLY contain locator strings and dynamic locator functions. They must NEVER contain Playwright actions (`click()`), assertions (`expect()`), waits, or business logic.
-
-* **Rule 2: No Duplication.** Never repeat the same raw selector string twice.
-
-* **Rule 3: No Step File Imports.** Step files (`.spec.js`) are strictly forbidden from importing from `dom-selectors/`. The flow is always: **Step File → POM → Selector File**.
-
-## Validation Checklist
-*To be used by the Step Definition Validator Agent:*
-
-1. [ ] Is the file placed in the correct `dom-selectors/` folder?
-2. [ ] Does the file name and exported object use `PascalCase` (e.g., `TicketSelectors`)?
-3. [ ] Are static keys `SCREAMING_SNAKE_CASE` and dynamic functions `camelCase`?
-4. [ ] Are there ZERO Playwright actions, assertions, or `page.` calls in the file?
-5. [ ] Are stable selectors (`data-test-id`) used instead of brittle DOM paths (`nth-child`)?
-6. [ ] Is the framework free of Step files directly importing this selector file?
-
----