Working towards android support (#4169)

## Part of Android support

### Relevant issues: 

- #3868
- #3550

### Outline

- Follow android studio + gradle standard for directory structure
- Unit test support (local runs - no android device needed)
- Integration test support (android tests, needs an android
device/emulator)

### New features

- Ability to install an apk in the default available android device
(tested against AVD)
- Ability to run all integration tests with the install command (android
manifest with instrumentation is needed, this needs to be a
functionality of integration tests support in the future instead)
- Classpath resolution (runtimeDependencies) for packaging with
dependencies and user's source code (tested against integration test and
running the android app itself via the emulator)
- Special classpath resolution and packaging for android tests
(integration tests)
- Mill integrates with avdmanager, adb and emulator to automate the run
of integration tests by creating virtual devices and controlling the
emulator (start, stop). Examples are added in documentation of both
kotlin and java app. This includes the ability to use different
emulators for different apps, by specifying identifiers and ports,
though this use case should be rare in app development lifecycles.
- Github actions & mill support to run integration tests in (headless)
emulator & differentiate from local mode (windowed emulator + default
gpu settings)

### Github actions

A sample repo to demonstrate what's needed to run the emulator
https://github.com/vaslabs-ltd/test-android-emulator

In the end what slowed me down was that for github actions, the AVD home
env var was needed, which wasn't obvious until I've tested it in
isolation . All the flags and kvm configs are also needed and it's what
https://github.com/ReactiveCircus/android-emulator-runner does

### Stubs and missing features

An effort was made to standardise the structure faster, so follow up PRs
will not use a non-standard structure. Things that are working but not
"production ready" are:

1. Integration tests debug apk: This inherits the current apk
construction, debug functionality needs to be added and separated from
the release androidApk task
2. No testOnly for integration tests: this is easy to do, but was not
added in the interest of not increasing the size of the PR and the
testing surface
3. Classpath resolution: For kotlin, jvm specific dependencies are
removed in a hardcoded way.
4. Desugaring: This shows as a warning in the android tests apk
creation, while the flow works, the d8 will need to be configured to
desugar annotations properly.
5. Emulator CI mode only recognises github actions

### Demo

#### Running android tests


https://github.com/user-attachments/assets/0cb47ac7-32ff-4d5c-a678-11cd18807b10

---------

Co-authored-by: irodotos7 <[email protected]>

Author: vaslabs

.github/workflows/post-build-selective.yml

@@ -53,6 +53,19 @@ jobs:
         if: ${{ inputs.install-android-sdk }}
         with:
           log-accepted-android-sdk-licenses: false
+          cmdline-tools-version: 11076708
+          packages: tools platform-tools emulator system-images;android-35;google_apis_playstore;x86_64
+
+      - name: Enable KVM group perms
+        if: ${{ inputs.install-android-sdk }}
+        run: |
+          echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules
+          sudo udevadm control --reload-rules
+          sudo udevadm trigger --name-match=kvm
+
+      - name: Set AVD environment variable globally
+        if: ${{ inputs.install-android-sdk }}
+        run: echo "ANDROID_AVD_HOME=/home/runner/.config/.android/avd" >> $GITHUB_ENV
 
       - run: ./mill -i -k selective.resolve ${{ inputs.millargs }}
 

example/android/javalib/1-hello-world/app/src/androidTest/java/com/helloworld/app/ExampleInstrumentedTest.java

@@ -0,0 +1,24 @@
+package com.helloworld.app;
+
+import static org.junit.Assert.*;
+
+import android.content.Context;
+import androidx.test.ext.junit.runners.AndroidJUnit4;
+import androidx.test.platform.app.InstrumentationRegistry;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+
+/**
+ * Instrumented test, which will execute on an Android device.
+ *
+ * @see <a href="http://d.android.com/tools/testing">Testing documentation</a>
+ */
+@RunWith(AndroidJUnit4.class)
+public class ExampleInstrumentedTest {
+  @Test
+  public void useAppContext() {
+    // Context of the app under test.
+    Context appContext = InstrumentationRegistry.getInstrumentation().getTargetContext();
+    assertEquals("com.helloworld.app", appContext.getPackageName());
+  }
+}

example/android/javalib/2-app-bundle/bundle/AndroidManifest.xml renamed to example/android/javalib/1-hello-world/app/src/main/AndroidManifest.xml

