Skip to main content

Multiple Image Injection

Overview

This guide documents the TestGrid APIs used to perform Image Injection on a real device, and how to chain multiple image-injection calls together within a single test case flow — without repeating the app install / resign step every time.

The typical flow has three stages:

  1. Install the application on the device and perform the first image injection (one-time per test run).
  2. Push additional images to the same running app session using the lightweight overlay API — no reinstall or resign required.
  3. (Optional) Kill and relaunch the app between injections if your test scenario requires a fresh app state.

 

Why This Matters
Re-installing and re-signing the app for every image injection is slow and, on iOS, resource intensive. Once the app is installed and the first image is injected, subsequent images can be pushed in seconds using the overlay API.

 

Flow Summary

Step API Purpose
1 /api/device/install/image-injection Install the app + inject the first image (required, one time).
2 /api/device/image-injection-image-overlay Overlay any subsequent image on the same installed app (repeatable, no reinstall/resign).
3 /api/device/app-auto-launch Optional — kill and relaunch the app between injection cycles.

Step 1 — Install App & First Image Injection

Use this API once per test run to install the application on the target device and perform the first image injection. This call also handles app re-signing (iOS) automatically, so it must be run before any overlay calls.

POST /api/device/install/image-injection 
Sample Request

curl --location 'https://domain.testgrid.io/api/device/install/image-injection' \
--form 'user_token="<Your_User_Token>"' \
--form 'device_id="<Your_device_id>"' \
--form 'apk_ipa_file=@"/path/to/file"' \
--form 'image=@"/path/to/file"' \
--form 'resign="<0 or 1>"'
Parameters
Parameter Type Required Description
user_token string Yes TestGrid API authentication token for the account.
device_id string Yes Unique identifier of the target real device on TestGrid.
apk_ipa_file file Yes The application binary to install — .apk for Android or .ipa for iOS.
image file Yes The image or video file to inject into the app’s camera/gallery feed for this session. See File Requirements below.
resign string No iOS only. Set to control app re-signing behaviour; leave empty to use default resigning.
File Requirements
  • Allowed file types: PNG, JPG, JPEG, GIF, MP4, MOV.
  • File size: Default size is 500 KB, this will be customizable.
Run This Once
This call installs the binary and performs the first injection in one step.
Do not call this again for the same test run — use the overlay API in Step 2 for every image after the first.

Step 2 — Subsequent Image Injections (Overlay)

Once the app is installed and the first image is injected, use this API for every additional image you want to inject into the same app session. It does not reinstall the app or trigger iOS re-signing, so it is fast enough to call repeatedly within a test flow.

POST /api/device/image-injection-image-overlay 
Sample Request
curl --location 'https://domain.testgrid.io/api/device/image-injection-image-overlay' \
--form 'user_token="<Your_User_Token>"' \
--form 'device_id="<Your_device_id>"' \
--form 'bundle_id="<Your_bundle_id>"' \
--form 'image=@"/path/to/file"'
Parameters
Parameter Type Required Description
user_token string Yes TestGrid API authentication token for the account.
device_id string Yes Unique identifier of the device already running the installed app.
bundle_id string Yes Package name (Android) or bundle identifier (iOS) of the already-installed app.
image file Yes The next image or video file to overlay/inject into the running app session. See File Requirements below.

Repeat this call as many times as needed—once per image—for as long as the app remains installed and running on the device.

Step 3 (Optional) — Kill & Relaunch the App

If your test scenario requires the app to be killed and relaunched between image injections (for example, to validate that an injected image persists or is re-read on a fresh app launch), use the app-auto-launch API. This is optional and is not required for a basic multi-image injection flow.

POST /api/device/app-auto-launch 
Sample Request
curl --location 'https://domain.testgrid.io/api/device/app-auto-launch' \
--form 'user_token="<Your_User_Token>"' \
--form 'device_id="<Your_device_id>"' \
--form 'bundle_id="<Your_bundle_id>"'
Parameters
Parameter Type Required Description
user_token string Yes TestGrid API authentication token for the account.
device_id string Yes Unique identifier of the target device.
bundle_id string Yes Package name (Android) or bundle identifier (iOS) of the app to kill and relaunch.

Typical usage: call this API, then call the overlay API (Step 2) again once the app has relaunched, to inject the next image into the fresh app session.

Table of Contents