README.md
1# Vogar
2
3Vogar is a generic code/test/benchmark runner tool for Android. It is
4primarily used to run libcore and art tests and benchmarks, however
5this tool can also run arbitrary Java files either on host or target
6device.
7
8Vogar supports multiple testing frameworks and configurations:
9
10 * Allows running JUnit tests, TestNG tests, jtreg tests, Caliper
11 benchmarks or executable Java classes. It supports running
12 fine-grained tests that can be specified with hash symbol, e.g.
13 "com.android.Test#test".
14
15 * Allows running tests and benchmarks using five available runtime
16 modes: `activity`, `app_process`, `device`, `host` or `jvm`.
17
18## Building and running
19
20First build it:
21
22* With a minimal `aosp/master-art` tree:
23```bash
24export SOONG_ALLOW_MISSING_DEPENDENCIES=true
25${ANDROID_BUILD_TOP}/art/tools/buildbot-build.sh --target
26```
27
28* With a full Android (AOSP) `aosp/master` tree:
29```bash
30m vogar
31```
32
33## Features
34
35Vogar supports running tests and/or benchmarks (called "actions" below in the document)
36in five different modes (specified with `--mode` option). An "action" is a `.java` file,
37directory or class names:
38
39 1. Activity (`--mode=activity`)
40
41 Vogar runs given action in the context of an [`android.app.Activity`](https://developer.android.com/reference/android/app/Activity) on a device.
42
43 2. App (`--mode=app_process`)
44
45 Vogar runs given action in an app_process runtime on a device or emulator.
46 Used in conjunction with the `--benchmark` option for running Caliper benchmarks.
47 This is required to benchmark any code relying on the android framework.
48
49 ```bash
50 Vogar --mode app_process --benchmark frameworks/base/core/tests/benchmarks/src/android/os/ParcelBenchmark.java
51 ```
52
533. Device (`--mode=device`)
54
55 Vogar runs given action in an ART runtime on a device or emulator.
56
574. Host (`--mode=host`)
58
59 Vogar runs in an ART runtime on the local machine built with any lunch combo.
60 Similar to "Device" mode but running local ART.
61
625. JVM (`--mode=jvm`)
63
64 Vogar runs given action in a Java VM on the local machine.
65
66Most frequently you will use either `--mode=device` or `--mode=host` mode.
67
68## Testing and debugging
69
70Vogar has unit test coverage around basic functionality. Most of the coverage
71is for [JUnit](https://junit.org/) and [TestNG](https://testng.org/) integration.
72
73### Building and running
74
75First, build tests with:
76```bash
77m vogar-tests
78```
79
80Run all tests using phony make target with:
81```bash
82m run-vogar-tests
83```
84
85Or run manually (if you want to specify a subset of all unit tests, for example):
86```bash
87java -cp ${ANDROID_BUILD_TOP}/out/host/linux-x86/framework/vogar-tests.jar \
88 org.junit.runner.JUnitCore vogar.AllTests
89```
90
91## Architecture and implementation
92
93High level model of each Vogar run is:
94
95 1. Parsing input options.
96 2. Creating a list of `Task` objects that encapsulate various steps required.
97 These `Task` objects can depend on each other, and get executed only if all
98 dependencies are already executed.
99 3. Executing tasks. It include assembling the code, dexing it, packing in
100 an activity/runnable dex jar, preparing the environment (host or device),
101 pushing all artifacts, and running it.
102
103### Classes overview
104
105The basic building block of Vogar execution is the `Task` class. There are several
106sub classes of `Task`, for example:
107
108 * `MkdirTask`
109 * `RmTask`
110 * `PrepareTarget`
111
112The `Target` class encapsulates the runtime environment, for example a
113remote device or the local host. There are four available environments:
114
115 * `AdbTarget` is used when `--mode=device` is set.
116
117 It makes sure device is connected, required directories are mount
118 properly, and all required files are synced to the device.
119
120 * `AdbChrootTarget` is used when `--mode=device --chroot=/data/chroot/`
121 are set.
122
123 Same as `AdbTarget` but relatively to a specified chroot directory
124 (instead of the whole system under the root directory on the device).
125
126 * `LocalTarget` is used when `--mode=host` or `--mode=jvm` are set.
127
128 Same as `AdbTarget` but runs on the host machine.
129
130 * `SshTarget` is used when `--ssh <host:port>` is set.
131
132 Same as `LocalTarget` but on a remote machine at the given address.
133
134After parsing command line options, Vogar builds a list of tasks which
135are put in a `TaskQueue`. They are executed using all available cores
136except when "Activity" mode is enabled -- in that case it is always one
137thread.
138
139