Perfecto provides cloud-based testing on real devices with enterprise features. This guide walks through setup from account creation to running your first test.

We’ll cover security tokens, Selenium/Appium configuration, and CI/CD integration.

Prerequisites

Before starting, ensure you have:

  • Java, Python, or JavaScript environment
  • Selenium or Appium client libraries installed
  • A mobile app (.apk or .ipa) for mobile testing
  • Basic test automation knowledge

Step 1: Create a Perfecto Account

  1. Go to perfecto.io
  2. Click Start Free Trial
  3. Complete registration (14-day trial, no credit card)
  4. Access your Perfecto cloud URL (e.g., yourcompany.perfectomobile.com)

After signup, you’ll receive access to Perfecto’s cloud portal.

Step 2: Generate a Security Token

Security tokens authenticate your tests with Perfecto’s cloud.

  1. Log into Perfecto portal
  2. Click your profile icon (top right)
  3. Select My Profile
  4. Navigate to Security Token
  5. Click Generate (or copy existing token)

Save this token securely — it’s your API key for all test execution.

Security Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Important: Don’t commit tokens to source control. Use environment variables.

Step 3: Identify Your Cloud URL

Your Perfecto cloud URL follows this pattern:

https://[cloudname].perfectomobile.com

For example:

  • https://mycompany.perfectomobile.com
  • https://trial.perfectomobile.com

Find your cloud URL in the browser address bar when logged into the portal.

Step 4: Configure Selenium for Web Testing

Java Example

java 
import org.openqa.selenium.remote.RemoteWebDriver;
import org.openqa.selenium.remote.DesiredCapabilities;
import java.net.URL;

public class PerfectoWebTest {
    public static void main(String[] args) throws Exception {
        String cloudUrl = "https://yourcloud.perfectomobile.com/nexperience/perfectomobile/wd/hub";
        String securityToken = System.getenv("PERFECTO_TOKEN");
        
        DesiredCapabilities capabilities = new DesiredCapabilities();
        capabilities.setCapability("securityToken", securityToken);
        capabilities.setCapability("platformName", "Windows");
        capabilities.setCapability("platformVersion", "11");
        capabilities.setCapability("browserName", "Chrome");
        capabilities.setCapability("browserVersion", "latest");
        
        // Perfecto-specific options
        capabilities.setCapability("perfecto:options", new HashMap<String, Object>() {{
            put("scriptName", "Web Test");
        }});
        
        RemoteWebDriver driver = new RemoteWebDriver(new URL(cloudUrl), capabilities);
        
        try {
            driver.get("https://example.com");
            System.out.println("Title: " + driver.getTitle());
        } finally {
            driver.quit();
        }
    }
}

Python Example

python 
from selenium import webdriver
from selenium.webdriver.common.desired_capabilities import DesiredCapabilities
import os

cloud_url = "https://yourcloud.perfectomobile.com/nexperience/perfectomobile/wd/hub"
security_token = os.environ.get("PERFECTO_TOKEN")

capabilities = {
    "securityToken": security_token,
    "platformName": "Windows",
    "platformVersion": "11",
    "browserName": "Chrome",
    "browserVersion": "latest",
    "perfecto:options": {
        "scriptName": "Web Test"
    }
}

driver = webdriver.Remote(
    command_executor=cloud_url,
    desired_capabilities=capabilities
)

try:
    driver.get("https://example.com")
    print(f"Title: {driver.title}")
finally:
    driver.quit()

JavaScript Example

javascript 
const { Builder } = require('selenium-webdriver');

async function runTest() {
  const cloudUrl = 'https://yourcloud.perfectomobile.com/nexperience/perfectomobile/wd/hub';
  const securityToken = process.env.PERFECTO_TOKEN;
  
  const capabilities = {
    securityToken: securityToken,
    platformName: 'Windows',
    platformVersion: '11',
    browserName: 'Chrome',
    browserVersion: 'latest',
    'perfecto:options': {
      scriptName: 'Web Test'
    }
  };
  
  const driver = await new Builder()
    .usingServer(cloudUrl)
    .withCapabilities(capabilities)
    .build();
  
  try {
    await driver.get('https://example.com');
    console.log('Title:', await driver.getTitle());
  } finally {
    await driver.quit();
  }
}

runTest();

Step 5: Configure Appium for Mobile Testing

Upload Your App

Before testing mobile apps, upload them to Perfecto:

Via Portal:

  1. Go to Apps in the left menu
  2. Click Upload App
  3. Select your .apk or .ipa file
  4. Note the repository path (e.g., PRIVATE:MyApp.apk)

Via API:

bash 
curl -X POST "https://yourcloud.perfectomobile.com/services/repositories/media/PRIVATE:MyApp.apk" \
  -H "Perfecto-Authorization: $PERFECTO_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @./app-debug.apk

Android Configuration (Java)

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

