testingbot 0.2.3 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 104c19c8464d4b3a2da5ca401c9435206893b9abcc9d633f8e06962573458ce3
-  data.tar.gz: 48f5415943bdbf9c89f4c386a5e74f1cefcba46f460108a9b9b9dbfc0be91c32
+  metadata.gz: 6582442d3ad5452bd9740e41449fd19553b7ac5fc6599b88ef4b5cd99a91f499
+  data.tar.gz: b7c0cff6163ce11322cfa5cb0d9f79c088f8136041a39bdd5e0ecddaa886e46b
 SHA512:
-  metadata.gz: af4c1c842c83a7321dfdf4278776f075d4241c810f73d99aff3368fa79c1b1ef58a07ac94b95cfdacafa62c273496262f545e2f7242f171077295d5cb966bf60
-  data.tar.gz: c1057b5b46786c4d4ba466e3324f9ba232d754811d813cbb6c3f61d511c3c3769c11b0cd81858565103b0436f6a8e114c5a6647bd3cbd64868228c8f9ef29429
+  metadata.gz: e2b457288bc301b01cc682c32a320301e3032f120034cca1d3dbcd267b22aa97cd872f199f4cc2c730996de0ee23d6bd524325bde1d3e1983f087369f6ae4fd7
+  data.tar.gz: 38813eb285af2892fafbf043e27c52055ed961ee8b135a8bb810ee7a3de722aafcec1c02323a403e9c4a81a900649d9e83fd52c4390fe526f5f55405da905502

data/.github/workflows/release.yml

@@ -0,0 +1,49 @@
+name: Release
+
+# Publishes the gem to RubyGems when a GitHub Release is published.
+# Uses RubyGems Trusted Publishing (OIDC) — no API key is stored in the repo.
+#
+# This builds and pushes the gem directly (no `rake release` / git tagging),
+# because the GitHub Release already created the tag.
+#
+# One-time setup on rubygems.org (Gem → Ownership/Trusted Publishers, or a
+# "pending" trusted publisher before the first push):
+#   - Repository:        testingbot/testingbot_ruby
+#   - Workflow filename:  release.yml
+#   - Environment:        leave blank
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  release:
+    name: Build and publish gem
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write  # request the OIDC token for Trusted Publishing
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true
+
+      - name: Unit tests (gate)
+        run: bundle exec rake unit
+
+      - name: Configure RubyGems trusted publishing (OIDC)
+        uses: rubygems/configure-rubygems-credentials@v2.0.0
+
+      - name: Build gem
+        run: gem build testingbot.gemspec
+
+      - name: Push to RubyGems
+        run: gem push testingbot-*.gem

data/.github/workflows/test.yml

@@ -1,25 +1,40 @@
 name: Test Changes
 
-on: [push, pull_request]
+on: [push, pull_request, workflow_dispatch]
 
 jobs:
-  test:
+  # Offline, mocked unit suite. Runs on every push/PR (incl. forks) with no
+  # credentials and gates the build.
+  unit:
     runs-on: ubuntu-latest
     strategy:
+      fail-fast: false
       matrix:
-        ruby: ['2.2', '2.5', '2.6', '2.7', '3.0', '3.1', head, jruby, jruby-head, truffleruby, truffleruby-head]
-    name: Ruby ${{ matrix.ruby }} test
+        ruby: ['2.7', '3.0', '3.1', '3.2', '3.3', head, jruby, truffleruby]
+    name: Ruby ${{ matrix.ruby }} unit
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: ${{ matrix.ruby }}
           bundler-cache: true
