AndroidViewClient

AndroidViewClient/culebra was initially conceived as an extension to monkeyrunner but has since evolved into a versatile pure Python tool. It streamlines test script creation for Android applications by automating tasks and simplifying interactions. This test framework:

• Automates the navigation of Android applications.
• Generates reusable scripts for efficient testing.
• Offers device-independent UI interaction based on views.
• Utilizes 'logical' screen comparison (UI Automator Hierarchy based) instead of image comparison, avoiding extraneous detail issues like time or data changes.
• Supports concurrent operation on multiple devices.
• Provides straightforward control for high-level operations such as language change and activity start.
• Fully supports all Android APIs.
• Written in Python with support for Python 3.6 and above in versions 20.x.y and beyond.

🛎	A new Kotlin backend is under development to provide more functionality and improve performance. Take a look at CulebraTester2 and 20.x.y-series prerelease.

NOTE: Pypi statistics are broken see here. The new statistics can be obtained from BigQuery.

As of February 2024 we have reached:

Thanks to all who made it possible.

Installation

pip3 install androidviewclient --upgrade

Or check the wiki for more alternatives.

AI-Powered Testing with MCP

NEW! AndroidViewClient now includes a Model Context Protocol (MCP) server that enables AI assistants like Kiro to interact with Android devices through natural language.

Quick Start with MCP

1. Install with MCP support:

   pip3 install androidviewclient --upgrade
   

2. Start CulebraTester2 on your device:

   Check the details at How to run CulebraTester2 ?

3. Configure your AI assistant:

   Add to .kiro/settings/mcp.json or ~/.kiro/settings/mcp.json:

   {
     "mcpServers": {
       "culebratester2": {
         "command": "culebra-mcp",
         "env": {
           "CULEBRATESTER2_URL": "http://localhost:9987"
         }
       }
     }
   }
   

4. Start testing with natural language:

   • "Get the device screen size"
   • "Launch the Calculator app"
   • "Find the button with text Submit and click it"
   • "Take a screenshot"
   • "Swipe up to scroll"

MCP Tools Available

The MCP server provides 20 tools for Android automation:

Element-based interactions:

• Find elements by text or resource ID
• Click, long-click, enter text, clear text
• Navigate with back/home buttons
• Launch applications

Coordinate-based interactions:

• Click/long-click at coordinates
• Swipe gestures

Device actions:

• Wake/sleep device
• Get current app
• Force stop apps
• Take screenshots

Configuration

For detailed MCP configuration options, see the MCP Configuration Guide.

Quick reference:

• User-level config (kiro-cli): ~/.kiro/settings/mcp.json
• Workspace config (Kiro IDE): .kiro/settings/mcp.json
• Examples: examples/mcp_config.json
• Usage examples: examples/test_calculator_mcp.py

Environment Variables

• CULEBRATESTER2_URL: Base URL for CulebraTester2 (default: http://localhost:9987)
• CULEBRATESTER2_TIMEOUT: HTTP timeout in seconds (default: 30)
• CULEBRATESTER2_DEBUG: Enable debug logging (1, true, or yes)

Want to learn more?

🚀 Check Examples and Screencasts and videos page to see it in action.

Detailed information can be found in the AndroidViewClient/culebra wiki