public class PerfectoAndroidTest {
    public static void main(String[] args) throws Exception {
        String cloudUrl = "https://yourcloud.perfectomobile.com/nexperience/perfectomobile/wd/hub";
        String securityToken = System.getenv("PERFECTO_TOKEN");
        
        DesiredCapabilities capabilities = new DesiredCapabilities();
        capabilities.setCapability("securityToken", securityToken);
        capabilities.setCapability("platformName", "Android");
        capabilities.setCapability("model", "Galaxy S23");
        capabilities.setCapability("app", "PRIVATE:MyApp.apk");
        capabilities.setCapability("appPackage", "com.example.myapp");
        capabilities.setCapability("autoInstrument", true);
        
        capabilities.setCapability("perfecto:options", new HashMap<String, Object>() {{
            put("scriptName", "Android App Test");
            put("enableAppiumBehavior", true);
        }});
        
        AndroidDriver driver = new AndroidDriver(new URL(cloudUrl), capabilities);
        
        try {
            // Your test code here
        } finally {
            driver.quit();
        }
    }
}

iOS Configuration (Java)

java 
import io.appium.java_client.ios.IOSDriver;
import org.openqa.selenium.remote.DesiredCapabilities;
import java.net.URL;

public class PerfectoIOSTest {
    public static void main(String[] args) throws Exception {
        String cloudUrl = "https://yourcloud.perfectomobile.com/nexperience/perfectomobile/wd/hub";
        String securityToken = System.getenv("PERFECTO_TOKEN");
        
        DesiredCapabilities capabilities = new DesiredCapabilities();
        capabilities.setCapability("securityToken", securityToken);
        capabilities.setCapability("platformName", "iOS");
        capabilities.setCapability("model", "iPhone 15");
        capabilities.setCapability("app", "PRIVATE:MyApp.ipa");
        capabilities.setCapability("bundleId", "com.example.myapp");
        capabilities.setCapability("autoInstrument", true);
        
        capabilities.setCapability("perfecto:options", new HashMap<String, Object>() {{
            put("scriptName", "iOS App Test");
            put("enableAppiumBehavior", true);
        }});
        
        IOSDriver driver = new IOSDriver(new URL(cloudUrl), capabilities);
        
        try {
            // Your test code here
        } finally {
            driver.quit();
        }
    }
}

Python Appium Example

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

cloud_url = "https://yourcloud.perfectomobile.com/nexperience/perfectomobile/wd/hub"
security_token = os.environ.get("PERFECTO_TOKEN")

options = AppiumOptions()
options.set_capability("securityToken", security_token)
options.set_capability("platformName", "Android")
options.set_capability("model", "Galaxy S23")
options.set_capability("app", "PRIVATE:MyApp.apk")
options.set_capability("appPackage", "com.example.myapp")
options.set_capability("autoInstrument", True)
options.set_capability("perfecto:options", {
    "scriptName": "Android Test",
    "enableAppiumBehavior": True
})

driver = webdriver.Remote(
    command_executor=cloud_url,
    options=options
)

try:
    # Your test code
    pass
finally:
    driver.quit()

Step 6: Key Perfecto Capabilities

Authentication

Capability Description Example
securityToken Your API key "eyJhbGci..."

Device Selection

Capability Description Example
platformName OS type "Android", "iOS", "Windows"
model Device model "Galaxy S23", "iPhone 15"
platformVersion OS version "14", "17"
manufacturer Device maker "Samsung", "Apple"

App Configuration

Capability Description Example
app App repository path "PRIVATE:MyApp.apk"
appPackage Android package "com.example.app"
bundleId iOS bundle ID "com.example.app"
autoInstrument Enable instrumentation true

Perfecto Options (perfecto:options)

Option Description Example
scriptName Test name in reports "Login Test"
scriptDescription Test description "Verify login flow"
enableAppiumBehavior Use Appium behavior true
takesScreenshot Capture screenshots true

Step 7: Working with Reportium (Reporting)

Perfecto’s Reportium SDK provides detailed test reporting.

Add Reportium Dependency (Maven)

xml 
<dependency>
    <groupId>com.perfecto.reporting-sdk</groupId>
    <artifactId>reportium-java</artifactId>
    <version>3.0.0</version>
</dependency>

Initialize Reportium

java 
import com.perfecto.reportium.client.ReportiumClient;
import com.perfecto.reportium.client.ReportiumClientFactory;
import com.perfecto.reportium.model.PerfectoExecutionContext;
import com.perfecto.reportium.model.Job;
import com.perfecto.reportium.model.Project;
import com.perfecto.reportium.test.TestContext;
import com.perfecto.reportium.test.result.TestResultFactory;

// After driver initialization
PerfectoExecutionContext executionContext = new PerfectoExecutionContext.PerfectoExecutionContextBuilder()
    .withProject(new Project("My Project", "1.0"))
    .withJob(new Job("My Job", 1))
    .withWebDriver(driver)
    .build();

ReportiumClient reportiumClient = new ReportiumClientFactory()
    .createPerfectoReportiumClient(executionContext);

