appium-mcp 1.8.15 → 1.9.0

package/src/tests/screenshot.test.ts

@@ -0,0 +1,279 @@
+import {
+  describe,
+  test,
+  expect,
+  beforeEach,
+  afterEach,
+  jest,
+} from '@jest/globals';
+import { join, isAbsolute } from 'path';
+import * as os from 'node:os';
+
+/**
+ * Local implementation of resolveScreenshotDir for testing.
+ * This mirrors the implementation in screenshot.ts to avoid importing
+ * the module which has heavy dependencies.
+ */
+function resolveScreenshotDir(): string {
+  const screenshotDir = process.env.SCREENSHOTS_DIR;
+
+  if (!screenshotDir) {
+    return os.tmpdir();
+  }
+
+  if (isAbsolute(screenshotDir)) {
+    return screenshotDir;
+  }
+
+  return join(process.cwd(), screenshotDir);
+}
+
+/**
+ * Interface for screenshot dependencies (mirrors screenshot.ts).
+ */
+interface ScreenshotDeps {
+  getDriver: () => { getScreenshot: () => Promise<string> } | null;
+  writeFile: (path: string, data: Buffer) => Promise<void>;
+  mkdir: (path: string, options: { recursive: boolean }) => Promise<void>;
+  resolveScreenshotDir: () => string;
+  dateNow: () => number;
+}
+
+/**
+ * Local implementation of executeScreenshot for testing.
+ * This mirrors the implementation in screenshot.ts.
+ */
+async function executeScreenshot(deps: ScreenshotDeps): Promise<any> {
+  const driver = deps.getDriver();
+  if (!driver) {
+    throw new Error('No driver found');
+  }
+
+  try {
+    const screenshotBase64 = await driver.getScreenshot();
+    const screenshotBuffer = Buffer.from(screenshotBase64, 'base64');
+    const timestamp = deps.dateNow();
+    const filename = `screenshot_${timestamp}.png`;
+    const screenshotDir = deps.resolveScreenshotDir();
+
+    await deps.mkdir(screenshotDir, { recursive: true });
+    const filepath = join(screenshotDir, filename);
+    await deps.writeFile(filepath, screenshotBuffer);
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Screenshot saved successfully to: ${filename}`,
+        },
+      ],
+    };
+  } catch (err: any) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Failed to take screenshot. err: ${err.toString()}`,
+        },
+      ],
+    };
+  }
+}
+
+describe('resolveScreenshotDir', () => {
+  const originalEnv = process.env.SCREENSHOTS_DIR;
+  const cwd = process.cwd();
+
+  beforeEach(() => {
+    delete process.env.SCREENSHOTS_DIR;
+  });
+
+  afterEach(() => {
+    if (originalEnv !== undefined) {
+      process.env.SCREENSHOTS_DIR = originalEnv;
+    } else {
+      delete process.env.SCREENSHOTS_DIR;
+    }
+  });
+
+  test('should return os.tmpdir() when SCREENSHOTS_DIR is not set', () => {
+    const result = resolveScreenshotDir();
+    expect(result).toBe(os.tmpdir());
+  });
+
+  test('should return os.tmpdir() when SCREENSHOTS_DIR is empty string', () => {
+    process.env.SCREENSHOTS_DIR = '';
+    const result = resolveScreenshotDir();
+    expect(result).toBe(os.tmpdir());
+  });
+
+  test('should return absolute path as-is when SCREENSHOTS_DIR is absolute', () => {
+    const absolutePath = '/tmp/screenshots';
+    process.env.SCREENSHOTS_DIR = absolutePath;
+    const result = resolveScreenshotDir();
+    expect(result).toBe(absolutePath);
+  });
+
+  test('should join relative path with process.cwd()', () => {
+    const relativePath = 'screenshots';
+    process.env.SCREENSHOTS_DIR = relativePath;
+    const result = resolveScreenshotDir();
+    expect(result).toBe(join(cwd, relativePath));
+  });
+
+  test('should handle nested relative paths', () => {
+    const relativePath = 'output/screenshots/test';
+    process.env.SCREENSHOTS_DIR = relativePath;
+    const result = resolveScreenshotDir();
+    expect(result).toBe(join(cwd, relativePath));
+  });
+
+  test('should handle relative path starting with ./', () => {
+    const relativePath = './screenshots';
+    process.env.SCREENSHOTS_DIR = relativePath;
+    const result = resolveScreenshotDir();
+    expect(result).toBe(join(cwd, relativePath));
+  });
+
+  test('should handle relative path with parent directory reference', () => {
+    const relativePath = '../screenshots';
+    process.env.SCREENSHOTS_DIR = relativePath;
+    const result = resolveScreenshotDir();
+    expect(result).toBe(join(cwd, relativePath));
+  });
+});
+
+describe('executeScreenshot', () => {
+  const mockBase64 = 'dGVzdA=='; // 'test' in base64
+  const mockTimestamp = 1234567890;
+
+  function createMockDeps(
+    overrides: Partial<ScreenshotDeps> = {}
+  ): ScreenshotDeps {
+    return {
+      getDriver: jest.fn(() => ({
+        getScreenshot: jest.fn(() => Promise.resolve(mockBase64)),
+      })) as any,
+      writeFile: jest.fn(() => Promise.resolve()) as any,
+      mkdir: jest.fn(() => Promise.resolve()) as any,
+      resolveScreenshotDir: jest.fn(() => '/mock/screenshots') as any,
+      dateNow: jest.fn(() => mockTimestamp) as any,
+      ...overrides,
+    };
+  }
+
+  test('should throw error when no driver found', async () => {
+    const deps = createMockDeps({
+      getDriver: jest.fn(() => null) as any,
+    });
+
+    await expect(executeScreenshot(deps)).rejects.toThrow('No driver found');
+  });
+
+  test('should return success content with filename', async () => {
+    const deps = createMockDeps();
+
+    const result = await executeScreenshot(deps);
+
+    expect(result).toEqual({
+      content: [
+        {
+          type: 'text',
+          text: `Screenshot saved successfully to: screenshot_${mockTimestamp}.png`,
+        },
+      ],
+    });
+  });
+
+  test('should use resolved screenshot directory from SCREENSHOTS_DIR', async () => {
+    const customDir = '/custom/path/screenshots';
+    const deps = createMockDeps({
+      resolveScreenshotDir: jest.fn(() => customDir) as any,
+    });
+
+    await executeScreenshot(deps);
+
+    expect(deps.mkdir).toHaveBeenCalledWith(customDir, { recursive: true });
+    expect(deps.writeFile).toHaveBeenCalledWith(
+      join(customDir, `screenshot_${mockTimestamp}.png`),
+      expect.any(Buffer)
+    );
+  });
+
+  test('should create directory with recursive option', async () => {
+    const deps = createMockDeps();
+
+    await executeScreenshot(deps);
+
+    expect(deps.mkdir).toHaveBeenCalledWith('/mock/screenshots', {
+      recursive: true,
+    });
+  });
+
+  test('should write screenshot buffer to correct filepath', async () => {
+    const deps = createMockDeps();
+
+    await executeScreenshot(deps);
+
+    expect(deps.writeFile).toHaveBeenCalledWith(
+      `/mock/screenshots/screenshot_${mockTimestamp}.png`,
+      Buffer.from(mockBase64, 'base64')
+    );
+  });
+
+  test('should return error content when screenshot fails', async () => {
+    const errorMessage = 'Screenshot capture failed';
+    const deps = createMockDeps({
+      getDriver: jest.fn(() => ({
+        getScreenshot: jest.fn(() => Promise.reject(new Error(errorMessage))),
+      })) as any,
+    });
+
+    const result = await executeScreenshot(deps);
+
+    expect(result).toEqual({
+      content: [
+        {
+          type: 'text',
+          text: `Failed to take screenshot. err: Error: ${errorMessage}`,
+        },
+      ],
+    });
+  });
+
+  test('should return error content when mkdir fails', async () => {
+    const errorMessage = 'Permission denied';
+    const deps = createMockDeps({
+      mkdir: jest.fn(() => Promise.reject(new Error(errorMessage))) as any,
+    });
+
+    const result = await executeScreenshot(deps);
+
+    expect(result).toEqual({
+      content: [
+        {
+          type: 'text',
+          text: `Failed to take screenshot. err: Error: ${errorMessage}`,
+        },
+      ],
+    });
+  });
+
+  test('should return error content when writeFile fails', async () => {
+    const errorMessage = 'Disk full';
+    const deps = createMockDeps({
+      writeFile: jest.fn(() => Promise.reject(new Error(errorMessage))) as any,
+    });
+
+    const result = await executeScreenshot(deps);
+
+    expect(result).toEqual({
+      content: [
+        {
+          type: 'text',
+          text: `Failed to take screenshot. err: Error: ${errorMessage}`,
+        },
+      ],
+    });
+  });
+});

