Execute Methods

note

All examples in this documentation are using the webdriverio client.

Overview

TV Labs provides a superset of Appium functionality through execute methods that expose additional functionality of the platform that aren't traditionally available through Appium. This page outlines the available execute methods.

Device

tvlabs: currentApp

Queries the device for the app currently running on it. Returns an object with app_id, app_version, and app_name fields, otherwise returns an error.

app_version and app_name may be null if the underlying device protocol can't cheaply report them.

note

This method is currently available on Roku, webOS, Android TV, and Android mobile devices. Support for the remaining platforms is coming soon.

Example:

const currentApp = await driver.execute('tvlabs: currentApp');

console.log(currentApp);
// { app_id: 'dev', app_name: 'TV Labs', app_version: '1.0.0' }

Network Control

tvlabs: disableNetwork

Disables the network connection for the device, simulating a network outage. Returns true if the network was successfully disabled, otherwise returns an error.

Example:

await driver.execute('tvlabs: disableNetwork');

note

If a network throttle is active, it will be disabled when tvlabs: disableNetwork is executed. After tvlabs: enableNetwork is executed, the network throttle command will need to be explicitly re-enabled if desired.

await driver.execute('tvlabs: enableNetworkThrottle', { limitDown: 5 });

// Network is throttled

await driver.execute('tvlabs: disableNetwork');

// Network is offline

await driver.execute('tvlabs: enableNetwork');

// Network is online, no throttling enabled

await driver.execute('tvlabs: enableNetworkThrottle', { limitDown: 5 });

// Throttling re-enabled

tvlabs: enableNetwork

Restores the network connection after tvlabs: disableNetwork was executed. Returns true if the network was successfully enabled, otherwise returns an error.

Example:

await driver.execute('tvlabs: enableNetwork');

tvlabs: isNetworkEnabled

Returns true if the network is enabled.

Example:

await driver.execute('tvlabs: disableNetwork');

const isNetworkEnabled = await driver.execute('tvlabs: isNetworkEnabled');

console.log(isNetworkEnabled);
// false

Network Throttling

tvlabs: enableNetworkThrottle

Enables network rate limiting for the device. Returns true if the rate limit was successfully enabled, otherwise returns an error.

Arguments:

• limitDown (required, number)
  • The download limit in mbits / second
• limitUp (optional, number | string)
  • The upload limit in mbits / second. Accepts "infinity" as a value.
  • Default: "infinity"

Example:

// Throttle download to 5 mbits / second
await driver.execute('tvlabs: enableNetworkThrottle', {
  limitDown: 5,
});

tvlabs: disableNetworkThrottle

Disables network rate limiting for the device. Returns true if the rate limit was successfully disabled, otherwise returns an error.

Example:

await driver.execute('tvlabs: disableNetworkThrottle');

tvlabs: isNetworkThrottleEnabled

Returns true if the rate limit is enabled.

Example:

await driver.execute('tvlabs: enableNetworkThrottle', {
  limitDown: 5,
});

const isNetworkThrottleEnabled = await driver.execute('tvlabs: isNetworkThrottleEnabled');

console.log(isNetworkThrottleEnabled);
// true

Network Usage

tvlabs: getNetworkUsage

Returns a snapshot of throughput and interface statistics for the device's network connection, measured over the most recent sampling interval (reported as interval_ms). Packet, error, drop, multicast, and collision values are the change observed during that interval, not cumulative totals.

Returns:

• rx_kbps (number)
  • Download throughput in kbits / second
• tx_kbps (number)
  • Upload throughput in kbits / second
• rx_packets (number)
  • Packets received during the interval
• tx_packets (number)
  • Packets transmitted during the interval
• rx_errors (number)
  • Receive errors during the interval
• tx_errors (number)
  • Transmit errors during the interval
• rx_dropped (number)
  • Inbound packets dropped during the interval
• tx_dropped (number)
  • Outbound packets dropped during the interval
• multicast (number)
  • Multicast frames received during the interval
• collisions (number)
  • Packet collisions detected during the interval
• interval_ms (number)
  • Length of the sampling window in milliseconds

Example:

const usage = await driver.execute('tvlabs: getNetworkUsage');

console.log(usage);
// {
//   rx_kbps: 1.03,
//   tx_kbps: 0.67,
//   rx_packets: 2,
//   tx_packets: 1,
//   rx_errors: 0,
//   tx_errors: 0,
//   rx_dropped: 0,
//   tx_dropped: 0,
//   multicast: 0,
//   collisions: 0,
//   interval_ms: 1000,
// }

Network Capture

More details on network capture functionality can be found on the main Network Capture page.

tvlabs: startNetworkCapture

Starts network capture for the current session.

Arguments:

• name (optional, string)
  • A name for the capture, used to identify it in the sessions dashboard
• direct_proxy (optional, boolean)
  • Enables direct proxy mode, where your application sends traffic to the proxy directly rather than having it intercepted transparently
  • Default: false
• filters (optional, array)
  • A list of filter objects to reduce HAR file size by dropping or omitting matched entries
• reload (optional, boolean)
  • Whether to reload the page after starting network capture
  • Chromium-based platforms only
  • Default: true
• cache (optional, boolean)
  • Whether to enable or disable the page cache
  • Chromium-based platforms only
  • Default: false

Example:

// Start a network capture with defaults
await driver.execute('tvlabs: startNetworkCapture');

// Start a named capture with direct proxy mode and a filter
await driver.execute('tvlabs: startNetworkCapture', {
  name: 'my-capture',
  direct_proxy: true,
  filters: [{ action: 'drop', mime_type: 'image/.+' }],
});

warning

On non-Chromium based platforms, after starting a network capture in an application that uses HTTP keep-alive, the application may need to be re-launched to ensure any open network connections are re-established and intercepted. This can be done with the terminateApp and activateApp methods.

On Tizen, webOS, and SmartCast, re-launching the app this way will also terminate the active ChromeDriver session — see ChromeDriver session lifecycle before doing this mid-test.

tvlabs: stopNetworkCapture

Stops network capture and finalizes the HAR file for download. If the session network capture was started using capabilities, this method may be used to stop the capture before the session ends.

Arguments: None

Example:

// Stop an already running capture
await driver.execute('tvlabs: stopNetworkCapture');