@@ -9,4 +9,7 @@
             </intent-filter>
         </activity>
     </application>
+    <instrumentation
+            android:name="androidx.test.runner.AndroidJUnitRunner"
+            android:targetPackage="com.helloworld.app" />
 </manifest>

example/android/javalib/1-hello-world/app/src/main/java/com/helloworld/SampleLogic.java

@@ -0,0 +1,8 @@
+package com.helloworld;
+
+class SampleLogic {
+
+  public static float textSize() {
+    return 32f;
+  }
+}

example/android/javalib/1-hello-world/app/resources/values/colors.xml renamed to example/android/javalib/1-hello-world/app/src/main/res/values/colors.xml

@@ -0,0 +1,17 @@
+package com.helloworld;
+
+import static org.junit.Assert.*;
+
+import org.junit.Test;
+
+/**
+ * Example local unit test, which will execute on the development machine (host).
+ *
+ * @see <a href="http://d.android.com/tools/testing">Testing documentation</a>
+ */
+public class ExampleUnitTest {
+  @Test
+  public void textSize_isCorrect() {
+    assertEquals(32f, SampleLogic.textSize(), 0.000001f);
+  }
+}

example/android/javalib/1-hello-world/app/resources/values/strings.xml renamed to example/android/javalib/1-hello-world/app/src/main/res/values/strings.xml

@@ -9,8 +9,11 @@
 //// SNIPPET:BUILD
 package build
 
-import mill._
+import mill._, javalib._
+
 import mill.javalib.android.{AndroidAppModule, AndroidSdkModule}
