@@ -25,7 +25,7 @@ you don't already have the SDK, here's how to install it:
2525The ` android.py ` script also requires the following commands to be on the ` PATH ` :
2626
2727* ` curl `
28- * ` java `
28+ * ` java ` (or set the ` JAVA_HOME ` environment variable)
2929* ` tar `
3030* ` unzip `
3131
@@ -80,18 +80,54 @@ call. For example, if you want a pydebug build that also caches the results from
8080
8181## Testing
8282
83- To run the Python test suite on Android:
84-
85- * Install Android Studio, if you don't already have it.
86- * Follow the instructions in the previous section to build all supported
87- architectures.
88- * Run ` ./android.py setup-testbed ` to download the Gradle wrapper.
89- * Open the ` testbed ` directory in Android Studio.
90- * In the * Device Manager* dock, connect a device or start an emulator.
91- Then select it from the drop-down list in the toolbar.
92- * Click the "Run" button in the toolbar.
93- * The testbed app displays nothing on screen while running. To see its output,
94- open the [ Logcat window] ( https://developer.android.com/studio/debug/logcat ) .
95-
96- To run specific tests, or pass any other arguments to the test suite, edit the
97- command line in testbed/app/src/main/python/main.py.
83+ The tests can be run on Linux, macOS, or Windows, although on Windows you'll
84+ have to build the ` cross-build/HOST ` subdirectory on one of the other platforms
85+ and copy it over.
86+
87+ The test suite can usually be run on a device with 2 GB of RAM, though for some
88+ configurations or test orders you may need to increase this. As of Android
89+ Studio Koala, 2 GB is the default for all emulators, although the user interface
90+ may indicate otherwise. The effective setting is ` hw.ramSize ` in
91+ ~ /.android/avd/* .avd/hardware-qemu.ini, whereas Android Studio displays the
92+ value from config.ini. Changing the value in Android Studio will update both of
93+ these files.
94+
95+ Before running the test suite, follow the instructions in the previous section
96+ to build the architecture you want to test. Then run the test script in one of
97+ the following modes:
98+
99+ * In ` --connected ` mode, it runs on a device or emulator you have already
100+ connected to the build machine. List the available devices with
101+ ` $ANDROID_HOME/platform-tools/adb devices -l ` , then pass a device ID to the
102+ script like this:
103+
104+ ``` sh
105+ ./android.py test --connected emulator-5554
106+ ```
107+
108+ * In ` --managed ` mode, it uses a temporary headless emulator defined in the
109+ ` managedDevices ` section of testbed/app/build.gradle.kts. This mode is slower,
110+ but more reproducible.
111+
112+ We currently define two devices: ` minVersion ` and ` maxVersion ` , corresponding
113+ to our minimum and maximum supported Android versions. For example:
114+
115+ ``` sh
116+ ./android.py test --managed maxVersion
117+ ```
118+
119+ By default, the only messages the script will show are Python's own stdout and
120+ stderr. Add the ` -v ` option to also show Gradle output, and non-Python logcat
121+ messages.
122+
123+ Any other arguments on the ` android.py test ` command line will be passed through
124+ to ` python -m test ` – use ` -- ` to separate them from android.py's own options.
125+ See the [ Python Developer's
126+ Guide] ( https://devguide.python.org/testing/run-write-tests/ ) for common options
127+ – most of them will work on Android, except for those that involve subprocesses,
128+ such as ` -j ` .
129+
130+ Every time you run ` android.py test ` , changes in pure-Python files in the
131+ repository's ` Lib ` directory will be picked up immediately. Changes in C files,
132+ and architecture-specific files such as sysconfigdata, will not take effect
133+ until you re-run ` android.py make-host ` or ` build ` .
0 commit comments