MCP Appium Server
Eine Model Context Protocol (MCP)-Serverimplementierung für die Automatisierung mobiler Apps mit Appium.
Voraussetzungen
- Node.js (v14 oder höher)
- Java Development Kit (JDK)
- Android SDK (zum Testen von Android)
- Xcode (für iOS-Tests, nur macOS)
- Appium Server
- Android-Gerät oder -Emulator / iOS-Gerät oder -Simulator
Umgebungs-Setup
Stellen Sie vor der Ausführung von Befehlen sicher, dass Ihre Umgebungsvariablen richtig eingerichtet sind:
- Stellen Sie sicher, dass Ihre
.bash_profile , .zshrc oder andere Shell-Konfigurationsdatei die erforderlichen Umgebungsvariablen enthält:
# 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
- Geben Sie Ihre Umgebungsdatei als Quelle ein, bevor Sie MCP-Appium ausführen:
source ~/.bash_profile # For bash
# OR
source ~/.zshrc # For zsh
Hinweis : Das System versucht beim Initialisieren des Treibers automatisch, Ihr .bash_profile zu beziehen. Es wird jedoch empfohlen, vor dem Ausführen von Tests in einer neuen Terminalsitzung manuell für eine ordnungsgemäße Umgebungseinrichtung zu sorgen.
Für iOS-Tests ist die richtige Konfiguration der Xcode-Befehlszeilentools unerlässlich:
- Installieren Sie die Xcode-Befehlszeilentools, falls sie noch nicht installiert sind:
- Überprüfen Sie die Installation und prüfen Sie den aktuellen Xcode-Pfad:
- Legen Sie bei Bedarf den richtigen Xcode-Pfad fest (insbesondere, wenn Sie mehrere Xcode-Versionen haben):
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
- Akzeptieren Sie die Xcode-Lizenzvereinbarungen:
sudo xcodebuild -license accept
- Stellen Sie zum Testen von iOS-Geräten sicher, dass Ihr Apple-Entwicklerkonto in Xcode richtig konfiguriert ist:
- Öffnen Sie Xcode
- Gehen Sie zu Einstellungen > Konten
- Fügen Sie Ihre Apple-ID hinzu, falls sie noch nicht hinzugefügt wurde
- Laden Sie die erforderlichen Bereitstellungsprofile herunter
- Richten Sie Umgebungsvariablen für die iOS-Entwicklung ein:
# Add these to your ~/.bash_profile or ~/.zshrc
export DEVELOPER_DIR="/Applications/Xcode.app/Contents/Developer"
export PATH="$DEVELOPER_DIR/usr/bin:$PATH"
- Quelle Ihrer aktualisierten Konfiguration:
source ~/.bash_profile # For bash
# OR
source ~/.zshrc # For zsh
Aufstellen
- Installieren Sie Abhängigkeiten:
- Installieren und starten Sie den Appium-Server:
npm install -g appium
appium
- Android-Gerät/Emulator einrichten:
- Aktivieren Sie die Entwickleroptionen auf Ihrem Android-Gerät
- USB-Debugging aktivieren
- Gerät per USB verbinden oder einen Emulator starten
- Überprüfen Sie, ob das Gerät mit
adb devices verbunden ist
- Für iOS-Tests (nur macOS):
- Stellen Sie sicher, dass die Xcode-Befehlszeilentools installiert sind:
xcode-select --install - Richten Sie einen iOS-Simulator ein oder verbinden Sie ein echtes Gerät
- Vertrauen Sie dem Entwicklungscomputer auf dem iOS-Gerät, wenn Sie ein echtes Gerät verwenden
Ausführen von Tests
- Erstellen Sie das Projekt:
- Starten Sie den MCP-Server:
- Führen Sie den Test in einem neuen Terminal aus:
Testkonfiguration
Android-Konfiguration
Der Beispieltest verwendet die Android-Einstellungen-App als Demo. So testen Sie Ihre eigene App:
- Bearbeiten Sie
examples/appium-test.ts :- Aktualisieren Sie
deviceName , damit er mit Ihrem Gerät übereinstimmt. - Legen Sie
app -Pfad zu Ihrer APK-Datei fest, oder - Aktualisieren Sie
appPackage und appActivity für eine installierte App
- Konfiguration allgemeiner Funktionen:
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-Konfiguration
Für iOS-Tests mit der neuen Xcode-Befehlszeilenunterstützung:
- Beispielkonfiguration in
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,
};
Verfügbare Aktionen
Der MCP-Server unterstützt verschiedene Appium-Aktionen:
- Elementinteraktionen:
- Elemente suchen
- Tippen/Klicken Sie auf Elemente mit der W3C Actions API (siehe Abschnitt „W3C-Standardgesten“)
- Text eingeben
- Mit der W3C Actions API zum Element scrollen
- Langes Drücken
- App-Verwaltung:
- App starten/schließen
- App zurücksetzen
- Aktuelles Paket/Aktuelle Aktivität abrufen
- Gerätesteuerung:
- Bildschirmausrichtung
- Tastaturbedienung
- Gerät sperren/entsperren
- Screenshots
- Batterieinformationen
- Erweiterte Funktionen:
- Kontextwechsel (Native/WebView)
- Dateivorgänge
- Benachrichtigungen
- Benutzerdefinierte Gesten
- Xcode-Befehlszeilentools (nur iOS):
- iOS-Simulatoren verwalten (Booten, Herunterfahren)
- Apps auf Simulatoren installieren/deinstallieren
- Apps starten/beenden
- Screenshots machen
- Videos aufnehmen
- Simulatoren erstellen/löschen
- Abrufen von Gerätetypen und Laufzeiten
W3C-Standardgesten
Die MCP-Appium-Bibliothek implementiert jetzt die W3C WebDriver Actions API für Touch-Gesten, den modernen Standard für mobile Automatisierung.
W3C-Aktionen für Tap-Elemente
Die Methode tapElement verwendet jetzt die W3C Actions API mit intelligenten Fallbacks:
// 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']");
Die Methode scrollToElement verwendet jetzt die W3C Actions API:
// 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
);
Benutzerdefinierte W3C-Gesten
Sie können Ihre eigenen benutzerdefinierten W3C-Gesten mit der Methode executeMobileCommand erstellen:
// 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]);
Weitere Beispiele für die Implementierung von Gesten nach W3C-Standard finden Sie examples/w3c-actions-swipe-demo.ts .
Die neue XcodeCommands Klasse bietet leistungsstarke Tools für iOS-Tests:
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");
Verwenden der Klickfunktion
Die Methode click() bietet eine intuitivere Alternative zu 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']");
Fehlerbehebung
- Gerät nicht gefunden:
- Überprüfen Sie die Ausgabe
adb devices - Überprüfen Sie, ob das USB-Debugging aktiviert ist
- Versuchen Sie, das Gerät erneut zu verbinden
- App wird nicht installiert:
- Überprüfen Sie, ob der APK-Pfad korrekt ist
- Überprüfen Sie, ob das Gerät über genügend Speicherplatz verfügt
- Stellen Sie sicher, dass die App zum Debuggen signiert ist
- Elemente nicht gefunden:
- Verwenden Sie Appium Inspector, um Selektoren zu überprüfen
- Überprüfen Sie, ob Elemente auf dem Bildschirm sichtbar sind
- Probieren Sie verschiedene Lokalisierungsstrategien aus
- Verbindungsprobleme:
- Überprüfen Sie, ob der Appium-Server ausgeführt wird
- Überprüfen Sie Portkonflikte
- Stellen Sie sicher, dass die richtigen Funktionen eingestellt sind
- Probleme mit dem iOS-Simulator:
- Überprüfen Sie, ob die Xcode-Befehlszeilentools installiert sind:
xcode-select -p - Überprüfen Sie, ob die UDID des Simulators korrekt ist, indem Sie
xcrun simctl list devices verwenden. - Schließen Sie den Simulator und starten Sie ihn neu, wenn er nicht mehr reagiert.
Beitragen
Sie können gerne Probleme und Pull Requests für zusätzliche Funktionen oder Fehlerbehebungen einreichen.
Lizenz
MIT