Kobiton provides cloud-based mobile testing on real devices. This guide walks through setup from account creation to running your first automated test.

We’ll cover Appium configuration, desired capabilities, app uploads, and CI/CD integration.

Prerequisites

Before starting, ensure you have:

  • Node.js (for JavaScript examples) or Java (for Java examples)
  • Appium client library for your language
  • A mobile app (.apk for Android, .ipa for iOS)
  • Basic Appium knowledge (element locators, driver commands)

For Appium fundamentals, see our Appium distributed setup guide.

Step 1: Create a Kobiton Account

  1. Go to portal.kobiton.com/register
  2. Enter your email and create a password
  3. No credit card required for trial

The free trial includes limited minutes on Kobiton’s public cloud devices. For pricing details, see our Kobiton pricing breakdown.

Step 2: Get Your Credentials

After logging in:

  1. Click your profile icon (top right)
  2. Select Settings
  3. Find your Username and API Key

Save these — you’ll need them for authentication.

Username: your_username
API Key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Step 3: Upload Your App

Using the Portal

  1. Navigate to Apps in the left menu
  2. Click Upload App
  3. Select your .apk or .ipa file
  4. Wait for upload to complete

After upload, note the App ID (format: kobiton-store:vXXXXXX).

Using the API

bash 
curl -X POST https://api.kobiton.com/v1/apps \
  -H "Authorization: Basic $(echo -n 'USERNAME:API_KEY' | base64)" \
  -H "Content-Type: application/octet-stream" \
  -H "x-kobiton-app-name: MyApp" \
  -H "x-kobiton-app-type: apk" \
  --data-binary @./app-debug.apk

Response:

json 
{
  "appId": "kobiton-store:v657531",
  "name": "MyApp",
  "version": "1.0.0"
}

Step 4: Select a Device

  1. Navigate to Devices in the left menu
  2. Browse available devices (filter by OS, manufacturer, etc.)
  3. Click the settings icon on your chosen device
  4. Select Automation Settings

This displays the desired capabilities for that device.

Step 5: Configure Appium (Basic Setup)

JavaScript (WebDriverIO)

javascript 
const { remote } = require('webdriverio');

const capabilities = {
  platformName: 'Android',
  'appium:deviceName': 'Galaxy S21',
  'appium:platformVersion': '12.0',
  'appium:app': 'kobiton-store:v657531',
  'kobiton:sessionName': 'My Test Session',
  'kobiton:sessionDescription': 'Testing login flow',
  'kobiton:deviceGroup': 'KOBITON'
};

const driver = await remote({
  protocol: 'https',
  hostname: 'api.kobiton.com',
  port: 443,
  path: '/wd/hub',
  user: 'YOUR_USERNAME',
  key: 'YOUR_API_KEY',
  capabilities
});

Java

java 
import io.appium.java_client.android.AndroidDriver;
import org.openqa.selenium.remote.DesiredCapabilities;
import java.net.URL;

public class KobitonTest {
    public static void main(String[] args) throws Exception {
        String kobitonServerUrl = "https://YOUR_USERNAME:[email protected]/wd/hub";

        DesiredCapabilities capabilities = new DesiredCapabilities();
        capabilities.setCapability("platformName", "Android");
        capabilities.setCapability("appium:deviceName", "Galaxy S21");
        capabilities.setCapability("appium:platformVersion", "12.0");
        capabilities.setCapability("appium:app", "kobiton-store:v657531");
        capabilities.setCapability("kobiton:sessionName", "My Test Session");
        capabilities.setCapability("kobiton:deviceGroup", "KOBITON");

        AndroidDriver driver = new AndroidDriver(
            new URL(kobitonServerUrl),
            capabilities
        );

        // Your test code here

        driver.quit();
    }
}

Python

python 
from appium import webdriver
from appium.options.common import AppiumOptions

options = AppiumOptions()
options.set_capability('platformName', 'Android')
options.set_capability('appium:deviceName', 'Galaxy S21')
options.set_capability('appium:platformVersion', '12.0')
options.set_capability('appium:app', 'kobiton-store:v657531')
options.set_capability('kobiton:sessionName', 'My Test Session')
options.set_capability('kobiton:deviceGroup', 'KOBITON')

driver = webdriver.Remote(
    command_executor='https://YOUR_USERNAME:[email protected]/wd/hub',
    options=options
)

# Your test code here

driver.quit()

Step 6: Appium 2.0 Configuration

