MCP Appium-сервер
Реализация сервера Model Context Protocol (MCP) для автоматизации мобильных приложений с использованием Appium.
Предпосылки
- Node.js (v14 или выше)
- Комплект разработчика Java (JDK)
- Android SDK (для тестирования Android)
- Xcode (для тестирования iOS, только macOS)
- Сервер Appium
- Устройство Android или эмулятор / Устройство iOS или симулятор
Настройка среды
Перед выполнением любых команд убедитесь, что переменные среды настроены правильно:
- Убедитесь, что ваш
.bash_profile , .zshrc или другой файл конфигурации оболочки содержит необходимые переменные среды:
# Example environment variables in ~/.bash_profile
export JAVA_HOME=/path/to/your/java
export ANDROID_HOME=/path/to/your/android/sdk
export PATH=$PATH:$ANDROID_HOME/tools:$ANDROID_HOME/platform-tools
- Перед запуском MCP-Appium создайте файл среды:
source ~/.bash_profile # For bash
# OR
source ~/.zshrc # For zsh
Примечание : система попытается автоматически получить ваш .bash_profile при инициализации драйвера, но рекомендуется вручную убедиться в правильности настройки среды перед запуском тестов в новом сеансе терминала.
Конфигурация инструментов командной строки Xcode
Для тестирования iOS необходима правильная настройка инструментов командной строки Xcode:
- Установите инструменты командной строки Xcode, если они еще не установлены:
- Проверьте установку и текущий путь Xcode:
- При необходимости укажите правильный путь Xcode (особенно если у вас несколько версий Xcode):
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
- Примите лицензионные соглашения Xcode:
sudo xcodebuild -license accept
- Для тестирования на реальном устройстве iOS убедитесь, что ваша учетная запись разработчика Apple правильно настроена в Xcode:
- Открыть X-код
- Перейдите в Настройки > Учетные записи.
- Добавьте свой Apple ID, если вы еще этого не сделали.
- Загрузите необходимые профили обеспечения
- Настройте переменные среды для разработки iOS:
# Add these to your ~/.bash_profile or ~/.zshrc
export DEVELOPER_DIR="/Applications/Xcode.app/Contents/Developer"
export PATH="$DEVELOPER_DIR/usr/bin:$PATH"
- Источник вашей обновленной конфигурации:
source ~/.bash_profile # For bash
# OR
source ~/.zshrc # For zsh
Настраивать
- Установить зависимости:
- Установите и запустите сервер Appium:
npm install -g appium
appium
- Настройте Android-устройство/эмулятор:
- Включите параметры разработчика на вашем Android-устройстве
- Включить отладку по USB
- Подключите устройство через USB или запустите эмулятор
- Проверьте, подключено ли устройство с помощью
adb devices
- Для тестирования iOS (только macOS):
- Убедитесь, что установлены инструменты командной строки Xcode:
xcode-select --install - Настройте симулятор iOS или подключите реальное устройство
- Доверяйте компьютеру разработчика на устройстве iOS, если используете реальное устройство
Проведение тестов
- Создайте проект:
- Запустите MCP-сервер:
- В новом терминале запустите тест:
Тестовая конфигурация
Конфигурация Android
В примере теста в качестве демо используется приложение Android Settings. Чтобы протестировать собственное приложение:
- Отредактируйте
examples/appium-test.ts :- Обновите
deviceName , чтобы он соответствовал вашему устройству. - Укажите путь
app в вашем APK-файле или - Обновление
appPackage и appActivity для установленного приложения
- Конфигурация общих возможностей:
const capabilities: AppiumCapabilities = {
platformName: "Android",
deviceName: "YOUR_DEVICE_NAME",
automationName: "UiAutomator2",
// For installing and testing an APK:
app: "./path/to/your/app.apk",
// OR for testing an installed app:
appPackage: "your.app.package",
appActivity: ".MainActivity",
noReset: true,
};
Конфигурация iOS
Для тестирования iOS с использованием новой поддержки командной строки Xcode:
- Пример конфигурации в
examples/xcode-appium-example.ts :
const capabilities: AppiumCapabilities = {
platformName: "iOS",
deviceName: "iPhone 13", // Your simulator or device name
automationName: "XCUITest",
udid: "DEVICE_UDID", // Get this from XcodeCommands.getIosSimulators()
// For installing and testing an app:
app: "./path/to/your/app.app",
// OR for testing an installed app:
bundleId: "com.your.app",
noReset: true,
};
Доступные действия
Сервер MCP поддерживает различные действия Appium:
- Взаимодействие элементов:
- Найти элементы
- Элементы касания/щелчка с API действий W3C (см. раздел «Стандартные жесты W3C»)
- Введите текст
- Прокрутите до элемента с помощью W3C Actions API
- Длительное нажатие
- Управление приложениями:
- Запустить/закрыть приложение
- Сбросить приложение
- Получить текущий пакет/активность
- Элементы управления устройством:
- Ориентация экрана
- Управление клавиатурой
- Блокировка/разблокировка устройства
- Скриншоты
- Информация о батарее
- Расширенные возможности:
- Переключение контекста (Native/WebView)
- Операции с файлами
- Уведомления
- Пользовательские жесты
- Инструменты командной строки Xcode (только для iOS):
- Управление симуляторами iOS (загрузка, выключение)
- Установка/удаление приложений на симуляторах
- Запуск/завершение работы приложений
- Делайте скриншоты
- Запись видео
- Создать/удалить симуляторы
- Получить типы устройств и время выполнения
Стандартные жесты W3C
Библиотека MCP-Appium теперь реализует API W3C WebDriver Actions для сенсорных жестов, что является современным стандартом мобильной автоматизации.
Действия W3C для элементов Tap
Метод tapElement теперь использует API действий W3C с интеллектуальными резервными вариантами:
// The method will try in this order:
// 1. Standard WebdriverIO click()
// 2. W3C Actions API
// 3. Legacy TouchAction API (fallback for backward compatibility)
await appium.tapElement("//android.widget.Button[@text='OK']");
// or using the click alias
await appium.click("//android.widget.Button[@text='OK']");
Действия W3C для прокрутки
Метод scrollToElement теперь использует API действий W3C:
// Uses W3C Actions API for more reliable scrolling
await appium.scrollToElement(
"//android.widget.TextView[@text='About phone']", // selector
"down", // direction: "up", "down", "left", "right"
"xpath", // strategy
10 // maxScrolls
);
Пользовательские жесты W3C
Вы можете создать свои собственные жесты W3C, используя метод executeMobileCommand :
// Create custom W3C Actions API gesture
const w3cActions = {
actions: [
{
type: "pointer",
id: "finger1",
parameters: { pointerType: "touch" },
actions: [
// Move to start position
{ type: "pointerMove", duration: 0, x: startX, y: startY },
// Press down
{ type: "pointerDown", button: 0 },
// Move to end position over duration milliseconds
{
type: "pointerMove",
duration: duration,
origin: "viewport",
x: endX,
y: endY,
},
// Release
{ type: "pointerUp", button: 0 },
],
},
],
};
// Execute the W3C Actions using executeScript
await appium.executeMobileCommand("performActions", [w3cActions.actions]);
Дополнительные примеры реализации жестов стандарта W3C см. в examples/w3c-actions-swipe-demo.ts
Использование инструментов командной строки Xcode
Новый класс XcodeCommands предоставляет мощные инструменты для тестирования iOS:
import { XcodeCommands } from "../src/lib/xcode/xcodeCommands.js";
// Check if Xcode CLI tools are installed
const isInstalled = await XcodeCommands.isXcodeCliInstalled();
// Get available simulators
const simulators = await XcodeCommands.getIosSimulators();
// Boot a simulator
await XcodeCommands.bootSimulator("SIMULATOR_UDID");
// Install an app
await XcodeCommands.installApp("SIMULATOR_UDID", "/path/to/app.app");
// Launch an app
await XcodeCommands.launchApp("SIMULATOR_UDID", "com.example.app");
// Take a screenshot
await XcodeCommands.takeScreenshot("SIMULATOR_UDID", "/path/to/output.png");
// Shutdown a simulator
await XcodeCommands.shutdownSimulator("SIMULATOR_UDID");
Использование функции щелчка
Метод click() представляет собой более интуитивно понятную альтернативу tapElement() :
// Using the click method
await appium.click("//android.widget.Button[@text='OK']");
// This is equivalent to:
await appium.tapElement("//android.widget.Button[@text='OK']");
Поиск неисправностей
- Устройство не найдено:
- Проверьте вывод
adb devices - Убедитесь, что отладка по USB включена.
- Попробуйте переподключить устройство.
- Приложение не устанавливается:
- Проверьте правильность пути APK
- Проверьте, достаточно ли на устройстве памяти.
- Убедитесь, что приложение подписано для отладки
- Элементы не найдены:
- Используйте Appium Inspector для проверки селекторов
- Проверьте, видны ли элементы на экране.
- Попробуйте разные стратегии поиска
- Проблемы с подключением:
- Убедитесь, что сервер Appium запущен
- Проверьте конфликты портов
- Убедитесь, что установлены правильные возможности
- Проблемы с симулятором iOS:
- Проверьте, установлены ли инструменты командной строки Xcode:
xcode-select -p - Проверьте правильность UDID симулятора с помощью
xcrun simctl list devices - Закройте и перезапустите симулятор, если он перестанет отвечать.
Внося вклад
Не стесняйтесь сообщать о проблемах и отправлять запросы на дополнительные функции или исправления ошибок.
Лицензия
Массачусетский технологический институт