@zosmaai/zosma-qa-appium

Appium mobile testing runner for zosma-qa — the open-source QA platform for Web, Mobile, Backend, and Load testing.

This package provides a Playwright-like test API for mobile apps, powered by WebdriverIO and Appium. It includes agent-friendly test helpers, automatic device detection, and zero-config defaults for React Native projects.

Installation

npm install -D @zosmaai/zosma-qa-appium

Peer dependency: You'll need Appium installed globally or locally:

npm install -g appium
appium driver install uiautomator2   # Android
appium driver install xcuitest       # iOS

Usage

Write a test

// tests/login.appium.ts
import { test } from '@zosmaai/zosma-qa-appium';
import { tapButton, fillInput, expectText } from '@zosmaai/zosma-qa-appium';

test.describe('Login Flow', () => {
  test.beforeEach(async ({ driver }) => {
    // driver is a WebdriverIO Browser instance
  });

  test('should login with valid credentials', async ({ driver }) => {
    await fillInput(driver, '[email protected]', { testID: 'email-input' });
    await fillInput(driver, 'password123', { testID: 'password-input' });
    await tapButton(driver, { testID: 'login-button' });
    await expectText(driver, 'Welcome back');
  });
});

Configure

// zosma.config.ts
import { defineConfig } from '@zosmaai/zosma-qa-core';

export default defineConfig({
  plugins: ['appium'],
  baseURL: 'localhost',
  browsers: ['chromium'],
});

Features

| Feature | Description | |---|---| | Playwright-like API | test(), test.describe(), test.beforeEach(), test.afterEach() | | Fixture injection | Tests receive { driver } — a WebdriverIO Browser instance | | Agent-friendly helpers | tapButton(), fillInput(), swipeDown(), expectText(), waitForElement() | | Auto-detection | Finds app path, app ID, and dev server automatically for React Native projects | | Session management | Handles WebdriverIO session lifecycle with retry and cleanup | | Device management | iOS Simulator and Android Emulator detection and control | | Server management | Starts and stops Appium server automatically with port allocation | | Multi-platform | React Native, iOS, Android, Flutter, React Native Web |

Test Helpers

High-level, agent-readable functions that wrap raw WebDriver calls:

import {
  tapButton,       // Tap a button by testID or text
  fillInput,       // Fill a text input
  expectText,      // Assert text is visible on screen
  waitForElement,  // Wait for an element to appear
  swipeDown,       // Swipe down gesture
  swipeUp,         // Swipe up gesture
  scrollToElement, // Scroll until element is visible
  takeScreenshot,  // Capture screenshot
} from '@zosmaai/zosma-qa-appium';

Each helper supports multiple locator strategies:

// By testID (recommended)
await tapButton(driver, { testID: 'submit-btn' });

// By visible text
await tapButton(driver, { text: 'Submit' });

// By raw selector
await tapButton(driver, '~submit-btn');

Platform Support

| Platform | Automation Engine | Status | |---|---|---| | React Native | XCUITest (iOS) / UIAutomator2 (Android) | Available | | iOS Native | XCUITest | Available | | Android Native | UIAutomator2 | Available | | Flutter | Flutter driver | Available | | React Native Web | Chromium | Available |

Smart Defaults

The runner applies sensible defaults so you can start testing without configuration:

| Setting | Default | Notes | |---|---|---| | platformName | ReactNative | Auto-detected from project | | appiumPort | 4723 | Auto-allocated if busy | | appiumHost | localhost | | | testDir | ./tests | | | workers | 1 | Mobile tests run serially | | timeout | 30000 | 30 seconds per test | | autoLaunchSimulator | true | Launches simulator if needed |

Advanced: Raw WebDriver Access

The driver fixture is a standard WebdriverIO Browser instance. Use it directly for anything the helpers don't cover:

test('advanced interaction', async ({ driver }) => {
  const element = await driver.$('~my-element');
  await element.click();

  const text = await element.getText();
  expect.toBe(text, 'Expected value');
});

Part of zosma-qa

• @zosmaai/zosma-qa-core — shared types and plugin interface
• @zosmaai/zosma-qa-playwright — Playwright runner and base config
• @zosmaai/zosma-qa-cli — interactive CLI (npx zosma-qa)
• @zosmaai/zosma-qa-appium — this package

Full documentation: github.com/zosmaai/zosma-qa

License

Apache-2.0