fastlane-plugin-developer_device_platform 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a99f79e05b0a9a125921c472bd1edac41dc27c87dac082aeef067c99a84586d3
+  data.tar.gz: 7e1751408cf3527c2b1ab83d8f66680137904a0acee6d82b4946c37b9b4a9ac1
+SHA512:
+  metadata.gz: d8e4599ff167590dc18b132e314e79e7ad7f9d4333f94c86999655e440898c89ceac4494185d780cc5763ad44e37f589ba6a12a821f452a7eaed05a1235f12a8
+  data.tar.gz: dacea5f0bc9b4b5596fa33bb75b799a525a355d3636f704a9733d97abed96fb3e7494ca3c552b65ec6773ba074668d9572c06fc1ac9166081e9f153bc5ec7ea2

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 ntsk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,168 @@
+# fastlane-plugin-developer_device_platform
+
+[![fastlane Plugin Badge](https://rawcdn.githack.com/fastlane/fastlane/master/fastlane/assets/plugin-badge.svg)](https://rubygems.org/gems/fastlane-plugin-developer_device_platform)
+[![Test](https://github.com/ntsk/fastlane-plugin-developer_device_platform/actions/workflows/test.yml/badge.svg)](https://github.com/ntsk/fastlane-plugin-developer_device_platform/actions/workflows/test.yml)
+
+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`.
+
+## What the action does
+
+1. Uploads the app and test APKs to Cloud Storage and submits a Device Run session (one job per device).
+2. Waits for the session to complete, streaming gcloud's progress to the fastlane log.
+3. Reads the full session report, prints a per-job result table and the Cloud Console link.
+4. Optionally downloads the artifacts (`junit.xml`, `logcat.txt`, `video.mp4`, ...) to a local directory.
+5. Fails the lane unless the session result is `PASSED` (configurable).
+
+## Prerequisites
+
+- [Google Cloud CLI](https://cloud.google.com/sdk/docs/install) on the machine running fastlane (`gcloud components update` if it predates Device Run).
+- A Google Cloud project with billing enabled and the APIs turned on:
+
+  ```sh
+  gcloud services enable devicerun.googleapis.com devicestreaming.googleapis.com testing.googleapis.com
+  ```
+
+- The account running the tests needs `roles/devicerun.admin` and `roles/serviceusage.serviceUsageConsumer` on the project (see the [quickstart](https://docs.cloud.google.com/developer-device-platform/quickstart)).
+- Authentication for gcloud. Either log in interactively (`gcloud auth login`) or pass a service account key with `service_account_key_file` (see [Authentication](#authentication)).
+
+## Installation
+
+```sh
+fastlane add_plugin developer_device_platform
+```
+
+## Usage
+
+```ruby
+lane :instrumentation_tests do
+  gradle(task: "assembleDebug assembleDebugAndroidTest")
+
+  developer_device_platform(
+    project_id: "my-gcp-project",
+    devices: ["shiba-34", "tokay-36"],
+    apps: ["app/build/outputs/apk/debug/app-debug.apk"],
+    test_apk: "app/build/outputs/apk/androidTest/debug/app-debug-androidTest.apk",
+    orchestrator_version: "auto",
+    instrumentation_timeout: "15m",
+    video: "on-failure",
+    download_dir: "build/device-run"
+  )
+end
+```
+
+Find device IDs with `gcloud beta device-run devices list` (for example `--filter="HARDWARE_TYPE=PHYSICAL AND OS_VERSION=35"`). An ID is `<model>-<api level>`, such as `shiba-34`, or a descriptive name for virtual devices, such as `mediumphone-arm-34`.
+
+Inputs may also be `gs://` URIs, in which case nothing is uploaded:
+
+```ruby
+developer_device_platform(
+  devices: ["mediumphone-arm-34"],
+  apps: ["gs://my-bucket/app-debug.apk"],
+  test_apk: "gs://my-bucket/app-debug-androidTest.apk",
+  sharding_option: "smart",
+  smart_sharding_target_duration: "5m",
+  smart_sharding_record_name: "nightly",
+  flaky_test_attempts: 2,
+  flaky_test_retry_level: "test"
+)
+```
+
+### 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>`.
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `devices` | Array | **Required.** Device type IDs. One job is created per device. |
+| `test_apk` | String | **Required.** Instrumentation test APK, local path or `gs://` URI. |
+| `apps` | Array | App files (`.apk`, `.aab`, `.apks`) installed before the test, in order. |
+| `project_id` | String | Google Cloud project. Defaults to the active gcloud configuration. |
+| `service_account_key_file` | String | Service account key JSON used to authenticate gcloud for this action only. |
+| `gcloud_binary` | String | Path to `gcloud`. Default `gcloud`. |
+| `location` | String | Cloud location of the session. Default `global`. |
+| `bucket_name` | String | Bucket for inputs and results. Defaults to `PROJECT_ID-devicerun`, created on first use. |
+| `test_runner_class` | String | Instrumentation runner class. Defaults to the manifest value. |
+| `test_targets` | Array | Targets such as `"class com.example.FooTest"` or `"notPackage com.example.slow"`. |
+| `additional_test_options` | Hash | Options passed to the runner, e.g. `{ clearPackageData: "true" }`. |
+| `other_files_to_push` | Hash | Files pushed before the test, `{ "local/or/gs/path" => "/sdcard/dest" }`. |
+| `paths_to_pull` | Array | Device paths pulled after the test. |
+| `instrumentation_timeout` | String | `1m` to `3h`. Default `5m`. |
+| `orchestrator_version` | String | Android Test Orchestrator version or `auto`. Unset means no orchestrator. |
+| `labels` | Hash | Labels attached to the session. |
+| `locale` | String | Device locale, e.g. `ja-JP`. |
+| `orientation` | String | `portrait` or `landscape`. |
+| `coordinates` | String | Mock GPS location `latitude,longitude`. |
+| `video` | String | `always` or `on-failure`. |
+| `dumpsys` | String | `always` or `on-failure`. |
+| `bugreport` | String | `always` or `on-failure`. |
+| `sharding_option` | String | `uniform` or `smart`. |
+| `uniform_sharding_count` | Integer | Shard count. Required with `uniform`. |
+| `smart_sharding_target_duration` | String | Target duration per shard, `2m` to `1h`. Required with `smart`. |
+| `smart_sharding_record_name` | String | Timing record name without extension. Required with `smart`. |
+| `smart_sharding_max_shard_count` | Integer | Maximum smart shards. `0` uses the system limit. |
+| `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`. |
+| `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`. |
+
+### Return value and lane context
+
+The action returns a `Fastlane::DeveloperDevicePlatform::Session` (or the session ID when `async` is true) and sets:
+
+| Lane context key | Value |
+| --- | --- |
+| `DEVELOPER_DEVICE_PLATFORM_SESSION_ID` | Session ID |
+| `DEVELOPER_DEVICE_PLATFORM_RESULT` | `PASSED`, `FAILED`, `ERROR`, `TIMED_OUT` or `CANCELLED` |
+| `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 |
+
+```ruby
+session = developer_device_platform(devices: ["shiba-34"], test_apk: "test.apk", fail_on_failure: false)
+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`.
+
+### Authentication
+
+On CI, the simplest setup is a service account key passed through `service_account_key_file`. The plugin hands it to gcloud via `CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE`, so the global gcloud configuration is left untouched. If your CI already authenticates gcloud (for example with Workload Identity Federation through `google-github-actions/auth`), omit the option and the active credentials are used.
+
+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
+bundle install
+bundle exec rake        # rspec + rubocop
+bundle exec fastlane action developer_device_platform
+```
+
+The gcloud integration is exercised against a fake `gcloud` executable in `spec/fixtures`, so the test suite needs neither credentials nor network access.
+
+## License
+
+MIT

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

@@ -0,0 +1,161 @@
+require 'fastlane/action'
+require_relative '../helper/device_run_client'
+require_relative '../helper/gcloud'
+require_relative '../helper/instrumentation_command'
+require_relative '../helper/options'
+require_relative '../helper/session_summary'
+
+module Fastlane
+  module Actions
+    module SharedValues
+      DEVELOPER_DEVICE_PLATFORM_SESSION_ID = :DEVELOPER_DEVICE_PLATFORM_SESSION_ID
+      DEVELOPER_DEVICE_PLATFORM_RESULT = :DEVELOPER_DEVICE_PLATFORM_RESULT
+      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
+    end
+
+    class DeveloperDevicePlatformAction < Action
+      COMMAND_OPTIONS = DeveloperDevicePlatform::InstrumentationCommand::FLAGS.keys
+      RECOVERABLE_ERRORS = [
+        DeveloperDevicePlatform::Gcloud::CommandError,
+        DeveloperDevicePlatform::DeviceRunClient::Error,
+        DeveloperDevicePlatform::Session::ParseError
+      ].freeze
+
+      def self.run(params)
+        client = DeveloperDevicePlatform::DeviceRunClient.new(gcloud: build_gcloud(params))
+        location = params[:location]
+
+        UI.message("Submitting instrumentation session to Developer Device Platform...")
+        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]
+
+        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)
+        publish(session)
+        download(client, session, params[:download_dir])
+        UI.message(DeveloperDevicePlatform::SessionSummary.new(session).to_s)
+        conclude(session, fail_on_failure: params[:fail_on_failure])
+      rescue *RECOVERABLE_ERRORS => e
+        UI.user_error!(e.message)
+      end
+
+      def self.build_gcloud(params)
+        DeveloperDevicePlatform::Gcloud.new(
+          binary: params[:gcloud_binary],
+          project: params[:project_id],
+          credential_file: params[:service_account_key_file]
+        )
+      end
+
+      def self.build_command(params)
+        DeveloperDevicePlatform::InstrumentationCommand.new(**COMMAND_OPTIONS.to_h { |key| [key, params[key]] })
+      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
+        lane_context[SharedValues::DEVELOPER_DEVICE_PLATFORM_CONSOLE_URL] = session.console_url
+      end
+
+      def self.download(client, session, destination)
+        return if destination.nil?
+
+        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
+        UI.success("Results downloaded to #{local_path}")
+      end
+
+      def self.conclude(session, fail_on_failure:)
+        outcome = "Device Run session #{session.id} finished with result #{session.result}"
+        if session.passed?
+          UI.success(outcome)
+        elsif fail_on_failure
+          UI.test_failure!(outcome)
+        else
+          UI.important(outcome)
+        end
+        session
+      end
+
+      def self.description
+        "Run Android instrumentation tests on Google Cloud Developer Device Platform (Device Run)"
+      end
+
+      def self.details
+        [
+          "Uploads your app and test APKs to Google Cloud Storage, submits an instrumentation session to Device Run",
+          "(the successor of Firebase Test Lab), waits for it to finish and reports the per-job results.",
+          "Requires the Google Cloud CLI (`gcloud`) with the Device Run API (devicerun.googleapis.com) enabled on the project.",
+          "Options mirror the flags of `gcloud beta device-run sessions submit instrumentation`."
+        ].join(" ")
+      end
+
+      def self.authors
+        ["ntsk"]
+      end
+
+      def self.return_value
+        "The DeveloperDevicePlatform::Session describing the finished session, or the session id when `async` is true"
+      end
+
+      def self.output
+        [
+          ["DEVELOPER_DEVICE_PLATFORM_SESSION_ID", "ID of the created Device Run session"],
+          ["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"]
+        ]
+      end
+
+      def self.example_code
+        [
+          <<~EXAMPLE,
+            developer_device_platform(
+              project_id: "my-gcp-project",
+              devices: ["shiba-34", "tokay-36"],
+              apps: ["app/build/outputs/apk/debug/app-debug.apk"],
+              test_apk: "app/build/outputs/apk/androidTest/debug/app-debug-androidTest.apk",
+              orchestrator_version: "auto",
+              instrumentation_timeout: "15m",
+              video: "on-failure",
+              download_dir: "build/device-run"
+            )
+          EXAMPLE
+          <<~EXAMPLE
+            developer_device_platform(
+              devices: ["mediumphone-arm-34"],
+              test_apk: "gs://my-bucket/app-debug-androidTest.apk",
+              apps: ["gs://my-bucket/app-debug.apk"],
+              sharding_option: "smart",
+              smart_sharding_target_duration: "5m",
+              smart_sharding_record_name: "nightly",
+              flaky_test_attempts: 2,
+              flaky_test_retry_level: "test"
+            )
+          EXAMPLE
+        ]
+      end
+
+      def self.category
+        :testing
+      end
+
+      def self.is_supported?(platform)
+        platform == :android
+      end
+
+      def self.available_options
+        DeveloperDevicePlatform::Options.all
+      end
+
+      private_class_method :build_gcloud, :build_command, :publish, :download, :conclude
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+require 'fileutils'
+require_relative 'gcloud'
+require_relative 'session'
+
+module Fastlane
+  module DeveloperDevicePlatform
+    class DeviceRunClient
+      class Error < StandardError; end
+
+      SESSION_ANNOUNCEMENT = /Creating session \[([^\]]+)\]/
+
+      attr_reader :gcloud
+
+      def initialize(gcloud:)
+        @gcloud = gcloud
+      end
+
+      def submit(command, &progress)
+        output = device_run("sessions", "submit", "instrumentation", *command.arguments, "--async", &progress)
+        output.stderr[SESSION_ANNOUNCEMENT, 1] ||
+          raise(Error, "Could not find the session id in gcloud output:\n#{output.stderr}")
+      end
+
+      def wait(session_id, location:, &progress)
+        device_run("sessions", "wait", session_id, "--location=#{location}", &progress)
+        nil
+      end
+
+      def describe(session_id, location:)
+        output = device_run("sessions", "describe", session_id, "--location=#{location}", "--full", "--format=json")
+        Session.parse(output.stdout)
+      end
+
+      def download(session, destination, &progress)
+        source = session.output_directory
+        raise Error, "Session #{session.id} has no output directory to download" if source.nil?
+
+        FileUtils.mkdir_p(destination)
+        gcloud.run("storage", "cp", "--recursive", source, destination, &progress)
+        File.join(destination, session.id)
+      end
+
+      private
+
+      def device_run(*args, &progress)
+        gcloud.run("beta", "device-run", *args, &progress)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+require 'open3'
+
+module Fastlane
+  module DeveloperDevicePlatform
+    class Gcloud
+      Output = Struct.new(:stdout, :stderr, keyword_init: true)
+
+      class CommandError < StandardError
+        attr_reader :command, :stderr, :exit_status
+
+        def initialize(command, stderr, exit_status)
+          @command = command
+          @stderr = stderr
+          @exit_status = exit_status
+          super("gcloud command failed#{" (exit #{exit_status})" if exit_status}: #{command.join(' ')}\n#{stderr}".rstrip)
+        end
+      end
+
+      attr_reader :binary, :project, :credential_file
+
+      def initialize(binary: "gcloud", project: nil, credential_file: nil)
+        @binary = binary
+        @project = project
+        @credential_file = credential_file
+      end
+
+      def run(*args, &on_stderr_line)
+        command = [binary, *args]
+        stdout, stderr, status = execute(command, &on_stderr_line)
+        raise CommandError.new(command, stderr, status.exitstatus) unless status.success?
+
+        Output.new(stdout:, stderr:)
+      rescue Errno::ENOENT => e
+        raise CommandError.new(command, e.message, nil)
+      end
+
+      def environment
+        {
+          "CLOUDSDK_CORE_DISABLE_PROMPTS" => "1",
+          "CLOUDSDK_CORE_PROJECT" => project,
+          "CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE" => credential_file
+        }.compact
+      end
+
+      private
+
+      def execute(command)
+        Open3.popen3(environment, *command) do |stdin, stdout, stderr, waiter|
+          stdin.close
+          stdout_reader = Thread.new { stdout.read }
+          stderr_text = +""
+          stderr.each_line do |line|
+            stderr_text << line
+            yield(line.chomp) if block_given?
+          end
+          [stdout_reader.value, stderr_text, waiter.value]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,90 @@
+module Fastlane
+  module DeveloperDevicePlatform
+    class InstrumentationCommand
+      module Flags
+        ALTERNATE_DELIMITER = "|".freeze
+
+        module_function
+
+        def value(flag, value)
+          value.nil? ? [] : ["--#{flag}=#{value}"]
+        end
+
+        def list(flag, values)
+          values = Array(values).compact
+          values.empty? ? [] : ["--#{flag}=#{join(values)}"]
+        end
+
+        def repeated(flag, values)
+          Array(values).compact.map { |item| "--#{flag}=#{join([item])}" }
+        end
+
+        def dict(flag, pairs)
+          (pairs || {}).map { |key, value| "--#{flag}=#{join(["#{key}=#{value}"])}" }
+        end
+
+        def boolean(flag, value)
+          case value
+          when true then ["--#{flag}"]
+          when false then ["--no-#{flag}"]
+          else []
+          end
+        end
+
+        def join(items)
+          items = items.map(&:to_s)
+          return items.join(",") if items.none? { |item| item.include?(",") }
+
+          "^#{ALTERNATE_DELIMITER}^#{items.join(ALTERNATE_DELIMITER)}"
+        end
+      end
+
+      FLAGS = {
+        devices: ["device", :list],
+        test_apk: ["test", :value],
+        apps: ["apps", :list],
+        location: ["location", :value],
+        bucket_name: ["bucket-name", :value],
+        test_runner_class: ["test-runner-class", :value],
+        test_targets: ["test-targets", :repeated],
+        additional_test_options: ["additional-test-options", :dict],
+        other_files_to_push: ["other-files-to-push", :dict],
+        paths_to_pull: ["paths-to-pull", :list],
+        instrumentation_timeout: ["instrumentation-timeout", :value],
+        orchestrator_version: ["orchestrator-version", :value],
+        locale: ["locale", :value],
+        orientation: ["orientation", :value],
+        coordinates: ["coordinates", :value],
+        video: ["video", :value],
+        dumpsys: ["dumpsys", :value],
+        bugreport: ["bugreport", :value],
+        sharding_option: ["sharding-option", :value],
+        uniform_sharding_count: ["uniform-sharding-count", :value],
+        smart_sharding_target_duration: ["smart-sharding-target-duration", :value],
+        smart_sharding_record_name: ["smart-sharding-record-name", :value],
+        smart_sharding_max_shard_count: ["smart-sharding-max-shard-count", :value],
+        flaky_test_attempts: ["flaky-test-attempts", :value],
+        flaky_test_parallel_retry: ["flaky-test-parallel-retry", :boolean],
+        flaky_test_retry_level: ["flaky-test-retry-level", :value],
+        labels: ["labels", :dict]
+      }.freeze
+
+      attr_reader :options
+
+      def initialize(devices:, test_apk:, **options)
+        unknown = options.keys - FLAGS.keys
+        raise ArgumentError, "unknown options: #{unknown.join(', ')}" unless unknown.empty?
+        raise ArgumentError, "devices must contain at least one device id" if Array(devices).compact.empty?
+        raise ArgumentError, "test_apk is required" if test_apk.to_s.empty?
+
+        @options = { devices: Array(devices), test_apk: test_apk, **options }.freeze
+      end
+
+      def arguments
+        FLAGS.flat_map do |key, (flag, kind)|
+          Flags.public_send(kind, flag, options[key])
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,122 @@
+require 'fastlane/boolean'
+require 'fastlane_core/configuration/config_item'
+require 'fastlane_core/ui/ui'
+
+module Fastlane
+  UI = FastlaneCore::UI unless Fastlane.const_defined?(:UI)
+
+  module DeveloperDevicePlatform
+    module Options
+      COLLECTION_MODES = ["always", "on-failure"].freeze
+      ORIENTATIONS = ["portrait", "landscape"].freeze
+      SHARDING_OPTIONS = ["uniform", "smart"].freeze
+      RETRY_LEVELS = ["shard", "test"].freeze
+
+      module_function
+
+      def all
+        execution_options + device_options + sharding_options + retry_options + behaviour_options
+      end
+
+      def execution_options
+        [
+          option(:gcloud_binary, "Path to the gcloud executable", default_value: "gcloud"),
+          option(:project_id, "Google Cloud project ID (defaults to the active gcloud configuration)"),
+          option(:service_account_key_file, "Path to a service account key JSON used to authenticate gcloud",
+                 verify_block: file_exists("service_account_key_file")),
+          option(:location, "Cloud location of the session", default_value: "global"),
+          option(:devices, "Device type IDs to run on, e.g. [\"shiba-34\"]. One job is created per device",
+                 type: Array, optional: false, verify_block: non_empty("devices")),
+          option(:test_apk, "Path to the instrumentation test APK (local or gs://)",
+                 optional: false, verify_block: input_exists("test_apk")),
+          option(:apps, "Application files (.apk, .aab, .apks) to install before the test, in order (local or gs://)",
+                 type: Array, verify_block: inputs_exist("apps")),
+          option(:bucket_name, "Cloud Storage bucket for inputs and results (defaults to PROJECT_ID-devicerun)"),
+          option(:test_runner_class, "Instrumentation test runner class (defaults to the one in the manifest)"),
+          option(:test_targets, "Test targets, e.g. [\"class com.example.FooTest\", \"notPackage com.example.slow\"]", type: Array),
+          option(:additional_test_options, "Key-value options passed to the instrumentation runner", type: Hash),
+          option(:other_files_to_push, "Files to push to the device before the test, as { source => destination }", type: Hash),
+          option(:paths_to_pull, "Device paths to pull after the test", type: Array),
+          option(:instrumentation_timeout, "Maximum duration of the test run, 1m to 3h (default 5m)"),
+          option(:orchestrator_version, "Android Test Orchestrator version, or 'auto' (unset means no orchestrator)"),
+          option(:labels, "Key-value labels attached to the session", type: Hash)
+        ]
+      end
+
+      def device_options
+        [
+          option(:locale, "Device locale in language-region form, e.g. ja-JP"),
+          enum_option(:orientation, "Device orientation", ORIENTATIONS),
+          option(:coordinates, "Mock GPS location as latitude,longitude"),
+          enum_option(:video, "When to record a video of the screen", COLLECTION_MODES),
+          enum_option(:dumpsys, "When to collect dumpsys output", COLLECTION_MODES),
+          enum_option(:bugreport, "When to collect a bugreport", COLLECTION_MODES)
+        ]
+      end
+
+      def sharding_options
+        [
+          enum_option(:sharding_option, "Sharding strategy", SHARDING_OPTIONS),
+          option(:uniform_sharding_count, "Number of uniform shards (required with sharding_option 'uniform')", type: Integer),
+          option(:smart_sharding_target_duration, "Target duration per shard, 2m to 1h (required with sharding_option 'smart')"),
+          option(:smart_sharding_record_name, "Timing record name without extension (required with sharding_option 'smart')"),
+          option(:smart_sharding_max_shard_count, "Maximum number of smart shards (0 uses the system limit)", type: Integer)
+        ]
+      end
+
+      def retry_options
+        [
+          option(:flaky_test_attempts, "Maximum execution attempts per shard (default 1)", type: Integer),
+          option(:flaky_test_parallel_retry, "Retry failures in parallel instead of sequentially", type: Boolean),
+          enum_option(:flaky_test_retry_level, "Retry at the shard or the test level", RETRY_LEVELS)
+        ]
+      end
+
+      def behaviour_options
+        [
+          option(:async, "Return the session id right after submission instead of waiting", type: Boolean, default_value: false),
+          option(:download_dir, "Local directory to download the session artifacts into"),
+          option(:fail_on_failure, "Fail the lane when the session result is not PASSED", type: Boolean, default_value: true)
+        ]
+      end
+
+      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}",
+          description: description,
+          type: type,
+          optional: optional,
+          default_value: default_value,
+          verify_block: verify_block
+        )
+      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)
+        end)
+      end
+
+      def non_empty(name)
+        proc { |value| UI.user_error!("#{name} must contain at least one entry") if value.empty? }
+      end
+
+      def file_exists(name)
+        proc { |path| UI.user_error!("Could not find #{name} at path '#{path}'") unless File.exist?(path) }
+      end
+
+      def input_exists(name)
+        proc { |path| UI.user_error!("Could not find #{name} at path '#{path}'") unless remote?(path) || File.exist?(path) }
+      end
+
+      def inputs_exist(name)
+        proc { |paths| paths.each { |path| input_exists(name).call(path) } }
+      end
+
+      def remote?(path)
+        path.start_with?("gs://")
+      end
+    end
+  end
+end

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

