Android Device Reference

Reference notes for the device object from @qawolf/flows/android.

device is a runtime proxy over the Android emulator API. Use it for emulator-level operations — such as setting location, placing images in the virtual camera scene, or configuring network proxies — that sit outside app UI interactions. Use driver for interacting with the app itself.

device is only available while a flow is running.

import { device, flow } from "@qawolf/flows/android";

setGeoLocation

Sets the emulator’s GPS location.

function setGeoLocation(options: GeoLocationOptions): Promise<string>;

type GeoLocationOptions = {
  latitude: number;
  longitude: number;
  altitude?: number;
  satellites?: number;
  velocity?: number;
};

Example:

import { device, flow } from "@qawolf/flows/android";

export default flow("Set device location", "Android - Pixel", async () => {
  await device.setGeoLocation({
    latitude: 37.7749,
    longitude: -122.4194,
  });
});

Use this to test location-aware features without physically moving a device. See Mock device location for a full walkthrough.

setVirtualSceneImage

Places an image into the Android emulator’s virtual camera scene. Use this to test features that require the camera to see a specific image — such as barcode or QR code scanning.

function setVirtualSceneImage(options: VirtualSceneImageOptions): Promise<string>;

type VirtualSceneImageOptions = {
  /** Path to the image file to place in the virtual scene. Defaults to the default virtual scene image when omitted. */
  image?: string;
  /** Where to place the image in the virtual scene. */
  location: "table" | "wall";
};

Example:

import { device, flow } from "@qawolf/flows/android";

export default flow(
  "Scan barcode",
  { target: "Android - Pixel", launch: true },
  async ({ driver, test }) => {
    await test("place barcode image", async () => {
      await device.setVirtualSceneImage({
        image: "/path/to/barcode.jpg",
        location: "table",
      });
    });
  },
);

Virtual scene is scoped to barcode/QR code scanning and augmented reality (AR) use cases. It is not a general photo or video injection mechanism. See Android barcode and QR scanning for a full walkthrough.

playAutomation

Triggers an automation macro on the Android emulator. Use this in combination with setVirtualSceneImage to animate the virtual camera toward a placed image.

function playAutomation(options: PlayAutomationOptions): Promise<string>;

type PlayAutomationOptions =
  | {
      /** Name of a built-in emulator macro. */
      macro: "Reset_position" | "Track_horizontal_plane" | "Track_vertical_plane" | "Walk_to_image_room";
      /** Optional path to override the macro file. */
      overrideMacroPath?: string;
    }
  | {
      /** Path to a custom macro file. */
      file: string;
    };

Example:

import { device, flow } from "@qawolf/flows/android";

export default flow(
  "Scan barcode",
  { target: "Android - Pixel", launch: true },
  async ({ driver, test }) => {
    await test("place barcode and animate camera", async () => {
      await device.setVirtualSceneImage({
        image: "/path/to/barcode.jpg",
        location: "table",
      });

      await device.playAutomation({
        macro: "Walk_to_image_room",
      });
    });
  },
);

Available built-in macros are determined by the Android emulator. Walk_to_image_room is the macro used to animate the virtual camera toward a placed image. See Android Emulator camera support for more detail on virtual scene automation.

setProxy

Configures a proxy for the Android emulator’s network traffic.

function setProxy(options: ProxyOptions): Promise<string>;

type ProxyOptions = {
  /** Proxy URL. Include credentials in the URL if authentication is required (e.g. `http://username:[e-mail]:8080`). */
  url: string;
};

Example:

import { device, flow } from "@qawolf/flows/android";

export default flow("Set proxy", "Android - Pixel", async () => {
  await device.setProxy({
    url: "http://proxy.example.com:8080",
  });
});

clearProxy

Removes any proxy configuration from the Android emulator.

function clearProxy(): Promise<string>;

Example:

import { device, flow } from "@qawolf/flows/android";

export default flow("Clear proxy", "Android - Pixel", async () => {
  await device.clearProxy();
});

Call clearProxy() at the end of any flow that sets a proxy to avoid affecting subsequent flows.