Skip to content
Tutorials Center
My learning

Topics

Lesson 29 of 37 ยท Cloud Device Farms

Connecting to a Cloud Grid: URLs, Vendor Options and Secrets

Point Appium tests at a cloud device farm: remote hub URL, vendor option blocks, app upload, build and session names, secret handling and result reporting.

Moving a test from your laptop to a cloud farm changes surprisingly little. The Appium protocol is the same, so the test still creates a session, finds elements and quits. Three things differ: the URL the driver connects to, the capabilities that say which device you want, and the credentials that identify your account. Each vendor adds a block of its own options inside the capabilities, namespaced with a prefix such as bstack:options (BrowserStack), sauce:options (Sauce Labs) or lt:options (LambdaTest).

This lesson shows the general pattern, how to keep secrets and vendor details out of your tests, and how to report the pass or fail result back to the dashboard. No vendor account is available here, so the Appium code is read-only. The URLs, option names and endpoints change; always confirm them in your vendor's current documentation. The runnable examples build and validate configuration objects, with invented credentials read from a fake environment.

The shape of a cloud session

Python
import os
from appium import webdriver
from appium.options.android import UiAutomator2Options

options = UiAutomator2Options()
options.platform_name = "Android"
options.set_capability("appium:app", os.environ["CLOUD_APP_URL"])      # an id returned by the app upload
options.set_capability("vendor:options", {                          # the vendor's namespace, e.g. bstack:options
    "userName": os.environ["CLOUD_USER"],
    "accessKey": os.environ["CLOUD_KEY"],
    "deviceName": "Samsung Galaxy S23",
    "osVersion": "14.0",
    "projectName": "Shop app",
    "buildName": os.environ.get("BUILD_NUMBER", "local"),
    "sessionName": "login tests",
})

driver = webdriver.Remote(os.environ["CLOUD_HUB_URL"], options=options)

Notice what is not hard-coded: the hub URL, the credentials and the app location come from the environment. A local run uses http://127.0.0.1:4723 and no vendor block; a cloud run sets the environment variables instead.

Some vendors accept credentials inside the URL (https://user:key@hub...); prefer the options block or headers if the vendor supports it, because URLs appear in logs.

App upload

A cloud device cannot read the APK on your laptop. You upload it first, usually with a REST call, and the vendor returns an identifier or URL that you pass as appium:app:

Terminal
curl -u "$CLOUD_USER:$CLOUD_KEY" -X POST "$CLOUD_UPLOAD_URL" -F "file=@app/build/outputs/apk/debug/app-debug.apk"

Do this step in CI, once per build, and pass the returned id to the tests. Some vendors let you give the upload a custom id (a name that always points to the latest upload), which is handy, but a unique id per commit is safer because it makes results reproducible.

Keep configuration out of tests

Create one small module that decides where tests run. Tests then import make_driver() and never mention vendors:

Python
# config.py
import os

def target():
    return os.environ.get("TARGET", "local")      # local | cloud

def make_driver():
    if target() == "cloud":
        return create_cloud_driver()
    return create_local_driver()

This is the same idea as the screen object (see The Page Object Model): hide what changes behind one function.

Stand-in: build a vendor-neutral config

The next example builds the capabilities for a local or cloud target from a fake environment, refuses to run without credentials, and masks secrets when printing. It is a sketch of the config.py idea, not a vendor client.

Python Config builder with masked secrets (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Naming sessions and builds

Cloud dashboards group sessions by project, build and session name. Fill them in so a failure can be found quickly: the build name is the CI build number or commit hash, the session name is the test name. Many teams set the session name from the test fixture, so each recording is labelled with its test.

Reporting the result

The vendor cannot know whether your assertions passed; the dashboard shows "completed" unless you tell it otherwise. Mark the status at the end of each test, typically with a vendor-specific command run through execute_script:

Python
# the exact command name and payload differ by vendor; check the docs
driver.execute_script('vendor: setSessionStatus', {"status": "failed", "reason": "total was wrong"})

Put this in the fixture teardown using the test result (see Test Data, Screenshots and Reports for the hook), so every test reports automatically.

Local testing through a tunnel

If the app talks to a staging server that is not on the public internet, the cloud device cannot reach it. Vendors provide a small tunnel program you run on your CI machine; it opens a secure connection and routes the device's traffic through it. Enable it with the vendor's capability (often named local or tunnelName), and close the tunnel at the end of the job.

Stand-in: pick the endpoint and timeouts

Python Choosing timeouts for remote sessions (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The latency numbers are illustrative, but the effect is real: every command is a network round trip, so cloud runs are slower per step. Reduce the number of commands (use deep links and API setup, avoid long find_elements loops) rather than raising timeouts forever.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What usually changes when a test moves from a local emulator to a cloud farm?

    The protocol is the same; you point to a different endpoint with vendor options and credentials.
  2. 2. Where should the cloud username and access key come from?

    Secrets stay out of source control and logs.
  3. 3. Why upload the app before the session?

    The cloud device needs the app stored on the vendor side; the upload returns an identifier.
  4. 4. Why must a test report its status to the dashboard?

    Assertions run in your test process, so you must tell the vendor the outcome.

Summary

  • Cloud sessions differ from local ones in URL, vendor options and credentials; the test logic stays the same.
  • Read endpoints and secrets from the environment, and keep them in one config module.
  • Upload the app in CI and pass the returned identifier as appium:app.
  • Name projects, builds and sessions, and report pass or fail from teardown.
  • Use a tunnel for private backends, and expect higher latency per command.

Next: Parallel Runs and the Device Matrix