@@ -0,0 +1,111 @@
+require 'json'
+
+module Fastlane
+  module DeveloperDevicePlatform
+    class Session
+      class ParseError < StandardError; end
+
+      CONSOLE_STORAGE_BROWSER = "https://console.cloud.google.com/storage/browser/".freeze
+
+      module Outcome
+        def done?
+          status == "DONE"
+        end
+
+        def passed?
+          result == "PASSED"
+        end
+      end
+
+      Execution = Struct.new(:display_name, :status, :result, :message, :output_files, keyword_init: true) do
+        include Outcome
+      end
+
+      Job = Struct.new(:display_name, :status, :result, :message, :output_files, :executions, keyword_init: true) do
+        include Outcome
+      end
+
+      def self.parse(json)
+        new(JSON.parse(json))
+      rescue JSON::ParserError => e
+        raise ParseError, "Could not parse session JSON: #{e.message}"
+      end
+
+      def initialize(attributes)
+        @attributes = attributes
+      end
+
+      def name
+        @attributes["name"]
+      end
+
+      def id
+        name&.split("/")&.last || report["id"]
+      end
+
+      def status
+        report.dig("status", "statusType")
+      end
+
+      def done?
+        status == "DONE"
+      end
+
+      def result
+        report.dig("result", "resultType")
+      end
+
+      def passed?
+        result == "PASSED"
+      end
+
+      def result_message
+        report.dig("result", "cause", "summary", "message")
+      end
+
+      def output_directory
+        base = @attributes.dig("sessionConfig", "outputDirectoryConfig", "gcsOutputDirectory", "path")
+        return nil if base.nil? || id.nil?
+
+        "#{base.chomp('/')}/#{id}"
+      end
+
+      def console_url
+        directory = output_directory
+        return nil if directory.nil?
+
+        "#{CONSOLE_STORAGE_BROWSER}#{directory.delete_prefix('gs://')}/"
+      end
+
+      def jobs
+        Array(report["jobReports"]).map do |job|
+          Job.new(**report_fields(job), executions: executions_of(job))
+        end
+      end
+
+      def output_files
+        jobs.flat_map { |job| job.output_files + job.executions.flat_map(&:output_files) }
+      end
+
+      private
+
+      def report
+        @attributes["sessionReport"] || {}
+      end
+
+      def executions_of(job)
+        Array(job["executionReports"]).map { |execution| Execution.new(**report_fields(execution)) }
+      end
+
+      def report_fields(node)
+        {
+          display_name: node["displayName"],
+          status: node.dig("status", "statusType"),
+          result: node.dig("result", "resultType"),
+          message: node.dig("result", "cause", "summary", "message") || Array(node.dig("status", "progressMessages")).last,
+          output_files: Array(node["outputFiles"]).filter_map { |file| file.dig("gcsOutputFile", "path") }
+        }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+require 'terminal-table'
+require_relative 'session'
+
+module Fastlane
+  module DeveloperDevicePlatform
+    class SessionSummary
+      HEADINGS = ["JOB", "EXECUTION", "RESULT"].freeze
+
+      attr_reader :session
+
+      def initialize(session)
+        @session = session
+      end
+
+      def rows
+        session.jobs.flat_map do |job|
+          if job.executions.empty?
+            [[job.display_name, "", describe(job)]]
+          else
+            job.executions.map { |execution| [job.display_name, execution.display_name, describe(execution)] }
+          end
+        end
+      end
+
+      def to_s
+        lines = [headline, session.result_message]
+        lines << Terminal::Table.new(headings: HEADINGS, rows: rows).to_s unless rows.empty?
+        lines << "Result files: #{session.console_url}" if session.console_url
+        lines.compact.join("\n")
+      end
+
+      private
+
+      def headline
+        if session.done?
+          "Session #{session.id} finished with result #{session.result}"
+        else
+          "Session #{session.id} is #{session.status}"
+        end
+      end
+
+      def describe(report)
+        return report.result if report.passed?
+
+        [report.result, report.message].compact.join(": ")
+      end
+    end
+  end
+end

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

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

