@wdio/appium-service

What is @wdio/appium-service?

@wdio/appium-service is a WebdriverIO service that helps you run Appium seamlessly when running your WebdriverIO tests. It simplifies the process of starting and stopping the Appium server, making it easier to manage mobile testing environments.

What are @wdio/appium-service's main functionalities?

Starting Appium Server

This code sample demonstrates how to start an Appium server using WebdriverIO with the @wdio/appium-service. It sets up the desired capabilities for an Android device and starts a session.

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

const opts = {
  path: '/wd/hub',
  port: 4723,
  capabilities: {
    platformName: 'Android',
    platformVersion: '9',
    deviceName: 'emulator-5554',
    app: '/path/to/the/app.apk',
    automationName: 'UiAutomator2'
  }
};

(async () => {
  const client = await remote(opts);
  await client.deleteSession();
})();

Stopping Appium Server

This code sample shows how to stop the Appium server after the test session ends. The @wdio/appium-service handles the stopping of the server automatically when the session is deleted.

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

const opts = {
  path: '/wd/hub',
  port: 4723,
  capabilities: {
    platformName: 'Android',
    platformVersion: '9',
    deviceName: 'emulator-5554',
    app: '/path/to/the/app.apk',
    automationName: 'UiAutomator2'
  }
};

(async () => {
  const client = await remote(opts);
  await client.deleteSession();
  // Appium server will stop automatically after the session ends
})();

Custom Appium Server Arguments

This code sample demonstrates how to pass custom arguments to the Appium server using the @wdio/appium-service. It configures the server to run on a specific address and port, and to log output to a file.

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

const opts = {
  path: '/wd/hub',
  port: 4723,
  capabilities: {
    platformName: 'Android',
    platformVersion: '9',
    deviceName: 'emulator-5554',
    app: '/path/to/the/app.apk',
    automationName: 'UiAutomator2'
  },
  services: [['appium', {
    args: {
      address: '127.0.0.1',
      port: 4723,
      log: './appium.log'
    }
  }]]
};

(async () => {
  const client = await remote(opts);
  await client.deleteSession();
})();

Other packages similar to @wdio/appium-service

appium

Appium is an open-source tool for automating mobile applications. It allows you to write tests for multiple platforms (iOS, Android) using the same API. Compared to @wdio/appium-service, Appium is the core server that @wdio/appium-service interacts with to manage mobile testing.

wdio-selenium-standalone-service

The wdio-selenium-standalone-service is a WebdriverIO service that helps you run a standalone Selenium server seamlessly when running your WebdriverIO tests. It is similar to @wdio/appium-service but is used for web browser automation instead of mobile app automation.

webdriverio

WebdriverIO is a popular testing framework for Node.js that allows you to write and run tests for web and mobile applications. While WebdriverIO provides the framework and API for writing tests, @wdio/appium-service specifically helps manage the Appium server for mobile testing.

README

WebdriverIO Appium Service

Handling the Appium server is out of the scope of the actual WebdriverIO project. This service helps you to run the Appium server seamlessly when running tests with the WDIO testrunner. It starts the Appium Server in a child process.

Installation

The easiest way is to keep @wdio/appium-service as a devDependency in your package.json, via:

npm install @wdio/appium-service --save-dev

Instructions on how to install WebdriverIO can be found here.

Configuration

In order to use the service you need to add appium to your service array:

// wdio.conf.js
export const config = {
    // ...
    port: 4723, // default appium port
    services: ['appium'],
    // ...
};

Options

The following options can be added to the wdio.conf.js file. To define options for the service you need to add the service to the services list in the following way:

// wdio.conf.js
export const config = {
    // ...
    port: 4723, // default appium port
    services: [
        ['appium', {
            // Appium service options here
            // ...
        }]
    ],
    // ...
};

logPath

The path where all logs from the Appium server should be stored.

Type: String

Example:

export const config = {
    // ...
    services: [
        ['appium', {
            logPath : './'
        }]
    ],
    // ...
}

command

To use your installation of Appium, e.g. globally installed, specify the command which should be started.

Type: String

Example:

export const config = {
    // ...
    services: [
        ['appium', {
            command : 'appium'
        }]
    ],
    // ...
}

args

Map of arguments for the Appium server, passed directly to appium.

See the documentation for possible arguments. The arguments are supplied in lower camel case. For instance, debugLogSpacing: true transforms into --debug-log-spacing, or they can be supplied as outlined in the Appium documentation.

Type: Object

Default: {}

Example:

export const config = {
    // ...
    services: [
        ['appium', {
            args: {
                // ...
                debugLogSpacing: true,
                platformName: 'iOS'
                // ...
            }
        }]
    ],
    // ...
}

Note: The utilization of aliases is discouraged and unsupported. Instead, please use the full property name in lower camel case.

---

For more information on WebdriverIO see the homepage.

Changelog

v9.2.14 (2024-11-14)

:rocket: New Feature

• webdriverio
  • #13870 feat: enhance scrollIntoView to support native mobile (@wswebcreation)

:nail_care: Polish

• wdio-cucumber-framework, wdio-reporter, wdio-spec-reporter
  • #13880 polish(@wdio/reporter): better display retried scenarios (@christian-bromann)

Committers: 2

• Christian Bromann (@christian-bromann)
• Wim Selles (@wswebcreation)