package/src/tests/test-setup-wda.ts

@@ -0,0 +1,255 @@
+/**
+ * Test file for setup-wda tool
+ * Run with: npx tsx src/tests/test-setup-wda.ts
+ */
+import path from 'path';
+import fs from 'fs';
+import os from 'os';
+import { createRequire } from 'module';
+import https from 'https';
+import { exec } from 'child_process';
+import { promisify } from 'util';
+
+const execAsync = promisify(exec);
+
+// Mock server object to test the tool
+class MockServer {
+  private tools: Map<string, any> = new Map();
+
+  addTool(tool: any) {
+    this.tools.set(tool.name, tool);
+    console.log(`✅ Tool registered: ${tool.name}`);
+  }
+
+  getTool(name: string) {
+    return this.tools.get(name);
+  }
+}
+
+async function downloadFile(url: string, destPath: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const file = fs.createWriteStream(destPath);
+
+    https
+      .get(url, async (response) => {
+        // Handle redirects
+        if (response.statusCode === 302 || response.statusCode === 301) {
+          file.close();
+          fs.unlinkSync(destPath);
+          try {
+            await downloadFile(response.headers.location!, destPath);
+            resolve();
+          } catch (err) {
+            reject(err);
+          }
+          return;
+        }
+
+        if (response.statusCode !== 200) {
+          file.close();
+          fs.unlinkSync(destPath);
+          return reject(
+            new Error(`Failed to download: ${response.statusCode}`)
+          );
+        }
+
+        const totalSize = parseInt(
+          response.headers['content-length'] || '0',
+          10
+        );
+        let downloadedSize = 0;
+
+        response.on('data', (chunk) => {
+          downloadedSize += chunk.length;
+          const percent = ((downloadedSize / totalSize) * 100).toFixed(1);
+          process.stdout.write(
+            `\r   Downloading... ${percent}% (${Math.round(downloadedSize / 1024 / 1024)}MB / ${Math.round(totalSize / 1024 / 1024)}MB)`
+          );
+        });
+
+        response.pipe(file);
+
+        file.on('finish', () => {
+          file.close();
+          process.stdout.write('\n');
+          resolve();
+        });
+      })
+      .on('error', (err) => {
+        file.close();
+        fs.unlinkSync(destPath);
+        reject(err);
+      });
+  });
+}
+
+async function unzipFile(zipPath: string, destDir: string): Promise<void> {
+  console.log(`   Extracting to: ${destDir}`);
+  await execAsync(`unzip -q "${zipPath}" -d "${destDir}"`);
+  console.log('   ✅ Extraction complete');
+}
+
+function cachePath(folder: string): string {
+  return path.join(os.homedir(), '.cache', 'appium-mcp', folder);
+}
+
+async function getLatestWDAVersion(): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const options = {
+      hostname: 'api.github.com',
+      path: '/repos/appium/WebDriverAgent/releases/latest',
+      method: 'GET',
+      headers: {
+        'User-Agent': 'mcp-appium-test',
+        Accept: 'application/vnd.github.v3+json',
+      },
+    };
+
+    https
+      .get(options, (response) => {
+        let data = '';
+
+        response.on('data', (chunk) => {
+          data += chunk;
+        });
+
+        response.on('end', () => {
+          try {
+            const release = JSON.parse(data);
+            if (release.tag_name) {
+              // Remove 'v' prefix if present
+              const version = release.tag_name.replace(/^v/, '');
+              resolve(version);
+            } else {
+              reject(new Error('No tag_name found in release data'));
+            }
+          } catch (error) {
+            reject(error);
+          }
+        });
+      })
+      .on('error', (err) => {
+        reject(err);
+      });
+  });
+}
+
+async function main() {
+  console.log('🧪 Testing WDA Download and Setup\n');
+  console.log('='.repeat(60));
+
+  try {
+    // Fetch latest WDA version from GitHub releases API
+    console.log('\n🔍 Fetching latest WDA version from GitHub...');
+    const wdaVersion = await getLatestWDAVersion();
+    console.log(`✅ Latest WDA Version: v${wdaVersion}`);
+    console.log(
+      '   Source: https://github.com/appium/WebDriverAgent/releases/latest'
+    );
+
+    // Create cache directory structure using home directory
+    const versionCacheDir = cachePath(`wda/${wdaVersion}`);
+    const extractDir = path.join(versionCacheDir, 'extracted');
+    const zipPath = path.join(
+      versionCacheDir,
+      'WebDriverAgentRunner-Runner.zip'
+    );
+    const appPath = path.join(extractDir, 'WebDriverAgentRunner-Runner.app');
+
+    console.log('\n📁 Cache Directory:', versionCacheDir);
+    console.log(`   (~/.cache/appium-device-farm/wda/${wdaVersion})`);
+
+    // Check if this version is already cached
+    if (fs.existsSync(appPath)) {
+      console.log('\n✅ WDA version already cached! Skipping download.');
+      console.log(`   Location: ${appPath}`);
+
+      // Show app contents
+      const appContents = fs.readdirSync(appPath);
+      console.log('\n📋 Cached App bundle contents:');
+      appContents.forEach((item) => {
+        console.log(`      - ${item}`);
+      });
+
+      console.log('\n' + '='.repeat(60));
+      console.log('🎉 Using cached WDA!');
+      console.log(`💡 Cache location: ${versionCacheDir}`);
+      return;
+    }
+
+    // Version not cached, proceed with download
+    console.log('\n⚠️  Version not found in cache. Downloading...');
+
+    // Create cache directories
+    fs.mkdirSync(versionCacheDir, { recursive: true });
+    fs.mkdirSync(extractDir, { recursive: true });
+
+    // Download URL
+    const downloadUrl = `https://github.com/appium/WebDriverAgent/releases/download/v${wdaVersion}/WebDriverAgentRunner-Runner.zip`;
+
+    console.log('\n⬇️  Downloading WDA from GitHub releases...');
+    console.log(`   URL: ${downloadUrl}`);
+
+    const startTime = Date.now();
+    await downloadFile(downloadUrl, zipPath);
+    const downloadTime = ((Date.now() - startTime) / 1000).toFixed(1);
+
+    console.log(`   ✅ Download complete (${downloadTime}s)`);
+
+    // Check file size
+    const stats = fs.statSync(zipPath);
+    const fileSizeMB = (stats.size / 1024 / 1024).toFixed(2);
+    console.log(`   📦 File size: ${fileSizeMB} MB`);
+
+    // Unzip the file
+    console.log('\n📂 Extracting WDA bundle...');
+    await unzipFile(zipPath, extractDir);
+
+    // List contents
+    console.log('\n📋 Extracted contents:');
+    const contents = fs.readdirSync(extractDir);
+    contents.forEach((item) => {
+      const itemPath = path.join(extractDir, item);
+      const isDir = fs.statSync(itemPath).isDirectory();
+      console.log(`   ${isDir ? '📁' : '📄'} ${item}`);
+    });
+
+    // Check if WebDriverAgentRunner-Runner.app exists
+    if (fs.existsSync(appPath)) {
+      console.log('\n✅ WebDriverAgentRunner-Runner.app found!');
+      console.log(`   Location: ${appPath}`);
+
+      // Show app contents
+      const appContents = fs.readdirSync(appPath);
+      console.log('\n   App bundle contents:');
+      appContents.forEach((item) => {
+        console.log(`      - ${item}`);
+      });
+    } else {
+      console.log('\n⚠️  WebDriverAgentRunner-Runner.app not found');
+    }
+
+    console.log('\n' + '='.repeat(60));
+    console.log('🎉 Download and setup completed successfully!');
+    console.log(`\n💡 Cached location: ${versionCacheDir}`);
+    console.log(
+      '   This version will be reused on subsequent runs (no re-download needed)'
+    );
+  } catch (error: any) {
+    console.error('\n❌ Test failed:', error.message);
+    if (error.stack) {
+      console.error('\nStack trace:', error.stack);
+    }
+    process.exit(1);
+  }
+}
+
+// Run main function
+(async () => {
+  try {
+    await main();
+  } catch (error: any) {
+    console.error('\n💥 Unexpected error:', error);
+    process.exit(1);
+  }
+})();