// Start test
reportiumClient.testStart("Login Test", new TestContext("Login", "Smoke"));

// Add test steps
reportiumClient.stepStart("Navigate to login page");
driver.get("https://example.com/login");
reportiumClient.stepEnd();

reportiumClient.stepStart("Enter credentials");
// ... test actions
reportiumClient.stepEnd();

// End test
reportiumClient.testStop(TestResultFactory.createSuccess());

// Get report URL
String reportUrl = reportiumClient.getReportUrl();
System.out.println("Report: " + reportUrl);

Step 8: CI/CD Integration

Jenkins

Using Environment Variables:

  1. Add PERFECTO_TOKEN to Jenkins credentials
  2. Reference in pipeline:
groovy 
pipeline {
    agent any
    
    environment {
        PERFECTO_TOKEN = credentials('perfecto-token')
        PERFECTO_CLOUD = 'yourcloud.perfectomobile.com'
    }
    
    stages {
        stage('Test') {
            steps {
                sh 'mvn test'
            }
        }
    }
    
    post {
        always {
            publishHTML([
                reportDir: 'target/reports',
                reportFiles: 'index.html',
                reportName: 'Perfecto Report'
            ])
        }
    }
}

GitHub Actions

yaml 
name: Perfecto Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Set up Java
        uses: actions/setup-java@v4
        with:
          java-version: '17'
          distribution: 'temurin'
      
      - name: Run Perfecto tests
        env:
          PERFECTO_TOKEN: ${{ secrets.PERFECTO_TOKEN }}
          PERFECTO_CLOUD: yourcloud.perfectomobile.com
        run: mvn test
      
      - name: Upload reports
        uses: actions/upload-artifact@v4
        with:
          name: perfecto-reports
          path: target/reports/

Azure DevOps

yaml 
trigger:
  - main

pool:
  vmImage: 'ubuntu-latest'

variables:
  - group: perfecto-credentials

steps:
  - task: JavaToolInstaller@0
    inputs:
      versionSpec: '17'
      jdkArchitectureOption: 'x64'
  
  - script: mvn test
    displayName: 'Run Perfecto Tests'
    env:
      PERFECTO_TOKEN: $(PERFECTO_TOKEN)
      PERFECTO_CLOUD: yourcloud.perfectomobile.com
  
  - task: PublishTestResults@2
    inputs:
      testResultsFormat: 'JUnit'
      testResultsFiles: '**/TEST-*.xml'

Common Setup Issues

“Invalid security token”

Cause: Token expired, incorrectly copied, or missing.

Solutions:

  1. Regenerate token in Perfecto portal
  2. Verify no extra spaces/characters
  3. Check token environment variable is set

“Device not available”

Cause: Requested device is busy or doesn’t exist.

Solutions:

  1. Use less specific device criteria (model instead of UDID)
  2. Check device availability in portal
  3. Try different device model

“App not found”

Cause: App not uploaded or wrong repository path.

Solutions:

  1. Verify app exists in Perfecto repository
  2. Use correct path format: PRIVATE:filename.apk
  3. Re-upload app if needed

“Connection timeout”

Cause: Network issues or wrong cloud URL.

Solutions:

  1. Verify cloud URL is correct
  2. Check network connectivity
  3. Try from different network

“Capability not recognized”

Cause: Wrong capability format or spelling.

Solutions:

  1. Use perfecto:options for Perfecto-specific capabilities
  2. Check capability documentation
  3. Verify JSON/Map structure

Viewing Test Results

After test execution:

  1. Go to Perfecto portal
  2. Navigate to Reporting > Test Analysis
  3. Find your test by name or time
  4. View:
    • Video recording
    • Screenshots
    • Device logs
    • Test steps (if using Reportium)
    • Performance metrics
    • Heatmaps (for multiple runs)

Frequently Asked Questions

How do I get started with Perfecto?

Sign up for a 14-day free trial at perfecto.io. After account creation, generate a security token from your profile settings. Configure your Selenium/Appium scripts with Perfecto’s cloud URL and your security token to start testing.

What is a Perfecto security token?

A security token is your API key for authenticating with Perfecto’s cloud. Generate it from My Profile > Security Token in the Perfecto portal. Use it in your test capabilities instead of username/password authentication.

How do I configure Appium for Perfecto?

Set the Appium server URL to your Perfecto cloud (e.g., https://yourcloud.perfectomobile.com/nexperience/perfectomobile/wd/hub). Add your security token and device capabilities. Perfecto uses standard Appium with perfecto:options for custom settings.

Does Perfecto support Selenium WebDriver?

Yes, Perfecto fully supports Selenium WebDriver for web testing. Configure your RemoteWebDriver to point to Perfecto’s cloud URL with your security token in capabilities.

How do I integrate Perfecto with Jenkins?

Install the Perfecto Jenkins plugin or use environment variables. Store your security token in Jenkins credentials. Configure your test job to use Perfecto’s cloud URL and pass the token via environment variable for security.

Next Steps

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