appium-mcp 1.8.15 → 1.8.16

package/src/session-store.ts

@@ -0,0 +1,151 @@
+import { AndroidUiautomator2Driver } from 'appium-uiautomator2-driver';
+import { XCUITestDriver } from 'appium-xcuitest-driver';
+import type { Client } from 'webdriver';
+import log from './logger.js';
+
+let driver: any = null;
+let sessionId: string | null = null;
+let isDeletingSession = false; // Lock to prevent concurrent deletion
+
+// Type aliases for driver variants used throughout the project.
+export type DriverInstance =
+  | Client
+  | AndroidUiautomator2Driver
+  | XCUITestDriver;
+export type NullableDriverInstance = DriverInstance | null;
+
+export const PLATFORM = {
+  android: 'Android',
+  ios: 'iOS',
+};
+
+/**
+ * Determine whether the provided driver represents a remote driver session.
+ *
+ * This checks for the presence of a string-valued `sessionId` property on the
+ * driver object, which indicates a remote/WebDriver session.
+ *
+ * @param driver - The driver instance to inspect (may be a Client, AndroidUiautomator2Driver, XCUITestDriver, or null).
+ * @returns `true` if `driver` is non-null and has a string `sessionId`; otherwise `false`.
+ */
+export function isRemoteDriverSession(driver: NullableDriverInstance): boolean {
+  if (driver) {
+    return (
+      !(driver instanceof AndroidUiautomator2Driver) &&
+      !(driver instanceof XCUITestDriver)
+    );
+  }
+  return false;
+}
+
+/**
+ * Type-guard that asserts the provided driver is an Android UiAutomator2 driver.
+ *
+ * Performs a runtime `instanceof` check. When this function returns `true`,
+ * TypeScript will narrow the variable's type to `AndroidUiautomator2Driver`.
+ * Use this helper to safely call Android-specific driver methods without
+ * casting.
+ *
+ * @param driver - The driver instance to test (may be a `Client`,
+ *   `AndroidUiautomator2Driver`, `XCUITestDriver`, or `null`).
+ * @returns `true` if `driver` is an `AndroidUiautomator2Driver`.
+ */
+export function isAndroidUiautomator2DriverSession(
+  driver: NullableDriverInstance
+): driver is AndroidUiautomator2Driver {
+  return driver instanceof AndroidUiautomator2Driver;
+}
+
+/**
+ * Type-guard that asserts the provided driver is an XCUITest (iOS) driver.
+ *
+ * Performs a runtime `instanceof` check and narrows the type to
+ * `XCUITestDriver` when true. This lets callers invoke iOS-specific driver
+ * APIs without explicit casts.
+ *
+ * @param driver - The driver instance to test (may be a `Client`,
+ *   `AndroidUiautomator2Driver`, `XCUITestDriver`, or `null`).
+ * @returns `true` if `driver` is an `XCUITestDriver`.
+ */
+export function isXCUITestDriverSession(
+  driver: NullableDriverInstance
+): driver is XCUITestDriver {
+  return driver instanceof XCUITestDriver;
+}
+
+export function setSession(d: DriverInstance, id: string | null) {
+  driver = d;
+  sessionId = id;
+  // Reset deletion flag when setting a new session
+  if (d && id) {
+    isDeletingSession = false;
+  }
+}
+
+export function getDriver(): NullableDriverInstance {
+  return driver;
+}
+
+export function getSessionId() {
+  return sessionId;
+}
+
+export function isDeletingSessionInProgress() {
+  return isDeletingSession;
+}
+
+export function hasActiveSession(): boolean {
+  return driver !== null && sessionId !== null && !isDeletingSession;
+}
+
+export async function safeDeleteSession(): Promise<boolean> {
+  // Check if there's no session to delete
+  if (!driver || !sessionId) {
+    log.info('No active session to delete.');
+    return false;
+  }
+
+  // Check if deletion is already in progress
+  if (isDeletingSession) {
+    log.info('Session deletion already in progress, skipping...');
+    return false;
+  }
+
+  // Set lock
+  isDeletingSession = true;
+
+  try {
+    log.info('Deleting current session');
+    await driver.deleteSession();
+
+    // Clear the session from store
+    driver = null;
+    sessionId = null;
+
+    log.info('Session deleted successfully.');
+    return true;
+  } catch (error) {
+    log.error('Error deleting session:', error);
+    throw error;
+  } finally {
+    // Always release lock
+    isDeletingSession = false;
+  }
+}
+
+export const getPlatformName = (driver: any): string => {
+  if (driver instanceof AndroidUiautomator2Driver) {
+    return PLATFORM.android;
+  }
+  if (driver instanceof XCUITestDriver) {
+    return PLATFORM.ios;
+  }
+
+  if ((driver as Client).isAndroid) {
+    return PLATFORM.android;
+  } else if ((driver as Client).isIOS) {
+    return PLATFORM.ios;
+  }
+
+  throw new Error('Unknown driver type');
+};