Kobiton uses Xium (their optimized Appium implementation) by default. To use standard Appium 2.0:

Enable Basic Appium 2

Add this capability:

javascript 
'kobiton:runtime': 'appium'

Vendor Prefixes (Required for Appium 2)

Appium 2.0 requires vendor prefixes on non-standard capabilities:

javascript 
// Appium 1.x style (won't work with Appium 2)
{
  deviceName: 'Galaxy S21',
  platformVersion: '12.0',
  automationName: 'UiAutomator2'
}

// Appium 2.x style (correct)
{
  'appium:deviceName': 'Galaxy S21',
  'appium:platformVersion': '12.0',
  'appium:automationName': 'UiAutomator2'
}

Complete Appium 2 Example

javascript 
const capabilities = {
  // Standard capabilities (no prefix)
  platformName: 'iOS',

  // Appium capabilities (appium: prefix)
  'appium:automationName': 'XCUITest',
  'appium:bundleId': 'com.example.app',
  'appium:deviceOrientation': 'portrait',
  'appium:deviceName': '*',
  'appium:udid': 'aa2ace81ea5b7e6164965b97c5bf432432',
  'appium:noReset': true,
  'appium:fullReset': false,

  // Kobiton capabilities (kobiton: prefix)
  'kobiton:runtime': 'appium',  // Use Appium 2 instead of Xium
  'kobiton:sessionName': 'iOS App Test',
  'kobiton:sessionDescription': 'Automation session',
  'kobiton:app': 'kobiton-store:v657531',
  'kobiton:deviceGroup': 'ORGANIZATION'
};

Note: Basic Appium 2 on Kobiton is in beta. Some features like device logs and network payload capture may be limited.

Step 7: iOS-Specific Configuration

Real iOS Devices

For physical iPhones/iPads, you need signing capabilities:

javascript 
{
  'appium:xcodeOrgId': '<YOUR_TEAM_ID>',
  'appium:xcodeSigningId': 'iPhone Developer'
}

Get your Team ID from the Apple Developer Portal. Note that iOS entitlements may be stripped when apps are re-signed for cloud testing.

Using .xcconfig File

Alternatively, create an .xcconfig file:

DEVELOPMENT_TEAM = <Team ID>
CODE_SIGN_IDENTITY = iPhone Developer

Then reference it:

javascript 
{
  'appium:xcodeConfigFile': '/path/to/.xcconfig'
}

Simulators (No Signing Required)

For iOS Simulators on Kobiton, signing configuration isn’t needed.

Step 8: Kobiton-Specific Capabilities

Capability Description Example
kobiton:sessionName Name shown in portal "Login Test"
kobiton:sessionDescription Description for session "Testing login flow"
kobiton:deviceGroup Device pool "KOBITON" or "ORGANIZATION"
kobiton:app App from Kobiton store "kobiton-store:v657531"
kobiton:runtime Appium version "appium" for Appium 2
kobiton:captureScreenshots Auto-capture screens true
kobiton:networkActivity Capture network logs true

Device Groups

  • KOBITON: Public cloud (shared devices)
  • ORGANIZATION: Your organization’s private devices

Step 9: Running Your First Test

Sample Test (JavaScript)

javascript 
const { remote } = require('webdriverio');

async function runTest() {
  const driver = await remote({
    protocol: 'https',
    hostname: 'api.kobiton.com',
    port: 443,
    path: '/wd/hub',
    user: process.env.KOBITON_USERNAME,
    key: process.env.KOBITON_API_KEY,
    capabilities: {
      platformName: 'Android',
      'appium:deviceName': '*',  // Any available device
      'appium:app': 'kobiton-store:v657531',
      'kobiton:sessionName': 'Sample Test',
      'kobiton:deviceGroup': 'KOBITON'
    }
  });

  try {
    // Wait for app to load
    await driver.pause(3000);

    // Find and click login button
    const loginBtn = await driver.$('~login_button');
    await loginBtn.click();

    // Enter credentials
    const usernameField = await driver.$('~username_field');
    await usernameField.setValue('testuser');

    const passwordField = await driver.$('~password_field');
    await passwordField.setValue('password123');

    // Submit
    const submitBtn = await driver.$('~submit_button');
    await submitBtn.click();

    // Verify success
    const welcomeText = await driver.$('~welcome_message');
    const text = await welcomeText.getText();
    console.log('Welcome message:', text);

  } finally {
    await driver.deleteSession();
  }
}

runTest().catch(console.error);