package/src/tools/README.md

@@ -0,0 +1,179 @@
+# Tools Directory
+
+This directory contains all MCP tools available in MCP Appium.
+
+## Tool Categories
+
+### Session Management (`session/`)
+
+- `create-session.ts` - Create mobile automation sessions
+- `delete-session.ts` - Clean up sessions
+- `select-platform.ts` - Choose Android or iOS
+- `select-device.ts` - Choose specific device
+
+### iOS Setup (`ios/`)
+
+- `boot-simulator.ts` - Boot iOS simulators
+- `setup-wda.ts` - Setup WebDriverAgent
+- `install-wda.ts` - Install WebDriverAgent
+
+### Navigation (`navigations/`)
+
+- `scroll.ts` - Scroll screens
+- `scroll-to-element.ts` - Scroll until element found
+- `swipe.ts` - Swipe screens in any direction or between custom coordinates
+
+### Element Interactions (`interactions/`)
+
+- `find.ts` - Find elements
+- `click.ts` - Click elements
+- `double-tap.ts` - Double tap elements
+- `long-press.ts` - Long press (press and hold) elements
+- `drag-and-drop.ts` - Drag and drop elements or coordinates
+- `set-value.ts` - Enter text
+- `get-text.ts` - Get element text
+- `get-page-source.ts` - Get page source (XML) from current screen
+- `screenshot.ts` - Capture screenshots
+
+### App Management (`app-management/`)
+
+- `activate-app.ts` - Activate apps
+- `terminate-app.ts` - Terminate apps
+- `install-app.ts` - Install apps
+- `uninstall-app.ts` - Uninstall apps
+- `list-apps.ts` - List installed apps
+
+### Test Generation (`test-generation/`)
+
+- `locators.ts` - Generate page locators
+- `generate-tests.ts` - Generate test code from scenarios
+
+### Documentation (`documentation/`)
+
+- `answer-appium.ts` - Answer Appium questions using RAG
+
+## Adding a New Tool
+
+See [docs/CONTRIBUTING.md](../../docs/CONTRIBUTING.md) for detailed instructions.
+
+Quick steps:
+
+1. Create a new file in the appropriate subdirectory (e.g., `interactions/my-tool.ts`)
+2. Define the tool following the template
+3. Import and register it in `index.ts`
+4. Test with `npm run build && npm start`
+
+### Tool Template
+
+```typescript
+import { FastMCP } from 'fastmcp/dist/FastMCP.js';
+import { z } from 'zod';
+import { getDriver } from '../../session-store.js';
+
+export default function myTool(server: FastMCP): void {
+  server.addTool({
+    name: 'appium_my_tool',
+    description: 'What this tool does',
+    parameters: z.object({
+      param: z.string().describe('Parameter description'),
+    }),
+    annotations: {
+      readOnlyHint: false,
+      openWorldHint: false,
+    },
+    execute: async (args: any, context: any): Promise<any> => {
+      const driver = getDriver();
+      if (!driver) {
+        throw new Error('No active session');
+      }
+
+      // Implementation
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: 'Success',
+          },
+        ],
+      };
+    },
+  });
+}
+```
+
+### Registering a Tool
+
+Add to `src/tools/index.ts`:
+
+```typescript
+import myTool from './interactions/my-tool.js';
+
+export default function registerTools(server: FastMCP): void {
+  // ... existing tools ...
+  myTool(server);
+  // ...
+}
+```
+
+## Best Practices
+
+1. **Always check for active session**: Use `getDriver()` and check for null
+2. **Provide helpful errors**: Give clear error messages
+3. **Use proper types**: Leverage TypeScript and Zod for type safety
+4. **Add logging**: Use the logger from `logger.js` for debugging. Import with: `import log from 'logger.js'`. Use `log.info()`, `log.error()`, `log.warn()` instead of `console.log/error/warn` to maintain JSON-RPC compatibility
+5. **Handle errors**: Always wrap risky operations in try-catch
+6. **Return proper format**: Always return content in expected MCP format
+
+## Session Store
+
+Tools interact with the session through `session-store.ts`:
+
+```typescript
+import {
+  getDriver,
+  hasActiveSession,
+  safeDeleteSession,
+} from '../../session-store.js';
+
+// Check if session exists
+if (!hasActiveSession()) {
+  throw new Error('No active session');
+}
+
+// Get the driver
+const driver = getDriver();
+
+// Use the driver
+await driver.someMethod();
+```
+
+## Common Patterns
+
+### Platform-Specific Logic
+
+```typescript
+import { getPlatformName } from '../../session-store.js';
+
+if (getPlatformName(driver) === 'Android') {
+  // Android implementation
+} else if (getPlatformName(driver) === 'iOS') {
+  // iOS implementation
+}
+```
+
+## Testing
+
+After adding a new tool:
+
+1. Build: `npm run build`
+2. Run linter: `npm run lint`
+3. Test with an MCP client
+4. Verify tool appears in tools list
+
+## Need Help?
+
+- Check existing tools for examples
+- Read [docs/CONTRIBUTING.md](../../docs/CONTRIBUTING.md)
+- Look at examples in `examples/` directory
+- Open an issue for questions