package/src/tests/README.md

@@ -0,0 +1,83 @@
+# Tests for Mobile Agent
+
+This directory contains unit tests for the Mobile Agent project.
+
+## Running Tests
+
+To run all tests:
+
+```bash
+npm test
+```
+
+To run specific test files:
+
+```bash
+# Run tests for the locator generation functionality
+npm run test:locators
+```
+
+## Test Files
+
+### generate-all-locators.test.ts
+
+This file contains tests for the `generateAllElementLocators` function, which is responsible for generating locators for all elements in a page source XML.
+
+The tests cover:
+
+1. Basic functionality with valid XML
+2. Handling of invalid/empty XML
+3. Various filtering options:
+   - `includeTagNames` - Include only specific element types
+   - `excludeTagNames` - Exclude specific element types
+   - `minAttributeCount` - Filter elements by minimum attribute count
+   - `fetchableOnly` - Include only interactable elements (platform-specific)
+   - `clickableOnly` - Include only clickable elements
+
+## Adding New Tests
+
+When adding new tests:
+
+1. Create a new test file in the `src/tests` directory with the `.test.ts` extension
+2. Import the necessary functions and types from the source files
+3. Use Jest's `describe`, `test`, and `expect` functions to structure your tests
+4. Add a new script to `package.json` for running your specific test file
+
+## Test Structure
+
+Tests should follow this general structure:
+
+```typescript
+import { describe, test, expect } from '@jest/globals';
+import { functionToTest } from '../path/to/function.js';
+
+describe('functionToTest', () => {
+  test('should do something specific', () => {
+    // Arrange - set up test data
+    const input = 'some input';
+    
+    // Act - call the function
+    const result = functionToTest(input);
+    
+    // Assert - verify the result
+    expect(result).toBe('expected output');
+  });
+});
+```
+
+## Mocking
+
+For tests that require mocking dependencies, use Jest's mocking capabilities:
+
+```typescript
+import { jest } from '@jest/globals';
+
+// Mock a module
+jest.mock('../path/to/module.js');
+
+// Create a mock function
+const mockFunction = jest.fn();
+mockFunction.mockReturnValue('mocked value');
+```
+
+Note that when working with ESM modules, you may need to use different mocking approaches than with CommonJS modules.

package/src/tests/__mocks__/@appium/support.ts

@@ -0,0 +1,30 @@
+// Mock @appium/support for Jest tests
+// This avoids the ESM/CommonJS mismatch with uuid dependency
+
+export const logger = {
+  getLogger: (name: string) =>
+    // Simple logger implementation for tests
+    // No-op functions that match the logger interface
+    ({
+      debug: (message: string, ...args: any[]) => {
+        // Silent in tests by default
+      },
+      info: (message: string, ...args: any[]) => {
+        // Silent in tests by default
+      },
+      warn: (message: string, ...args: any[]) => {
+        // Silent in tests by default
+      },
+      error: (message: string, ...args: any[]) => {
+        // Silent in tests by default
+      },
+      trace: (message: string, ...args: any[]) => {
+        // Silent in tests by default
+      },
+    }),
+};
+
+// Export other commonly used utilities from @appium/support if needed
+export default {
+  logger,
+};

package/src/tests/generate-all-locators.test.ts

