playwright-windows-wrapper 1.0.0

package/README.md

@@ -0,0 +1,23 @@
+# playwright-windows-wrapper
+
+A unified, hybrid test automation wrapper that bridges **Playwright** (for web automation) and **Appium/WinAppDriver** (for native Windows desktop applications). Write single-script end-to-end flows that seamlessly jump between standard browsers and native `.exe` applications.
+
+---
+
+## 🚀 Key Features
+
+* **Unified API:** Control both web elements and native desktop UI components using one client interface.
+* **Advanced Desktop Interactions:** Right-clicks, double-clicks, drag-and-drop, and hardware keyboard shortcuts (`Ctrl + A`, etc.) mapped natively to Windows.
+* **Window Controls:** Maximize, minimize, and inspect native application windows easily.
+
+---
+
+## 🛠️ Prerequisites
+
+Because Windows desktop automation requires access to OS-level accessibility trees, you must configure your host machine before running desktop tests:
+
+1. **Enable Windows Developer Mode:**  
+   Go to **Settings > Update & Security > For developers** and toggle **Developer Mode** to **On**.
+2. **Install Appium Globally:**  
+```bash
+   npm install -g appium

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,172 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const playwright_1 = require("playwright");
+const webdriverio_1 = require("webdriverio");
+const webdriverio_2 = require("webdriverio"); // Used for native key simulations
+class UltimateAutomationWrapper {
+    webBrowser = null;
+    webPage = null;
+    desktopSession = null;
+    // ==========================================
+    // INITIALIZATION
+    // ==========================================
+    async initWeb() {
+        this.webBrowser = await playwright_1.chromium.launch({ headless: false });
+        this.webPage = await this.webBrowser.newPage();
+        return this.webPage;
+    }
+    async initDesktop(appPathOrId) {
+        const appiumOptions = {
+            hostname: '127.0.0.1',
+            port: 4723,
+            logLevel: 'error',
+            capabilities: {
+                platformName: 'Windows',
+                'appium:automationName': 'windows',
+                'appium:app': appPathOrId,
+            }
+        };
+        this.desktopSession = await (0, webdriverio_1.remote)(appiumOptions);
+        return this.desktopSession;
+    }
+    // ==========================================
+    // WINDOW STATE OPERATIONS
+    // ==========================================
+    async windowMaximize() {
+        if (!this.desktopSession)
+            throw new Error('Desktop session uninitialized.');
+        await this.desktopSession.maximizeWindow();
+    }
+    async windowMinimize() {
+        if (!this.desktopSession)
+            throw new Error('Desktop session uninitialized.');
+        await this.desktopSession.minimizeWindow();
+    }
+    async getWindowTitle() {
+        if (!this.desktopSession)
+            throw new Error('Desktop session uninitialized.');
+        return await this.desktopSession.getTitle();
+    }
+    // ==========================================
+    // BASIC & ADVANCED MOUSE OPERATIONS
+    // ==========================================
+    async click(selector) {
+        const el = await this.desktopSession.$(selector);
+        await el.click();
+    }
+    async doubleClick(selector) {
+        const el = await this.desktopSession.$(selector);
+        await el.doubleClick();
+    }
+    async rightClick(selector) {
+        const el = await this.desktopSession.$(selector);
+        // Uses WebdriverIO / Appium W3C Actions for a custom context-click context
+        await this.desktopSession.action('pointer')
+            .move({ origin: el })
+            .down({ button: 2 }) // 2 is the Right Mouse Button
+            .up({ button: 2 })
+            .perform();
+    }
+    async dragAndDrop(sourceSelector, targetSelector) {
+        const source = await this.desktopSession.$(sourceSelector);
+        const target = await this.desktopSession.$(targetSelector);
+        await this.desktopSession.action('pointer')
+            .move({ origin: source })
+            .down({ button: 0 }) // Left click hold
+            .pause(100)
+            .move({ origin: target, duration: 500 }) // Smooth drag
+            .up({ button: 0 }) // Release
+            .perform();
+    }
+    // ==========================================
+    // KEYBOARD & INPUT OPERATIONS
+    // ==========================================
+    async typeText(selector, text) {
+        const el = await this.desktopSession.$(selector);
+        await el.setValue(text);
+    }
+    async clearInput(selector) {
+        const el = await this.desktopSession.$(selector);
+        await el.clearValue();
+    }
+    /**
+     * Simulates hotkey combinations (e.g., Ctrl + S, Ctrl + A)
+     */
+    async pressShortcut(modifier, letter) {
+        // Maps semantic keys to WebdriverIO Key Enums
+        const modKey = modifier.toLowerCase() === 'ctrl' ? webdriverio_2.Key.Control : webdriverio_2.Key.Alt;
+        await this.desktopSession.action('key')
+            .down(modKey)
+            .down(letter)
+            .up(letter)
+            .up(modKey)
+            .perform();
+    }
+    async pressGlobalKey(keyName) {
+        // Sends independent key strokes like 'Enter', 'Tab', 'Escape'
+        await this.desktopSession.keys([keyName]);
+    }
+    // ==========================================
+    // INSPECTION & ASSERTION OPERATIONS
+    // ==========================================
+    async isElementDisplayed(selector) {
+        const el = await this.desktopSession.$(selector);
+        return await el.isDisplayed();
+    }
+    async isElementEnabled(selector) {
+        const el = await this.desktopSession.$(selector);
+        return await el.isEnabled();
+    }
+    async getElementText(selector) {
+        const el = await this.desktopSession.$(selector);
+        return await el.getText();
+    }
+    // ==========================================
+    // TEARDOWN
+    // ==========================================
+    async closeAll() {
+        if (this.webBrowser)
+            await this.webBrowser.close();
+        if (this.desktopSession)
+            await this.desktopSession.deleteSession();
+    }
+}
+// ==========================================
+// RUNNING THE WORKFLOW IN WINDOWS CALC & NOTEPAD
+// ==========================================
+(async () => {
+    const driver = new UltimateAutomationWrapper();
+    try {
+        console.log('--- Instantiating Windows Calculator App ---');
+        // 'Microsoft.WindowsCalculator_8wekyb3d8bbwe!App' is the AppID for standard Win10/Win11 calc
+        await driver.initDesktop('Microsoft.WindowsCalculator_8wekyb3d8bbwe!App');
+        await driver.windowMaximize();
+        console.log('Performing native UI Math: 7 x 8 =');
+        await driver.click('~num7Button'); // '~' is WebdriverIO shorthand for AccessibilityId
+        await driver.click('~multiplyButton');
+        await driver.click('~num8Button');
+        await driver.click('~equalButton');
+        const result = await driver.getElementText('~CalculatorResults');
+        console.log(`Retrieved UI Text State: "${result}"`);
+        // Clean up Calculator session to open up Notepad
+        await driver.closeAll();
+        console.log('\n--- Instantiating Windows Notepad App ---');
+        await driver.initDesktop('notepad.exe');
+        console.log('Typing Text & Clearing Input...');
+        await driver.typeText('//*[@Name="Text Editor"]', 'This text will be replaced.');
+        await driver.clearInput('//*[@Name="Text Editor"]');
+        console.log('Typing formal entry...');
+        await driver.typeText('//*[@Name="Text Editor"]', 'Final clean text string automation input.');
+        console.log('Executing Windows Hotkeys (Ctrl + A)...');
+        await driver.pressShortcut('ctrl', 'a');
+        console.log('Sending Backspace key to erase execution selection...');
+        await driver.pressGlobalKey(webdriverio_2.Key.Backspace);
+    }
+    catch (err) {
+        console.error('Automation Runtime Failure:', err);
+    }
+    finally {
+        await driver.closeAll();
+        console.log('Wrapper execution cleaned up safely.');
+    }
+})();

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "playwright-windows-wrapper",
+  "version": "1.0.0",
+  "description": "A unified automation wrapper combining Playwright and Appium for hybrid web and Windows native testing.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+"build": "npx tsc",
+  "prepare": "npm run build"
+  },
+  "keywords": [
+    "playwright",
+    "appium",
+    "windows",
+    "automation",
+    "testing"
+  ],
+  "author": "Your Name",
+  "license": "MIT",
+  "dependencies": {
+    "appium": "^2.0.0",
+    "playwright": "^1.40.0",
+    "webdriverio": "^8.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,194 @@
+import { chromium, Browser as PWBrowser, Page as PWPage } from 'playwright';
+import { remote, RemoteOptions, Browser as AppiumBrowser } from 'webdriverio';
+import { Key } from 'webdriverio'; // Used for native key simulations
+
+class UltimateAutomationWrapper {
+  private webBrowser: PWBrowser | null = null;
+  private webPage: PWPage | null = null;
+  private desktopSession: AppiumBrowser | null = null;
+
+  // ==========================================
+  // INITIALIZATION
+  // ==========================================
+  async initWeb(): Promise<PWPage> {
+    this.webBrowser = await chromium.launch({ headless: false });
+    this.webPage = await this.webBrowser.newPage();
+    return this.webPage;
+  }
+
+  async initDesktop(appPathOrId: string): Promise<AppiumBrowser> {
+    const appiumOptions: RemoteOptions = {
+      hostname: '127.0.0.1',
+      port: 4723,
+      logLevel: 'error',
+      capabilities: {
+        platformName: 'Windows',
+        'appium:automationName': 'windows',
+        'appium:app': appPathOrId,
+      }
+    };
+    this.desktopSession = await remote(appiumOptions);
+    return this.desktopSession;
+  }
+
+  // ==========================================
+  // WINDOW STATE OPERATIONS
+  // ==========================================
+  async windowMaximize(): Promise<void> {
+    if (!this.desktopSession) throw new Error('Desktop session uninitialized.');
+    await this.desktopSession.maximizeWindow();
+  }
+
+  async windowMinimize(): Promise<void> {
+    if (!this.desktopSession) throw new Error('Desktop session uninitialized.');
+    await this.desktopSession.minimizeWindow();
+  }
+
+  async getWindowTitle(): Promise<string> {
+    if (!this.desktopSession) throw new Error('Desktop session uninitialized.');
+    return await this.desktopSession.getTitle();
+  }
+
+  // ==========================================
+  // BASIC & ADVANCED MOUSE OPERATIONS
+  // ==========================================
+  async click(selector: string): Promise<void> {
+    const el = await this.desktopSession!.$(selector);
+    await el.click();
+  }
+
+  async doubleClick(selector: string): Promise<void> {
+    const el = await this.desktopSession!.$(selector);
+    await el.doubleClick();
+  }
+
+  async rightClick(selector: string): Promise<void> {
+    const el = await this.desktopSession!.$(selector);
+    // Uses WebdriverIO / Appium W3C Actions for a custom context-click context
+    await this.desktopSession!.action('pointer')
+      .move({ origin: el })
+      .down({ button: 2 }) // 2 is the Right Mouse Button
+      .up({ button: 2 })
+      .perform();
+  }
+
+  async dragAndDrop(sourceSelector: string, targetSelector: string): Promise<void> {
+    const source = await this.desktopSession!.$(sourceSelector);
+    const target = await this.desktopSession!.$(targetSelector);
+    
+    await this.desktopSession!.action('pointer')
+      .move({ origin: source })
+      .down({ button: 0 }) // Left click hold
+      .pause(100)
+      .move({ origin: target, duration: 500 }) // Smooth drag
+      .up({ button: 0 }) // Release
+      .perform();
+  }
+
+  // ==========================================
+  // KEYBOARD & INPUT OPERATIONS
+  // ==========================================
+  async typeText(selector: string, text: string): Promise<void> {
+    const el = await this.desktopSession!.$(selector);
+    await el.setValue(text);
+  }
+
+  async clearInput(selector: string): Promise<void> {
+    const el = await this.desktopSession!.$(selector);
+    await el.clearValue();
+  }
+
+  /**
+   * Simulates hotkey combinations (e.g., Ctrl + S, Ctrl + A)
+   */
+  async pressShortcut(modifier: string, letter: string): Promise<void> {
+    // Maps semantic keys to WebdriverIO Key Enums
+    const modKey = modifier.toLowerCase() === 'ctrl' ? Key.Control : Key.Alt;
+    
+    await this.desktopSession!.action('key')
+      .down(modKey)
+      .down(letter)
+      .up(letter)
+      .up(modKey)
+      .perform();
+  }
+
+  async pressGlobalKey(keyName: string): Promise<void> {
+    // Sends independent key strokes like 'Enter', 'Tab', 'Escape'
+    await this.desktopSession!.keys([keyName]);
+  }
+
+  // ==========================================
+  // INSPECTION & ASSERTION OPERATIONS
+  // ==========================================
+  async isElementDisplayed(selector: string): Promise<boolean> {
+    const el = await this.desktopSession!.$(selector);
+    return await el.isDisplayed();
+  }
+
+  async isElementEnabled(selector: string): Promise<boolean> {
+    const el = await this.desktopSession!.$(selector);
+    return await el.isEnabled();
+  }
+
+  async getElementText(selector: string): Promise<string> {
+    const el = await this.desktopSession!.$(selector);
+    return await el.getText();
+  }
+
+  // ==========================================
+  // TEARDOWN
+  // ==========================================
+  async closeAll(): Promise<void> {
+    if (this.webBrowser) await this.webBrowser.close();
+    if (this.desktopSession) await this.desktopSession.deleteSession();
+  }
+}
+
+// ==========================================
+// RUNNING THE WORKFLOW IN WINDOWS CALC & NOTEPAD
+// ==========================================
+(async () => {
+  const driver = new UltimateAutomationWrapper();
+
+  try {
+    console.log('--- Instantiating Windows Calculator App ---');
+    // 'Microsoft.WindowsCalculator_8wekyb3d8bbwe!App' is the AppID for standard Win10/Win11 calc
+    await driver.initDesktop('Microsoft.WindowsCalculator_8wekyb3d8bbwe!App');
+    await driver.windowMaximize();
+
+    console.log('Performing native UI Math: 7 x 8 =');
+    await driver.click('~num7Button');      // '~' is WebdriverIO shorthand for AccessibilityId
+    await driver.click('~multiplyButton');
+    await driver.click('~num8Button');
+    await driver.click('~equalButton');
+
+    const result = await driver.getElementText('~CalculatorResults');
+    console.log(`Retrieved UI Text State: "${result}"`);
+
+    // Clean up Calculator session to open up Notepad
+    await driver.closeAll();
+
+    console.log('\n--- Instantiating Windows Notepad App ---');
+    await driver.initDesktop('notepad.exe');
+
+    console.log('Typing Text & Clearing Input...');
+    await driver.typeText('//*[@Name="Text Editor"]', 'This text will be replaced.');
+    await driver.clearInput('//*[@Name="Text Editor"]');
+    
+    console.log('Typing formal entry...');
+    await driver.typeText('//*[@Name="Text Editor"]', 'Final clean text string automation input.');
+
+    console.log('Executing Windows Hotkeys (Ctrl + A)...');
+    await driver.pressShortcut('ctrl', 'a');
+    
+    console.log('Sending Backspace key to erase execution selection...');
+    await driver.pressGlobalKey(Key.Backspace);
+
+  } catch (err) {
+    console.error('Automation Runtime Failure:', err);
+  } finally {
+    await driver.closeAll();
+    console.log('Wrapper execution cleaned up safely.');
+  }
+})();

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "CommonJS",
+    "lib": ["ES2022"],
+    "declaration": true,          // Generates corresponding '.d.ts' file for type safety
+    "outDir": "./dist",           // Redirect output structure to the directory
+    "rootDir": "./src",           // Only look for TypeScript files inside /src
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"]
+}