fastlane-plugin-testingbot

A fastlane plugin that uploads your mobile app builds to TestingBot Storage, 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:

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. The recommended way to provide them is via environment variables, which the plugin picks up automatically:

export TESTINGBOT_KEY="your-api-key"
export TESTINGBOT_SECRET="your-api-secret"

Usage

Upload a local app file

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:

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:

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:

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.:

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

bundle install
bundle exec rake

Releasing

Releases are published to RubyGems.org automatically by the Publish gem GitHub Action whenever a v* tag is pushed. It uses RubyGems 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:

# 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 to get started, and note that this project follows a Code of Conduct. For security issues, follow the private process in 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.

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.

License

MIT