GienTech · Test Automation Enablement

Onboarding to the pCloudy Device Farm

What every team needs before their Playwright browser tests or Java Appium mobile tests will run on real cloud devices.

Orientation

What actually changes when you go remote

Your test code does not change. Only where the browser or device lives, and how the session is requested.

// local
chromium.launch()

// pCloudy Browser Cloud
chromium.connect(
  `wss://browser.device.pcloudy.com/playwright
   ?capabilities=${encoded}`)

// local
new AndroidDriver(
  "http://127.0.0.1:4723", opts)

// pCloudy Mobile Farm
new AndroidDriver(
  "https://device.pcloudy.com/appiumcloud/wd/hub",
  caps)

{
  "browserName": "chrome",
  "pcloudy:options": {
    "userName":       "you@gientech.com",
    "accessKey":      "<YOUR_ACCESS_KEY>",
    "os":             "Windows",
    "osVersion":      "11",
    "browserVersion": "118",
    "local":          false
  }
}

{
  "appium:platformName":            "Android",
  "appium:platformVersion":         "11.0.0",
  "appium:automationName":          "uiautomator2",
  "appium:appPackage":             "com.gientechmobilebanking",
  "appium:appActivity":            ".MainActivity",
  "appium:pCloudy_ApplicationName": "app-release.apk",
  "pcloudy:options": {
    "pCloudy_Username":         "you@gientech.com",             // $PCLOUDY_USERNAME
    "pCloudy_ApiKey":           "<YOUR_API_KEY>",  // $PCLOUDY_API_KEY
    "pCloudy_DeviceFullName":    "(picked from the pool — Samsung preferred)",
    "pCloudy_WildNet":          false,
    "pCloudy_EnableVideo":       true,
    "pCloudy_EnableDeviceLogs":  true,
    "appiumVersion":            "2.0.0"
  }
}

Prerequisites

Before you write a single line

Checklist

Access & connectivity — verify before blaming your code

• 1pCloudy access works. Sign in from a browser at https://device.pcloudy.com/.
• 2Network access. Allow *.pcloudy.com over HTTPS (443), plus WebSocket for Playwright.
• 3Entitlement for the product you need. Browser Cloud and mobile devices are licensed separately — an account can see one and not the other.
• 4API key generated and stored in .env, never in code.
• 5Auth test passes from your machine (next slide).
• 6App uploaded (mobile) or app URL reachable (browser).
• 7iOS: UDIDs in the provisioning profile and the IPA re-exported after any change.

Credentials

Getting the API key, and where it belongs

One page, both products — there is no separate key for browser and mobile:

https://device.pcloudy.com/pro/profile

The same two values authenticate the REST API, the Appium hub and the Playwright WebSocket endpoint. Regenerating the key on that page invalidates the old one everywhere at once.

PCLOUDY_USERNAME=you@gientech.com
PCLOUDY_API_KEY=your_key_here

PCLOUDY_USERNAME=you@gientech.com
PCLOUDY_API_KEY=your_key_here
PCLOUDY_WS_HOST=browser.device.pcloudy.com
PCLOUDY_BROWSER=chrome
PCLOUDY_OS=Windows
PCLOUDY_OS_VERSION=11
USE_PCLOUDY=true

Credentials

What the Profile page looks like

Admin → Profile. My Details holds the two values every framework needs; URL Information lists every regional endpoint plus the Browser Cloud URL.

Connectivity test

Prove the key works before anything else

Run these two calls before touching any test code. The first confirms your credentials and the network path; the second confirms your entitlement and returns the exact device names to put in your pool.

Raw API — works from any stack

$pair  = "$env:PCLOUDY_USERNAME:$env:PCLOUDY_API_KEY"
$basic = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes($pair))
Invoke-RestMethod https://device.pcloudy.com/api/access `
  -Headers @{ Authorization = "Basic $basic" }

Configuration · 🖥 Browser

Pointing Playwright at Browser Cloud

One connection object. The credentials travel inside the capabilities, URL-encoded onto the WebSocket endpoint.

// tests/pcloudy/config.js
// Browser Cloud host from Profile > URL Information, WITHOUT the https://
const PLAYWRIGHT_WS_HOST =
  process.env.PCLOUDY_WS_HOST || 'browser.device.pcloudy.com';

const capabilities = {
  browserName: selectedBrowser,              // chrome | edge | opera
  'pcloudy:options': {
    userName:       USERNAME,
    accessKey:      API_KEY,
    os:             OS,                      // Windows | Mac
    osVersion:      OS_VERSION,              // 10 | 11 | Ventura | Sonoma
    browserVersion: BROWSER_VERSION,
    local:          false,
  },
};

