@acabai/android v2.0.6

@acabai/android

Android automation library for acabAI. Automate UI actions, extract data, and perform assertions using AI.

This package uses Appium and WebdriverIO to provide a robust and flexible Android automation solution.

Note: Version 2.0.0 introduces a complete rewrite using Appium and WebdriverIO. If you're migrating from v1.x, please refer to the Migration Guide.

Installation

npm install @acabai/android webdriverio

Note: You need to have Appium server installed and running to use this package. See Appium Installation Guide for details.

AI Methods

The Android agent provides powerful AI-powered methods for automating interactions with Android apps:

Example of AI-Powered Automation

import { agentFromLocalAppium, type AppiumBaseCapabilities } from '@acabai/android';

// Create an agent using the local Appium server
const agent = await agentFromLocalAppium({
  platformName: 'Android',
  'appium:automationName': 'UiAutomator2',
  'appium:deviceName': 'Android Device'
});

// Launch the settings app
await agent.launch('com.android.settings');

// Use AI to find and tap on the "Wi-Fi" option
await agent.aiAction('Find and tap on the Wi-Fi option');

// Use AI to check if Wi-Fi is enabled
const wifiStatus = await agent.aiAssert('Is Wi-Fi enabled?');
console.log('Wi-Fi status:', wifiStatus);

// Use AI to go back to the main settings screen
await agent.aiAction('Go back to the main settings screen');

// Use AI to find and tap on the "Display" option
await agent.aiAction('Find and tap on the Display option');

// Use AI to query information about the current brightness
const brightnessInfo = await agent.aiQuery('string, What is the current brightness level?');
console.log('Brightness info:', brightnessInfo);

Using Custom Appium Server (Hub URL)

import {
  agentFromAppiumServer,
  type AppiumServerConfig,
  type AppiumBaseCapabilities
} from '@acabai/android';

// Define Appium server configuration (Hub URL)
const serverConfig: AppiumServerConfig = {
  hostname: '192.168.1.100',  // Your Appium server hostname or IP
  port: 4723,                 // Your Appium server port (default: 4723)
  path: '/wd/hub',            // WebDriver path (default: '/wd/hub')
  protocol: 'http'            // Protocol (http or https)
};

// The complete Hub URL will be: http://192.168.1.100:4723/wd/hub

// Define capabilities for the Android device
const capabilities: AppiumBaseCapabilities = {
  platformName: 'Android',
  'appium:automationName': 'UiAutomator2',
  'appium:deviceName': 'Android Device'
};

// Create an agent using the specified Appium server
const agent = await agentFromAppiumServer(serverConfig, capabilities);

// You can also use environment variables to configure the server
// Example:
// const serverConfig: AppiumServerConfig = {
//   hostname: process.env.APPIUM_HOST || 'localhost',
//   port: parseInt(process.env.APPIUM_PORT || '4723'),
//   path: process.env.APPIUM_PATH || '/wd/hub',
//   protocol: (process.env.APPIUM_PROTOCOL || 'http') as 'http' | 'https'
// };

Using Sauce Labs for Cloud Testing

Sauce Labs provides cloud-based testing infrastructure for mobile apps. This package includes built-in support for Sauce Labs, making it easy to run your tests on a wide range of real Android devices in the cloud.

Basic Sauce Labs Setup

import {
  agentFromSauceLabs,
  type SauceLabsConfig,
  type AppiumBaseCapabilities,
  type SauceLabsCapabilities
} from '@acabai/android';
import 'dotenv/config';

// Define Sauce Labs configuration
const sauceConfig: SauceLabsConfig = {
  user: process.env.SAUCE_USERNAME || 'your-username',
  key: process.env.SAUCE_ACCESS_KEY || 'your-access-key',
  region: 'us-west-1'  // Options: 'us-west-1', 'eu-central-1', 'apac-southeast-1'
};

// Define capabilities for the Android device
const capabilities: AppiumBaseCapabilities & SauceLabsCapabilities = {
  platformName: 'Android',
  'appium:automationName': 'UiAutomator2',
  'appium:platformVersion': '12.0',
  'appium:deviceName': 'Samsung Galaxy S21',
  'sauce:options': {
    build: 'my-build-name',
    name: 'my-test-name',
    appiumVersion: '2.0.0'
  }
};

// Create an agent using Sauce Labs
const agent = await agentFromSauceLabs(sauceConfig, capabilities);

// Use AI methods for automation
await agent.aiAction('Find and tap on the Settings button');
await agent.aiAssert('Is Wi-Fi enabled?');

Example .env File for Sauce Labs

SAUCE_USERNAME=your-sauce-username
SAUCE_ACCESS_KEY=your-sauce-access-key

