fastlane-plugin-testingbot 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 69119bf112788b514fc5b4a0b2eb3c24505f1f5b30cd2017355843ad8a844b47
+  data.tar.gz: 581d283e00ca2e607bb31d816f57fce730ab15dde7c406c4bbff998c31f2af23
+SHA512:
+  metadata.gz: 89d617bbd6961baf8f8e82aa72502e7bd5ff2797c0ced4c53e196d4dd15f6bd14a31614f2b6bfc20195bc03f5e8c81a897b6c0e54e0025cfa48fc993f505476e
+  data.tar.gz: 19c19c0dc321c48939e2ba6342c4506e64b352127abd8c948df5a11190bf7e33594be57cfdc0f50884e69eff2362c70ac6dbb3056e10e13691532edf7a358f49

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TestingBot
+
+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,161 @@
+# fastlane-plugin-testingbot
+
+[![fastlane Plugin Badge](https://rawcdn.githack.com/fastlane/fastlane/master/fastlane/assets/plugin-badge.svg)](https://rubygems.org/gems/fastlane-plugin-testingbot)
+
+A [_fastlane_](https://fastlane.tools) plugin that uploads your mobile app builds to [TestingBot Storage](https://testingbot.com/support/api#upload),
+so they can be used for automated (App Automate) and manual (App Live) testing on TestingBot's real devices and emulators/simulators.
+
+## Getting Started
+
+Add the plugin to your project:
+
+```bash
+fastlane add_plugin testingbot
+```
+
+This adds the plugin to your `fastlane/Pluginfile` and installs it. Commit the updated `Gemfile`, `Gemfile.lock`, and `fastlane/Pluginfile`.
+
+## Credentials
+
+The plugin authenticates with your **TestingBot API Key** and **API Secret**, which you can find in your
+[TestingBot account](https://testingbot.com/members/user/edit). The recommended way to provide them is via environment variables,
+which the plugin picks up automatically:
+
+```bash
+export TESTINGBOT_KEY="your-api-key"
+export TESTINGBOT_SECRET="your-api-secret"
+```
+
+## Usage
+
+### Upload a local app file
+
+```ruby
+upload_to_testingbot(
+  file_path: "./app/build/outputs/apk/debug/app-debug.apk"
+)
+```
+
+`file_path` is optional — if omitted, the plugin uses the output of a preceding `gym` (iOS `IPA_OUTPUT_PATH`) or
+`gradle` (`GRADLE_APK_OUTPUT_PATH` / `GRADLE_AAB_OUTPUT_PATH`) action in the same lane:
+
+```ruby
+gradle(task: "assembleDebug")
+upload_to_testingbot # automatically uploads the freshly built APK
+```
+
+Supported formats: `.apk` and `.aab` (Android), `.ipa` (iOS real devices), and `.zip` (iOS simulator builds).
+
+### Upload from a remote URL
+
+Have TestingBot fetch the binary server-side instead of uploading bytes from the CI machine:
+
+```ruby
+upload_to_testingbot(
+  remote_url: "https://example.com/MyApp.ipa"
+)
+```
+
+### Replace a build in place (stable identifier)
+
+Pass an existing `app_url` to overwrite the binary while keeping the same `tb://` identifier — useful when your test
+configuration references a fixed id across CI runs:
+
+```ruby
+upload_to_testingbot(
+  file_path: "./MyApp.ipa",
+  app_url: "tb://abc123"
+)
+```
+
+## Output
+
+On success the action returns the `tb://<appkey>` app URL and exposes it for downstream lanes/processes:
+
+| Source | Value |
+|---|---|
+| return value | `tb://<appkey>` |
+| `lane_context[SharedValues::TESTINGBOT_APP_URL]` | `tb://<appkey>` |
+| `lane_context[SharedValues::TESTINGBOT_APP_KEY]` | `<appkey>` (scheme stripped) |
+| `lane_context[SharedValues::TESTINGBOT_STORAGE_RESPONSE]` | full parsed JSON response |
+| `ENV["TESTINGBOT_APP_URL"]` / `ENV["TESTINGBOT_APP_KEY"]` | same values, for external test processes |
+
+Use the `tb://` app URL as the Appium `appium:app` (legacy `app`) capability when starting your test session, e.g.:
+
+```ruby
+app = lane_context[SharedValues::TESTINGBOT_APP_URL]
+# capabilities["appium:app"] = app
+```
+
+> **Note:** Uploaded apps are automatically deleted by TestingBot after 62 days. For a long-lived, stable reference,
+> re-upload using the `app_url` (replace) option so the `tb://` identifier stays the same.
+
+## Action options
+
+| Option | Environment variable | Required | Description |
+|---|---|---|---|
+| `testingbot_key` | `TESTINGBOT_KEY` | yes | Your TestingBot API key |
+| `testingbot_secret` | `TESTINGBOT_SECRET` | yes | Your TestingBot API secret |
+| `file_path` | `TESTINGBOT_FILE_PATH` | no | Local app file to upload (auto-resolved from gym/gradle if omitted) |
+| `remote_url` | `TESTINGBOT_REMOTE_URL` | no | Remote URL for TestingBot to fetch (mutually exclusive with `file_path`) |
+| `app_url` | `TESTINGBOT_REPLACE_APP_URL` | no | Existing `tb://...` app to replace in place |
+
+Run `fastlane action upload_to_testingbot` to see this list from the command line.
+
+## Run tests for this plugin
+
+To run both the tests, and code style validation, run
+
+```bash
+bundle install
+bundle exec rake
+```
+
+## Releasing
+
+Releases are published to [RubyGems.org](https://rubygems.org/gems/fastlane-plugin-testingbot) automatically by the
+[`Publish gem`](.github/workflows/publish.yml) GitHub Action whenever a `v*` tag is pushed. It uses
+[RubyGems Trusted Publishing](https://guides.rubygems.org/trusted-publishing/) (OIDC), so **no API key secret is stored**
+— which is required because this gem sets `rubygems_mfa_required`.
+
+**One-time setup on RubyGems.org** (per gem):
+
+1. Sign in to RubyGems.org and open **Trusted Publishers** (under your profile, or the gem's settings once it exists).
+2. Add a new GitHub Actions trusted publisher with:
+   - **Repository owner / name:** `testingbot/testingbot-fastlane-plugin`
+   - **Workflow filename:** `publish.yml`
+   - **Environment:** `rubygems.org`
+   For a brand-new gem that isn't on RubyGems yet, create it as a *pending* trusted publisher.
+
+**To cut a release:**
+
+```bash
+# bump VERSION in lib/fastlane/plugin/testingbot/version.rb first
+git commit -am "Release v0.1.0"
+git tag v0.1.0
+git push origin main --tags
+```
+
+The workflow runs the test suite + RuboCop, then builds and pushes the gem.
+
+## Contributing
+
+Bug reports and pull requests are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) to get started, and note
+that this project follows a [Code of Conduct](CODE_OF_CONDUCT.md). For security issues, follow the private process in
+[SECURITY.md](SECURITY.md).
+
+## Issues and Feedback
+
+For any other issues and feedback about this plugin, please submit it to this repository.
+
+## Using _fastlane_ Plugins
+
+For more information about how the `fastlane` plugin system works, check out the [Plugins documentation](https://docs.fastlane.tools/plugins/create-plugin/).
+
+## About _fastlane_
+
+_fastlane_ is the easiest way to automate beta deployments and releases for your iOS and Android apps. To learn more, check out [fastlane.tools](https://fastlane.tools).
+
+## License
+
+MIT

data/lib/fastlane/plugin/testingbot/actions/upload_to_testingbot_action.rb

@@ -0,0 +1,197 @@
+require 'fastlane/action'
+require_relative '../helper/testingbot_helper'
+
+module Fastlane
+  module Actions
+    module SharedValues
+      TESTINGBOT_APP_URL ||= :TESTINGBOT_APP_URL
+      TESTINGBOT_APP_KEY ||= :TESTINGBOT_APP_KEY
+      TESTINGBOT_STORAGE_RESPONSE ||= :TESTINGBOT_STORAGE_RESPONSE
+    end
+
+    class UploadToTestingbotAction < Action
+      UPLOAD_API_PATH = '/v1/storage'.freeze
+      SUPPORTED_FILE_EXTENSIONS = %w[apk aab ipa zip].freeze
+
+      def self.run(params)
+        file_path, remote_url = resolve_source(params[:file_path], params[:remote_url])
+        validate_file_path!(file_path) if file_path
+
+        path = upload_path(params[:app_url])
+
+        UI.message("Uploading to TestingBot Storage #{file_path ? "(#{File.basename(file_path)})" : "from #{remote_url}"} ...")
+
+        response = Helper::TestingbotHelper.upload(
+          params[:testingbot_key],
+          params[:testingbot_secret],
+          path,
+          file_path: file_path,
+          remote_url: remote_url
+        )
+
+        publish_result(response)
+      end
+
+      # Decide what to upload, enforcing that exactly one source is used.
+      # An explicit remote_url takes precedence over the auto-resolved default file path.
+      def self.resolve_source(file_path, remote_url)
+        file_path = presence(file_path)
+        remote_url = presence(remote_url)
+
+        UI.user_error!('Provide either `file_path` or `remote_url`, not both.') if file_path && remote_url
+
+        file_path = presence(default_file_path) if file_path.nil? && remote_url.nil?
+
+        UI.user_error!('No app to upload. Provide `file_path` (a local .apk/.aab/.ipa/.zip) or `remote_url`.') if file_path.nil? && remote_url.nil?
+
+        [file_path, remote_url]
+      end
+
+      def self.publish_result(response)
+        app_url = response['app_url']
+        UI.user_error!("TestingBot did not return an app_url. Response: #{response}") if presence(app_url).nil?
+
+        app_key = strip_scheme(app_url)
+        Actions.lane_context[SharedValues::TESTINGBOT_APP_URL] = app_url
+        Actions.lane_context[SharedValues::TESTINGBOT_APP_KEY] = app_key
+        Actions.lane_context[SharedValues::TESTINGBOT_STORAGE_RESPONSE] = response
+        ENV['TESTINGBOT_APP_URL'] = app_url
+        ENV['TESTINGBOT_APP_KEY'] = app_key
+
+        UI.success("Successfully uploaded app to TestingBot: #{app_url}")
+        app_url
+      end
+
+      def self.upload_path(app_url)
+        return UPLOAD_API_PATH if presence(app_url).nil?
+
+        "#{UPLOAD_API_PATH}/#{strip_scheme(app_url)}"
+      end
+
+      # Strip only the leading "tb://" scheme, preserving any remaining path.
+      def self.strip_scheme(app_url)
+        app_url.to_s.sub(%r{\Atb://}, '')
+      end
+
+      # Resolve a sensible default app path from earlier build actions in the same lane.
+      def self.default_file_path
+        if Actions.lane_context[SharedValues::PLATFORM_NAME] == :ios
+          Actions.lane_context[SharedValues::IPA_OUTPUT_PATH]
+        else
+          Actions.lane_context[SharedValues::GRADLE_APK_OUTPUT_PATH] ||
+            Actions.lane_context[SharedValues::GRADLE_AAB_OUTPUT_PATH]
+        end
+      end
+
+      def self.validate_file_path!(file_path)
+        UI.user_error!("Couldn't find file at path '#{file_path}'") unless File.exist?(file_path)
+
+        extension = File.extname(file_path).delete('.').downcase
+        return if SUPPORTED_FILE_EXTENSIONS.include?(extension)
+
+        supported = SUPPORTED_FILE_EXTENSIONS.map { |ext| ".#{ext}" }.join(', ')
+        UI.user_error!("Unsupported file type '.#{extension}'. TestingBot supports: #{supported}")
+      end
+
+      def self.presence(value)
+        value.to_s.empty? ? nil : value
+      end
+
+      #####################################################
+      # @!group Documentation
+      #####################################################
+
+      def self.description
+        'Uploads an app (.apk/.aab/.ipa/.zip) to TestingBot Storage'
+      end
+
+      def self.details
+        [
+          'Uploads a local app file or a remote app URL to TestingBot Storage so it can be used in App Automate / App Live test runs.',
+          'On success the returned `tb://<appkey>` identifier is stored in the lane context (`SharedValues::TESTINGBOT_APP_URL`) and in `ENV`, ready to be used as the Appium `appium:app` capability.',
+          'Pass an existing `app_url` to replace the binary in place while keeping the same `tb://` identifier (handy for stable CI references).'
+        ].join("\n")
+      end
+
+      def self.authors
+        ['TestingBot']
+      end
+
+      def self.return_value
+        'The TestingBot app_url of the uploaded app (e.g. "tb://abc123"). Also exposed via lane_context[SharedValues::TESTINGBOT_APP_URL] and ENV["TESTINGBOT_APP_URL"].'
+      end
+
+      def self.available_options
+        [
+          FastlaneCore::ConfigItem.new(key: :testingbot_key,
+                                       env_name: 'TESTINGBOT_KEY',
+                                       description: 'Your TestingBot API key (find it at https://testingbot.com/members/user/edit)',
+                                       sensitive: true,
+                                       optional: false,
+                                       type: String,
+                                       verify_block: proc do |value|
+                                         UI.user_error!('No TestingBot API key given, pass using `testingbot_key:` or the TESTINGBOT_KEY environment variable') if value.to_s.empty?
+                                       end),
+          FastlaneCore::ConfigItem.new(key: :testingbot_secret,
+                                       env_name: 'TESTINGBOT_SECRET',
+                                       description: 'Your TestingBot API secret (find it at https://testingbot.com/members/user/edit)',
+                                       sensitive: true,
+                                       optional: false,
+                                       type: String,
+                                       verify_block: proc do |value|
+                                         UI.user_error!('No TestingBot API secret given, pass using `testingbot_secret:` or the TESTINGBOT_SECRET environment variable') if value.to_s.empty?
+                                       end),
+          FastlaneCore::ConfigItem.new(key: :file_path,
+                                       env_name: 'TESTINGBOT_FILE_PATH',
+                                       description: 'Path to the local app file (.apk, .aab, .ipa or .zip) to upload. Defaults to the output of a preceding gym/gradle build',
+                                       optional: true,
+                                       type: String),
+          FastlaneCore::ConfigItem.new(key: :remote_url,
+                                       env_name: 'TESTINGBOT_REMOTE_URL',
+                                       description: 'A publicly accessible URL to the app file; TestingBot downloads it server-side (mutually exclusive with file_path)',
+                                       optional: true,
+                                       type: String),
+          FastlaneCore::ConfigItem.new(key: :app_url,
+                                       env_name: 'TESTINGBOT_REPLACE_APP_URL',
+                                       description: 'An existing TestingBot app_url (tb://...) to replace in place, keeping the same identifier',
+                                       optional: true,
+                                       type: String)
+        ]
+      end
+
+      def self.output
+        [
+          ['TESTINGBOT_APP_URL', 'The tb:// app_url of the uploaded app'],
+          ['TESTINGBOT_APP_KEY', 'The app key (app_url without the tb:// scheme)'],
+          ['TESTINGBOT_STORAGE_RESPONSE', 'The full parsed JSON response from TestingBot Storage']
+        ]
+      end
+
+      def self.category
+        :testing
+      end
+
+      def self.example_code
+        [
+          'upload_to_testingbot(
+            testingbot_key: ENV["TESTINGBOT_KEY"],
+            testingbot_secret: ENV["TESTINGBOT_SECRET"],
+            file_path: "./app/build/outputs/apk/debug/app-debug.apk"
+          )',
+          'upload_to_testingbot(
+            remote_url: "https://example.com/MyApp.ipa"
+          )',
+          '# Replace an existing build in place (keeps the same tb:// identifier)
+          upload_to_testingbot(
+            file_path: "./MyApp.ipa",
+            app_url: "tb://abc123"
+          )'
+        ]
+      end
+
+      def self.is_supported?(platform)
+        %i[ios android mac].include?(platform)
+      end
+    end
+  end
+end

data/lib/fastlane/plugin/testingbot/helper/testingbot_helper.rb

@@ -0,0 +1,68 @@
+require 'fastlane_core/ui/ui'
+require 'rest-client'
+require 'json'
+
+module Fastlane
+  UI = FastlaneCore::UI unless Fastlane.const_defined?(:UI)
+
+  module Helper
+    class TestingbotHelper
+      API_BASE_URL = 'https://api.testingbot.com'.freeze
+
+      # App binaries can be large; mirror the official TestingBot Ruby client's generous read timeout.
+      UPLOAD_TIMEOUT = 600
+      OPEN_TIMEOUT = 30
+
+      # Uploads (or replaces) an app on TestingBot Storage.
+      #
+      # @param key [String] TestingBot API key (used as the HTTP Basic auth username)
+      # @param secret [String] TestingBot API secret (used as the HTTP Basic auth password)
+      # @param path [String] the request path, e.g. "/v1/storage" or "/v1/storage/<appkey>"
+      # @param file_path [String, nil] a local app file to upload via multipart/form-data
+      # @param remote_url [String, nil] a publicly reachable URL for TestingBot to fetch server-side
+      # @return [Hash] the parsed JSON response, e.g. {"app_url" => "tb://<appkey>"}
+      def self.upload(key, secret, path, file_path: nil, remote_url: nil)
+        file = file_path ? File.new(file_path, 'rb') : nil
+        payload = file ? { multipart: true, file: file } : { url: remote_url }
+
+        response = RestClient::Request.execute(
+          method: :post,
+          url: "#{API_BASE_URL}#{path}",
+          user: key,
+          password: secret,
+          payload: payload,
+          headers: { 'User-Agent' => "fastlane-plugin-testingbot/#{Fastlane::Testingbot::VERSION}" },
+          timeout: UPLOAD_TIMEOUT,
+          open_timeout: OPEN_TIMEOUT
+        )
+
+        parse_success(response)
+      rescue RestClient::ExceptionWithResponse => e
+        UI.user_error!("App upload to TestingBot failed: #{error_reason(e.response)}")
+      rescue StandardError => e
+        UI.user_error!("App upload to TestingBot failed: #{e.message}")
+      ensure
+        file&.close
+      end
+
+      def self.parse_success(response)
+        body = parse_json(response.body)
+        UI.user_error!('App upload to TestingBot failed: could not parse the server response') unless body.is_a?(Hash)
+
+        body
+      end
+
+      def self.error_reason(response)
+        body = response ? parse_json(response.body) : nil
+        message = body.is_a?(Hash) && (body['error'] || body['message'])
+        message || (response && "HTTP #{response.code}") || 'unknown error'
+      end
+
+      def self.parse_json(raw)
+        JSON.parse(raw.to_s)
+      rescue JSON::ParserError
+        nil
+      end
+    end
+  end
+end

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

@@ -0,0 +1,5 @@
+module Fastlane
+  module Testingbot
+    VERSION = '0.1.0'.freeze
+  end
+end

data/lib/fastlane/plugin/testingbot.rb

@@ -0,0 +1,16 @@
+require 'fastlane/plugin/testingbot/version'
+
+module Fastlane
+  module Testingbot
+    # Return all .rb files inside the "actions" and "helper" directory
+    def self.all_classes
+      Dir[File.expand_path('**/{actions,helper}/*.rb', File.dirname(__FILE__))]
+    end
+  end
+end
+
+# By default we want to import all available actions and helpers
+# A plugin can contain any number of actions and plugins
+Fastlane::Testingbot.all_classes.each do |current|
+  require current
+end

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification
+name: fastlane-plugin-testingbot
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- TestingBot
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-06-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rest-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.0.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.0.2
+description:
+email: info@testingbot.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/fastlane/plugin/testingbot.rb
+- lib/fastlane/plugin/testingbot/actions/upload_to_testingbot_action.rb
+- lib/fastlane/plugin/testingbot/helper/testingbot_helper.rb
+- lib/fastlane/plugin/testingbot/version.rb
+homepage: https://github.com/testingbot/testingbot-fastlane-plugin
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/testingbot/testingbot-fastlane-plugin
+  bug_tracker_uri: https://github.com/testingbot/testingbot-fastlane-plugin/issues
+  changelog_uri: https://github.com/testingbot/testingbot-fastlane-plugin/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.3
+signing_key:
+specification_version: 4
+summary: Uploads .apk/.aab/.ipa/.zip files to TestingBot Storage for mobile app testing
+test_files: []