adbkit

If you are upgrading from version 1.x to 2.x, be aware of several breaking changes related to the transition from a callback-based API to a Promise-based API:

• Promises instead of Callbacks: Most API methods now return Promises (using Bluebird) instead of relying solely on callbacks. This allows for better error propagation and the use of .finally() for resource cleanup.
• Chaining Behavior: In version 1.x, many methods returned the current instance to allow chaining, which often resulted in commands running in parallel. In version 2.x, methods return a Promise, meaning you must use await or .then() to ensure serial execution.
• Argument Consolidation: Some methods that previously accepted multiple callback arguments have been refactored to return a single resolved value in the Promise to better align with Promise patterns (e.g., client.framebuffer()).

Note: Despite the shift to Promises, most API methods still accept callbacks for backward compatibility.

Extras are passed to the activity using the --e flag with a type prefix. You can provide extras in two ways:

1. Short-hand Object Syntax

Pass an object where keys are the extra names and values are the data. The type is inferred from the JavaScript type:

• string -> s
• boolean -> z
• number -> i (integer)
• null -> sn (null)
• object -> Use long-hand syntax for complex types.

Note: Short-hand syntax does not support arrays. If you need to pass an array, use the long-hand syntax.

2. Long-hand Array Syntax

Pass an array of Extra objects for full control over types. Supported types include:

• string (s)
• null (sn)
• bool (z)
• int (i)
• long (l)
• float (f)
• uri (u)
• component (cn)

For array values, the type suffix a is appended (e.g., --esa for a string array).

// Short-hand example
const options = {
  extras: {
    my_string: 'hello',
    my_bool: true,
    my_int: 42,
    my_null: null
  }
};

// Long-hand example (required for arrays or specific types)
const options = {
  extras: [
    { key: 'my_list', type: 'string', value: ['item1', 'item2'] },
    { key: 'my_long', type: 'long', value: 123456789 }
  ]
};

Use client.pull(deviceId, remotePath) to pull a file from a device. The returned object is a stream that emits progress, end, and error events.

import Bluebird from 'bluebird';
import fs from 'fs';
import Adb from '@devicefarmer/adbkit';
const client = Adb.createClient();

const test = async () => {
    try {
        const devices = await client.listDevices();
        await Bluebird.map(devices, async (device) => {
            const transfer = await client.pull(device.id, '/system/build.prop');
            const fn = `/tmp/${device.id}.build.prop`;
            await new Bluebird((resolve, reject) => {
                transfer.on('progress', (stats) =>
                    console.log(`[${device.id}] Pulled ${stats.bytesTransferred} bytes so far`),
                );
                transfer.on('end', () => {
                    console.log(`[${device.id}] Pull complete`);
                    resolve(device.id);
                });
                transfer.on('error', reject);
                transfer.pipe(fs.createWriteStream(fn));
            });
        });
        console.log('Done pulling /system/build.prop from all connected devices');
    } catch (err) {
        console.error('Something went wrong:', err.stack);
    }
};

Use client.readdir(deviceId, remotePath) to list files in a directory. The returned file objects have a .isFile() method to distinguish between files and directories.

import Bluebird from 'bluebird';
import Adb from '@devicefarmer/adbkit';
const client = Adb.createClient();

const test = async () => {
    try {
        const devices = await client.listDevices();
        await Bluebird.map(devices, async (device) => {
            const files = await client.readdir(device.id, '/sdcard');
            // Synchronous, so we don't have to care about returning at the
            // right time
            files.forEach((file) => {
                if (file.isFile()) {
                    console.log(`[${device.id}] Found file "${file.name}"`);
                }
            });
        });
        console.log('Done checking /sdcard files on connected devices');
    } catch (err) {
        console.error('Something went wrong:', err.stack);
    }
};

When running long-running commands (like logcat), device.shell() returns a stream. You can listen to the data event to process output progressively and call conn.end() to terminate the process on the device.

import Bluebird from 'bluebird';
import Adb from '@devicefarmer/adbkit';

const client = Adb.createClient();

client.listDevices()
  .then(function(devices) {
    return Bluebird.map(devices, function(deviceInfo) {
      const device = client.getDevice(deviceInfo.id);
      return device.shell('logcat')
        .then(function(conn) {
          let line = 0;
          conn.on('data', function(data) {
            console.log(data.toString());
            line += 1;
            // Terminate the command after 100 lines
            if (line > 100) conn.end();
          });
          conn.on('close', function() {
            console.log('100 lines read already, bye');
          });
        });
    });
  })
  .then(() => console.log('Done.'))
  .catch(err => console.error('Error:', err.stack));

Use client.push(deviceId, localPath, remotePath) to push a file to a device. The returned object is a stream that emits progress, end, and error events.

import Bluebird from 'bluebird';
import Adb from '@devicefarmer/adbkit';
const client = Adb.createClient();

const test = async () => {
    try {
        const devices = await client.listDevices();
        await Bluebird.map(devices, async (device) => {
            const transfer = await client.push(device.id, 'temp/foo.txt', '/data/local/tmp/foo.txt');
            await new Bluebird(function (resolve, reject) {
                transfer.on('progress', (stats) =>
                    console.log(`[${device.id}] Pushed ${stats.bytesTransferred} bytes so far`),
                );
                transfer.on('end', () => {
                    console.log('[${device.id}] Push complete');
                    resolve();
                });
                transfer.on('error', reject);
            });
        });
        console.log('Done pushing foo.txt to all connected devices');
    } catch (err) {
        console.error('Something went wrong:', err.stack);
    }
};