README_eng.md
SoloPi is an open-source automation and AI Harness project for mobile development. It preserves SoloPi's recording, replay, assertion, and performance-diagnostic capabilities on physical Android devices, while adding Agent integration, safe execution on dynamic pages, independent result adjudication, unattended managed execution, and same-run evidence. This turns a device interaction into a conclusion that can be delivered into development and CI workflows.
The planned public distribution includes only the three product modules
solopi-app,solopi-harness-cli, andsolopi-skill, together with the necessary root-level documentation and license files.
| Module | Role | Primary responsibilities |
|---|---|---|
solopi-app/ | Physical-device execution kernel | Recording and replay, page observation, pre-touch verification, assertions, performance and network collection, and action receipts; the current open-source implementation is for Android |
solopi-harness-cli/ | Host-side responsibility center | Typed CLI, device protocol, verification plans, result judge, single-host managed execution, evidence reports, and an optional model lifecycle |
solopi-skill/ | Agent entry point | Describes capabilities, validates input, defines safety rules and result semantics, and routes Agent requests to the controlled CLI; it does not contain the execution kernel |
The app under test does not need to integrate an Agent SDK or change its business code in order to use the Harness.
User goal
|
v
Skill-capable Agent
|
v
solopi-skill
| Typed tasks and safety constraints
v
solopi-harness-cli
| ADB + controlled protocol
v
solopi-app --------------------> App under test
| |
`---------- Receipts and evidence <-'
|
v
passed / failed / not_tested
SoloPi is a wireless, non-invasive testing tool for automatic Android software testing. The Beta version has 3 main features: record and replay, performance testing, multi-device compatibility testing (OneToMany).
SoloPi also has a HarmonyOS version. To try it, switch to the
solopi-harmonybranch.
Record the testing on a mobile game.
Record the testing on a native phone app.
SoloPi captures all actions performed during testing sessions so that issues can be identified and resolved more quickly. The recording can be played on any device. All these actions can be done on just one single phone. See Record and Replay.
SoloPi JSON can be converted into other automation scripts. Appium and Macaca are currently supported; download and try SoloPi-Convertor.
Use the performance analysis function
Use the launch time calculator
Video-difference response-time analysis requires the
hulu_screenRecordplugin. By default, SoloPi uses the ABI compatibility manifests in the repository root to fetch plugin assets pinned tov0.12.0. The source can be cleared or replaced in the App settings, or a local archive can be installed withsolopi-skill/scripts/solopi-ai plugin-install --file <plugin ZIP>. Restart SoloPi after installation. Thestartup-timecommand for cold or warm launches does not require this plugin.
SoloPi is able to record and show the app's performance data, such as CPU, memory, and internet speed, while testing. The performance window with selected testing metrics will float on top. After testing, you can check each testing parameter in generated data graphs.
SoloPi can also change the testing environment to simulate certain situations. For instance, it can slow down the internet speed to simulate using the app with a poor network connection.
SoloPi also adds a function to calculate app launch time. This tool shows the actual launch time to the greatest extent possible. The calculator can be incorporated into UI automation tests by sending broadcast messages. See Performance Testing.
Simultaneous multi-device testing
SoloPi supports simultaneous multi-device compatibility testing controlled by one device. This enormously improves the efficiency of testing on different devices. See Multi-device Compatibility Testing.
Open-source SoloPi excludes the multi-device compatibility testing feature because it is still unstable. Work on opening this feature will continue.
Download the appropriate SDK Platform Tools,
unzip them, and add ANDROID_SDK=${SDK path} to your system environment variables. You can also
refer to an ADB configuration guide.
On Windows 10 and later, the environment variable takes effect in a newly opened command prompt. Older Windows versions may need to be restarted. On Linux and macOS, run
echo $ANDROID_SDKto verify the setting.
Open the Settings app. Under "About phone -> Software information," tap "Build number" seven times. The system will indicate that developer mode has been enabled. Return to the Settings home page, open "Developer options," and enable "USB debugging."
If you encounter a problem, first check Known Issues.
First connect the device to the computer and verify the connection with the following command. The device will ask whether to allow USB debugging; confirm the request.
Windows:
%ANDROID_SDK%\platform-tools\adb.exe devices
macOS or Linux:
$ANDROID_SDK/platform-tools/adb devices
If the command lists a device serial number with the status device, the connection is successful.
Windows may require an Android device driver, which can be downloaded from the device vendor's website. If the device status is not
device, verify that the driver is installed and USB debugging is allowed. If necessary, change the USB connection mode to "Media Transfer Protocol (MTP)."
For a single device:
%ANDROID_SDK%\platform-tools\adb.exe tcpip 5555
$ANDROID_SDK/platform-tools/adb tcpip 5555
For multiple devices, first record each device serial number:
%ANDROID_SDK%\platform-tools\adb.exe -s <device-serial-number> tcpip 5555
$ANDROID_SDK/platform-tools/adb -s <device-serial-number> tcpip 5555
The device will usually display restarting in TCP mode port: 5555, indicating that wireless ADB
debugging has been enabled.
Make sure the device is on a secure network. Do not accept ADB debugging requests casually, as doing so may cause unnecessary loss.
Download a packaged SoloPi APK from GitHub Releases, or clone the source and build it yourself. See solopi-app Quick Start for detailed instructions.
passed, failed, and not_tested outcomes with evidence referencesSpecific metrics depend on what the target device actually returns. An on-device model is an optional enhancement, not a prerequisite for using the Harness.
adbsolopi-app./solopi-app/gradlew -p solopi-app \
:app:testDebugUnitTest \
:agentmodel:testDebugUnitTest \
:portal:assembleDebug
adb install -r solopi-app/portal/build/outputs/apk/debug/portal-debug.apk
Accessibility, display-over-other-apps permission, battery-optimization allowlisting, and other required permissions must be confirmed by the user on the device. The tool does not grant them silently.
Run the source entry point directly:
./solopi-harness-cli/solopi-ai --pretty actions
./solopi-harness-cli/solopi-ai --pretty doctor
Alternatively, install it in a virtual environment:
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e ./solopi-harness-cli
solopi-ai --pretty actions
Purely local commands such as actions, case templates, and verification-plan compilation do not
require a device. Before using a physical-device protocol operation, run doctor and resolve the
readiness gaps it reports.
solopi-skill is the rules entry point for Skill-capable Agents. It invokes the CLI in the same
repository:
./solopi-skill/scripts/solopi-ai --pretty doctor
./solopi-skill/scripts/solopi-ai --pretty capabilities
Read solopi-skill/SKILL.md in full before use. Natural language is
interpreted by the Agent according to the Skill rules. The Skill itself is not a large language
model, and it does not bypass the CLI or the device-side safety boundaries.
The basic gate for the public source depends only on these three modules:
python3 -m unittest discover -s solopi-harness-cli/tests -v
./solopi-skill/scripts/solopi-ai --pretty actions
./solopi-app/gradlew -p solopi-app \
:app:testDebugUnitTest \
:agentmodel:testDebugUnitTest \
:portal:assembleDebug
Physical-device tests read pages, screenshots, logs, and performance data. Use a dedicated test device and test account. Do not run them with production accounts, in a real payment environment, or against an app you are not authorized to test.
app: application business logicshared: core application functions, primarily including node (page-node acquisition and
operations), event (event monitoring, including accessibility and touch events), io (data
maintenance and database), and display (performance-tool metrics)common: application-framework functions, including wrappers for ADB capabilities, global
Service capabilities, the messaging module, and common utilitiesmdlibrary: Proxy generation for ExportService (referenced)permission: permission-handling package (referenced)AdbLib: ADB connection handling (referenced)androidWebscokets: WebSocket implementation for Android (referenced)SoloPi is intended for professionals working in software testing. If you have feedback or suggestions, you are welcome to discuss them through Issues, PRs, or the community.
SoloPi needs developers to build it together and hopes to grow with their support. If you have developed a capability based on SoloPi that better fits a business scenario, whether commercial or non-commercial, please contact us. We also hope you will contribute features, bug fixes, and Issues and help maintain the SoloPi automation tool.
See Contributing Code, the guide for participating in SoloPi development.
The heart of open source is sharing technology. When you have an idea about the project, you can express it in a more constructive way:
Stars, forks, Merge Requests, and Issues are always welcome. If you have a good idea, please contact us for a deeper discussion and help move this mobile-testing framework forward.
The project uses third-party libraries. See Attributions for details.
done is only the Agent's stop signal. The formal conclusion always comes from the Result Judge.not_tested when the result
cannot be observed reliably or when evidence is missing.Read CONTRIBUTING.md. Before submitting third-party code, models, images, or binaries, provide the exact source, version, license, and a description of your changes.
SoloPi is open source under the Apache License 2.0. Third-party components remain subject to their respective license and attribution requirements.
Copyright (C) 2015-present, Ant Financial Services Group
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.