Gray box: the guide, the tutorial, and examples in every client

data/runs.json

@@ -714,5 +714,23 @@
   "verbatim": true,
   "exit": 0,
   "output": "moved label=Volume to position 0.3 — it reads \"3.0\", was \"5.0\""
+ },
+ "app_launch[1]": {
+  "tool": "app_launch",
+  "index": 1,
+  "command": "mobium launch --gray-box dev.mobium.mobiumapp",
+  "verbatim": true,
+  "exit": 0,
+  "output": "launched dev.mobium.mobiumapp, with the gray box: every action waits for the app to say it is idle"
+ },
+ "app_tap[3]": {
+  "tool": "app_tap",
+  "index": 3,
+  "command": "mobium tap testid=busyRowB",
+  "verbatim": true,
+  "exit": 0,
+  "output": "tapped testid=busyRowB at (540, 1095)\ngray box: waited 307 ms for the app to go idle (busy: quiet)",
+  "caption": "`mobium tap testid=busyRowB` on MobiumApp's Busy Demo, Android 15 emulator, launched with `--gray-box`: the tap waited for the quiet refresh to finish, and Row B is the new generation's",
+  "after": "/img/shots/app_tap-3-after.jpg"
  }
 }

examples/canonical.json

@@ -332,6 +332,14 @@
       "args": {
         "app": "com.android.settings"
       }
+    },
+    {
+      "title": "Launch an app with the gray box on, so every action waits for it to be idle",
+      "cli": "mobium launch --gray-box dev.mobium.mobiumapp",
+      "args": {
+        "app": "dev.mobium.mobiumapp",
+        "gray_box": true
+      }
     }
   ],
   "app_list_apps": [
@@ -709,6 +717,13 @@
         "target": "@e2",
         "double": true
       }
