fastlane-plugin-developer_device_platform 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a99f79e05b0a9a125921c472bd1edac41dc27c87dac082aeef067c99a84586d3
-  data.tar.gz: 7e1751408cf3527c2b1ab83d8f66680137904a0acee6d82b4946c37b9b4a9ac1
+  metadata.gz: 7d7beb8da7cf98d4f592a20ab3b957b2e5a059a6959f52b560beab245ae251a0
+  data.tar.gz: b526995df11c60771ff7653ff3a947c910ece216bce370a855ef3d67bc500ca5
 SHA512:
-  metadata.gz: d8e4599ff167590dc18b132e314e79e7ad7f9d4333f94c86999655e440898c89ceac4494185d780cc5763ad44e37f589ba6a12a821f452a7eaed05a1235f12a8
-  data.tar.gz: dacea5f0bc9b4b5596fa33bb75b799a525a355d3636f704a9733d97abed96fb3e7494ca3c552b65ec6773ba074668d9572c06fc1ac9166081e9f153bc5ec7ea2
+  metadata.gz: 7a7abb638d150564242a219cdaed48b953a3557e9521b1c58cc0a869a32d67366605f03f9fe20751473dc30337c3cbaec2c6808987996a625344758f56f042d7
+  data.tar.gz: 970889f67676b92e02a4103e370d95d3367b58f41b3698fe78c09d453e71b45f4d4fe7f23777690e46132f96329f6f9ff429a182b1fb8b6700b6d109e39051f2

data/README.md