@@ -0,0 +1,178 @@
+import { describe, test, expect } from '@jest/globals';
+import {
+  generateAllElementLocators,
+  ElementWithLocators,
+} from '../locators/generate-all-locators.js';
+
+describe('generateAllElementLocators', () => {
+  // Sample XML for testing
+  const sampleXML = `
+    <hierarchy>
+      <android.widget.FrameLayout resource-id="android:id/content">
+        <android.widget.LinearLayout>
+          <android.widget.TextView text="Hello World" resource-id="com.example:id/text_view" clickable="true" enabled="true" displayed="true" />
+          <android.widget.Button text="Click Me" resource-id="com.example:id/button" clickable="true" enabled="true" displayed="true" />
+          <android.widget.EditText text="" resource-id="com.example:id/edit_text" clickable="true" enabled="true" displayed="true" />
+        </android.widget.LinearLayout>
+      </android.widget.FrameLayout>
+    </hierarchy>
+  `;
+
+  // Sample iOS XML for testing
+  const sampleIOSXML = `
+    <hierarchy>
+      <XCUIElementTypeApplication>
+        <XCUIElementTypeWindow>
+          <XCUIElementTypeButton name="Click Me" enabled="true" visible="true" />
+          <XCUIElementTypeTextField name="Enter text" enabled="true" visible="true" />
+          <XCUIElementTypeStaticText name="Hello World" enabled="true" visible="true" />
+        </XCUIElementTypeWindow>
+      </XCUIElementTypeApplication>
+    </hierarchy>
+  `;
+
+  test('should return an array when given valid XML', () => {
+    // Call the function with the sample XML
+    const result = generateAllElementLocators(sampleXML, true, 'uiautomator2');
+
+    // Basic validation of the result
+    expect(Array.isArray(result)).toBe(true);
+    expect(result.length).toBeGreaterThan(0);
+
+    // Verify the structure of the returned elements
+    if (result.length > 0) {
+      const element = result[0];
+      expect(element).toHaveProperty('tagName');
+      expect(element).toHaveProperty('locators');
+      expect(element).toHaveProperty('text');
+      expect(element).toHaveProperty('contentDesc');
+      expect(element).toHaveProperty('resourceId');
+      expect(element).toHaveProperty('clickable');
+      expect(element).toHaveProperty('enabled');
+      expect(element).toHaveProperty('displayed');
+    }
+  });
+
+  test('should return an empty array when given invalid XML', () => {
+    // Call the function with invalid XML (just a root element with no content)
+    const result = generateAllElementLocators(
+      '<hierarchy></hierarchy>',
+      true,
+      'uiautomator2'
+    );
+
+    // Verify the result is an empty array or at least doesn't throw an error
+    expect(Array.isArray(result)).toBe(true);
+    expect(result.length).toBe(0);
+  });
+
+  test('should apply includeTagNames filter correctly', () => {
+    // Call the function with filters
+    const result = generateAllElementLocators(sampleXML, true, 'uiautomator2', {
+      includeTagNames: ['android.widget.Button'],
+    });
+
+    // If the filter works, either the result will be empty (if no buttons found)
+    // or all elements will be buttons
+    if (result.length > 0) {
+      expect(
+        result.every((element) => element.tagName.includes('Button'))
+      ).toBe(true);
+    }
+  });
+
+  test('should apply excludeTagNames filter correctly', () => {
+    // Call the function with excludeTagNames filter
+    const result = generateAllElementLocators(sampleXML, true, 'uiautomator2', {
+      excludeTagNames: ['android.widget.Button'],
+    });
+
+    // Verify no Button elements are included
+    expect(result.every((element) => !element.tagName.includes('Button'))).toBe(
+      true
+    );
+  });
+
+  test('should apply minAttributeCount filter correctly', () => {
+    // Call the function with minAttributeCount filter
+    const result = generateAllElementLocators(sampleXML, true, 'uiautomator2', {
+      minAttributeCount: 3,
+    });
+
+    // All elements should have at least 3 attributes
+    if (result.length > 0) {
+      // We can't directly check the attributes count since we only have the processed elements
+      // But we can verify that elements with fewer attributes are filtered out
+      expect(result.length).toBeLessThanOrEqual(
+        generateAllElementLocators(sampleXML, true, 'uiautomator2').length
+      );
+    }
+  });
+
+  test('should handle fetchableOnly filter for Android', () => {
+    // Call the function with fetchableOnly filter
+    const result = generateAllElementLocators(sampleXML, true, 'uiautomator2', {
+      fetchableOnly: true,
+    });
+
+    // Verify the result contains only interactable elements
+    if (result.length > 0) {
+      const interactableTags = [
+        'EditText',
+        'Button',
+        'ImageButton',
+        'CheckBox',
+        'RadioButton',
+        'Switch',
+        'ToggleButton',
+        'TextView',
+      ];
+
+      expect(
+        result.every(
+          (element) =>
+            interactableTags.some((tag) => element.tagName.includes(tag)) ||
+            element.clickable === true
+        )
+      ).toBe(true);
+    }
+  });
+
+  test('should handle fetchableOnly filter for iOS', () => {
+    // Call the function with fetchableOnly filter for iOS
+    const result = generateAllElementLocators(sampleIOSXML, true, 'xcuitest', {
+      fetchableOnly: true,
+    });
+
+    // Verify the result contains only interactable iOS elements
+    if (result.length > 0) {
+      const interactableTags = [
+        'XCUIElementTypeTextField',
+        'XCUIElementTypeSecureTextField',
+        'XCUIElementTypeButton',
+        'XCUIElementTypeImage',
+        'XCUIElementTypeSwitch',
+        'XCUIElementTypeStaticText',
+        'XCUIElementTypeTextView',
+        'XCUIElementTypeCell',
+        'XCUIElementTypeLink',
+      ];
+
+      expect(
+        result.every((element) =>
+          interactableTags.some((tag) => element.tagName.includes(tag))
+        )
+      ).toBe(true);
+    }
+  });
+
+  test('should handle clickableOnly filter correctly', () => {
+    // Call the function with clickableOnly filter
+    const result = generateAllElementLocators(sampleXML, true, 'uiautomator2', {
+      clickableOnly: true,
+    });
+
+    // Verify all elements are clickable
+    expect(result.every((element) => element.clickable === true)).toBe(true);
+  });
+});