playwright-ts-automationframework 1.1.73 → 1.1.75

package/API-REFERENCE.md

@@ -0,0 +1,365 @@
+# Playwright TS Automation Framework — API Reference
+
+Public API exported from `src/index.ts` (published as `playwright-ts-automationframework`, entry `lib/index.js` / `lib/index.d.ts`).
+
+Use this document when consuming the package from another solution or as AI context for page objects and tests.
+
+---
+
+## Package import
+
+```typescript
+import {
+  BasePage,
+  Actions,
+  Assertion,
+  WebControl,
+  Configuration,
+  globalSetup,
+  globalTearDown,
+  logAction,
+  logVerification,
+  logError,
+  logConsole,
+  logTestResult,
+} from 'playwright-ts-automationframework';
+```
+
+### Class hierarchy
+
+```
+BasePage
+  └── Actions
+        └── Assertion
+```
+
+`Assertion` instances inherit all methods from `Actions` and `BasePage`.
+
+### Playwright config (global hooks)
+
+```typescript
+import { defineConfig } from '@playwright/test';
+import { globalSetup, globalTearDown } from 'playwright-ts-automationframework';
+
+export default defineConfig({
+  globalSetup,
+  globalTeardown: globalTearDown,
+});
+```
+
+---
+
+## Standalone exports
+
+| Export | Signature | Description |
+|--------|-----------|-------------|
+| `globalSetup` | `(config: FullConfig) => Promise<void>` | Clears execution log file before run |
+| `globalTearDown` | `(config: FullConfig) => Promise<void>` | Sends execution result email after run |
+| `logAction` | `(message: string) => void` | Log UI action (console + file) |
+| `logVerification` | `(message: string) => void` | Log verification message |
+| `logError` | `(message: string) => void` | Log error |
+| `logConsole` | `(message: string) => void` | Log info to console |
+| `logTestResult` | `(message: string) => void` | Log test start/end banners |
+
+---
+
+## WebControl
+
+Wraps a Playwright `Locator` with a human-readable description for logging.
+
+### Constructor
+
+```typescript
+new WebControl(controlLocator: Locator, controlDescription: string)
+```
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `controlLocator` | `Locator` | Playwright locator |
+| `controlDescription` | `string` | Label used in logs (e.g. `'Login button'`) |
+
+### Example
+
+```typescript
+const loginBtn = new WebControl(page.locator('#login'), 'Login button');
+```
+
+---
+
+## Configuration (static)
+
+Reads/writes `AppConfigurations.json` and `ExecutionSettings.json` (paths resolved relative to consumer project layout).
+
+### Static fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `Environment` | `string` | `"QA"` | Environment key when not overridden by settings |
+| `EmailRecievers` | `string` | `";"` | Fallback email recipients |
+| `SenderEmail` | `string` | `";"` | Fallback sender email |
+| `SenderPassword` | `string` | `";"` | Fallback sender password |
+
+### Static getters
+
+| Getter | Returns | Description |
+|--------|---------|-------------|
+| `environment` | `string` | From `ExecutionSettings.json` or `Configuration.Environment` |
+| `emailRecievers` | `string` | From settings or static fallback |
+| `senderEmail` | `string` | From settings |
+| `senderPassword` | `string` | From settings |
+| `configurationData` | `JSON` | Environment block from `AppConfigurations.json` |
+
+### Static methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `get` | `(key: string) => any` | Read config value for current environment |
+| `set` | `(key: string, value: any) => void` | Set value and persist to `AppConfigurations.json` |
+
+### Example
+
+```typescript
+const url = Configuration.get('URL');
+Configuration.set('URL', 'https://example.com');
+```
+
+---
+
+## BasePage
+
+Browser initialization and test lifecycle logging.
+
+### Constructor
+
+```typescript
+constructor(page: Page)
+```
+
+### Instance methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `initializeBrowser` | `(url?: string) => Promise<void>` | Navigate to URL (default: `Configuration.get("URL")`), 60s timeout, `waitUntil: "load"` |
+
+### Static methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `setTestCaseID` | `(testInfo: TestInfo) => void` | Log test start banner |
+| `executionCompleted` | `(testInfo: TestInfo) => void` | Log test end banner with status |
+
+### Example
+
+```typescript
+const pageObj = new BasePage(page);
+await pageObj.initializeBrowser();
+
+BasePage.setTestCaseID(test.info);
+BasePage.executionCompleted(test.info);
+```
+
+---
+
+## Actions (extends BasePage)
+
+Logged wrappers around common Playwright interactions. All methods take `WebControl` unless noted.
+
+### Constructor
+
+```typescript
+constructor(page: Page)
+```
+
+### Interaction
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `click` | `(control, isforceful?: boolean) => Promise<void>` | Click element (`force` when `isforceful` is true) |
+| `mouseHover` | `(control) => Promise<void>` | Hover over element |
+| `focusAndPressKeyboardEvent` | `(control, action: string) => Promise<void>` | Focus then press key |
+| `type` | `(control, textTobeEntered: string) => Promise<void>` | Fill text (logged) |
+| `typePassword` | `(control, textTobeEntered: string) => Promise<void>` | Fill password (logged as `********`) |
+| `pressKeyboardEvent` | `(control, key: string) => Promise<void>` | Press key on element |
+| `selectFromDropdownByValue` | `(control, optionTobeSelcted: string) => Promise<void>` | `selectOption({ value })` |
+| `selectFromDropdownByText` | `(control, optionTobeSelcted: string) => Promise<void>` | `selectOption({ label })` |
+| `selectFromDropdownByPartialText` | `(control, partialText: string) => Promise<void>` | Select first option containing partial text |
+| `selectFromDropdownByIndex` | `(control, index: number) => Promise<void>` | `selectOption({ index })` |
+| `selectCheckbox` | `(control, expectedCheckboxValue?: boolean) => Promise<void>` | Check/uncheck (default: checked) |
+| `scrollToControl` | `(control) => Promise<void>` | `scrollIntoViewIfNeeded` |
+| `navigateBack` | `() => Promise<void>` | Browser back |
+| `handleAlert` | `(action: string) => Promise<void>` | Register dialog handler; `"accept"` accepts, else dismiss |
+| `closeBrowser` | `() => Promise<void>` | Close page |
+
+### Read / state
+
+| Method | Signature | Returns | Description |
+|--------|-----------|---------|-------------|
+| `isSelected` | `(control)` | `Promise<boolean>` | Checkbox/radio checked state |
+| `isEnabled` | `(control)` | `Promise<boolean>` | Enabled state |
+| `isDisplayed` | `(control)` | `Promise<boolean>` | Visible state |
+| `getText` | `(control)` | `Promise<string>` | `innerText` |
+| `getTextboxValue` | `(control)` | `Promise<string>` | `inputValue` |
+| `getInputValue` | `(control)` | `Promise<string>` | `inputValue` |
+| `getSelectedItemFromDropdown` | `(control)` | `Promise<string>` | Selected dropdown value (`inputValue`) |
+| `getAttributeValue` | `(control, attributeName: string)` | `Promise<string \| null>` | Attribute value |
+| `findAll` | `(control)` | `Promise<Locator[]>` | All matching locators (waits for present) |
+| `getAllInnerText` | `(control)` | `Promise<string[]>` | All `innerText` values |
+| `getAllTextContents` | `(control)` | `Promise<string[]>` | All `textContent` values |
+| `getURL` | `()` | `Promise<string>` | Current page URL |
+| `getTitle` | `()` | `Promise<string>` | Page title |
+| `getAlertDialogMessage` | `()` | `Promise<...>` | Dialog message via handler |
+
+### Waits / navigation
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `waitTillPageURLContains` | `(url: string, timeoutInSeconds?: number) => Promise<...>` | `waitForURL` (default timeout 60s) |
+| `waitTillElementIsPresent` | `(control, timeoutInSeconds?: number) => Promise<void>` | Wait visible (default 60s) |
+| `waitTillElementIsEnabled` | `(control, timeoutInSeconds?: number) => Promise<void>` | Wait enabled (default 60s) |
+| `waitTillElementIsAttached` | `(control, timeoutInSeconds?: number) => Promise<void>` | Wait attached in DOM (default 60s) |
+| `waitTillElementIsNotPresent` | `(control, timeoutInSeconds?: number) => Promise<void>` | Wait hidden (default 60s) |
+| `sleep` | `(timeInSeconds?: number) => Promise<void>` | Fixed delay (default 5s) |
+| `waitForPageTimeout` | `(timeoutInSeconds?: number) => Promise<void>` | `page.waitForTimeout` (default 5s) |
+| `waitForPageLoad` | `(timeInSeconds?: number) => Promise<void>` | `load` state (default 30s) |
+| `waitForPageDOMcontentLoaded` | `(timeInSeconds?: number) => Promise<void>` | `domcontentloaded` (default 30s) |
+| `waitForNetworkIdle` | `(timeInSeconds?: number) => Promise<void>` | `networkidle` (default 30s) |
+| `refreshWebPage` | `(timeInSeconds?: number) => Promise<void>` | Reload page (default 30s) |
+
+---
+
+## Assertion (extends Actions)
+
+Verification helpers using Playwright `expect.soft` and framework logging.
+
+### Constructor
+
+```typescript
+constructor(page: Page)
+```
+
+### Generic comparisons
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `verifyIsEquals` | `(object1: any, object2: any, controlDescription?: string) => void` | Strict equality |
+| `verifyIsNotEquals` | `(object1: any, object2: any, controlDescription?: string) => void` | Not equal |
+| `verifyIsEqualIgnorecase` | `(object1, object2, controlDescription?, caseInsensitive?: boolean) => void` | Equal; optional case-insensitive for strings |
+| `verifyIsContains` | `(actual: string \| string[], expected: string, controlDescription?: string) => void` | String or array contains substring |
+
+### Element state
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `verifyIsDisplayed` | `(control, expectedIsDisplayed?: boolean) => Promise<void>` | Visible/hidden (default: displayed) |
+| `verifyIsNotDisplayed` | `(control, isAlreadyHidden?: boolean) => Promise<void>` | Element is hidden |
+| `verifyIsEnabled` | `(control, expValue?: boolean) => Promise<void>` | Enabled (default true); else calls `verifyIsDisabled` |
+| `verifyIsDisabled` | `(control, expValue?: boolean) => Promise<void>` | Disabled |
+| `verifyIsSelected` | `(control, expValue?: boolean) => Promise<void>` | Checkbox/radio selected |
+| `verifyCheckboxValue` | `(control, value: boolean) => Promise<void>` | Checkbox matches expected |
+| `verifyTagName` | `(control, expectedTagName: string) => Promise<void>` | Tag name (case-insensitive) |
+
+### Text and attributes
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `verifyAttributeValue` | `(control, attributeName, expectedAttributeValue) => Promise<void>` | Attribute equals |
+| `verifyAttributeValueContains` | `(control, attributeName, attributeValue) => Promise<void>` | Attribute contains |
+| `verifyDisplayedText` | `(control, expectedText) => Promise<void>` | `innerText` equals |
+| `verifyDisplayedTextContains` | `(control, expectedText) => Promise<void>` | `innerText` contains |
+| `verifyDisplayedTextDoesNotContains` | `(control, expectedText) => Promise<void>` | `innerText` does not contain |
+| `verifyTextboxValue` | `(control, expectedText) => Promise<void>` | `value` attribute equals |
+| `verifyTextboxValueContains` | `(control, expectedText) => Promise<void>` | `value` attribute contains |
+| `verifyInnerText` | `(control, expectedText) => Promise<void>` | `innerText` equals |
+| `verifyInnerTextContains` | `(control, expectedText) => Promise<void>` | `innerText` contains |
+| `verifyInputValue` | `(control, expectedText) => Promise<void>` | `inputValue` equals |
+| `verifyInputValueContains` | `(control, expectedText) => Promise<void>` | `inputValue` contains |
+
+### Lists and counts
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `verifyListContainsValue` | `(control, valueToVerify: string) => Promise<void>` | At least one list item contains value |
+| `verifyListContainsMultipleValues` | `(control, listOfValueToVerify: string[], waitTillElementIsDisplayed?) => Promise<void>` | Each value present in list |
+| `verifyDropdownOptions` | `(control, listOfValueToVerify: string[], waitTillElementIsDisplayed?) => Promise<void>` | Dropdown options contain values |
+| `verifyListForMultipleValues` | `(control, listOfValueToVerify: string[], waitTillElementIsDisplayed?) => Promise<void>` | Index-aligned list text match |
+| `verifyCountOfElements` | `(control, expectedCount: number) => Promise<void>` | Locator count equals |
+| `verifyCountOfElementsIsGreaterOrEqual` | `(control, expectedCount: number) => Promise<void>` | Count >= expected |
+| `verifyCountOfElementsIsLesseOrEqual` | `(control, expectedCount: number) => Promise<void>` | Count <= expected |
+
+### Page and alert
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `verifyAlertText` | `(expectedText: string) => Promise<void>` | Alert message contains text |
+| `verifyURLContains` | `(subString: string) => Promise<void>` | Current URL contains substring |
+| `verifyPageTitleContains` | `(expectedText: string) => Promise<void>` | Page title contains text |
+
+---
+
+## Recommended usage patterns
+
+### Page object extending Assertion
+
+```typescript
+import { Page } from '@playwright/test';
+import { Assertion, WebControl } from 'playwright-ts-automationframework';
+
+export class LoginPage extends Assertion {
+  private readonly username = new WebControl(
+    page.locator('#username'),
+    'Username textbox'
+  );
+
+  constructor(page: Page) {
+    super(page);
+  }
+
+  async login(user: string, pass: string) {
+    await this.type(this.username, user);
+    // ...
+  }
+}
+```
+
+### Test hooks
+
+```typescript
+import { test } from '@playwright/test';
+import { BasePage } from 'playwright-ts-automationframework';
+
+test.beforeEach(async ({}, testInfo) => {
+  BasePage.setTestCaseID(testInfo);
+});
+
+test.afterEach(async ({}, testInfo) => {
+  BasePage.executionCompleted(testInfo);
+});
+```
+
+---
+
+## Not part of the public API
+
+The following exist in the repo but are **not** exported from `src/index.ts`:
+
+| Symbol | Location | Notes |
+|--------|----------|-------|
+| `SendEmail` | `src/core/sendEmail.ts` | Used internally by `globalTearDown` only |
+
+---
+
+## Export summary
+
+| Category | Count |
+|----------|-------|
+| Standalone functions | 7 |
+| Exported classes | 5 (`BasePage`, `Actions`, `Assertion`, `WebControl`, `Configuration`) |
+| `BasePage` public methods | 3 (+ constructor) |
+| `Actions` public methods | 38 (+ constructor) |
+| `Assertion` public methods | 35 (+ constructor) |
+| `WebControl` | constructor + 2 properties |
+| `Configuration` | 4 fields + 5 getters + `get` / `set` |
+
+**Version:** See `package.json` → `"version"` (e.g. `1.1.74` at time of writing).

