capsule: Rename files and fix README.
Change the name of main.py and crawlui.py, and improve the README by
giving it a title (oops!), adding requirements, and changing line
length to 80 chars.
Change-Id: I43a96a00b5e776fa7701baaa76df216ba3667335
diff --git a/capsule/README.md b/capsule/README.md
index 0c120f7..7b282d5 100644
--- a/capsule/README.md
+++ b/capsule/README.md
@@ -1,75 +1,89 @@
+# Capsule
+
+Crawling Apps UIs (and Learning Everything)
+
## Synopsis
-Capsule is a program designed to crawl all of the UIs of an Android app and store the view
-hierarchies, screenshots, and relationships between views. It attempts to click on all clickable
-components and reach as many unique views as possible.
+Capsule is a program designed to crawl all of the UIs of an Android app and
+store the view hierarchies, screenshots, and relationships between views. It
+attempts to click on all clickable components and reach as many unique views as possible.
-Capsule requires an Android emulator or phone using a debug version of Android and uses the
+Capsule requires an Android emulator or phone using a debug version of Android
+and uses the
[AndroidViewClient](https://github.com/dtmilano/AndroidViewClient) library and
-[Android Debug Bridge](https://developer.android.com/studio/command-line/adb.html) commands to
-communicate with the device.
+[Android Debug Bridge](https://developer.android.com/studio/command-line/adb.html) commands to communicate with the device.
-The application considers views to be distinct if they have a different activity name, fragment
-composition, or view hierarchy.
+The application considers views to be distinct if they have a different activity
+name, fragment composition, or view hierarchy.
+
## Code Example
-If Capsule is run with no command line arguments with the command, it crawls the current app
-(assuming that the current view is the starting view of the app.)
+If Capsule is run with no command line arguments with the command, it crawls the current app (assuming that the current view is the starting view of the app.)
+```$ python capsule.py```
-```$ python main.py```
+If a text file is passed in as a command line argument, Capsule attempts to
+crawl each app listed in the file (one app per line), assuming that all of the packages are already installed on the device.
-If a text file is passed in as a command line argument, Capsule attempts to crawl each app listed
-in the file (one app per line), assuming that all of the packages are already installed on the
-device.
+```$ python capsule.py /[PATH TO FILE]/list.txt```
-```$ python main.py /[PATH TO FILE]/list.txt```
+If a directory is passed in as an argument, Capsule installs, crawls, and
+uninstalls each of the apps in the directory in alphabetical order.
-
-If a directory is passed in as an argument, Capsule installs, crawls, and uninstalls each of the
-apps in the directory in alphabetical order.
-
-```$ python main.py /[PATH TO APKS]/```
-
+```$ python capsule.py /[PATH TO APKS]/```
## Motivation
-Capsule serves many purposes, included automated testing and acquiring large samples of Android UIs
-with very little effort. Developers can use it to test the behavior of all of their clickable
-components and can find bugs, crashes, and possible user traces without having to rely on a testing
-framework or change the tests as the app’s UIs change. Although exhaustively searching each app will
-not replicate typical user behavior, it can help gain a large corpus of data and find bugs or
-unintended app behaviors.
+Capsule serves many purposes, included automated testing and acquiring large
+samples of Android UIs with very little effort. Developers can use it to test
+the behavior of all of their clickable components and can find bugs, crashes,
+and possible user traces without having to rely on a testing framework or change
+the tests as the app’s UIs change. Although exhaustively searching each app will
+not replicate typical user behavior, it can help gain a large corpus of data and
+find bugs or unintended app behaviors.
## Installation
+### Requirements
+
+* OS
+ - Linux
+ - Mac OS X
+* Tools
+ - [ADB](http://developer.android.com/tools/help/adb.html): must be
+installed and accessible from `PATH`. ADB comes with the Android SDK.
+
To use Capsule, you must have AndroidViewClient installed.
-If you are just cloning this repo, you can either directly install AndroidViewClient by reading the
-instructions on
+### AndroidViewClient
+If you are just cloning this repo, you can either directly install
+AndroidViewClient by reading the instructions on
[dtmilano’s wiki](https://github.com/dtmilano/AndroidViewClient/wiki#using-easy_install) or by:
``$ sudo apt-get install python-setuptools # not needed on Ubuntu``
``$ sudo easy_install --upgrade androidviewclient``
-However, if you have [installed Vanadium](https://vanadium.github.io/installation/), you can import
-the luma and luma.third_party repositories by adding the luma manifest to your .jiri_manifest file
-or adding it to your manifest from the command line:
-``$ jiri import -name=manifest luma https://vanadium.googlesource.com/manifest && jiri update``
+However, if you have
+[installed Vanadium](https://vanadium.github.io/installation/), you can import
+the luma and luma.third\_party repositories by adding the luma manifest to your
+.jiri_manifest file or adding it to your manifest from the command line:
+``$ jiri import -name=manifest luma https://vanadium.googlesource.com/manifest
+&& jiri update``
After this, you will need to add the AndroidViewClient to your PYTHONPATH:
``export PYTHONPATH=$PYTHONPATH:$JIRI_ROOT/release/projects/luma_third_party/AndroidViewClient/``
## Contributors
-We are happy to accept contributions. However, Vanadium does not accept pull requests, so you must
-follow the [Vanadium contributing](https://vanadium.github.io/community/contributing.html)
+We are happy to accept contributions. However, Vanadium does not accept pull
+requests, so you must follow the
+[Vanadium contributing](https://vanadium.github.io/community/contributing.html)
instructions.
In addition, feel free to file issues on the
-[luma issue tracker](https://github.com/vanadium/luma/issues) or contact the Capsule engineering
-lead, [Dan Afergan](afergan@google.com)
+[luma issue tracker](https://github.com/vanadium/luma/issues) or contact the
+Capsule engineering lead, [Dan Afergan](afergan@google.com)
## License
This is not an official Google product.
@@ -78,4 +92,5 @@
[luma LICENSE file](https://github.com/vanadium/luma/blob/master/LICENSE).
-Capsule lives in the Vanadium codebase, but is no longer affiliated with Vanadium.
+Capsule lives in the Vanadium codebase, but is no longer affiliated with
+Vanadium.
diff --git a/capsule/main.py b/capsule/capsule.py
similarity index 94%
rename from capsule/main.py
rename to capsule/capsule.py
index f3a2788..2417bdb 100644
--- a/capsule/main.py
+++ b/capsule/capsule.py
@@ -10,7 +10,7 @@
from com.dtmilano.android.common import obtainAdbPath
from com.dtmilano.android.viewclient import ViewClient
-import crawlui
+import crawlpkg
ADB_PATH = obtainAdbPath()
# os.environ['ANDROID_ADB_SERVER_PORT'] = '5554'
@@ -41,7 +41,7 @@
vc = ViewClient(device, serialno, **kwargs2)
if DEBUG:
- crawlui.crawl_package(vc, device)
+ crawlpkg.crawl_package(vc, device)
else:
package_list = sorted(os.listdir(APK_DIR))
for package in package_list:
@@ -61,5 +61,5 @@
subprocess.call([ADB_PATH, 'shell', 'monkey', '-p', package_name, '-c',
'android.intent.category.LAUNCHER', '1'])
- crawlui.crawl_package(vc, device, package_name)
+ crawlpkg.crawl_package(vc, device, package_name)
subprocess.call([ADB_PATH, 'uninstall', package_name])
diff --git a/capsule/crawlui.py b/capsule/crawlpkg.py
similarity index 100%
rename from capsule/crawlui.py
rename to capsule/crawlpkg.py