const PLAYWRIGHT_WS_ENDPOINT =
  `wss://${PLAYWRIGHT_WS_HOST}/playwright?capabilities=` +
  encodeURIComponent(JSON.stringify(capabilities));

// then, instead of chromium.launch():
const browser = await chromium.connect(PLAYWRIGHT_WS_ENDPOINT);

npm run pcloudy:chrome
npm run pcloudy:edge
npm run pcloudy:smoke

🖥 Per pCloudy documentation

The vendor's documented Playwright setup

From pcloudy.com/docs/playwright — worth following on a first connection, because it is what their support will assume you did.

Endpoint shape

# the docs show the pattern; the HOST comes from YOUR Profile page
wss://<your-browser-cloud-host>/playwright?capabilities=<url-encoded JSON>

# ours, from Profile > URL Information
wss://browser.device.pcloudy.com/playwright?capabilities=…

Configuration · 📱 Mobile

Pointing Java Appium at the device farm

pCloudy's capability shape is strict. The booking block is identical on both platforms; only the app-identity capabilities differ.

caps.setCapability("appium:platformName",   "Android");
caps.setCapability("appium:automationName", "uiautomator2");
caps.setCapability("appium:platformVersion","13.0.0");

// Android identifies an app by package + activity
caps.setCapability("appium:appPackage",  "com.gientechmobilebanking");
caps.setCapability("appium:appActivity", ".MainActivity");

// which uploaded build to install — TOP LEVEL
caps.setCapability("appium:pCloudy_ApplicationName",
                   "GienTechMobileBanking.apk");

caps.setCapability("appium:platformName",   "iOS");
caps.setCapability("appium:automationName", "XCUITest");
caps.setCapability("appium:platformVersion","18.3.0");

// iOS identifies an app by bundle ID — no activity
caps.setCapability("appium:bundleId",
                   "org.reactjs.native.example.GienTechMobileBanking");
caps.setCapability("appium:acceptAlerts", true);

// same capability, .ipa instead of .apk
caps.setCapability("appium:pCloudy_ApplicationName",
                   "GienTechMobileBanking.ipa");

// identical on both platforms — booking, auth and session options
HashMap<String,Object> pcloudy = new HashMap<>();
pcloudy.put("pCloudy_Username", USERNAME);   pcloudy.put("pCloudy_ApiKey", API_KEY);
pcloudy.put("pCloudy_DeviceFullName", deviceName);
pcloudy.put("pCloudy_EnableVideo", true);      pcloudy.put("pCloudy_EnableDeviceLogs", true);
pcloudy.put("appiumVersion", "2.0.0");
caps.setCapability("pcloudy:options", pcloudy);

// region URL from Profile > URL Information + /appiumcloud/wd/hub
String HUB = "https://device.pcloudy.com/appiumcloud/wd/hub";

new AndroidDriver(new URL(HUB), caps);
new IOSDriver(new URL(HUB), caps);      // same hub, iOS caps

Configuration · Region

Region is not cosmetic — it is a different farm

Each region has its own device inventory, its own uploaded apps, and its own device names. A name valid in India does not exist in Singapore.

Note the asymmetry: the mobile farm is regional — five separate inventories — while Browser Cloud is a single global endpoint. Your API key works against all of them.

mvn clean test -Ppcloudy-android -Dpcloudy.cloud.url=https://device.pcloudy.com

App binaries · 📱 Mobile

Upload before you execute — console or API

pCloudy installs the app from its own cloud drive, never from your laptop. Upload once per build; the capability pCloudy_ApplicationName then refers to it by filename.

Automatable via API — no console needed

# Android — filter=apk
curl -X POST https://device.pcloudy.com/api/upload_file \
  -F "token=<TOKEN>" -F "source_type=raw" -F "filter=apk" \
  -F "file=@./GienTechMobileBanking.apk"

# iOS — filter=ipa
curl -X POST https://device.pcloudy.com/api/upload_file \
  -F "token=<TOKEN>" -F "source_type=raw" -F "filter=ipa" \
  -F "file=@./ipa-adhoc/GienTechMobileBanking.ipa"

App binaries · The big trap

pCloudy never overwrites an upload

Upload a file whose name already exists and pCloudy keeps the original, storing yours as MyApp-1784530345.ipa. Meanwhile the tooling prints the local filename and reports success.

