app_background

This tool on every surface: CLI · MCP · Python · JavaScript · Go · Java · .NET

Send the app in front to the background for a number of seconds, then bring the same app back — resumed where it was, not relaunched — and confirm it is in front again. This is how a resume path is tested: what the app does when it comes back. Android presses Home, confirms the app left, waits, and brings its task to the front; iOS uses XCTest's own. Refuses if the app is not in front. At most 180 seconds; for longer, app_press home and app_launch it later.

Changes the device, the app or the session: readOnlyHint is false.

Arguments

Name	Type	Required	What it is
app	string		The app to send away, which must be in front. Defaults to the one in front.
device	string		Device serial to target, e.g. "emulator-5554". Omit when only one device is running.
driver	string: uiautomator2, uiautomator, wda		Driver to use: "uiautomator2" (default for Android; fast, installs a server APK on first use), "uiautomator" (Android, installs nothing, slower, cannot type), or "wda" (WebDriverAgent: iOS simulators and iPhones).
seconds	number	yes	How long it stays in the background, more than 0 and at most 180.

Examples

Each is the arguments of a tools/call request; the first is shown whole.

Send the app away for five seconds, and bring it back

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "app_background",
    "arguments": {
      "seconds": 5
    }
  }
}

On an Android 15 emulator the answer's text was:

com.android.settings was in the background for 5s and is in front again