{"id":28225443,"url":"https://github.com/pocmo/uitest-agent","last_synced_at":"2026-06-28T21:31:04.805Z","repository":{"id":290550392,"uuid":"968131097","full_name":"pocmo/uitest-agent","owner":"pocmo","description":"A natural language-based agent for automating UI testing on mobile devices and web applications using Google's Gemini AI models.","archived":false,"fork":false,"pushed_at":"2025-05-30T13:53:00.000Z","size":36,"stargazers_count":3,"open_issues_count":5,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-10-28T21:52:10.088Z","etag":null,"topics":["agent","ai","mobile","testing","ui-testing","web"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pocmo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-04-17T15:00:12.000Z","updated_at":"2025-07-15T02:59:59.000Z","dependencies_parsed_at":null,"dependency_job_id":"d4522e2b-55c6-4d0e-a251-7ec4ead7a3f6","html_url":"https://github.com/pocmo/uitest-agent","commit_stats":null,"previous_names":["pocmo/uitest-agent"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/pocmo/uitest-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pocmo%2Fuitest-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pocmo%2Fuitest-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pocmo%2Fuitest-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pocmo%2Fuitest-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pocmo","download_url":"https://codeload.github.com/pocmo/uitest-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pocmo%2Fuitest-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34905180,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-28T02:00:05.809Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","ai","mobile","testing","ui-testing","web"],"created_at":"2025-05-18T10:09:51.027Z","updated_at":"2026-06-28T21:31:04.800Z","avatar_url":"https://github.com/pocmo.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# UI Test Agent\n\nA natural language-based agent for automating UI testing on mobile devices and web applications using Google's Agent Development Kit (ADK). This tool allows testers and developers to write test instructions in plain English and have them executed on Android, iOS, or web platforms.\n\n\u003e **Note:** This is a prototype/experimental project. While functional, it is not yet ready for production use. Use at your own risk.\n\n## Features\n\n- Natural language interface for UI automation and testing\n- Cross-platform support (Android, iOS, Web)\n- Integration with Google's Agent Development Kit (ADK)\n- Support for both Gemini models and local models through LiteLLM\n- Support for complex, multi-step test scenarios\n- Real-time feedback and test results\n\n## Requirements\n\n- Python 3.8+\n- Google Gemini API key \n- For mobile testing: Android device/emulator or iOS device connected to your machine\n- For web testing: Compatible browser\n\n## Quick Setup\n\n0. Create and activate a virtual environment (recommended):\n   ```\n   # Create a virtual environment\n   python -m venv venv\n   \n   # Activate the virtual environment\n   # On macOS/Linux:\n   source venv/bin/activate\n   # On Windows:\n   venv\\Scripts\\activate\n   ```\n\n1. Install dependencies:\n   ```\n   pip install -r requirements.txt\n   ```\n\n2. Configure:\n   ```\n   cp config.sample.yaml config.yaml\n   ```\n   Edit `config.yaml` with your Google API key.\n\n3. Run:\n   ```\n   python main.py --target [android|ios|web] --query \"YOUR_TEST_INSTRUCTION\"\n   ```\n   \n   Or pipe content from a file or another command:\n   ```\n   cat test_prompt.txt | python main.py --target [android|ios|web]\n   echo \"Check the login screen\" | python main.py --target android\n   ```\n\n## Configuration Options\n\nThe `config.yaml` file supports the following options:\n\n- `google_api_key`: Your Google API key for Gemini models\n- `use_vertex_ai`: Boolean to use Google Cloud Vertex AI (default: false)\n- `model_name`: The model to use (default: \"gemini-2.5-pro-preview-03-25\")\n- `use_litellm`: Boolean to use LiteLLM for local models (default: false)\n- `mobile_mcp_path`: Optional path to local mobile-mcp installation\n- `web_mcp_path`: Optional path to local playwright-mcp installation\n\n## Model Options\n\nThe UI Test Agent supports two ways to use models:\n\n1. **Google Gemini Models**: By default, the agent uses Gemini models from Google. Set `use_litellm: false` in your config.\n\n2. **Local Models via LiteLLM**: For local model support (such as Ollama, LLaMA, etc.), set `use_litellm: true` in your config. This allows you to:\n   - Run the agent with local models for offline use\n   - Use custom or open source models\n   - Avoid API costs by using locally deployed models\n\nWhen using LiteLLM, the `model_name` in your config should follow LiteLLM's model naming convention (e.g., \"ollama_chat/llama3.2\").\n\n## Usage Notes\n\n- Mobile MCP server is available as a remote service by default\n- Local MCP installation is optional\n- The `--target` parameter is required and must be either `android`, `ios`, or `web`\n- When `--query` is not provided, the tool reads from stdin, enabling piped inputs\n\n## Examples\n\n### Android Examples\n```\npython main.py --target android --query \"What do you see on the current screen?\"\n\npython main.py --target android --query \"Open settings and turn on airplane mode\"\n\npython main.py --target android --query \"Go to the YouTube app. Search for 'meet firefox mobile, part II' then play the first video from the search results.\"\n```\n\n### iOS Examples\n```\npython main.py --target ios --query \"Go to Apple Maps and find a restaurant in New York. Recommend a good one.\"\n\npython main.py --target ios --query \"Open the calendar and add a new appointment for tomorrow: 'Eat burrito'\"\n```\n\n### Web Examples\n```\npython main.py --target web --query \"Navigate to github.com and search for 'UI testing frameworks'. List some popular frameworks.\"\n\npython main.py --target web --query \"Go to a news website and tell me about the top story\"\n\npython main.py --target web --query \"Go to league.com and verify that the careers page has some open positions listed\"\n```\n\n## System Prompts and Instruction Files\n\nThe UI Test Agent uses specialized instruction files (system prompts) to guide the AI's behavior when testing different platforms. These files are located in the `prompts/` directory:\n\n### Available Instruction Files\n\n- **agent_instruction.txt**: Core instructions for the UI testing agent that apply to all platforms\n- **mobile_instruction.txt**: General mobile testing instructions shared by Android and iOS platforms\n- **android_instruction.txt**: Android-specific testing instructions\n- **ios_instruction.txt**: iOS-specific testing instructions\n- **web_instruction.txt**: Web platform testing instructions\n\nWhen you run a test with a specific target (android, ios, or web), the system combines the appropriate instruction files to create a comprehensive prompt for the AI. For example, when testing an Android app:\n\n1. First, it loads the core `agent_instruction.txt`\n2. Then appends the general `mobile_instruction.txt`\n3. Finally adds the target-specific `android_instruction.txt`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpocmo%2Fuitest-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpocmo%2Fuitest-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpocmo%2Fuitest-agent/lists"}