# what the CLI said
Upload complete: GienTechMobileBanking.ipa      ← the LOCAL name

# what was actually on the drive
GienTechMobileBanking-1784530345.ipa            ← your new build
GienTechMobileBanking.ipa                       ← the OLD build, still what runs install

Defence — always verify the drive after uploading

curl -s -X POST https://device.pcloudy.com/api/drive \
  -H "Content-Type: application/json" \
  -d '{"token":"<TOKEN>","limit":20,"filter":"all"}' | python3 -m json.tool

Delete the old file in the console before re-uploading so the replacement keeps the plain name your config expects.

iOS signing · 1 of 2

iOS will not run without device UDIDs in the profile

Android installs anywhere. iOS checks that this exact handset is listed inside the IPA's embedded provisioning profile — otherwise:

A valid provisioning profile for this executable was not found.
# or, through Appium:
SessionNotCreatedException … Message: Application Installation failed

iOS signing · 2 of 2

The Ad Hoc procedure, end to end

1. Collect farm UDIDs from Utility → Device UDID: https://device.pcloudy.com/pro/device-udid. One table lists every device with its Device Full Name, version, UDID and location, with search and a Copy UDID action.
2. Register at developer.apple.com → Devices. Devices in Processing state cannot be added to a profile yet — wait for them to go active.
3. Check which distribution certificate you hold the private key for — security find-identity -v -p codesigning. Apple's portal lists a legacy "iOS Distribution" and a modern "Distribution (Xcode 11 or later)"; only the one in your keychain can sign.
4. Generate an Ad Hoc profile for the app's exact bundle ID, tick the farm devices, name it.
5. Re-export the IPA — no rebuild needed, export only (~1 min).
6. Re-upload, deleting the old file first.

# ExportOptions-adhoc.plist → method ad-hoc, signingStyle manual,
# provisioningProfiles maps bundleId → profile NAME
xcodebuild -exportArchive -archivePath MyApp.xcarchive \
  -exportOptionsPlist ExportOptions-adhoc.plist -exportPath ./ipa-adhoc

# verify BEFORE uploading — 30s saves a wasted booking
codesign -dvv Payload/*.app 2>&1 | grep Authority    # expect Apple Distribution
plutil -extract ProvisionedDevices json -o - prof.plist # expect your farm UDIDs

Device availability

The pool is shared — plan for contention

A device farm is a contested resource. Any code that assumes a specific device will be free is code that fails intermittently for reasons unrelated to your app.

Register a pool, in preference order

# pcloudy-android-devices.properties
android.device.1=Samsung_GalaxyF12_Android_13.0.0_53b39
android.device.2=Samsung_GalaxyA52_Android_13.0.0_fcafd
android.device.3=Samsung_GalaxyF145G_Android_13.0.0_dd226

# pcloudy-ios-devices.properties
ios.device.1=Apple_iPhone14ProMax_Ios_18.3.0_eb352
ios.device.2=Apple_iPhone15ProMax_Ios_18.6.2_92d62
ios.device.3=Apple_iPhone12ProMax_Ios_16.3.1_22ba7

Troubleshooting · 🖥 Browser

Playwright-specific failures

Definition of done

You are onboarded when every connection test passes

Each step proves one link in the chain. Run them in order — the first failure tells you exactly which link is broken, instead of leaving you guessing from a red suite.

• 1Console reachable. You can sign in and see devices from your corporate network — no proxy or IP block in the way.
• 2Auth returns a token. GET /api/access with your email and key responds 200 with a token. Proves credentials and network path.
• 3Devices list is non-empty. POST /api/devices returns hardware for your platform. Proves entitlement, and tells you the exact device names to put in your pool.
• 4📱 App resolves on the drive. POST /api/drive lists the exact filename your config passes as pCloudy_ApplicationName.
• 5🖥 WebSocket connects. Playwright reaches wss://browser.device.pcloudy.com/playwright without the socket closing — proves WSS is not blocked by a proxy.
• 6Session is created. Appium or Playwright gets a session id back. Proves capabilities are shaped correctly and a device was actually booked.
• 7App launches. iOS additionally proves the UDID is in the provisioning profile — the step that fails when signing is wrong.
• 8One test asserts and passes end to end.

Demo · the whole thing in one command

One command books a device, runs the test, and reports green

zsh — gientech-mobile-banking-appium Replay

‹ ›

❚❚

Demo · 🖥 Browser Cloud · one command

Same story on the web — Playwright books a browser and runs the suite

zsh — gientech-web-banking-playwright Replay

‹ ›

❚❚