Taking Screenshots with Sauce Labs

The package includes support for taking screenshots using the Sauce Labs agent:

// Take a screenshot using Sauce Labs
await agent.page.takeScreenshot('test-screenshot');

// The screenshot will be available in your Sauce Labs dashboard

Required Appium Capabilities

The following capabilities are required for basic Appium functionality:

• platformName: Must be 'Android'
• appium:automationName: Recommended to use 'UiAutomator2'
• appium:deviceName: A name for the device (can be arbitrary for real devices)

Additional useful capabilities:

• appium:udid: Device ID for connecting to a specific device
• appium:app: Path or URL to the APK file
• appium:appPackage: Package name of the app
• appium:appActivity: Activity name to launch
• appium:autoGrantPermissions: Automatically grant app permissions

Remote Appium Server Configuration

When working with remote Appium servers, you can use environment variables to simplify configuration:

// Load environment variables from .env file
import 'dotenv/config';

// Define Appium server configuration using environment variables
const serverConfig: AppiumServerConfig = {
  hostname: process.env.APPIUM_HOST || 'localhost',
  port: parseInt(process.env.APPIUM_PORT || '4723'),
  path: process.env.APPIUM_PATH || '/wd/hub',
  protocol: (process.env.APPIUM_PROTOCOL || 'http') as 'http' | 'https'
};

// Create an agent using the specified Appium server
const agent = await agentFromAppiumServer(serverConfig, capabilities);

// Use AI methods for automation
await agent.aiAction('Find and tap on the Settings button');

Example .env file:

APPIUM_HOST=192.168.1.100
APPIUM_PORT=4725
APPIUM_PATH=/wd/hub
APPIUM_PROTOCOL=http

W3C Actions API

Version 2.0.0 uses the W3C Actions API for touch interactions instead of the deprecated TouchAction API. This provides better compatibility with modern Appium versions and follows the WebDriver standard.

Example of W3C Actions API Usage

// Tap at specific coordinates
await agent.page.tap(100, 200);

// Swipe from one point to another
await agent.page.swipe(
  100, 200,  // start coordinates (x, y)
  300, 400,  // end coordinates (x, y)
  800        // duration in milliseconds
);

// Type text using keyboard actions
await agent.page.keyboard.type('Hello World');

For a complete example, see the W3C Actions example.

Device Performance Metrics

You can retrieve various performance metrics from Android devices using the WebdriverIO API. This is useful for monitoring device performance during test execution.

Example of Retrieving Performance Metrics

// Get the WebdriverIO driver instance
const driver = (agent.page as any).driver;

// Get available performance data types
const performanceTypes = await driver.getPerformanceDataTypes();
console.log('Available performance data types:', performanceTypes);

// Get CPU info
const cpuInfo = await driver.getPerformanceData('com.android.settings', 'cpuinfo', 5);

// Get memory info
const memoryInfo = await driver.getPerformanceData('com.android.settings', 'memoryinfo', 5);

// Get battery info
const batteryInfo = await driver.getPerformanceData('com.android.settings', 'batteryinfo', 5);

// Get network info
const networkInfo = await driver.getPerformanceData('com.android.settings', 'networkinfo', 5);

// Execute custom adb shell commands for additional metrics
const deviceModel = await driver.executeScript('mobile: shell', [{
  command: 'getprop ro.product.model'
}]);

const totalRam = await driver.executeScript('mobile: shell', [{
  command: 'cat /proc/meminfo | grep MemTotal'
}]);

For a complete example, see the Performance Metrics example.

Continuous Performance Monitoring

For more advanced performance monitoring during test execution, you can use the PerformanceMonitor class:

import { PerformanceMonitor } from '@acabai/android';

// Create a performance monitor for a specific app package
const performanceMonitor = new PerformanceMonitor(agent.page, 'com.example.app');

// Initialize the monitor and get available metrics
await performanceMonitor.initialize();

// Get device information
const deviceInfo = await performanceMonitor.getDeviceInfo();

// Start monitoring performance metrics every 2 seconds
performanceMonitor.startMonitoring(2000);

// Perform your test actions...

// Stop monitoring
performanceMonitor.stopMonitoring();

// Get collected metrics
const metrics = performanceMonitor.getMetrics();

// Export metrics to JSON
const metricsJson = performanceMonitor.exportMetricsToJson();

The PerformanceMonitor class provides the following features:

• Collecting CPU, memory, battery, and network metrics
• Getting detailed device information
• Continuous monitoring at specified intervals
• Exporting metrics to JSON for analysis

For a complete example with HTML report generation, see the Performance Monitoring example.

License

acabAI is MIT licensed.