-
Notifications
You must be signed in to change notification settings - Fork 61
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
e1c611f
commit 000e08a
Showing
1 changed file
with
56 additions
and
61 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,92 +1,87 @@ | ||
| # appetizer-toolkit [](https://travis-ci.org/appetizerio/appetizer-toolkit) [](https://ci.appveyor.com/project/mingyuan-xia/appetizer-toolkit) | ||
| [中文说明](./README.cn.md) | ||
|
|
||
| `appetizer-toolkit` is the core of [Appetizer](https://www.appetizer.io), which provides the ability to: | ||
| `appetizer-toolkit` is a command line tool intended for mobile continuous integration, which provides the ability to: | ||
| * record touchscreen events from one device and replay to many (aspect ratios must be the same) | ||
| * control multiple devices concurrently (e.g., run a shell command, install an app, etc.) | ||
| * mirror the touchscreen events from one device to many in real time (aspect ratios must be the same) | ||
|
|
||
| `appetizer-toolkit` is a command line tool, available on Windows 7+, MacOS Mavericks+ and Linux. It also comes with SDK for [Python](https://github.com/appetizerio/appetizer-toolkit-py) and [Nodejs](https://github.com/appetizerio/appetizer-toolkit-js). `appetizer-toolkit` requires `adb` to be present in `PATH`. | ||
| `appetizer-toolkit` can work on Windows 7+, MacOS Mavericks+ and Linux. To integrate it with existing CI infrastructure, consider the [Python SDK](https://github.com/appetizerio/appetizer-toolkit-py). | ||
|
|
||
| Please submit issues for bug reports, enhancements and feature requests. Pull requests are welcomed too. | ||
|
|
||
| ## Installation | ||
| The executable file can be found in the `darwin/` for MacOS, `win32/` for Windows and `linux/` for Ubuntu, Fedora and CentOS. You might want to add to PATH to use the tool globally. Linux and MacOS build are both 64-bit and Windows build is 32-bit (compatible with 64-bit as WOW) | ||
| The executable file can be found in the `darwin/` for MacOS, `win32/` for Windows and `linux/` for Ubuntu, Fedora and CentOS. You might want to add to PATH to use the tool globally. Linux and MacOS build are both 64-bit and Windows build is 32-bit (compatible with 64-bit as WOW). `appetizer-toolkit` requires `adb` to be present in `PATH`. You can install the Android SDK and ensure `<sdk>/platform-tools` is in your PATH. | ||
|
|
||
| ``` | ||
| usage: appetizer [-h] {version,trace,adb,devices,plan} ... | ||
| positional arguments: | ||
| {version,trace,adb,devices,plan} | ||
| commands | ||
| version Print the version information and exit | ||
| trace Record and replay touchscreen events | ||
| adb Control the local ADB | ||
| devices Command devices | ||
| plan Compose and execute a test plan file | ||
| optional arguments: | ||
| -h, --help show this help message and exit | ||
| ## Control Multiple Devices | ||
| Suppose you have several devices attached to the development machine via USB and you want them to perform the same action. | ||
|
|
||
| First, make sure the toolkit recognizes all of them devices: | ||
| ``` | ||
| ./darwin/appetizer devices list | ||
| ``` | ||
| You should see a JSON output. Note the `serialno` field, which is the same as the `adb devices` output. A serialno uniquely identifies a connected device. | ||
|
|
||
| ## Record and Replay | ||
| To record and replay touchscreen events, use `appetizer trace`: | ||
| Next, you can try these: | ||
| ``` | ||
| usage: appetizer trace [-h] {info,replay,record} ... | ||
| DEVICE=serialno1,serialno2 # device serialnos, comma separated, no whitespace! | ||
| appetizer devices control $DEVICE uninstall com.helloworld # uninstall an app on those devices | ||
| appetizer devices control $DEVICE install hellworld.apk # install an app | ||
| appetizer devices control $DEVICE kill_all # kill all background apps | ||
| appetizer devices control $DEVICE launch_pkg com.helloworld # launch an app | ||
| appetizer devices control $DEVICE shell input keyevent KEYCODE_HOME # simulate the home button | ||
| appetizer devices control $DEVICE shell pm grant com.helloworld android.permission.SOME_PERMISSION # grant a permission to an app | ||
| appetizer devices control $DEVICE shell "input keyboard text 'Paste%stext%son%sAndroid%sDevice'" # input text (pre Android 6) | ||
| appetizer devices control $DEVICE shell "input keyboard text 'Paste text on Android Device'" # input text (Android 6+) | ||
| appetizer devices control $DEVICE shell screenrecord /sdcard/demo.mp4 # record screen into a video（Android 4.4+） | ||
| ``` | ||
| Basically everything you did with `adb shell` can now be replaced with `appetizer devices control serialno1,serialno2 shell` to perform that on multiple devices simultaneously. | ||
|
|
||
| positional arguments: | ||
| {info,replay,record} actions | ||
| info Get the detail of a trace file | ||
| replay Replay a touchscreen event trace to some devices | ||
| record Record a trace of touchscreen events | ||
| And, just in case you need them: | ||
| * [Key code cheatsheet](https://developer.android.com/reference/android/view/KeyEvent.html) | ||
| * [Common ADB shell commands](http://stackoverflow.com/documentation/android/1051/adb-android-debug-bridge) | ||
|
|
||
| optional arguments: | ||
| -h, --help show this help message and exit | ||
| ## Record and Replay touchscreen events | ||
| The toolkit can record touchscreen events from one device and replay back to many to automate stuff. | ||
| ``` | ||
| appetizer trace record --device serailno mytrace.trace | ||
| ``` | ||
| Now find the device and start touching. The touchsceen events will be captured and saved to `mytrace.trace`. If you are done, type in `exit` to stop. You are all set if seeing "Recorder stopped, trace saved to mytrace.trace". Try not to use `Ctrl+C`. | ||
|
|
||
| Record and replay demo: | ||
| [](https://vimeo.com/176421640) | ||
| Check if the trace is good: | ||
| ``` | ||
| appetizer trace info mytrace.trace | ||
| ``` | ||
| Again, it shows a JSON about the recorded trace, showing the screen resolution, time length, how many fingers, etc. | ||
|
|
||
| ## Control Multiple Devices and Mirror Touchscreen Events | ||
| To work with multiple devices, use `appetizer devices`: | ||
| Next replay the trace back to see how it goes: | ||
| ``` | ||
| usage: appetizer devices [-h] | ||
| {list,screenshot,mirror,control} | ||
| ... | ||
| appetizer trace replay mytrace.trace serialno | ||
| ``` | ||
| You will see something like the video below: | ||
| [](https://vimeo.com/176421640) | ||
|
|
||
| positional arguments: | ||
| {list,screenshot,mirror,control} | ||
| actions on the devices | ||
| list List the details of connected devices | ||
| screenshot Take a screenshot | ||
| mirror Mirror the touchscreen events from one device to many | ||
| in real-time | ||
| control Control devices | ||
| If you want to replay to more than one devices, simply replace `serialno` with a comma-separated serialno list like `serialno1, serialno2`. | ||
|
|
||
| optional arguments: | ||
| -h, --help show this help message and exit | ||
| ## Mirror Touchscreen Events | ||
| With the toolkit, you can mirror the touchscreen events from one device to other device in real time. | ||
| ``` | ||
| appetizer devices mirror <from_device> <to_device> | ||
| ``` | ||
| The `<from_device>` is a single serialno while `<to_device>` can be a comma-separated list of device serialnos. | ||
| Make sure all involving devices have the same aspect ratio. Otherwise the command will fail. | ||
| For devices with the same aspect ratio, the touchscreen events will automatically scale to adapt to the screen resolution. | ||
|
|
||
| Mirror the touchscreen events from one device to many in real-time demo: | ||
| Here is a demo: | ||
| [](https://vimeo.com/176421482) | ||
|
|
||
| ## ADB related | ||
| `adb` from Android SDK is required for `appetizer-toolkit`. The toolkit itself can detect the existence of the adb binary and control the adb server with it. | ||
| Finally, the toolkit provides some commands to check the ADB environment. | ||
| ``` | ||
| usage: appetizer adb [-h] | ||
| {check-server,start-server,kill-server,detectadb} | ||
| ... | ||
| positional arguments: | ||
| {check-server,start-server,kill-server,detectadb} | ||
| actions on the adb server | ||
| check-server Check the state of the adb server | ||
| start-server Start the adb server | ||
| kill-server Kill the adb server | ||
| detectadb Detect the path to the adb program | ||
| optional arguments: | ||
| -h, --help show this help message and exit | ||
| appetizer adb start-server # start the ADB server | ||
| appetizer adb kill-server # kill the ADB server | ||
| appetizer adb detectadb # this tells where the adb binary locates. If not found, tune your PATH | ||
| appetizer adb check-server # check if the adb server is running properly now | ||
| ``` | ||
| ## License | ||
| Apache License v2 |