data/lib/fastlane/plugin/developer_device_platform.rb

@@ -0,0 +1,13 @@
+require 'fastlane/plugin/developer_device_platform/version'
+
+module Fastlane
+  module DeveloperDevicePlatform
+    def self.all_classes
+      Dir[File.expand_path('**/{actions,helper}/*.rb', File.dirname(__FILE__))]
+    end
+  end
+end
+
+Fastlane::DeveloperDevicePlatform.all_classes.each do |current|
+  require current
+end

metadata

@@ -0,0 +1,221 @@
+--- !ruby/object:Gem::Specification
+name: fastlane-plugin-developer_device_platform
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- ntsk
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-10-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.4.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 5.0.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.4.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 5.0.0
+- !ruby/object:Gem::Dependency
+  name: fastlane
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.239.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.239.0
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: rspec_junit_formatter
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1.51'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1.51'
+- !ruby/object:Gem::Dependency
+  name: rubocop-ast
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.38.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.38.0
+- !ruby/object:Gem::Dependency
+  name: rubocop-performance
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.17'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.17'
+- !ruby/object:Gem::Dependency
+  name: rubocop-require_tools
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+description:
+email: contact@ntsk.jp
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/fastlane/plugin/developer_device_platform.rb
+- lib/fastlane/plugin/developer_device_platform/actions/developer_device_platform_action.rb
+- lib/fastlane/plugin/developer_device_platform/helper/device_run_client.rb
+- lib/fastlane/plugin/developer_device_platform/helper/gcloud.rb
+- lib/fastlane/plugin/developer_device_platform/helper/instrumentation_command.rb
+- lib/fastlane/plugin/developer_device_platform/helper/options.rb
+- lib/fastlane/plugin/developer_device_platform/helper/session.rb
+- lib/fastlane/plugin/developer_device_platform/helper/session_summary.rb
+- lib/fastlane/plugin/developer_device_platform/version.rb
+homepage: https://github.com/ntsk/fastlane-plugin-developer_device_platform
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Run Android instrumentation tests on Google Cloud Developer Device Platform
+  (Device Run)
+test_files: []