@roopesh.yadava/qa-pack 1.0.3

package/claude/skills/automation/BDD_TEMPLATES.md

@@ -0,0 +1,237 @@
+# BDD Templates & Reference
+
+> Load this file at the start of Phase 1 (Gherkin generation) and Phase 3 (POM).
+> Contains Gherkin format examples, step definition templates, POM class template,
+> Faker.js patterns, file upload guide, and BDD API hook reference.
+
+---
+
+## Gherkin Format Example
+
+```gherkin
+Feature: <feature title from card>
+
+  Background: (optional — only if 2+ scenarios share the same Given)
+    Given ...
+
+  Rule: <business rule — taken verbatim from AC/COS>
+
+    @add_user
+    Example: <Persona> as <role> <scenario description>
+      Given <persona> is on the <page name> page
+      When <persona> <action described as intent, not mechanics>
+      Then <persona> should <observable outcome>
+
+    @add_user
+    Example: <Different persona or variation under same Rule>
+      Given ...
+      When ...
+      Then ...
+
+    @add_subscription
+    @add_subscription_offer
+    Scenario Outline: <persona> <flow description> with multiple <data type>
+      Given <persona> is on the <page name> page
+      When <persona> enters credentials "<email>" and "<password>"
+      Then <persona> should see "<expected_message>"
+
+      Examples:
+        | persona | email           | password     | expected_message     |
+        | John    | john@test.com   | Admin@1234   | Verification passed  |
+        | Maria   | maria@test.com  | Branch@1234  | Verification passed  |
+```
+
+---
+
+## Step Definition Template
+
+```javascript
+const { Given, When, Then, Before, After } = require('@cucumber/cucumber');
+const { faker } = require('@faker-js/faker');
+const AddUserPage = require('../../Pages/UserManagement/add-user.cjs');
+
+// API imports — only what this feature needs
+const { createUserViaApi } = require('../../BDDUtilies/bdd_api/addUserApi.cjs');
+
+let addUserPage;
+
+// ── Unconditional Before — restore globals ────────────────────────────────────
+Before(async function () {
+  if (global.lastCreatedUserName) {
+    this.lastCreatedUserName = global.lastCreatedUserName;
+  }
+});
+
+// ── Tagged Before hooks (API seeding) ────────────────────────────────────────
+// Check Driver.cjs first — do not duplicate existing hooks.
+
+Before({ tags: '@add_user' }, async function () {
+  await waitForToken();
+  const result = await createUserViaApi();
+  this.createdUser          = result.data.user;
+  this.createdUserEmail     = result.payload.email;
+  this.username             = result.payload.email;
+  this.createdUserData      = result.createdUserData;
+  this.viewAdminData        = result.viewAdminData;
+  this.lastCreatedUserName  = result.payload.name;
+  global.lastCreatedUserName = result.payload.name;
+});
+
+// ── Steps ────────────────────────────────────────────────────────────────────
+
+Given('{word} is on the add user page', async function (persona) {
+  addUserPage = new AddUserPage(this.page);
+  await addUserPage.navigate();
+});
+
+When('{word} fills in the new user details', async function (persona) {
+  await addUserPage.fillUserForm();
+});
+
+Then('{word} should see the user created successfully', async function (persona) {
+  await addUserPage.verifyUserCreated();
+});
+```
+
+---
+
+## POM Class Template
+
+```javascript
+const { expect } = require('@playwright/test');
+const { faker }  = require('@faker-js/faker');
+
+class AddUserPage {
+  /**
+   * @param {import('@playwright/test').Page} page
+   */
+  constructor(page) {
+    this.page = page;
+
+    // ── Locators (constructor ONLY — never inside methods) ───────────────
+    // All locators confirmed via Playwright MCP on live DOM
+    // Priority: data-testid → getByRole → getByLabel/getByText → id → CSS → XPath
+    this.nameInput        = page.getByTestId('add-user-name');
+    this.emailInput       = page.getByTestId('add-user-email');
+    this.roleSelect       = page.getByTestId('add-user-role');
+    this.submitButton     = page.getByTestId('add-user-submit');
+    this.successMessage   = page.getByTestId('add-user-success');
+    this.errorMessage     = page.getByTestId('add-user-error');
+  }
+
+  // ── Navigation ───────────────────────────────────────────────────────
+
+  async navigate() {
+    await this.page.goto('/users/add');
+  }
+
+  // ── Actions ──────────────────────────────────────────────────────────
+
+  async fillUserForm() {
+    await this.nameInput.fill(faker.string.alphanumeric(15));
+    await this.emailInput.fill(`test+${faker.string.alphanumeric(8)}@yourdomain.com`);
+    await this.roleSelect.selectOption('admin');
+    await this.submitButton.click();
+  }
+
+  // ── Assertions ───────────────────────────────────────────────────────
+
+  async verifyUserCreated() {
+    await expect(this.successMessage).toBeVisible();
+  }
+
+  async verifyErrorMessage(expectedText) {
+    await this.page.getByText(expectedText, { exact: false })
+      .waitFor({ state: 'visible', timeout: 60000 });
+  }
+
+  async verifyAllAdminData(apiData) {
+    expect(await this.page.getByTestId('user-email').textContent()).toBe(apiData.email);
+    expect(await this.page.getByTestId('user-role').textContent()).toBe(apiData.role);
+  }
+}
+
+module.exports = AddUserPage;
+```
+
+---
+
+## Faker.js Patterns
+
+```javascript
+const { faker } = require('@faker-js/faker');
+
+faker.string.alphanumeric(15)                             // random name
+`test+${faker.string.alphanumeric(8)}@yourdomain.com`     // email
+'999999999'                                               // fixed test phone
+faker.location.streetAddress()
+faker.location.city()
+faker.location.zipCode('##-###')
+faker.number.int({ min: 1, max: 100 })
+faker.date.future().toISOString().split('T')[0]           // 'YYYY-MM-DD'
+```
+
+Generate inside the method — never in the constructor or at module scope.
+
+---
+
+## File Upload — Decision Guide
+
+| Situation | Method |
+|-----------|--------|
+| Visible or hidden `<input type="file">` | `setInputFiles()` directly on locator |
+| Styled button that opens OS file picker | `uploadViaButton()` — `waitForEvent('filechooser')` |
+| Drag-and-drop zone, no visible input | `dragAndDropFile()` — tiny buffer trick (default) |
+
+Use `test/support/` fixture files only when the user explicitly says so.
+
+---
+
+## BDD API Hooks — Existing Tags
+
+Check Driver.cjs before creating new hooks — do not duplicate.
+
+| Tag | Type | API | Requires |
+|-----|------|-----|---------|
+| `@Logout` | Before | clears storage | — |
+| `@Logout1` | After | clears storage | — |
+| `@add_subscription` | Before | POST subscription | logged-in admin |
+| `@add_subscription_10` | Before | POST subscription ×10 | logged-in admin |
+| `@add_subscription_offer` | Before | POST offer | `@add_subscription` first |
+| `@add_subscription_offer_10` | Before | POST subscription+offer ×10 | logged-in admin |
+| `@add_client_paid` | Before | POST client (paid) | logged-in admin |
+| `@add_client_unpaid` | Before | POST client (unpaid) | logged-in admin |
+| `@add_client_paid_10` | Before | POST client ×10 | logged-in admin |
+| `@add_user` | Before | POST user | logged-in admin |
+| `@add_user_10` | Before | POST user ×10 | logged-in admin |
+| `@add_technician` | Before | POST technician | logged-in admin |
+| `@add_technician_10` | Before | POST technician ×10 | logged-in admin |
+| `@add_facility_under_client` | Before | POST facility (fixed client) | logged-in admin |
+| `@client_privilege_initial` | Before | PATCH privileges (reset) | logged-in admin |
+| `@delete_facility_bdd_api` | After | DELETE facilities cleanup | — |
+| `@full_privilege_client` | After | PATCH privileges (full) | — |
+
+**Stacking order matters** — `@add_subscription` must always be above `@add_subscription_offer`.
+
+---
+
+## Quick Reference
+
+| Content | Location |
+|---------|----------|
+| Business rule | `Rule:` in `.feature` |
+| Persona/role variation | `Example:` block |
+| Same flow, different data | `Scenario Outline` + `Examples:` |
+| Multiple variations of same rule | Multiple `Example:` under one `Rule:` |
+| API seeding tag | Above `Example:` / `Scenario Outline:` line |
+| Locators discovered | Playwright MCP on live DOM |
+| Locators written | POM constructor only |
+| Actions | POM async methods |
+| Assertions | POM `verify*` methods |
+| Generated test data | `faker.js` — inside methods |
+| `page.locator()` in step files | ❌ Never |
+| Hardcoded waits | ❌ Never |
+| XPath | ❌ Last resort only |
+| `import`/`export` | ❌ Use `require`/`module.exports` |
+| Gate 1 skipped | ❌ Never — always confirm Gherkin before writing code |
+| Gate 2 skipped | ❌ Never — always confirm step defs before writing POM |