@@ -5,7 +5,7 @@
 
 Run Android instrumentation tests on [Google Cloud Developer Device Platform](https://docs.cloud.google.com/developer-device-platform) (Device Run) from fastlane.
 
-Firebase Test Lab is [deprecated and shuts down on September 30, 2027](https://firebase.google.com/docs/test-lab/migrate-faq). Developer Device Platform is its successor on Google Cloud. This plugin is a drop-in replacement for [fastlane-plugin-firebase_test_lab_android](https://github.com/cats-oss/fastlane-plugin-firebase_test_lab_android) built on `gcloud beta device-run`.
+Firebase Test Lab is [deprecated and shuts down on September 30, 2027](https://firebase.google.com/docs/test-lab/migrate-faq). Developer Device Platform is its successor on Google Cloud. This plugin wraps `gcloud beta device-run` so Android instrumentation tests can keep running from a fastlane lane.
 
 ## What the action does
 
@@ -17,7 +17,7 @@ Firebase Test Lab is [deprecated and shuts down on September 30, 2027](https://f
 
 ## Prerequisites
 
-- [Google Cloud CLI](https://cloud.google.com/sdk/docs/install) on the machine running fastlane (`gcloud components update` if it predates Device Run).
+- [Google Cloud CLI](https://cloud.google.com/sdk/docs/install) 580.0.0 or newer with the `beta` component on the machine running fastlane (`gcloud components update && gcloud components install beta`). On GitHub Actions, pin `version` in `google-github-actions/setup-gcloud`; its default `latest` can resolve to an older release that predates Device Run.
 - A Google Cloud project with billing enabled and the APIs turned on:
 
   ```sh
@@ -71,7 +71,7 @@ developer_device_platform(
 
 ### Options
 
-Options mirror the flags of `gcloud beta device-run sessions submit instrumentation`. Every option can also be set through the environment variable `DEVELOPER_DEVICE_PLATFORM_<OPTION>`.
+Options mirror the flags of `gcloud beta device-run sessions submit instrumentation`. Every option except the hash-valued ones (`additional_test_options`, `other_files_to_push`, `labels`) can also be set through the environment variable `DEVELOPER_DEVICE_PLATFORM_<OPTION>`; array values are comma-separated.
 
 | Option | Type | Description |
 | --- | --- | --- |
@@ -105,7 +105,7 @@ Options mirror the flags of `gcloud beta device-run sessions submit instrumentat
 | `flaky_test_attempts` | Integer | Attempts per shard. Default `1`. |
 | `flaky_test_parallel_retry` | Boolean | Retry in parallel instead of sequentially. |
 | `flaky_test_retry_level` | String | `shard` or `test`. |
-| `async` | Boolean | Return the session ID right after submission. Default `false`. |
+| `async` | Boolean | Return the session ID right after submission; the output directory and console URL are still exposed. Default `false`. |
 | `download_dir` | String | Local directory to download the session artifacts into. |
 | `fail_on_failure` | Boolean | Fail the lane when the result is not `PASSED`. Default `true`. |
 
@@ -120,6 +120,7 @@ The action returns a `Fastlane::DeveloperDevicePlatform::Session` (or the sessio
 | `DEVELOPER_DEVICE_PLATFORM_OUTPUT_DIRECTORY` | `gs://BUCKET/automation/sessions/SESSION_ID` |
 | `DEVELOPER_DEVICE_PLATFORM_CONSOLE_URL` | Cloud Console link to the artifacts |
 | `DEVELOPER_DEVICE_PLATFORM_DOWNLOAD_DIR` | Local artifact directory when `download_dir` is set |
+| `DEVELOPER_DEVICE_PLATFORM_JUNIT_FILES` | Local `junit.xml` paths, one per job, when `download_dir` is set |
 
 ```ruby
 session = developer_device_platform(devices: ["shiba-34"], test_apk: "test.apk", fail_on_failure: false)
@@ -128,7 +129,9 @@ session.jobs.each { |job| puts "#{job.display_name}: #{job.result} #{job.message
 
 ### Results
 
-Artifacts land in `gs://BUCKET/automation/sessions/SESSION_ID/job-NNN/`: `merged_junit.xml` per job, and `junit.xml`, `instrumentation.log`, `logcat.txt`, `video.mp4` and pulled files per execution. With `download_dir` the same tree is copied to `<download_dir>/<SESSION_ID>/`, so JUnit reporters can pick up `**/merged_junit.xml`.
+Artifacts land in `gs://BUCKET/automation/sessions/SESSION_ID/job-NNN/`: a `junit.xml` per job, and `test_result.xml`, `instrument.log`, `logcat.txt`, video recordings and pulled files under `execution-NNN/`. With `download_dir` the same tree is copied to `<download_dir>/<SESSION_ID>/` and the `junit.xml` paths are exposed in `DEVELOPER_DEVICE_PLATFORM_JUNIT_FILES` for JUnit reporters.
+
+Interrupting fastlane while it waits (Ctrl-C, or a cancelled CI job) cancels the Device Run session before exiting, so no job keeps running unattended.
 
 ### Authentication
 
@@ -136,23 +139,6 @@ On CI, the simplest setup is a service account key passed through `service_accou
 
 Device Run reads inputs and writes results through its own service agent (`service-PROJECT_NUMBER@gcp-sa-devicerun.iam.gserviceaccount.com`). When you point `bucket_name` at a bucket in another project, grant that agent `roles/storage.objectViewer` on it (see [Share storage](https://docs.cloud.google.com/developer-device-platform/device-run/share-storage)).
 
-## Migrating from fastlane-plugin-firebase_test_lab_android
-
-| firebase_test_lab_android | developer_device_platform |
-| --- | --- |
-| `project_id` | `project_id` |
-| `gcloud_service_key_file` | `service_account_key_file` |
-| `type: "instrumentation"` | Only instrumentation tests are supported by Device Run. Robo tests have no equivalent. |
-| `devices: [{ model:, version:, locale:, orientation: }]` | `devices: ["<model>-<version>"]`, plus `locale` and `orientation` applied to every device |
-| `app_apk` / `app_test_apk` | `apps: [app_apk]` / `test_apk` |
-| `use_orchestrator: true` | `orchestrator_version: "auto"` |
-| `timeout` | `instrumentation_timeout` |
-| `firebase_test_lab_results_bucket` | `bucket_name` |
-| `firebase_test_lab_results_dir` | Not supported. Results are grouped by session ID. |
-| `download_dir` | `download_dir` |
-| `extra_options` | The corresponding typed option (`test_targets`, `additional_test_options`, `video`, ...) |
-| `slack_url`, `github_*` | Not included. Use `slack` or GitHub actions with the lane context values above. |
-
 ## Development
 
 ```sh

data/lib/fastlane/plugin/developer_device_platform/actions/developer_device_platform_action.rb

@@ -13,6 +13,7 @@ module Fastlane
       DEVELOPER_DEVICE_PLATFORM_OUTPUT_DIRECTORY = :DEVELOPER_DEVICE_PLATFORM_OUTPUT_DIRECTORY
       DEVELOPER_DEVICE_PLATFORM_CONSOLE_URL = :DEVELOPER_DEVICE_PLATFORM_CONSOLE_URL
       DEVELOPER_DEVICE_PLATFORM_DOWNLOAD_DIR = :DEVELOPER_DEVICE_PLATFORM_DOWNLOAD_DIR
+      DEVELOPER_DEVICE_PLATFORM_JUNIT_FILES = :DEVELOPER_DEVICE_PLATFORM_JUNIT_FILES
     end
 
     class DeveloperDevicePlatformAction < Action
@@ -31,11 +32,12 @@ module Fastlane
         session_id = client.submit(build_command(params)) { |line| UI.message(line) }
         lane_context[SharedValues::DEVELOPER_DEVICE_PLATFORM_SESSION_ID] = session_id
         UI.success("Created Device Run session #{session_id}")
-        return session_id if params[:async]
+        if params[:async]
+          publish(client.describe(session_id, location: location))
+          return session_id
+        end
 
-        UI.message("Waiting for session #{session_id} to complete...")
-        client.wait(session_id, location: location) { |line| UI.message(line) }
-        session = client.describe(session_id, location: location)
+        session = await(client, session_id, location)
         publish(session)
         download(client, session, params[:download_dir])
         UI.message(DeveloperDevicePlatform::SessionSummary.new(session).to_s)
@@ -56,6 +58,23 @@ module Fastlane
         DeveloperDevicePlatform::InstrumentationCommand.new(**COMMAND_OPTIONS.to_h { |key| [key, params[key]] })
       end
 
+      def self.await(client, session_id, location)
+        UI.message("Waiting for session #{session_id} to complete...")
+        client.wait(session_id, location: location) { |line| UI.message(line) }
+        client.describe(session_id, location: location)
+      rescue SignalException
+        cancel(client, session_id, location)
+        raise
+      end
+
+      def self.cancel(client, session_id, location)
+        UI.important("Interrupted. Cancelling Device Run session #{session_id}...")
+        client.cancel(session_id, location: location)
+        UI.important("Cancelled Device Run session #{session_id}")
+      rescue *RECOVERABLE_ERRORS => e
+        UI.error("Could not cancel Device Run session #{session_id}: #{e.message}")
+      end
+
       def self.publish(session)
         lane_context[SharedValues::DEVELOPER_DEVICE_PLATFORM_RESULT] = session.result
         lane_context[SharedValues::DEVELOPER_DEVICE_PLATFORM_OUTPUT_DIRECTORY] = session.output_directory
@@ -68,6 +87,7 @@ module Fastlane
         UI.message("Downloading results of session #{session.id} to #{destination}...")
         local_path = client.download(session, destination) { |line| UI.verbose(line) }
         lane_context[SharedValues::DEVELOPER_DEVICE_PLATFORM_DOWNLOAD_DIR] = local_path
+        lane_context[SharedValues::DEVELOPER_DEVICE_PLATFORM_JUNIT_FILES] = Dir.glob(File.join(local_path, "**", "junit.xml"))
         UI.success("Results downloaded to #{local_path}")
       end
 
@@ -110,7 +130,8 @@ module Fastlane
           ["DEVELOPER_DEVICE_PLATFORM_RESULT", "Overall result (PASSED, FAILED, ERROR, TIMED_OUT, CANCELLED)"],
           ["DEVELOPER_DEVICE_PLATFORM_OUTPUT_DIRECTORY", "Cloud Storage directory (gs://...) holding the session artifacts"],
           ["DEVELOPER_DEVICE_PLATFORM_CONSOLE_URL", "Cloud Console URL of the session artifacts"],
-          ["DEVELOPER_DEVICE_PLATFORM_DOWNLOAD_DIR", "Local directory the artifacts were downloaded to, when download_dir is set"]
+          ["DEVELOPER_DEVICE_PLATFORM_DOWNLOAD_DIR", "Local directory the artifacts were downloaded to, when download_dir is set"],
+          ["DEVELOPER_DEVICE_PLATFORM_JUNIT_FILES", "Downloaded junit.xml paths, one per job, when download_dir is set"]
         ]
       end
 
@@ -155,7 +176,7 @@ module Fastlane
         DeveloperDevicePlatform::Options.all
       end
 
-      private_class_method :build_gcloud, :build_command, :publish, :download, :conclude
+      private_class_method :build_gcloud, :build_command, :await, :cancel, :publish, :download, :conclude
     end
   end
 end

data/lib/fastlane/plugin/developer_device_platform/helper/device_run_client.rb

@@ -8,6 +8,15 @@ module Fastlane
       class Error < StandardError; end
 
       SESSION_ANNOUNCEMENT = /Creating session \[([^\]]+)\]/
+      MINIMUM_GCLOUD_VERSION = "580.0.0".freeze
+
+      ENVIRONMENT_HINTS = {
+        /Invalid choice: 'device-run'/ =>
+          "The installed gcloud does not provide the device-run command group. " \
+          "Device Run requires Google Cloud CLI #{MINIMUM_GCLOUD_VERSION} or newer; run `gcloud components update`.",
+        /installation of components: \[beta\]/ =>
+          "The gcloud beta component is not installed; run `gcloud components install beta`."
+      }.freeze
 
       attr_reader :gcloud
 
@@ -26,6 +35,11 @@ module Fastlane
         nil
       end
 
+      def cancel(session_id, location:)
+        device_run("sessions", "cancel", session_id, "--location=#{location}")
+        nil
+      end
+
       def describe(session_id, location:)
         output = device_run("sessions", "describe", session_id, "--location=#{location}", "--full", "--format=json")
         Session.parse(output.stdout)
@@ -44,6 +58,15 @@ module Fastlane
 
       def device_run(*args, &progress)
         gcloud.run("beta", "device-run", *args, &progress)
+      rescue Gcloud::CommandError => e
+        hint = environment_hint(e.stderr)
+        raise e unless hint
+
+        raise Error, "#{hint}\n#{e.message}"
+      end
+
+      def environment_hint(stderr)
+        ENVIRONMENT_HINTS.find { |pattern, _| pattern.match?(stderr) }&.last
       end
     end
   end

data/lib/fastlane/plugin/developer_device_platform/helper/gcloud.rb

@@ -51,7 +51,7 @@ module Fastlane
           stderr_text = +""
           stderr.each_line do |line|
             stderr_text << line
-            yield(line.chomp) if block_given?
+            yield(line.chomp) if block_given? && !line.strip.empty?
           end
           [stdout_reader.value, stderr_text, waiter.value]
         end

data/lib/fastlane/plugin/developer_device_platform/helper/options.rb

@@ -83,7 +83,7 @@ module Fastlane
       def option(key, description, type: String, optional: true, default_value: nil, verify_block: nil)
         FastlaneCore::ConfigItem.new(
           key: key,
-          env_name: "DEVELOPER_DEVICE_PLATFORM_#{key.to_s.upcase}",
+          env_name: env_name_for(key, type),
           description: description,
           type: type,
           optional: optional,
@@ -92,6 +92,12 @@ module Fastlane
         )
       end
 
+      def env_name_for(key, type)
+        return nil if type == Hash
+
+        "DEVELOPER_DEVICE_PLATFORM_#{key.to_s.upcase}"
+      end
+
       def enum_option(key, description, values)
         option(key, "#{description} (#{values.join(' | ')})", verify_block: proc do |value|
           UI.user_error!("#{key} must be one of #{values.join(', ')}, got '#{value}'") unless values.include?(value)

data/lib/fastlane/plugin/developer_device_platform/version.rb

@@ -1,5 +1,5 @@
 module Fastlane
   module DeveloperDevicePlatform
-    VERSION = "0.1.0".freeze
+    VERSION = "0.2.0".freeze
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fastlane-plugin-developer_device_platform
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - ntsk