Lesson 02 — Sessions and Capabilities

// Correct Appium 2 format — note the "appium:" prefix
const capabilities = {
  platformName: "Android",          // No prefix — standard W3C capability
  "appium:deviceName": "Pixel_6",   // Appium-specific — needs "appium:" prefix
  "appium:automationName": "UiAutomator2",
};

// WRONG — Appium 1 style, will cause warnings or errors in Appium 2
const wrongCapabilities = {
  platformName: "Android",
  deviceName: "Pixel_6",           // Missing "appium:" prefix!
  automationName: "UiAutomator2",  // Missing "appium:" prefix!
};

// capabilities for testing an Android app
const androidCapabilities = {
  // Which OS we're targeting
  platformName: "Android",

  // Which Appium driver to use for Android
  // UiAutomator2 is the standard Android driver
  "appium:automationName": "UiAutomator2",

  // Name of the emulator or physical device
  // Run "adb devices" in terminal to see connected devices
  "appium:deviceName": "Pixel_6_API_33",

  // Android version on the device (optional but recommended)
  "appium:platformVersion": "13",

  // Full path to your APK file
  // Use an absolute path to avoid confusion
  "appium:app": "/Users/qa/projects/shop-app/build/app-debug.apk",

  // Don't wipe app data between test runs
  // Set to false if you need a clean state each time
  "appium:noReset": false,

  // Android will automatically grant location/camera/mic permissions
  // This prevents permission dialogs from blocking your test
  "appium:autoGrantPermissions": true,

  // If Appium receives no command for 60 seconds, end the session
  // Prevents orphaned sessions from blocking the device
  "appium:newCommandTimeout": 60,
};

// Use appPackage + appActivity instead of app path
const androidCapabilitiesInstalled = {
  platformName: "Android",
  "appium:automationName": "UiAutomator2",
  "appium:deviceName": "Pixel_6_API_33",

  // The app's package name (find it in AndroidManifest.xml or Play Store URL)
  "appium:appPackage": "com.example.myshop",

  // The activity to launch (usually the main/launcher activity)
  "appium:appActivity": "com.example.myshop.MainActivity",

  // Since app is installed, no need to reinstall
  "appium:noReset": true,
};

// Capabilities for testing an iOS app in a simulator
const iosCapabilities = {
  // Which OS we're targeting
  platformName: "iOS",

  // Which Appium driver to use for iOS
  // XCUITest is Apple's own UI testing framework, used by Appium
  "appium:automationName": "XCUITest",

  // Name of the simulator
  // Open Xcode > Devices and Simulators to see available simulators
  "appium:deviceName": "iPhone 14",

  // iOS version on the simulator
  "appium:platformVersion": "16.4",

  // Full path to your IPA file (built for simulator — not signed for real device)
  "appium:app": "/Users/qa/projects/shop-app/build/MyShop.app",

  // Don't reset app state between sessions
  "appium:noReset": false,

  // How long to wait before Appium times out an idle session
  "appium:newCommandTimeout": 60,
};

// Additional capabilities for real iOS device
const iosRealDeviceCapabilities = {
  platformName: "iOS",
  "appium:automationName": "XCUITest",
  "appium:deviceName": "My iPhone",
  "appium:platformVersion": "16.4",

  // For real devices, use bundleId of an app already installed
  "appium:bundleId": "com.example.myshop",

  // The UDID of your specific device
  // Find it in Xcode > Window > Devices and Simulators
  "appium:udid": "00008101-001234AB5678901E",

  // Your Apple Developer Team ID (found in Apple Developer account)
  "appium:xcodeOrgId": "YOUR_TEAM_ID",

  // Your signing certificate name
  "appium:xcodeSigningId": "iPhone Developer",
};

// WRONG — Appium 2 will reject or warn about this
{
  deviceName: "Pixel_6_API_33",   // Missing appium: prefix
  automationName: "UiAutomator2", // Missing appium: prefix
}

// CORRECT
{
  "appium:deviceName": "Pixel_6_API_33",
  "appium:automationName": "UiAutomator2",
}

# Android: see connected devices and emulators
adb devices

# iOS: see simulators (macOS only)
xcrun simctl list devices | grep Booted

// WRONG — relative path is unreliable
"appium:app": "./app-debug.apk",

// CORRECT — use an absolute path
"appium:app": "/Users/qa/projects/shop-app/build/app-debug.apk",
// or in Windows:
"appium:app": "C:\\Users\\qa\\projects\\shop-app\\build\\app-debug.apk",

// WRONG — using Android driver for iOS test
{
  platformName: "iOS",
  "appium:automationName": "UiAutomator2", // This is Android-only!
}

// CORRECT
{
  platformName: "iOS",
  "appium:automationName": "XCUITest",
}

# Check what drivers are installed
appium driver list --installed

# Install the missing driver
appium driver install uiautomator2
appium driver install xcuitest

// Set a global implicit wait of 10 seconds
await driver.implicitWait(10000); // milliseconds

// Wait for a specific element to be visible — up to 10 seconds
const loginButton = await driver.$('~loginButton');
await loginButton.waitForDisplayed({ timeout: 10000 });

// Wait for text to contain a specific value
const welcomeMessage = await driver.$('~welcomeText');
await welcomeMessage.waitForExist({ timeout: 5000 });

// Set a short implicit wait as a fallback
await driver.implicitWait(2000);

// Use explicit waits for anything that loads asynchronously
const dynamicContent = await driver.$('~productList');
await dynamicContent.waitForDisplayed({
  timeout: 15000,
  // Custom error message makes debugging much easier
  timeoutMsg: 'Product list did not appear within 15 seconds',
});

import { remote } from "webdriverio";

// Define capabilities
const capabilities = {
  platformName: "Android",
  "appium:automationName": "UiAutomator2",
  "appium:deviceName": "Pixel_6_API_33",
  "appium:app": "/absolute/path/to/your/app.apk",
  "appium:noReset": false,
};

// WebdriverIO options — point to your running Appium server
const wdioOptions = {
  hostname: "localhost",
  port: 4723,
  logLevel: "info",
  capabilities,
};

// Always wrap in try/finally to guarantee session cleanup
async function runTest() {
  let driver;

  try {
    // This starts the session — sends POST /session to Appium
    driver = await remote(wdioOptions);

    // Your test actions go here
    const loginButton = await driver.$("~loginButton");
    await loginButton.waitForDisplayed({ timeout: 5000 });
    await loginButton.click();

    console.log("Test passed!");
  } catch (error) {
    console.error("Test failed:", error.message);
    throw error;
  } finally {
    // Always end the session — even if the test throws an error
    // This sends DELETE /session to Appium
    if (driver) {
      await driver.deleteSession();
    }
  }
}

runTest();