+    },
+    {
+      "title": "Tap right after work the screen does not show, with the gray box on",
+      "cli": "mobium tap testid=busyRowB",
+      "args": {
+        "target": "testid=busyRowB"
+      }
     }
   ],
   "app_terminate": [

examples/dotnet.json

@@ -169,6 +169,9 @@
     "app_launch": [
       {
         "code": "device.Launch(\"com.android.settings\");"
+      },
+      {
+        "code": "device.LaunchWithGrayBox(\"dev.mobium.mobiumapp\");"
       }
     ],
     "app_list_apps": [
@@ -359,6 +362,9 @@
       },
       {
         "code": "device.DoubleTap(\"@e2\");"
+      },
+      {
+        "code": "device.LaunchWithGrayBox(\"dev.mobium.mobiumapp\");\ndevice.Tap(\"testid=busyQuiet\");\ndevice.Tap(\"testid=busyRowB\");   // waits for the app to say it is idle"
       }
     ],
     "app_terminate": [

examples/go.json

@@ -169,6 +169,9 @@
     "app_launch": [
       {
         "code": "if err := dev.Launch(ctx, \"com.android.settings\"); err != nil {\n\treturn err\n}"
+      },
+      {
+        "code": "if err := dev.LaunchWithGrayBox(ctx, \"dev.mobium.mobiumapp\"); err != nil {\n\treturn err\n}"
       }
     ],
     "app_list_apps": [
@@ -359,6 +362,9 @@
       },
       {
         "code": "if err := dev.DoubleTap(ctx, \"@e2\"); err != nil {\n\treturn err\n}"
+      },
+      {
+        "code": "if err := dev.LaunchWithGrayBox(ctx, \"dev.mobium.mobiumapp\"); err != nil {\n\treturn err\n}\nif err := dev.Tap(ctx, \"testid=busyQuiet\"); err != nil {\n\treturn err\n}\n// Waits for the app to say it is idle.\nif err := dev.Tap(ctx, \"testid=busyRowB\"); err != nil {\n\treturn err\n}"
       }
     ],
     "app_terminate": [

examples/java.json

@@ -169,6 +169,9 @@
     "app_launch": [
       {
         "code": "device.launch(\"com.android.settings\");   // returns once it is in front"
+      },
+      {
+        "code": "device.launchWithGrayBox(\"dev.mobium.mobiumapp\");"
       }
     ],
     "app_list_apps": [
@@ -359,6 +362,9 @@
       },
       {
         "code": "device.doubleTap(\"@e2\");"
+      },
+      {
+        "code": "device.launchWithGrayBox(\"dev.mobium.mobiumapp\");\ndevice.tap(\"testid=busyQuiet\");\ndevice.tap(\"testid=busyRowB\");   // waits for the app to say it is idle"
       }
     ],
     "app_terminate": [

examples/javascript.json

@@ -169,6 +169,9 @@
     "app_launch": [
       {
         "code": "await device.launch('com.android.settings')"
+      },
+      {
+        "code": "await device.launch('dev.mobium.mobiumapp', { grayBox: true })"
       }
     ],
     "app_list_apps": [
@@ -359,6 +362,9 @@
       },
       {
         "code": "await device.doubleTap('@e2')"
+      },
+      {
+        "code": "await device.launch('dev.mobium.mobiumapp', { grayBox: true })\nawait device.tap('testid=busyQuiet')\nawait device.tap('testid=busyRowB')   // waits for the app to say it is idle"
       }
     ],
     "app_terminate": [

examples/python.json

@@ -169,6 +169,9 @@
     "app_launch": [
       {
         "code": "device.launch(\"com.android.settings\")"
+      },
+      {
+        "code": "device.launch(\"dev.mobium.mobiumapp\", gray_box=True)"
       }
     ],
     "app_list_apps": [
@@ -359,6 +362,9 @@
       },
       {
         "code": "device.double_tap(\"@e2\")"
+      },
+      {
+        "code": "device.launch(\"dev.mobium.mobiumapp\", gray_box=True)\ndevice.tap(\"testid=busyQuiet\")\ndevice.tap(\"testid=busyRowB\")   # waits for the app to say it is idle"
       }
     ],
     "app_terminate": [

scripts/capture.py

@@ -60,12 +60,21 @@ def app_screen(name):
 PLAN = [
     dict(tool="app_devices", i=0),
     dict(tool="app_launch", i=0, setup=[f"terminate {SETTINGS}"], after=True),
+    # MobiumApp links Mobium's gray-box library; the launch says the app answered.
+    dict(tool="app_launch", i=1, setup=[f"terminate {APP}"]),
     dict(tool="app_map", i=0, setup=settings_root(), after=True),
     dict(tool="app_text", i=0, setup=settings_root(), after=True),
     dict(tool="app_find", i=0, setup=settings_root(), after=True),
     dict(tool="app_current", i=0),
     dict(tool="app_state", i=0),
     dict(tool="app_tap", i=0, setup=settings_root(), before=True, after=True),
+    # The gray box: a tap right after a quiet refresh waits for the app to say
+    # it is idle, and the result says how long, and for what.
+    dict(tool="app_tap", i=3, setup=[f"terminate {APP}", f"launch --gray-box {APP}",
+                                     "scroll-to 'label=Busy Demo' --direction down", "tap 'label=Busy Demo'",
+                                     "tap testid=busyQuiet"], after=True,
+         caption="`mobium tap testid=busyRowB` on MobiumApp's Busy Demo, Android 15 emulator, launched with "
+                 "`--gray-box`: the tap waited for the quiet refresh to finish, and Row B is the new generation's"),
     dict(tool="app_scroll_to", i=0, setup=settings_root(), before=True, after=True),
     # The horizontal case, on MobiumApp's Pager Demo: Card 8 starts off screen
     # to the right, as mobium-app.sh checks.

scripts/generate.py

@@ -535,7 +535,8 @@ def doc_text(doc, lang):
 # section's.
 SYNC = {
     "quickstart": ["README.md", "cli.md", "mcp.md", "python.md", "javascript.md", "go.md", "java.md", "dotnet.md"],
-    "guides": ["README.md", "autowait.md", "cli.md", "test-runner.md", "grid.md", "network.md", "inspector.md", "mcp.md"],
+    "guides": ["README.md", "autowait.md", "graybox.md", "graybox-tutorial.md", "cli.md", "test-runner.md", "grid.md",
+               "network.md", "inspector.md", "mcp.md"],
 }