package/claude/skills/automation/LOCATOR_PATTERNS.md

@@ -0,0 +1,169 @@
+# Locator Patterns — Hard-Won Lessons
+
+> Load this file before Phase 2 (Step Definitions) and Phase 3 (POM).
+> These rules are learned from real QE-89 failures. Apply every one before writing any locator.
+
+---
+
+### 1. Floating-label UI — never use `getByPlaceholder()`
+
+Floating-label inputs look like they have placeholder text but the visible text is a
+**CSS `<label>` element** that moves upward on focus. There is **no actual HTML `placeholder`
+attribute** on the input.
+
+```javascript
+// ❌ WRONG — times out because there is no placeholder attr
+this.emailInput = page.getByPlaceholder('Adres e-mail');
+
+// ✅ CORRECT — positional selector, confirmed via Playwright MCP / screenshot
+this.emailInput    = page.locator('input').nth(0);
+this.passwordInput = page.locator('input').nth(1);
+```
+
+**How to detect:** Open DevTools → inspect input → if there is no `placeholder="..."` attr,
+you are on a floating-label form.
+
+---
+
+### 2. Custom password field — never use `input[type="password"]`
+
+Password inputs with a show/hide eye icon are often rendered with a **custom component**
+that does not use `type="password"` on the native input element.
+
+```javascript
+// ❌ WRONG — element never found
+this.passwordInput = page.locator('input[type="password"]');
+
+// ✅ CORRECT
+this.passwordInput = page.locator('input').nth(1);
+```
+
+---
+
+### 3. `navigate()` must use an absolute URL
+
+Playwright throws `"Cannot navigate to invalid URL"` when you pass a relative path without
+a `baseURL` configured in `playwright.config`. Always compose the full URL:
+
+```javascript
+// ❌ WRONG
+await this.page.goto('/login');
+
+// ✅ CORRECT
+const baseUrl = process.env.BASE_URL || 'https://qa.loopay.com.pl';
+await this.page.goto(`${baseUrl}/login`);
+```
+
+---
+
+### 4. Post-login redirect — don't assume `/dashboard` in the URL
+
+After a successful login+OTP the app may redirect to `/home`, `/overview`, or any route.
+Do **not** use `waitForURL(/dashboard/)` unless you have confirmed the exact redirect path.
+
+```javascript
+// ❌ WRONG — times out if redirect URL is /home or /overview
+await this.page.waitForURL(/dashboard/, { timeout: 30000 });
+
+// ✅ CORRECT — generic "we left the login page" check
+await this.page.waitForFunction(
+  () => !window.location.href.includes('/login'),
+  { timeout: 30000 }
+);
+```
+
+---
+
+### 5. Invalid-credentials error is inline text, not `role="alert"`
+
+Error messages shown below a form field (e.g. "Błędny e-mail lub hasło.") are plain
+`<span>` or `<p>` elements. `getByRole('alert')` returns nothing and times out.
+
+```javascript
+// ❌ WRONG
+await expect(page.getByRole('alert')).toBeVisible();
+
+// ✅ CORRECT — match the actual inline error text
+this.credentialsErrorText = page.getByText(/błędny e-mail lub hasło/i);
+await this.credentialsErrorText.waitFor({ state: 'visible', timeout: 10000 });
+```
+
+---
+
+### 6. Multiple toast alerts — strict-mode violation
+
+When a wrong OTP is submitted the app may fire **two** alert toasts at once
+(e.g. "Code sent" + "New code sent"). `getByRole('alert')` then throws a strict-mode
+violation because it resolves to 2 elements.
+
+```javascript
+// ❌ WRONG — strict mode violation when 2 alerts are present
+await expect(page.getByRole('alert')).toBeVisible();
+
+// ✅ CORRECT — use .first() or filter by hasText
+await expect(page.getByRole('alert').first()).toBeVisible({ timeout: 10000 });
+```
+
+---
+
+### 7. 6-box OTP PIN component — use `keyboard.type()`, not `fill()`
+
+The OTP screen uses a PIN component with 6 individual boxes. Calling `.fill()` on the
+first box only populates one digit and the component does not auto-advance.
+
+```javascript
+// ❌ WRONG — only fills box 1, leaves 5 empty
+await this.otpInput.fill('999999');
+
+// ✅ CORRECT — click first box to focus, then type digit-by-digit
+await this.otpInput.waitFor({ state: 'visible', timeout: 15000 });
+await this.otpInput.click();
+await this.page.keyboard.type(otp);   // component auto-advances on each digit
+```
+
+---
+
+### 8. Resend OTP state — inspect before assuming
+
+The Resend OTP feature can behave differently across environments:
+- **Some envs:** countdown text "Wróć ponownie po X:XX" shown for 60 s, then replaced by clickable link.
+- **QA env (qa.loopay.com.pl):** the countdown is skipped; "Wyślij kod ponownie" is shown immediately.
+
+**Always use Playwright MCP or failure screenshots** to confirm the exact text before writing the locator.
+
+```javascript
+// ❌ FRAGILE — countdown may not appear in this environment
+this.resendCountdown = page.getByText(/wróć ponownie po/i);
+
+// ✅ CONFIRMED against QA env screenshot
+this.resendOtpLink = page.getByText(/wyślij kod ponownie/i);
+```
+
+---
+
+### 9. Read failure screenshots before every locator decision
+
+Every failed scenario saves a screenshot to:
+```
+test/step-definations/failed_scenarios/<uuid>_<scenario-name>.png
+```
+
+**Always read the latest screenshot for a failing scenario** using the `Read` tool.
+The screenshot shows exactly what the browser sees and prevents guessing:
+- What text is rendered
+- Which elements are present
+- Whether a toast/alert is shown
+
+---
+
+### 10. Submit-button locator — use the exact visible button text
+
+The login submit button text is in the UI language (Polish: "Zaloguj się").
+The OTP verify button is "Zweryfikuj". These are confirmed from screenshots.
+
+```javascript
+this.submitButton = page.getByRole('button', { name: 'Zaloguj się' });
+this.otpSubmit    = page.getByRole('button', { name: /zweryfikuj|zatwierdź|verify|potwierdź/i });
+```
+
+Use a regex when the exact label might vary by role or locale.