package/README.md

@@ -1,5 +1,11 @@
 # Playwright Typescript Automation framework library
 
+## API Reference
+
+Full list of Actions, Assertions, WebControl, Configuration, and logging APIs: [API-REFERENCE.md](./API-REFERENCE.md)
+
+After `npm install`, the same file is available at `node_modules/playwright-ts-automationframework/API-REFERENCE.md`.
+
 Sample Project: https://github.com/ketanp88/PlaywrightFrameworkDemoProject
 
 Playwright Typescript Automation framework

package/lib/core/actions.core.d.ts

@@ -313,6 +313,19 @@ export declare class Actions extends BasePage {
    * waitTillElementIsPresent(usernameTxtbx);
    */
     waitTillElementIsPresent(control: WebControl, timeoutInSeconds?: number): Promise<void>;
+    /**
+   * Wait till element is enabled
+   *
+   * @param control Wait for element to be enabled.
+   * @param timeoutInSeconds Timeout in seconds (default 60).
+   *
+   * Example:
+   *
+   * uploadBtn = new WebControl(this.page.getByRole('button', { name: 'Upload files' }), 'Upload files button');
+   *
+   * waitTillElementIsEnabled(uploadBtn);
+   */
+    waitTillElementIsEnabled(control: WebControl, timeoutInSeconds?: number): Promise<void>;
     /**
        * Wait till element is attached to the dom
        *

package/lib/core/actions.core.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Actions = void 0;
+const test_1 = require("@playwright/test");
 const basePage_core_1 = require("./basePage.core");
 const logs_core_1 = require("./logs.core");
 /**
@@ -631,6 +632,27 @@ class Actions extends basePage_core_1.BasePage {
             (0, logs_core_1.logError)(`❌ waitTillElementIsPresent failed for '${control.controlDescription}' (visible, ${timeoutInSeconds}s) due to reason: '${error}'`);
         }
     }
+    /**
+   * Wait till element is enabled
+   *
+   * @param control Wait for element to be enabled.
+   * @param timeoutInSeconds Timeout in seconds (default 60).
+   *
+   * Example:
+   *
+   * uploadBtn = new WebControl(this.page.getByRole('button', { name: 'Upload files' }), 'Upload files button');
+   *
+   * waitTillElementIsEnabled(uploadBtn);
+   */
+    async waitTillElementIsEnabled(control, timeoutInSeconds = 60) {
+        try {
+            await this.page.waitForLoadState("domcontentloaded");
+            await (0, test_1.expect)(control.controlLocator.first()).toBeEnabled({ timeout: timeoutInSeconds * 1000 });
+        }
+        catch (error) {
+            (0, logs_core_1.logError)(`❌ waitTillElementIsEnabled failed for '${control.controlDescription}' (enabled, ${timeoutInSeconds}s) due to reason: '${error}'`);
+        }
+    }
     /**
        * Wait till element is attached to the dom
        *

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "playwright-ts-automationframework",
-  "version": "1.1.73",
-  "description": "",
+  "version": "1.1.75",
+  "description": "Playwright TypeScript automation framework with Actions, Assertions, and WebControl wrappers",
+  "homepage": "https://github.com/ketanp88/playwright-TS-AutomationFramework/blob/main/API-REFERENCE.md",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "scripts": {
@@ -19,15 +20,17 @@
     "ignore-case": "^0.1.0"
   },
   "dependencies": {
-    "@playwright/test": "^1.59.1",
-    "@types/node": "^25.6.0",
+    "@playwright/test": "^1.60.0",
+    "@types/node": "^25.7.0",
     "log4js": "^6.9.1",
     "nodemailer": "^8.0.7",
-    "npm": "^11.13.0",
+    "npm": "^11.14.1",
     "path": "^0.12.7",
     "typescript": "^6.0.3"
   },
   "files": [
-    "lib/**/**"
+    "lib/**/**",
+    "README.md",
+    "API-REFERENCE.md"
   ]
 }