trace and map --diff: examples in every client

app_trace landed on mobium main in #60 with no example, which the
generator refuses. Its start and stop are examples in all five clients,
and map --diff is a second app_map scenario. The trace page says why it
has no screenshot: what it keeps is a zip for the Playwright viewer.

Author: lana-20

examples/canonical.json

@@ -394,6 +394,13 @@
       "title": "Map what can be acted on, with a ref for each",
       "cli": "mobium map",
       "args": {}
+    },
+    {
+      "title": "What the last action changed",
+      "cli": "mobium map --diff",
+      "args": {
+        "diff": true
+      }
     }
   ],
   "app_network": [
@@ -712,6 +719,24 @@
       }
     }
   ],
+  "app_trace": [
+    {
+      "title": "Start tracing the session",
+      "cli": "mobium trace start --name \"sign in\"",
+      "args": {
+        "action": "start",
+        "name": "sign in"
+      }
+    },
+    {
+      "title": "Stop, and save the trace",
+      "cli": "mobium trace stop -o sign-in.zip",
+      "args": {
+        "action": "stop",
+        "path": "sign-in.zip"
+      }
+    }
+  ],
   "app_type": [
     {
       "title": "Type after what a field holds",

examples/dotnet.json

@@ -204,6 +204,9 @@
     "app_map": [
       {
         "code": "foreach (var e in device.Map())\n    Console.WriteLine($\"{e.Ref} {e.Role} {e.Label}\");"
+      },
+      {
+        "code": "var diff = device.MapDiff();\nConsole.WriteLine(diff[\"added\"]);\nConsole.WriteLine(diff[\"changed\"]);"
       }
     ],
     "app_network": [
@@ -369,6 +372,14 @@
         "code": "string zone = device.Timezone(\"Asia/Tokyo\");"
       }
     ],
+    "app_trace": [
+      {
+        "code": "device.TraceStart(\"sign in\");"
+      },
+      {
+        "code": "var saved = device.TraceStop(\"sign-in.zip\");\nConsole.WriteLine($\"{saved[\"calls\"]} {saved[\"path\"]}\");"
+      }
+    ],
     "app_type": [
       {
         "code": "device.Type(\"testid=email\", \"hello@example.com\");"

examples/go.json

@@ -204,6 +204,9 @@
     "app_map": [
       {
         "code": "elements, err := dev.Map(ctx)\nif err != nil {\n\treturn err\n}\nfor _, el := range elements {\n\tfmt.Println(el.Ref, el.Role, el.Label)\n}"
+      },
+      {
+        "code": "diff, err := dev.MapDiff(ctx)\nif err != nil {\n\treturn err\n}\nfor _, e := range diff.Added {\n\tfmt.Println(\"+\", e.Ref, e.Label)\n}\nfor _, c := range diff.Changed {\n\tfmt.Println(\"~\", c.After.Ref, c.After.Label, c.What)\n}"
       }
     ],
     "app_network": [
@@ -369,6 +372,14 @@
         "code": "if err := dev.SetTimezone(ctx, \"Asia/Tokyo\"); err != nil {\n\treturn err\n}"
       }
     ],
+    "app_trace": [
+      {
+        "code": "if _, err := dev.TraceStart(ctx, &mobium.TraceOptions{Name: \"sign in\"}); err != nil {\n\treturn err\n}"
+      },
+      {
+        "code": "saved, err := dev.TraceStop(ctx, \"sign-in.zip\")\nif err != nil {\n\treturn err\n}\nfmt.Println(saved.Calls, saved.Path)"
+      }
+    ],
     "app_type": [
       {
         "code": "if err := dev.Type(ctx, \"testid=email\", \"hello@example.com\"); err != nil {\n\treturn err\n}"

examples/java.json

@@ -204,6 +204,9 @@
     "app_map": [
       {
         "code": "for (Element e : device.map()) {\n    System.out.println(e.ref() + \" \" + e.role() + \" \" + e.label());\n}"
+      },
+      {
+        "code": "Map<String, Object> diff = device.mapDiff();\nSystem.out.println(diff.get(\"added\"));\nSystem.out.println(diff.get(\"changed\"));"
       }
     ],
     "app_network": [
@@ -369,6 +372,14 @@
         "code": "String zone = device.timezone(\"Asia/Tokyo\");   // read back"
       }
     ],
+    "app_trace": [
+      {
+        "code": "device.traceStart(\"sign in\");"
+      },
+      {
+        "code": "Map<String, Object> saved = device.traceStop(\"sign-in.zip\");\nSystem.out.println(saved.get(\"calls\") + \" \" + saved.get(\"path\"));"
+      }
+    ],
     "app_type": [
       {
         "code": "device.type(\"testid=email\", \"hello@example.com\");"

examples/javascript.json

@@ -204,6 +204,9 @@
     "app_map": [
       {
         "code": "const elements = await device.map()\nfor (const e of elements) console.log(e.ref, e.role, e.label)\n// @e1 button Network & internet ..."
+      },
+      {
+        "code": "const diff = await device.mapDiff()\nfor (const e of diff.added) console.log('+', e.ref, e.label)\nfor (const c of diff.changed) console.log('~', c.after.ref, c.after.label, c.what)"
       }
     ],
     "app_network": [
@@ -369,6 +372,14 @@
         "code": "const zone = await device.timezone('Asia/Tokyo')"
       }
     ],
+    "app_trace": [
+      {
+        "code": "await device.traceStart({ name: 'sign in' })"
+      },
+      {
+        "code": "const saved = await device.traceStop('sign-in.zip')\nconsole.log(saved.calls, saved.path)"
+      }
+    ],
     "app_type": [
       {
         "code": "await device.type('testid=email', 'hello@example.com')"

examples/no-picture.json

@@ -23,5 +23,6 @@
   "source": "it reads the hierarchy, and nothing on the screen changes.",
   "state": "it reads whether an app is running, and nothing on the screen changes.",
   "time": "it reads the device's clock, and nothing on the screen changes.",
+  "trace": "what it keeps is a zip, which opens in the Playwright trace viewer: every step, and the screen after each with the map drawn over it.",
   "uninstall": "it removes an app, which shows nowhere on the screen in front."
 }

examples/python.json

@@ -204,6 +204,9 @@
     "app_map": [
       {
         "code": "for el in device.map():\n    print(el.ref, el.label)"
+      },
+      {
+        "code": "diff = device.map_diff()\nfor e in diff[\"added\"]:\n    print(\"+\", e.ref, e.label)\nfor c in diff[\"changed\"]:\n    print(\"~\", c[\"after\"].ref, c[\"after\"].label, c[\"what\"])"
       }
     ],
     "app_network": [
@@ -369,6 +372,14 @@
         "code": "device.timezone(\"Asia/Tokyo\")"
       }
     ],
+    "app_trace": [
+      {
+        "code": "device.trace_start(name=\"sign in\")"
+      },
+      {
+        "code": "saved = device.trace_stop(\"sign-in.zip\")\nprint(saved[\"calls\"], saved[\"path\"])"
+      }
+    ],
     "app_type": [
       {
         "code": "device.type(\"testid=email\", \"hello@example.com\")"