Run the Test

bash 
# Set environment variables
export KOBITON_USERNAME=your_username
export KOBITON_API_KEY=your_api_key

# Run test
node test.js

Step 10: CI/CD Integration

GitHub Actions

yaml 
name: Mobile Tests

on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '18'

      - name: Install dependencies
        run: npm install

      - name: Run Kobiton tests
        env:
          KOBITON_USERNAME: ${{ secrets.KOBITON_USERNAME }}
          KOBITON_API_KEY: ${{ secrets.KOBITON_API_KEY }}
        run: npm test

Jenkins

groovy 
pipeline {
    agent any

    environment {
        KOBITON_USERNAME = credentials('kobiton-username')
        KOBITON_API_KEY = credentials('kobiton-api-key')
    }

    stages {
        stage('Test') {
            steps {
                sh 'npm install'
                sh 'npm test'
            }
        }
    }

    post {
        always {
            junit 'test-results/*.xml'
        }
    }
}

CircleCI

yaml 
version: 2.1

jobs:
  test:
    docker:
      - image: cimg/node:18.0
    steps:
      - checkout
      - run: npm install
      - run:
          name: Run Kobiton tests
          command: npm test
          environment:
            KOBITON_USERNAME: ${KOBITON_USERNAME}
            KOBITON_API_KEY: ${KOBITON_API_KEY}

workflows:
  main:
    jobs:
      - test

For more CI/CD patterns, see our CI/CD integration guide.

Common Setup Issues

“Device not found”

The specified device isn’t available. Solutions:

  1. Use 'appium:deviceName': '*' to accept any available device
  2. Check device availability in the Kobiton portal
  3. Ensure correct deviceGroup setting

“Invalid app”

The app URL is incorrect. Solutions:

  1. Verify app uploaded successfully in portal
  2. Use exact kobiton-store:vXXXXXX format
  3. Check app hasn’t been deleted

“Authentication failed”

Credentials are wrong. Solutions:

  1. Verify username (not email)
  2. Regenerate API key if needed
  3. Check for trailing spaces in credentials

“Capability not recognized”

Appium 2 prefix issue. Solutions:

  1. Add appium: prefix to device capabilities
  2. Add kobiton: prefix to Kobiton-specific capabilities
  3. Check for typos in capability names

iOS Signing Errors

Missing or wrong signing configuration. Solutions:

  1. Add xcodeOrgId and xcodeSigningId
  2. Verify Team ID from Apple Developer Portal
  3. Ensure provisioning profile allows the device UDID

For more troubleshooting help, see our guides on tests failing in CI.

Viewing Test Results

After your test runs:

  1. Go to Sessions in Kobiton portal
  2. Find your session by name
  3. View:
    • Video recording
    • Screenshots (if enabled)
    • Device logs
    • Appium commands
    • Network activity (if enabled)

The Session Explorer shows step-by-step execution with timestamps. For standardized reporting across platforms, see our test reports guide.

Frequently Asked Questions

How do I get started with Kobiton?

Create a free trial account at portal.kobiton.com (no credit card required). Select a device from the portal, copy the automation settings, and update your Appium script with Kobiton’s server URL and capabilities. Upload your app to get a kobiton-store URL.

What are Kobiton desired capabilities?

Kobiton capabilities include kobiton:sessionName, kobiton:sessionDescription, kobiton:deviceGroup, and kobiton:app. With Appium 2.0, add the ‘appium:’ prefix to standard capabilities like deviceName and platformVersion.

How do I upload an app to Kobiton?

Use the Kobiton API: POST to https://api.kobiton.com/v1/apps with your APK/IPA file. The response includes an appId. Reference it in capabilities as ‘kobiton:app’: ‘kobiton-store:vXXXXXX’.

Does Kobiton support Appium 2.0?

Yes, Kobiton supports Appium 2.0 in beta. Add ‘kobiton:runtime’: ‘appium’ to use basic Appium 2 instead of Xium (Kobiton’s default). Note that Appium 2 requires vendor prefixes on non-standard capabilities.

How do I run Kobiton tests in CI/CD?

Set KOBITON_USERNAME and KOBITON_API_KEY as environment variables in your CI system. Update your Appium script to read credentials from environment variables. Use Kobiton’s Jenkins, GitHub Actions, or CircleCI integrations.

Next Steps

Want simpler setup? DeviceLab runs Appium on your own devices with one curl command — no app uploads, no capability wrestling, just your existing test scripts. Get started.