> ## Documentation Index
> Fetch the complete documentation index at: https://qawolf-mktg-5213-self-service-faq-page.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```typescript theme={null}
import { device, flow } from "@qawolf/flows/android";
```

## `setGeoLocation`

Sets the emulator's GPS location.

```typescript theme={null}
function setGeoLocation(options: GeoLocationOptions): Promise<string>;

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

Example:

```typescript theme={null}
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,
  });
});
```

<Note>
  Use this to test location-aware features without physically moving a device. See [Mock device location](/qawolf/android-location-mocking) for a full walkthrough.
</Note>

## `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.

```typescript theme={null}
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:

```typescript theme={null}
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",
      });
    });
  },
);
```

<Note>
  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](/qawolf/android-barcode) for a full walkthrough.
</Note>

## `playAutomation`

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

```typescript theme={null}
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:

```typescript theme={null}
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",
      });
    });
  },
);
```

<Note>
  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](https://developer.android.com/studio/run/emulator-use-camera#arcore) for more detail on virtual scene automation.
</Note>

## `setProxy`

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

```typescript theme={null}
function setProxy(options: ProxyOptions): Promise<string>;

type ProxyOptions = {
  /** Proxy URL. Include credentials in the URL if authentication is required (e.g. `http://username:password@proxy.example.com:8080`). */
  url: string;
};
```

Example:

```typescript theme={null}
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.

```typescript theme={null}
function clearProxy(): Promise<string>;
```

Example:

```typescript theme={null}
import { device, flow } from "@qawolf/flows/android";

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

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