-      - name: Build and test
-        run: |
-          sudo apt-get -yqq install libpq-dev
-          bundle exec rake spec
+      - name: Unit tests (mocked, offline)
+        run: bundle exec rake unit
+
+  # Live integration suite. Runs only on demand or on a schedule, where the
+  # TB_KEY / TB_SECRET secrets are available (not exposed to fork PRs).
+  integration:
+    if: ${{ github.event_name == 'workflow_dispatch' || github.event_name == 'schedule' }}
+    runs-on: ubuntu-latest
+    name: Live integration
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true
+      - name: Integration tests (live API)
+        run: bundle exec rake integration
         env:
           TB_KEY: ${{ secrets.TB_KEY }}
           TB_SECRET: ${{ secrets.TB_SECRET }}
-

data/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+## 1.0.0
+
+### Breaking changes
+
+- **Errors are now wrapped in a `TestingBot::Error` hierarchy.** Methods previously
+  leaked raw `RestClient` exceptions (`RestClient::Unauthorized`, `RestClient::NotFound`,
+  …) and raised a bare `String` for in-body API errors. They now raise
+  `TestingBot::AuthenticationError`, `TestingBot::NotFoundError`,
+  `TestingBot::RateLimitError`, `TestingBot::ClientError`, `TestingBot::ServerError`,
+  `TestingBot::ApiError`, `TestingBot::ParseError` or `TestingBot::ConnectionError`
+  (all subclasses of `TestingBot::Error`, carrying `#http_status` and `#body`).
+  Update any `rescue RestClient::...` clauses accordingly.
+- The gem module is now consistently `TestingBot` (was split between `TestingBot` and
+  `Testingbot`). `TestingBot::VERSION` holds the gem version.
+
+### Fixed
+
+- `get_authentication_hash` no longer raises `NameError` — `digest` is now required.
+- `~/.testingbot` credentials are split on the first `:` only, so secrets containing a
+  colon are no longer truncated.
+- Path segments (IDs, session IDs, …) are URL-encoded; `upload_remote_file` and
+  `create_user_in_team` no longer post to trailing-slash paths.
+- `upload_local_file` no longer leaks a file descriptor and shares the versioned URL and
+  error handling with the other requests.
+- `update_*` / `delete_*` / `stop_test` return a real boolean instead of `nil` when the
+  response omits a `success` key.
+
+### Added — reliability
+
+- Configurable open/read timeouts on every request (defaults 10s / 30s).
+- Automatic retries with exponential backoff + jitter for idempotent requests on
+  transient failures (timeouts, 5xx) and 429 (honoring `Retry-After`). POSTs are not
+  auto-retried.
+- Non-JSON and empty response bodies are handled gracefully.
+- Debug output redacts secret-bearing fields.
+
+### Added — API coverage (parity with the Java SDK)
+
+- `get_job`
+- `get_tunnel`, and a no-argument `delete_tunnel`
+- `get_device`, server-side filtering on `get_devices`, `get_ip_ranges`
+- `get_user_keys`, `get_user_client_key`
+- optional filters on `get_tests`
+- Full Codeless **Lab tests** surface (`get_lab_tests`, `create_lab_test`, `get_lab_test`,
+  `update_lab_test`, `delete_lab_test`, steps, browsers, alert, report, schedule, trigger,
+  stop, `trigger_all_lab_tests`)
+- Full Codeless **Lab suites** surface (`get_lab_suites`, `create_lab_suite`,
+  `get_lab_suite`, `delete_lab_suite`, tests, browsers, trigger)
+- `update_local_file` / `update_remote_file` (replace a stored app binary)
+
+### Changed — internals & tooling
+
+- Transport extracted into `TestingBot::Connection` (a single `request` method,
+  dependency-injectable for testing) behind the unchanged `TestingBot::Api` surface.
+- New offline, mocked unit suite (WebMock) under `spec/unit`; the live suite under
+  `spec/integration` is tagged `:integration` and runs only with credentials.
+  `rake unit` is the default and CI gate; `rake integration` runs the live suite.
+- `bin/testingbot` validates input, reads the secret without echoing it, and writes the
+  credentials file with `0600` permissions.

data/README.md

@@ -3,7 +3,7 @@
 
 # Testingbot-Ruby
 
