Merge branch 'main' into release/v2

* main:
  Prepare for release 2.27.0.
  Clean up action description.
  Update dependencies (ReactiveCircus#282)
  Update Readme & Provide current context on Hardware Acceleration on Github (ReactiveCircus#279)
  Pre Emulator Launch Script (ReactiveCircus#247)
  Update to Node 16 (ReactiveCircus#276)

.eslintrc.json

@@ -5,9 +5,6 @@
  "es6": true
  },
  "extends": [
- "eslint:recommended",
- "plugin:@typescript-eslint/recommended",
- "prettier/@typescript-eslint",
  "plugin:prettier/recommended"
  ],
  "globals": {

.github/workflows/main.yml

@@ -1,5 +1,6 @@
 name: Main workflow
 on:
+ workflow_call:
  pull_request:
  paths-ignore:
  - '**.md'
@@ -114,6 +115,9 @@ jobs:
  disable-animations: true
  working-directory: ./test-fixture/
  channel: canary
+ pre-emulator-launch-script: |
+ echo "Running pre emulator launch script. Printing the working directory now:"
+ pwd
  script: |
  echo $GITHUB_REPOSITORY
  adb devices

.github/workflows/pr-comment.yml

@@ -0,0 +1,9 @@
+name: Re-Run Tests on PR Comment Workflow
+on:
+ issue_comment:
+ types: [created]
+
+jobs:
+ rerun-tests-job:
+ if: github.event.issue.pull_request && contains(github.event.comment.body, 'run tests') # if comment is created on a PR, can also use the syntax if: contains(github.event.comment.html_url, '/pull/')
+ uses: ./.github/workflows/main.yml

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Change Log
 
+## v2.27.0
+
+* Added `pre-emulator-launch-script` to support running script after creating the AVD and before launching the emulator. - [#247](https://github.com/ReactiveCircus/android-emulator-runner/pull/247) @nilsreichardt.
+* Update to Node 16. - [#276](https://github.com/ReactiveCircus/android-emulator-runner/pull/276) @mattjohnsonpint.
+* Update NPM dependencies. - [#282](https://github.com/ReactiveCircus/android-emulator-runner/pull/282) @mattjohnsonpint.
+* Update README with more context on hardware acceleration on GitHub hosted runners. - [#279](https://github.com/ReactiveCircus/android-emulator-runner/pull/279) @mrk-han.
+
+
 ## v2.26.0
 
 * Support [github-actions-typing](https://github.com/krzema12/github-actions-typing). - [#257](https://github.com/ReactiveCircus/android-emulator-runner/pull/257) @LeoColman.

README.md

@@ -6,12 +6,21 @@
 
 A GitHub Action for installing, configuring and running hardware-accelerated Android Emulators on macOS virtual machines.
 
-The old ARM-based emulators were slow and are no longer supported by Google. The modern Intel Atom (x86 and x86_64) emulators require hardware acceleration (HAXM on Mac & Windows, QEMU on Linux) from the host to run fast. This presents a challenge on CI as to be able to run hardware accelerated emulators within a docker container, **KVM** must be supported by the host VM which isn't the case for cloud-based CI providers due to infrastructural limits. If you want to learn more about this, here's an article I wrote: [Running Android Instrumented Tests on CI](https://dev.to/ychescale9/running-android-emulators-on-ci-from-bitrise-io-to-github-actions-3j76).
+The old ARM-based emulators were slow and are no longer supported by Google. The modern Intel Atom (x86 and x86_64) emulators can be fast, but rely on two forms of hardware acceleration to reach their peak potential: [Graphics Acceleration](https://developer.android.com/studio/run/emulator-acceleration#accel-graphics), e.g. `emulator -gpu host` and [Virtual Machine(VM) Acceleration](https://developer.android.com/studio/run/emulator-acceleration#accel-vm), e.g. `emulator -accel on`. **Note:** GPU and VM Acceleration are two different and non-mutually exclusive forms of Hardware Acceleration.
 
-The **macOS** VM provided by **GitHub Actions** has **HAXM** installed so we are able to create a new AVD instance, launch an emulator with hardware acceleration, and run our Android
-tests directly on the VM. You can also achieve this on a self-hosted Linux runner, but it will need to be on a compatible instance that allows you to enable KVM - for example AWS EC2 Bare Metal instances. 
+This presents a challenge when running emulators on CI especially when running emulators within a docker container, because **Nested Virtualization** must be supported by the host VM which isn't the case for most cloud-based CI providers due to infrastructural limits. If you want to learn more about Emulators on CI, here's an article [Yang](https://github.com/ychescale9) wrote: [Running Android Instrumented Tests on CI](https://dev.to/ychescale9/running-android-emulators-on-ci-from-bitrise-io-to-github-actions-3j76).
 
-This action automates the process by doing the following:
+## HAXM support on Github's MacOS Runners
+
+The 10.x **macOS** VM provided by **GitHub Actions** had **HAXM** [pre-installed](https://github.com/actions/runner-images/blob/main/images/macos/macos-10.15-Readme.md). However, Github's [macOS-11](https://github.com/actions/runner-images/blob/main/images/macos/macos-11-Readme.md) and [macOS-12](https://github.com/actions/runner-images/blob/main/images/macos/macos-12-Readme.md) VMs **no longer** come pre-installed with HAXM. See [here](https://github.com/actions/runner-images/issues/183#issuecomment-610723516) and [here](https://github.com/actions/runner-images/issues/6388) for more info. 
+
+**To run with HAXM on the macOS-11 and macOS-12 agents, you must install HAXM before starting your emulator**. See: [this snippet](https://gist.github.com/mrk-han/a0a11ed9bed966bb8b775ff55f2a87e9) for more info. This will enable VM acceleration, but as of right now running with GPU acceleration, e.g. `emulator -gpu host` is not possible with Github's standard runners.
+
+For Linux, Nested virtualization is possible on a self-hosted or 3rd party runner, but the VM will need to be hosted on a compatible machine that allows you to [enable KVM](https://developer.android.com/studio/run/emulator-acceleration#vm-linux), or is already configured with - for example the AWS EC2 Bare Metal instances. **The Github-hosted Linux runners are not currently KVM compatible.**
+
+## Purpose
+
+This action helps automate and configure the process of setting up an emulator and running your tests by doing the following:
 
 - Install / update the required **Android SDK** components including `build-tools`, `platform-tools`, `platform` (for the required API level), `emulator` and `system-images` (for the required API level).
 - Create a new instance of **AVD** with the provided [configurations](#configurations).
@@ -20,9 +29,7 @@ This action automates the process by doing the following:
 - Run a custom script provided by user once the Emulator is up and running - e.g. `./gradlew connectedCheck`.
 - Kill the Emulator and finish the action.
 
-## Usage
-
-It is recommended to run this action on a **macOS** VM, e.g. `macos-latest`, `macos-10.15` or `macos-11` to take advantage of hardware acceleration support provided by **HAXM**.
+## Usage & Examples
 
 A workflow that uses **android-emulator-runner** to run your instrumented tests on **API 29**:
 
@@ -146,7 +153,7 @@ jobs:
 | `ram-size` | Optional | N/A | Size of RAM to use for this AVD, in KB or MB, denoted with K or M. - e.g. `2048M` |
 | `heap-size` | Optional | N/A | Heap size to use for this AVD, in KB or MB, denoted with K or M. - e.g. `512M` |
 | `sdcard-path-or-size` | Optional | N/A | Path to the SD card image for this AVD or the size of a new SD card image to create for this AVD, in KB or MB, denoted with K or M. - e.g. `path/to/sdcard`, or `1000M`. |
-| `disk-size` | Optional | N/A | Disk size to use for this AVD. Either in bytes or KB, MB or GB, when denoted with K, M or G. - e.g. `2048M` |
+| `disk-size` | Optional | N/A | Disk size, or partition size to use for this AVD. Either in bytes or KB, MB or GB, when denoted with K, M or G. - e.g. `2048M` |
 | `avd-name` | Optional | `test` | Custom AVD name used for creating the Android Virtual Device. |
 | `force-avd-creation` | Optional | `true` | Whether to force create the AVD by overwriting an existing AVD with the same name as `avd-name` - `true` or `false`. |
 | `emulator-options` | Optional | See below | Command-line options used when launching the emulator (replacing all default options) - e.g. `-no-window -no-snapshot -camera-back emulated`. |
@@ -155,21 +162,21 @@ jobs:
 | `disable-linux-hw-accel` | Optional | `auto` | Whether to disable hardware acceleration on Linux machines - `true`, `false` or `auto`.|
 | `enable-hw-keyboard` | Optional | `false` | Whether to enable hardware keyboard - `true` or `false`. |
 | `emulator-build` | Optional | N/A | Build number of a specific version of the emulator binary to use e.g. `6061023` for emulator v29.3.0.0. |
-| `working-directory` | Optional | `./` | A custom working directory - e.g. `./android` if your root Gradle project is under the `./android` sub-directory within your repository. |
+| `working-directory` | Optional | `./` | A custom working directory - e.g. `./android` if your root Gradle project is under the `./android` sub-directory within your repository. Will be used for `script` & `pre-emulator-launch-script`. |
 | `ndk` | Optional | N/A | Version of NDK to install - e.g. `21.0.6113669` |
 | `cmake` | Optional | N/A | Version of CMake to install - e.g. `3.10.2.4988404` |
 | `channel` | Optional | stable | Channel to download the SDK components from - `stable`, `beta`, `dev`, `canary` |
 | `script` | Required | N/A | Custom script to run - e.g. to run Android instrumented tests on the emulator: `./gradlew connectedCheck` |
+| `pre-emulator-launch-script` | Optional | N/A | Custom script to run after creating the AVD and before launching the emulator - e.g. `./adjust-emulator-configs.sh` |
 
 Default `emulator-options`: `-no-window -gpu swiftshader_indirect -no-snapshot -noaudio -no-boot-anim`.
 
-## Can I use this action on Linux VMs?
+## Can I use this action on Github Hosted Linux VMs?
 
-The short answer is yes but on Github-hosted Linux runners it's expected to be a much worse experience (on some newer API levels it might not work at all) than running it on macOS. You can get it running much faster on self-hosted Linux runners but only if the underlying instances support KVM (which most don't).
+The short answer is yes but on Github-hosted Linux runners it's expected to be a much worse experience (on some newer API levels it might not work at all) than running it on macOS, because of the current lack of hardware acceleration support. You can get it running much faster on self-hosted Linux runners but only if the underlying instances support KVM (which most don't). Things might be better on the newer Larger runners but they are still in Beta. It is possible to use this Action with hardware accelerated Linux VMs hosted by a third-party runner provider.
 
 For a longer answer please refer to [this issue](https://github.com/ReactiveCircus/android-emulator-runner/issues/46).
 
-
 ## Who is using Android Emulator Runner?
 
 These are some of the open-source projects using (or used) **Android Emulator Runner**:
@@ -204,4 +211,4 @@ These are some of the open-source projects using (or used) **Android Emulator Ru
 - [tinylog-org/tinylog](https://github.com/tinylog-org/tinylog/blob/v3.0/.github/workflows/build.yaml)
 - [hzi-braunschweig/SORMAS-Project](https://github.com/hzi-braunschweig/SORMAS-Project/blob/development/.github/workflows/sormas_app_ci.yml)
 
-If you are using **Android Emulator Runner** and want your project included in the list, please feel free to create an issue or open a pull request.
+If you are using **Android Emulator Runner** and want your project included in the list, please feel free to open a pull request.

action-types.yml

@@ -62,3 +62,5 @@ inputs:
  - canary
  script:
  type: string
+ pre-emulator-launch-script:
+ type: string

action.yml

@@ -40,7 +40,7 @@ inputs:
  description: 'whether to disable animations - true or false'
  default: 'true'
  disable-spellchecker:
- description: 'whether to disable spellchecker - `true` or `false`'
+ description: 'whether to disable the Android spell checker framework, a common source of flakiness in text fields - `true` or `false`'
  default: 'false'
  disable-linux-hw-accel:
  description: 'whether to disable hardware acceleration on Linux machines - `true` or `false` or `auto`'
@@ -62,6 +62,8 @@ inputs:
  script:
  description: 'custom script to run - e.g. `./gradlew connectedCheck`'
  required: true
+ pre-emulator-launch-script:
+ description: 'custom script to run after creating the AVD and before launching the emulator - e.g. `./adjust-emulator-configs.sh`'
 runs:
- using: 'node12'
+ using: 'node16'
  main: 'lib/main.js'

lib/emulator-manager.js

@@ -1,7 +1,11 @@
 "use strict";
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
  if (k2 === undefined) k2 = k;
- Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+ var desc = Object.getOwnPropertyDescriptor(m, k);
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+ desc = { enumerable: true, get: function() { return m[k]; } };
+ }
+ Object.defineProperty(o, k2, desc);
 }) : (function(o, m, k, k2) {
  if (k2 === undefined) k2 = k;
  o[k2] = m[k];
@@ -14,7 +18,7 @@ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (
 var __importStar = (this && this.__importStar) || function (mod) {
  if (mod && mod.__esModule) return mod;
  var result = {};
- if (mod != null) for (var k in mod) if (k !== "default" && Object.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+ if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
  __setModuleDefault(result, mod);
  return result;
 };
@@ -75,8 +79,8 @@ function launchEmulator(apiLevel, target, arch, profile, cores, ramSize, heapSiz
  if (data.toString().includes('invalid command-line parameter')) {
  throw new Error(data.toString());
  }
- }
- }
+ },
+ },
  });
  // wait for emulator to complete booting
  yield waitForDevice();
@@ -110,7 +114,7 @@ function killEmulator() {
  yield exec.exec(`adb -s emulator-5554 emu kill`);
  }
  catch (error) {
- console.log(error.message);
+ console.log(error instanceof Error ? error.message : error);
  }
  finally {
  console.log(`::endgroup::`);
@@ -134,8 +138,8 @@ function waitForDevice() {
  listeners: {
  stdout: (data) => {
  result += data.toString();
- }
- }
+ },
+ },
  });
  if (result.trim() === '1') {
  console.log('Emulator booted.');
@@ -144,7 +148,7 @@ function waitForDevice() {
  }
  }
  catch (error) {
- console.warn(error.message);
+ console.warn(error instanceof Error ? error.message : error);
  }
  if (attempts < maxAttempts) {
  yield delay(retryInterval * 1000);
@@ -157,5 +161,5 @@ function waitForDevice() {
  });
 }
 function delay(ms) {
- return new Promise(resolve => setTimeout(resolve, ms));
+ return new Promise((resolve) => setTimeout(resolve, ms));
 }