+import coursier.maven.MavenRepository
+import mill.javalib.android.AndroidTestModule
 
 // Create and configure an Android SDK module to manage Android SDK paths and tools.
 object androidSdkModule0 extends AndroidSdkModule {
@@ -23,11 +26,71 @@ object app extends AndroidAppModule {
   def androidSdkModule = mill.define.ModuleRef(androidSdkModule0)
 
   // Configuration for ReleaseKey
+  override def releaseKeyPath = super.millSourcePath
+
   def androidReleaseKeyName: T[String] = Task { "releaseKey.jks" }
   def androidReleaseKeyAlias: T[String] = Task { "releaseKey" }
   def androidReleaseKeyPass: T[String] = Task { "MillBuildTool" }
   def androidReleaseKeyStorePass: T[String] = Task { "MillBuildTool" }
 
+  override def androidVirtualDeviceIdentifier: String = "java-test"
+
+  private def mainRoot = millSourcePath
+
+  object test extends AndroidAppTests with TestModule.Junit4 {
+    def testFramework = "com.novocode.junit.JUnitFramework"
+    def ivyDeps = super.ivyDeps() ++ Agg(
+      ivy"junit:junit:4.13.2"
+    )
+  }
+
+  object it extends AndroidAppIntegrationTests with AndroidTestModule.AndroidJUnit {
+    def repositoriesTask = Task.Anon {
+      super.repositoriesTask() ++
+        Seq(MavenRepository("https://maven.google.com"))
+    }
+
+    def androidSdkModule = mill.define.ModuleRef(androidSdkModule0)
+
+    override def instrumentationPackage = "com.helloworld.app"
+
+    /* TODO this needs to change to the location of the debug keystore once integration test */
+    override def releaseKeyPath = mainRoot
+
+    def androidReleaseKeyName: T[String] = Task {
+      "releaseKey.jks"
+    }
+
+    def androidReleaseKeyAlias: T[String] = Task {
+      "releaseKey"
+    }
+
+    def androidReleaseKeyPass: T[String] = Task {
+      "MillBuildTool"
+    }
+
+    def androidReleaseKeyStorePass: T[String] = Task {
+      "MillBuildTool"
+    }
+
+    /* TODO currently the dependency resolution ignores the platform type and kotlinx-coroutines-core has
+     * conflicting classes with kotlinx-coroutines-core-jvm . Remove the exclusions once the dependency
+     * resolution resolves conflicts between androidJvm and jvm platform types
+     */
+    def ivyDeps = super.ivyDeps() ++ Agg(
+      ivy"androidx.test.ext:junit:1.2.1".exclude((
+        "org.jetbrains.kotlinx",
+        "kotlinx-coroutines-core-jvm"
+      )),
+      ivy"androidx.test:runner:1.6.2",
+      ivy"androidx.test.espresso:espresso-core:3.5.1".exclude((
+        "org.jetbrains.kotlinx",
+        "kotlinx-coroutines-core-jvm"
+      )),
+      ivy"junit:junit:4.13.2"
+    )
+  }
+
 }
 
 ////SNIPPET:END
@@ -52,14 +115,59 @@ object app extends AndroidAppModule {
 //
 // ----
 // .
-// ├── app
-// │   ├── AndroidManifest.xml
-// │   ├── releaseKey.jks
-// │   ├── resources
-// │   │   └── values
-// │   │       ├── colors.xml
-// │   │       └── strings.xml
-// │   └── src/main/java/com/helloworld/app/MainActivity.java
-// └── build.mill
+//├── app
+//│     └── src
+//│         ├── androidTest/java/com/helloworld/app/ExampleInstrumentedTest.java
+//│         ├── main
+//│         │     ├── AndroidManifest.xml
+//│         │     ├── java/com/helloworld/app/MainActivity.java
+//│         │     └── res
+//│         │         └── values
+//│         │             ├── colors.xml
+//│         │             └── strings.xml
+//│         └── test/java/com/helloworld/app/ExampleUnitTest.java
+//└── build.mill
 // ----
 //
+
+/** Usage
+
+> ./mill show app.test
+...compiling 3 Java sources...
+
+> cat out/app/test/test.dest/out.json
+["",[{"fullyQualifiedName":"com.helloworld.ExampleUnitTest.textSize_isCorrect","selector":"com.helloworld.ExampleUnitTest.textSize_isCorrect","duration":...,"status":"Success"}]]
+
+*/
+
+// This command runs unit tests on your local environment.
+
+/** Usage
+
+> ./mill show app.createAndroidVirtualDevice
+...Name: java-test, DeviceId: medium_phone...
+
+> ./mill show app.startAndroidEmulator
+
+> ./mill show app.waitForDevice
+...emulator-5554...
+
+> ./mill show app.it | grep '"OK (1 test)"'
+..."OK (1 test)",
+
+> cat out/app/it/test.json | grep '"OK (1 test)"'
+..."OK (1 test)"...
+
+> ./mill show app.stopAndroidEmulator
+
+> ./mill show app.deleteAndroidVirtualDevice
+
+*/
+
+// The android tests (existing typically in androidTest directory, aka instrumented tests)
+// typically run on an android device.
+// The createAndroidVirtualDevice command creates an AVD (Android Virtual Device)
+// and the startAndroidEmulator command starts the AVD. The it task runs the android tests
+// against the available AVD. The stopAndroidEmulator command stops the AVD and the
+// destroyAndroidVirtualDevice command destroys the AVD.
+// The provided commands can be used in a CI/CD pipeline assuming the right setup is in place.

example/android/javalib/1-hello-world/app/src/test/java/com/helloworld/ExampleUnitTest.java

@@ -18,6 +18,8 @@ object androidSdkModule0 extends AndroidSdkModule {
 object bundle extends AndroidAppBundle {
   def androidSdkModule = mill.define.ModuleRef(androidSdkModule0)
 
+  override def releaseKeyPath = millSourcePath
+
   def androidReleaseKeyName: T[String] = Task { "releaseKey.jks" }
   def androidReleaseKeyAlias: T[String] = Task { "releaseKey" }
   def androidReleaseKeyPass: T[String] = Task { "MillBuildTool" }
@@ -45,14 +47,15 @@ object bundle extends AndroidAppBundle {
 //
 // ----
 // .
-// ├── app
-// │   ├── AndroidManifest.xml
-// │   ├── releaseKey.jks
-// │   ├── resources
-// │   │   └── values
-// │   │       ├── colors.xml
-// │   │       └── strings.xml
-// │   └── src/main/java/com/helloworld/app/MainActivity.java
-// └── build.mill
+//bundle/
+//└── src
+//    ├── main
+//    │   ├── AndroidManifest.xml
+//    │   └── java/com/helloworld/app/MainActivity.java
+//    └── res
+//        └── values
+//            ├── colors.xml
+//            └── strings.xml
+//
 // ----
 //