-This is the TestingBot Ruby client which makes it easy to 
+This is the TestingBot Ruby client which makes it easy to
 interact with the [TestingBot API](https://testingbot.com/support/api)
 
 ## Installation
@@ -23,68 +23,137 @@ Or install it yourself as:
 
 ## Configuration
 
-You'll need a [TestingBot account](https://testingbot.com).  TestingBot offers free trials.
+You'll need a [TestingBot account](https://testingbot.com). TestingBot offers free trials.
+Once you have an account, retrieve your unique TestingBot Key and Secret from the
+[TestingBot dashboard](https://testingbot.com/members).
 
-## Setup
+```ruby
+@api = TestingBot::Api.new(key, secret)
+```
 
-Once you have a TestingBot account, you can retrieve your unique TestingBot Key and Secret from the [TestingBot dashboard](https://testingbot.com/members)
+### Credential resolution
 
-## Usage
+If you do not pass a key/secret explicitly, the client resolves them in this order
+(the first source that provides both wins):
 
-```ruby
-@api = TestingBot::Api.new(key, secret)
+1. Arguments passed to `TestingBot::Api.new(key, secret)`
+2. The `~/.testingbot` file — a single line in the form `key:secret`
+3. The `TESTINGBOT_KEY` / `TESTINGBOT_SECRET` environment variables
+4. The `TB_KEY` / `TB_SECRET` environment variables
+
+```bash
+# environment variable style
+export TB_KEY=your-testingbot-key
+export TB_SECRET=your-testingbot-secret
 ```
 
-#### Environment variables
-You can set these environment variables to authenticate with our API:
+You can generate the `~/.testingbot` file interactively with the bundled CLI:
 
 ```bash
-TB_KEY=Your TestingBot Key
-TB_SECRET=Your TestingBot Secret
+$ testingbot
 ```
 
-### get_browsers
-Gets a list of browsers you can test on
+The file is created with `0600` permissions; the client warns if it finds the file
+readable by other users.
+
+### Options
+
+`TestingBot::Api.new` accepts an options hash as a third argument:
 
 ```ruby
-@api.get_browsers
+@api = TestingBot::Api.new(key, secret,
+  debug:        true,  # log (redacted) responses to STDERR
+  open_timeout: 10,    # seconds to wait for the connection (default 10)
+  read_timeout: 30,    # seconds to wait for the response   (default 30)
+  max_retries:  3      # retry budget for idempotent requests (default 3)
+)
 ```
 
-### get_devices
-Gets a list of (physical) devices you can test on
+Idempotent requests (GET/PUT/DELETE) are retried with exponential backoff on transient
+failures (timeouts, 5xx, and 429 — honoring `Retry-After`). POST requests are never
+retried automatically, to avoid duplicating side effects.
+
+### Error handling
+
+All failures raise a subclass of `TestingBot::Error`, which carries `#http_status` and
+`#body`:
+
+| Exception | Raised when |
+|-----------|-------------|
+| `TestingBot::AuthenticationError` | 401 / 403 (bad credentials or insufficient permissions) |
+| `TestingBot::NotFoundError`       | 404 |
+| `TestingBot::RateLimitError`      | 429 (exposes `#retry_after`) |
+| `TestingBot::ClientError`         | other 4xx |
+| `TestingBot::ServerError`         | 5xx |
+| `TestingBot::ApiError`            | a 200 response whose body contains an `error` field |
+| `TestingBot::ParseError`          | a non-JSON / unparseable response body |
+| `TestingBot::ConnectionError`     | network failure or timeout |
 
 ```ruby
-@api.get_devices
+begin
+  @api.get_test(session_id)
+rescue TestingBot::NotFoundError
+  # ...
+rescue TestingBot::Error => e
+  warn "TestingBot API error (#{e.http_status}): #{e.message}"
+end
 ```
 
-### get_available_devices
-Gets a list of available (physical) devices you can test on
+Most methods return the parsed JSON response (a `Hash` or `Array`). The mutating helpers
+`update_user_info`, `update_test`, `delete_test`, `stop_test` and `delete_uploaded_file`
+return a `Boolean` indicating success.
+
+## Usage
+
+### get_user_info
+Gets your user information.
 
 ```ruby
-@api.get_available_devices
+@api.get_user_info
+```
+
+### update_user_info
+Updates your user information. Returns `true`/`false`.
+
+```ruby
+@api.update_user_info({ "first_name" => 'my name' })
+```
+
+### get_user_keys
+Retrieves the API key/secret pair for the current account.
+
+```ruby
+@api.get_user_keys
 ```
 
 ### get_team
-Gets info about the current team you belong to
+Gets info about the current team you belong to.
 
 ```ruby
 @api.get_team
 ```
 
 ### get_users_in_team
-Gets all users in your team
+Gets all users in your team.
 
 ```ruby
 @api.get_users_in_team(offset = 0, count = 10)
 ```
 
 ### get_user_in_team
-Get info about a specific user in your team
+Get info about a specific user in your team.
 
 ```ruby
 @api.get_user_in_team(user_id)
 ```
 
+### get_user_client_key
+Gets a specific team member's API client key. Requires ADMIN rights.
+
+```ruby
+@api.get_user_client_key(user_id)
+```
+
 ### create_user_in_team
 Add a user to your current team. You need to have ADMIN rights to do this.
 
@@ -100,104 +169,134 @@ Updates a specific user in your team.
 ```
 
 ### reset_credentials
-Resets the credentials for a specific user
+Resets the credentials for a specific user.
 
 ```ruby
 @api.reset_credentials(user_id)
 ```
 
-### take_screenshots
-Take screenshots for a specific URL on specific browsers
+### get_browsers
+Gets a list of browsers you can test on.
 
 ```ruby
-@api.take_screenshots(configuration)
+@api.get_browsers
 ```
 
-### get_screenshots_history
-Retrieve screenshots that were previously generated
+### get_devices
+Gets a list of (physical) devices you can test on. Optionally filter by platform and/or web capability.
 
 ```ruby
-@api.get_screenshots_history(offset = 0, count = 10)
+@api.get_devices
+@api.get_devices("android", true)
 ```
 
-### get_screenshots
-Get screenshots from a specific id
+### get_available_devices
+Gets a list of available (physical) devices you can test on.
 
 ```ruby
-@api.get_screenshots(screenshots_id)
+@api.get_available_devices
 ```
 
-### get_user_info
-Gets your user information
+### get_device
+Gets a single physical device by its numeric ID.
 
 ```ruby
-@api.get_user_info
+@api.get_device(device_id)
 ```
 
-### update_user_info
-Updates your user information
+### get_ip_ranges
+Gets the IP ranges TestingBot tests originate from (useful for firewall allow-listing).
 
 ```ruby
-@api.update_user_info({ "first_name" => 'my name' })
+@api.get_ip_ranges
 ```
 
-### update_test
-Updates a Test with Meta-data to display on TestingBot.
-For example, you can specify the test name and whether the test succeeded or failed:
+### take_screenshots
+Take screenshots for a specific URL on specific browsers.
 
 ```ruby
-@api.update_test(webdriver_session_id, { :name => new_name, :success => true })
+@api.take_screenshots(configuration)
 ```
 
-### get_test
-Gets meta information for a test/job by passing in the WebDriver sessionID of the test you ran on TestingBot:
+### get_screenshots_history
+Retrieve screenshots that were previously generated.
 
 ```ruby
-@api.get_test(webdriver_session_id)
+@api.get_screenshots_history(offset = 0, count = 10)
+```
+
+### get_screenshots
+Get screenshots from a specific id.
+
+```ruby
+@api.get_screenshots(screenshots_id)
 ```
 
 ### get_tests
-Gets a list of previous jobs/tests that you ran on TestingBot, order by last run:
+Gets a list of previous jobs/tests that you ran on TestingBot, ordered by last run.
+The optional `filters` hash accepts the API's `since`, `browser_id`, `group`, `build` and `skip_fields` params.
 
 ```ruby
 @api.get_tests(0, 10)
+@api.get_tests(0, 10, build: "my-build")
+```
+
+### get_test
+Gets meta information for a test/job by passing in the WebDriver sessionID of the test you ran on TestingBot.
+
+```ruby
+@api.get_test(webdriver_session_id)
+```
+
+### update_test
+Updates a Test with meta-data to display on TestingBot (e.g. name and pass/fail). Returns `true`/`false`.
+
+```ruby
+@api.update_test(webdriver_session_id, { :name => new_name, :success => true })
 ```
 
 ### delete_test
-Deletes a test from TestingBot
+Deletes a test from TestingBot. Returns `true`/`false`.
 
 ```ruby
 @api.delete_test(webdriver_session_id)
 ```
 
 ### stop_test
-Stops a running test on TestingBot
+Stops a running test on TestingBot. Returns `true`/`false`.
 
 ```ruby
 @api.stop_test(webdriver_session_id)
 ```
 
 ### get_builds
-Gets a list of builds that you ran on TestingBot, order by last run:
+Gets a list of builds that you ran on TestingBot, ordered by last run.
 
 ```ruby
 @api.get_builds(0, 10)
 ```
 
 ### get_build
-Gets a build from TestingBot
+Gets a build from TestingBot.
 
 ```ruby
 @api.get_build(build_identifier)
 ```
 
 ### delete_build
-Deletes a build from TestingBot
+Deletes a build from TestingBot.
 
 ```ruby
 @api.delete_build(build_identifier)
 ```
 
+### get_job
+Polls the status/result of an asynchronous job (e.g. a Codeless Lab run started by a trigger endpoint).
+
+```ruby
+@api.get_job(job_id)
+```
+
 ### get_tunnels
 Gets a list of active tunnels for your account.
 
@@ -205,15 +304,25 @@ Gets a list of active tunnels for your account.
 @api.get_tunnels
 ```
 
+### get_tunnel
+Gets the active tunnel, or a specific tunnel by ID.
+
+```ruby
+@api.get_tunnel
+@api.get_tunnel(tunnel_id)
+```
+
 ### delete_tunnel
-Deletes an active tunnel.
+Deletes a tunnel by ID, or the active tunnel when called without an argument.
 
 ```ruby
 @api.delete_tunnel(tunnel_identifier)
+@api.delete_tunnel
 ```
 
 ### upload_local_file
 Uploads a local file (APK or IPA file) to TestingBot Storage for Mobile App Testing.
+This request uses a 600-second timeout to accommodate large uploads.
 
 ```ruby
 @api.upload_local_file(localFilePath)
@@ -226,11 +335,19 @@ Uploads a remote file (APK or IPA URL) to TestingBot Storage for Mobile App Test
 @api.upload_remote_file(remoteFileUrl)
 ```
 
+### update_local_file / update_remote_file
+Replaces the binary stored under an existing app key.
+
+```ruby
+@api.update_local_file(app_url, localFilePath)
+@api.update_remote_file(app_url, remoteFileUrl)
+```
+
 ### get_uploaded_files
-Retrieves files previously uploaded TestingBot Storage for Mobile App Testing.
+Retrieves files previously uploaded to TestingBot Storage for Mobile App Testing.
 
 ```ruby
-@api.get_uploaded_files(offset = 0, count = 30)
+@api.get_uploaded_files(offset = 0, count = 10)
 ```
 
 ### get_uploaded_file
@@ -241,26 +358,65 @@ Retrieves meta-data for a file previously uploaded to TestingBot Storage.
 ```
 
 ### delete_uploaded_file
-Deletes a previously uploaded file
+Deletes a previously uploaded file. Returns `true`/`false`.
 
 ```ruby
-@api.delete_uploaded_file(remoteFileUrl)
+@api.delete_uploaded_file(app_url)
 ```
 
-### upload_remote_file
-Uploads a remote file (APK or IPA URL) to TestingBot Storage for Mobile App Testing.
+### Codeless Lab tests
 
 ```ruby
-@api.upload_remote_file(remoteFileUrl)
+@api.get_lab_tests(offset = 0, count = 10)
+@api.create_lab_test(params = {})
+@api.get_lab_test(lab_test_id)
+@api.update_lab_test(lab_test_id, params = {})
+@api.delete_lab_test(lab_test_id)
+@api.get_lab_test_steps(lab_test_id)
+@api.set_lab_test_steps(lab_test_id, params = {})
+@api.get_lab_test_browsers(lab_test_id)
+@api.set_lab_test_browsers(lab_test_id, params = {})
+@api.add_lab_test_alert(lab_test_id, params = {})
+@api.update_lab_test_alert(lab_test_id, params = {})
+@api.create_lab_test_report(lab_test_id, params = {})
+@api.update_lab_test_report(lab_test_id, params = {})
+@api.schedule_lab_test(lab_test_id, params = {})
+@api.trigger_lab_test(lab_test_id, params = {})
+@api.stop_lab_test(lab_test_id)
+@api.trigger_all_lab_tests(params = {})
+```
+
+### Codeless Lab suites
+
+```ruby
+@api.get_lab_suites(offset = 0, count = 10)
+@api.create_lab_suite(params = {})
+@api.get_lab_suite(suite_id)
+@api.delete_lab_suite(suite_id)
+@api.get_lab_suite_tests(suite_id)
+@api.add_lab_suite_tests(suite_id, params = {})
+@api.remove_lab_suite_test(suite_id, test_id)
+@api.get_lab_suite_browsers(suite_id)
+@api.set_lab_suite_browsers(suite_id, params = {})
+@api.trigger_lab_suite(suite_id, params = {})
 ```
 
 ### get_authentication_hash
-Calculates the hash necessary to share tests with other people
+Calculates the hash necessary to share private tests/builds with other people.
+Returns `MD5("#{key}:#{secret}:#{identifier}")`.
 
 ```ruby
 @api.get_authentication_hash(identifier)
 ```
 
+## Development
+
+```bash
+bundle install
+bundle exec rake unit         # offline, mocked unit suite (no credentials required)
+bundle exec rake integration  # live suite, requires TB_KEY / TB_SECRET
+```
+
 ## Contributing
 
 1. Fork this repository
@@ -268,4 +424,3 @@ Calculates the hash necessary to share tests with other people
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create new Pull Request
-

data/Rakefile

@@ -1,16 +1,17 @@
 require "bundler/gem_tasks"
-require 'rake'
-require 'rake/testtask'
+require "rspec/core/rake_task"
 
-task :spec do
-  begin
-    require 'rspec/core/rake_task'
-    desc "Run the specs under spec/"
-    RSpec::Core::RakeTask.new do |t|
-    	t.fail_on_error = false
-	    t.pattern = FileList['spec/**/*_spec.rb'].exclude(/tunnel/)
-    end
-  rescue NameError, LoadError => e
-    puts e
-  end
-end
+# Offline, mocked unit suite — the default and CI gate. Needs no credentials.
+RSpec::Core::RakeTask.new(:unit) do |t|
+  t.pattern = "spec/unit/**/*_spec.rb"
+end
+
+# Live integration suite — hits the real API; requires TB_KEY / TB_SECRET.
+RSpec::Core::RakeTask.new(:integration) do |t|
+  t.pattern = "spec/integration/**/*_spec.rb"
+  t.rspec_opts = "--tag integration"
+end
+
+# `rake spec` and the default task run only the offline unit suite.
+task :spec => :unit
+task :default => :unit