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

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

@@ -0,0 +1,44 @@
+---
+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

@@ -0,0 +1,72 @@
+# 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?
+
+---