digital-ai-testing-mcp 2.2.2 → 2.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (102) hide show
  1. package/README.md +27 -15
  2. package/dist/api/browser-events.d.ts +48 -0
  3. package/dist/api/browser-events.d.ts.map +1 -0
  4. package/dist/api/browser-events.js +155 -0
  5. package/dist/api/browser-events.js.map +1 -0
  6. package/dist/api/browser-inspection.d.ts +21 -0
  7. package/dist/api/browser-inspection.d.ts.map +1 -1
  8. package/dist/api/browser-inspection.js +113 -20
  9. package/dist/api/browser-inspection.js.map +1 -1
  10. package/dist/api/playwright-runs.d.ts +42 -0
  11. package/dist/api/playwright-runs.d.ts.map +1 -0
  12. package/dist/api/playwright-runs.js +207 -0
  13. package/dist/api/playwright-runs.js.map +1 -0
  14. package/dist/api/reporting.d.ts.map +1 -1
  15. package/dist/api/reporting.js +4 -2
  16. package/dist/api/reporting.js.map +1 -1
  17. package/dist/api/repository.d.ts +13 -1
  18. package/dist/api/repository.d.ts.map +1 -1
  19. package/dist/api/repository.js +39 -4
  20. package/dist/api/repository.js.map +1 -1
  21. package/dist/api/test-requests.d.ts +4 -0
  22. package/dist/api/test-requests.d.ts.map +1 -1
  23. package/dist/api/test-requests.js +2 -0
  24. package/dist/api/test-requests.js.map +1 -1
  25. package/dist/api/test-runs.d.ts +5 -0
  26. package/dist/api/test-runs.d.ts.map +1 -1
  27. package/dist/api/test-runs.js.map +1 -1
  28. package/dist/api/webdriver.d.ts +25 -2
  29. package/dist/api/webdriver.d.ts.map +1 -1
  30. package/dist/api/webdriver.js +163 -11
  31. package/dist/api/webdriver.js.map +1 -1
  32. package/dist/index.js +1 -1
  33. package/dist/tools/boilerplate-tools.d.ts +22 -0
  34. package/dist/tools/boilerplate-tools.d.ts.map +1 -1
  35. package/dist/tools/boilerplate-tools.js +321 -43
  36. package/dist/tools/boilerplate-tools.js.map +1 -1
  37. package/dist/tools/device-group-tools.js +2 -2
  38. package/dist/tools/device-group-tools.js.map +1 -1
  39. package/dist/tools/device-tools.d.ts.map +1 -1
  40. package/dist/tools/device-tools.js +63 -11
  41. package/dist/tools/device-tools.js.map +1 -1
  42. package/dist/tools/inspection-tools.d.ts +24 -0
  43. package/dist/tools/inspection-tools.d.ts.map +1 -1
  44. package/dist/tools/inspection-tools.js +159 -14
  45. package/dist/tools/inspection-tools.js.map +1 -1
  46. package/dist/tools/meta-tools.d.ts +1 -1
  47. package/dist/tools/meta-tools.d.ts.map +1 -1
  48. package/dist/tools/meta-tools.js +3 -2
  49. package/dist/tools/meta-tools.js.map +1 -1
  50. package/dist/tools/prompt-tools.d.ts.map +1 -1
  51. package/dist/tools/prompt-tools.js +4 -0
  52. package/dist/tools/prompt-tools.js.map +1 -1
  53. package/dist/tools/reporting-tools.d.ts.map +1 -1
  54. package/dist/tools/reporting-tools.js +27 -8
  55. package/dist/tools/reporting-tools.js.map +1 -1
  56. package/dist/tools/repository-tools.d.ts.map +1 -1
  57. package/dist/tools/repository-tools.js +5 -3
  58. package/dist/tools/repository-tools.js.map +1 -1
  59. package/dist/tools/test-run-tools.d.ts.map +1 -1
  60. package/dist/tools/test-run-tools.js +107 -6
  61. package/dist/tools/test-run-tools.js.map +1 -1
  62. package/dist/tools/usage-report-tools.d.ts.map +1 -1
  63. package/dist/tools/usage-report-tools.js +6 -4
  64. package/dist/tools/usage-report-tools.js.map +1 -1
  65. package/dist/tools/web-inspection-tools.d.ts.map +1 -1
  66. package/dist/tools/web-inspection-tools.js +116 -13
  67. package/dist/tools/web-inspection-tools.js.map +1 -1
  68. package/dist/types/digital-ai.d.ts +6 -1
  69. package/dist/types/digital-ai.d.ts.map +1 -1
  70. package/dist/utils/adb-shell.d.ts +25 -0
  71. package/dist/utils/adb-shell.d.ts.map +1 -0
  72. package/dist/utils/adb-shell.js +87 -0
  73. package/dist/utils/adb-shell.js.map +1 -0
  74. package/dist/utils/credential-env.d.ts +36 -0
  75. package/dist/utils/credential-env.d.ts.map +1 -0
  76. package/dist/utils/credential-env.js +57 -0
  77. package/dist/utils/credential-env.js.map +1 -0
  78. package/dist/utils/failure-triage.d.ts +13 -0
  79. package/dist/utils/failure-triage.d.ts.map +1 -0
  80. package/dist/utils/failure-triage.js +53 -0
  81. package/dist/utils/failure-triage.js.map +1 -0
  82. package/dist/utils/locator-recommend.d.ts +27 -0
  83. package/dist/utils/locator-recommend.d.ts.map +1 -0
  84. package/dist/utils/locator-recommend.js +59 -0
  85. package/dist/utils/locator-recommend.js.map +1 -0
  86. package/dist/utils/response-formatter.d.ts +8 -0
  87. package/dist/utils/response-formatter.d.ts.map +1 -1
  88. package/dist/utils/response-formatter.js +34 -2
  89. package/dist/utils/response-formatter.js.map +1 -1
  90. package/dist/utils/usage-report-summary.d.ts +2 -0
  91. package/dist/utils/usage-report-summary.d.ts.map +1 -1
  92. package/dist/utils/usage-report-summary.js +5 -1
  93. package/dist/utils/usage-report-summary.js.map +1 -1
  94. package/package.json +8 -1
  95. package/resources/boilerplate/Android-Native/NodeJS (WebDriver)/wdio-oss.conf.js +1 -0
  96. package/resources/boilerplate/Android-Native/Python/AndroidNative-oss.py +3 -2
  97. package/resources/boilerplate/Android-Native/Python/pip-oss +1 -1
  98. package/resources/boilerplate/Android-Native/Robot Framework/AndroidNative-oss.robot +1 -1
  99. package/resources/boilerplate/iOS-Native/NodeJS (WebDriver)/wdio-oss.conf.js +1 -0
  100. package/resources/boilerplate/iOS-Native/Python/iOSNative-oss.py +3 -2
  101. package/resources/boilerplate/iOS-Native/Python/pip-oss.txt +1 -1
  102. package/resources/boilerplate/iOS-Native/Robot Framework/iOSNative-oss.robot +1 -1
@@ -4,6 +4,7 @@ import { getMyAccountInfo } from './users.js';
4
4
  import { getActiveUrl, getActiveAccessKey } from './client.js';
5
5
  import { checkDeleteAllowed } from './access-level.js';
6
6
  import { isEmulatorQuery } from '../utils/device-query.js';
7
+ import { stopBrowserEventCapture } from './browser-events.js';
7
8
  // In-process session registry — cleared on MCP server restart
8
9
  const sessionRegistry = new Map();
9
10
  // All report IDs created this process lifetime, mapped to the project name they
@@ -235,6 +236,7 @@ export async function createInspectionSession(opts) {
235
236
  }
236
237
  export async function quitInspectionSession(handle, keepReport = false) {
237
238
  const session = requireSession(handle);
239
+ stopBrowserEventCapture(handle); // browser sessions: close the BiDi socket (no-op otherwise)
238
240
  const client = makeClient();
239
241
  // A HAR / device-log capture left running would never be finalised once the session is gone — stop it first
240
242
  // (best-effort: the session may already be dead).
@@ -252,6 +254,18 @@ export async function quitInspectionSession(handle, keepReport = false) {
252
254
  }
253
255
  session[field] = undefined;
254
256
  }
257
+ // A simulated location outlives the session on the device (iOS keeps it until resetSimulatedLocation) — the next
258
+ // user of a shared phone would inherit it. Reset it before quitting (best-effort).
259
+ let geolocationReset;
260
+ if (session.geolocationSet) {
261
+ try {
262
+ await resetGeolocation(handle);
263
+ geolocationReset = true;
264
+ }
265
+ catch {
266
+ geolocationReset = false;
267
+ }
268
+ }
255
269
  try {
256
270
  await client.delete(`/session/${session.gridSessionId}`, { timeout: 30_000 });
257
271
  }
@@ -293,6 +307,7 @@ export async function quitInspectionSession(handle, keepReport = false) {
293
307
  canDeleteReport: session.canDeleteReport,
294
308
  reportTestId: session.reportTestId,
295
309
  reportUrl: session.reportUrl,
310
+ ...(geolocationReset !== undefined ? { geolocationReset } : {}),
296
311
  };
297
312
  }
298
313
  export async function captureScreenshot(handle) {
@@ -382,7 +397,10 @@ const rectToBounds = (r) => {
382
397
  const o = r;
383
398
  if (!o || o.x == null || o.width == null)
384
399
  return null;
385
- return `[${o.x},${o.y}][${o.x + o.width},${(o.y ?? 0) + (o.height ?? 0)}]`;
400
+ // Web elements report fractional CSS pixels (e.g. 165.23809814453125) — round for readability.
401
+ const n = (v) => Math.round(v);
402
+ const y = o.y ?? 0;
403
+ return `[${n(o.x)},${n(y)}][${n(o.x + o.width)},${n(y + (o.height ?? 0))}]`;
386
404
  };
387
405
  const asBool = (v) => (v === true || v === 'true' ? true : v === false || v === 'false' ? false : null);
388
406
  const asStr = (v) => (v == null ? null : String(v));
@@ -397,7 +415,9 @@ export async function findElements(handle, using, value, opts = {}) {
397
415
  const client = makeClient();
398
416
  const sid = session.gridSessionId;
399
417
  const inline = await ensureInlineAttributes(client, session);
400
- const inWebview = isWebviewContext(session);
418
+ // Browser sessions (desktop or a phone's browser) hold web elements too — read them the web way. They used to fall
419
+ // through to the Android native branch (class/resource-id/text attributes), which gave null text on Android Chrome.
420
+ const inWebview = isWebviewContext(session) || session.platform === 'web';
401
421
  let res;
402
422
  try {
403
423
  res = await client.post(`/session/${sid}/elements`, { using, value },
@@ -700,7 +720,9 @@ export function automotiveSessionHint(detail) {
700
720
  }
701
721
  if (/automotive dev mode|start Android Auto/i.test(detail)) {
702
722
  return 'The device could not switch on Android Auto developer mode. It needs Android 10 or later, and not every device ' +
703
- 'or host supports projection: try another device, or ask your platform admin which devices support it.';
723
+ 'or host supports projection. The platform does not say which device it allocated, so a retry with the same ' +
724
+ 'deviceQuery can land on the same phone: pin a different PHONE with device (find_available_device), or ask your ' +
725
+ 'platform admin which devices support it.';
704
726
  }
705
727
  return null;
706
728
  }
@@ -810,10 +832,31 @@ export async function swipeScreen(handle, startX, startY, endX, endY, durationMs
810
832
  }, { timeout: 30_000 });
811
833
  return gestureWithFallback(session, w3c, jwp);
812
834
  }
813
- export async function launchApp(handle, packageName, activity) {
835
+ export async function launchApp(handle, packageName, activity, launchArguments) {
814
836
  const session = requireSession(handle);
815
837
  const client = makeClient();
816
838
  const sid = session.gridSessionId;
839
+ // iOS launch arguments (e.g. -AppleLanguages (de), feature flags) — XCUITest `mobile: launchApp {arguments}`. A RUNNING
840
+ // app ignores them (verified live 2026-11-12, iOS 26.6: Settings stayed French), so the app is terminated first;
841
+ // after the terminate the same call opened Settings in German. Appium Server only — the Grid has no equivalent.
842
+ if (launchArguments && launchArguments.length > 0) {
843
+ if (session.platform !== 'ios')
844
+ throw new Error('launchArguments is iOS only. On Android, pass extras through the activity intent or a deep link.');
845
+ if (session.sessionFormat !== 'w3c')
846
+ throw new Error('launchArguments needs an Appium Server session; Appium Grid has no launch-arguments command.');
847
+ try {
848
+ await client.post(`/session/${sid}/execute/sync`, { script: 'mobile: terminateApp', args: [{ bundleId: packageName }] }, { timeout: 30_000 });
849
+ }
850
+ catch { /* not running — fine */ }
851
+ try {
852
+ await client.post(`/session/${sid}/execute/sync`, { script: 'mobile: launchApp', args: [{ bundleId: packageName, arguments: launchArguments }] }, { timeout: 30_000 });
853
+ }
854
+ catch (e) {
855
+ // Same shape as the other launch paths: the driver's own message, not a bare "status code 500".
856
+ throw new Error(`Could not launch ${packageName} with arguments: mobile: launchApp → ${describeWdError(e)}`);
857
+ }
858
+ return `Relaunched ${packageName} with arguments ${JSON.stringify(launchArguments)} via mobile: launchApp (terminated first — a running app ignores launch arguments)`;
859
+ }
817
860
  const errors = [];
818
861
  const tryAll = async (mechanisms) => {
819
862
  for (const [desc, fn] of mechanisms) {
@@ -1198,6 +1241,46 @@ export async function doubleTap(handle, opts) {
1198
1241
  }, { timeout: 30_000 });
1199
1242
  await gestureWithFallback(session, w3c, jwp);
1200
1243
  }
1244
+ /** Single tap at a screen point — W3C pointer actions, JWP touch/perform on the Grid (same fallback as doubleTap). */
1245
+ export async function tapAt(handle, x, y) {
1246
+ const session = requireSession(handle);
1247
+ const client = makeClient();
1248
+ const sid = session.gridSessionId;
1249
+ const jwp = () => client.post(`/session/${sid}/touch/perform`, { actions: [{ action: 'tap', options: { x, y } }] }, { timeout: 30_000 });
1250
+ const w3c = () => client.post(`/session/${sid}/actions`, {
1251
+ actions: [{
1252
+ type: 'pointer', id: 'finger1', parameters: { pointerType: 'touch' },
1253
+ actions: [
1254
+ { type: 'pointerMove', duration: 0, x, y },
1255
+ { type: 'pointerDown', button: 0 },
1256
+ { type: 'pause', duration: 80 },
1257
+ { type: 'pointerUp', button: 0 },
1258
+ ],
1259
+ }],
1260
+ }, { timeout: 30_000 });
1261
+ await gestureWithFallback(session, w3c, jwp);
1262
+ }
1263
+ /**
1264
+ * Android app runtime permissions (Appium Server, UiAutomator2 — verified live 2026-11-12 on a Pixel 7 / Android 14):
1265
+ * mobile: getPermissions {type, appPackage} lists requested / granted / denied; mobile: changePermissions grants or
1266
+ * revokes. Only permissions the app declares can change (granting an undeclared CAMERA was a silent no-op), and
1267
+ * REVOKING kills the app process — Android does that to any app whose permission is revoked.
1268
+ */
1269
+ export async function appPermissions(handle, action, appPackage, permissions = []) {
1270
+ const session = requireSession(handle);
1271
+ if (session.platform !== 'android' || session.sessionFormat !== 'w3c') {
1272
+ throw new Error('Permissions are an Android Appium Server feature (mobile: getPermissions / changePermissions). On iOS the system dialog is a normal alert — use device_control accept_alert / dismiss_alert.');
1273
+ }
1274
+ const client = makeClient();
1275
+ if (action !== 'list') {
1276
+ await execScript(client, session, 'mobile: changePermissions', [{ permissions, appPackage, action }], 30_000);
1277
+ }
1278
+ const get = async (type) => {
1279
+ const r = await execScript(client, session, 'mobile: getPermissions', [{ type, appPackage }], 30_000);
1280
+ return Array.isArray(r.data.value) ? r.data.value : [];
1281
+ };
1282
+ return { requested: await get('requested'), granted: await get('granted'), denied: await get('denied') };
1283
+ }
1201
1284
  export async function dragAndDrop(handle, startX, startY, endX, endY, holdMs = 600, moveMs = 1200) {
1202
1285
  const session = requireSession(handle);
1203
1286
  const client = makeClient();
@@ -1370,10 +1453,13 @@ const IOS_BUTTONS = {
1370
1453
  VOLUME_DOWN: { w3c: 'volumedown', grid: 'Volume Down' },
1371
1454
  POWER: { w3c: null, grid: 'Lock' },
1372
1455
  };
1373
- export async function pressKey(handle, key, keycode) {
1456
+ export async function pressKey(handle, key, keycode, longPress = false) {
1374
1457
  const session = requireSession(handle);
1375
1458
  const client = makeClient();
1376
1459
  const sid = session.gridSessionId;
1460
+ if (longPress && (session.platform === 'ios' || session.sessionFormat !== 'w3c')) {
1461
+ throw new Error('longPress is available on Android Appium Server sessions only (mobile: pressKey isLongPress).');
1462
+ }
1377
1463
  if (session.platform === 'ios') {
1378
1464
  const button = key ? IOS_BUTTONS[key] : undefined;
1379
1465
  if (!button) {
@@ -1411,7 +1497,12 @@ export async function pressKey(handle, key, keycode) {
1411
1497
  throw new Error('Provide a named key or an Android keycode.');
1412
1498
  // Confirmed live: the Grid routes the legacy press_keycode endpoint.
1413
1499
  const jwp = () => client.post(`/session/${sid}/appium/device/press_keycode`, { keycode: code }, { timeout: 15_000 });
1414
- const w3c = () => execScript(client, session, 'mobile: pressKey', [{ keycode: code }]);
1500
+ // isLongPress verified live 2026-11-12: a long HOME opened Google Assistant on a Galaxy S21 (Android 12).
1501
+ const w3c = () => execScript(client, session, 'mobile: pressKey', [longPress ? { keycode: code, isLongPress: true } : { keycode: code }]);
1502
+ if (longPress) {
1503
+ await w3c();
1504
+ return `${key ?? `keycode ${code}`} (long press)`;
1505
+ }
1415
1506
  const [primary, fallback] = session.sessionFormat === 'w3c' ? [w3c, jwp] : [jwp, w3c];
1416
1507
  try {
1417
1508
  await primary();
@@ -1492,8 +1583,26 @@ export async function appControl(handle, action, packageName, url, opts = {}) {
1492
1583
  const seconds = Math.max(1, Math.round(opts.seconds ?? 3));
1493
1584
  if (!isW3c)
1494
1585
  throw new Error('background is not available on Appium Grid sessions — press HOME (press_key) and relaunch with launch_app instead.');
1586
+ // backgroundApp acts on WHATEVER is in front and restores that — it said "brought back" for an app that was never
1587
+ // in front when the session had left the launcher showing (UAT 2026-11-13). Name what was actually in front.
1588
+ const front = async () => {
1589
+ if (!isIos)
1590
+ return getForegroundPackage(handle);
1591
+ try {
1592
+ const id = (await execScript(client, session, 'mobile: activeAppInfo')).data.value?.bundleId;
1593
+ return typeof id === 'string' && id ? id : null;
1594
+ }
1595
+ catch {
1596
+ return null;
1597
+ }
1598
+ };
1599
+ const before = await front();
1495
1600
  await execScript(client, session, 'mobile: backgroundApp', [{ seconds }], (seconds + 20) * 1000);
1496
- return `App sent to the background for ${seconds} s and brought back to the foreground. Verify the restored screen with take_inspection_screenshot.`;
1601
+ const after = await front();
1602
+ if (packageName && before && before !== packageName) {
1603
+ return `${packageName} was NOT in the foreground (${before} was), so nothing of it was backgrounded — ${before} was sent to the background for ${seconds} s and ${after ?? 'an app'} is in front now. Open the app first with launch_app.`;
1604
+ }
1605
+ return `${before ?? 'The foreground app'} was sent to the background for ${seconds} s; ${after ? `${after} is in front now` : 'the foreground could not be read afterwards'}. Verify the restored screen with take_inspection_screenshot.`;
1497
1606
  }
1498
1607
  case 'is_installed': {
1499
1608
  if (!packageName)
@@ -1589,9 +1698,11 @@ export async function appControl(handle, action, packageName, url, opts = {}) {
1589
1698
  throw new Error('deep_link requires url.');
1590
1699
  if (isW3c) {
1591
1700
  const args = { url };
1592
- // Android needs the handler package; iOS routes through the system.
1593
- if (packageName && !isIos)
1594
- args['package'] = packageName;
1701
+ // Android: the handler package. iOS: the bundle id of the app that should open it — com.apple.mobilesafari
1702
+ // opens a web URL straight in Safari with no "Open in …?" prompt (verified live 2026-11-12, iOS 26.6), so no
1703
+ // address-bar typing is needed.
1704
+ if (packageName)
1705
+ args[isIos ? 'bundleId' : 'package'] = packageName;
1595
1706
  await execScript(client, session, 'mobile: deepLink', [args]);
1596
1707
  return `Opened deep link ${url}.`;
1597
1708
  }
@@ -1663,6 +1774,7 @@ export async function setGeolocation(handle, latitude, longitude) {
1663
1774
  // setSimulatedLocation; UiAutomator2 uses setGeolocation — both confirmed live.
1664
1775
  const script = session.platform === 'ios' ? 'mobile: setSimulatedLocation' : 'mobile: setGeolocation';
1665
1776
  await execScript(client, session, script, [{ latitude, longitude }]);
1777
+ session.geolocationSet = true;
1666
1778
  return;
1667
1779
  }
1668
1780
  // Confirmed live on the Grid (both platforms): seetest:client.setLocation, string args.
@@ -1670,6 +1782,7 @@ export async function setGeolocation(handle, latitude, longitude) {
1670
1782
  String(latitude),
1671
1783
  String(longitude),
1672
1784
  ]);
1785
+ session.geolocationSet = true;
1673
1786
  }
1674
1787
  export async function resetGeolocation(handle) {
1675
1788
  const session = requireSession(handle);
@@ -1677,10 +1790,12 @@ export async function resetGeolocation(handle) {
1677
1790
  if (session.sessionFormat === 'jwp') {
1678
1791
  // seetest:client.clearLocation() — inline 0-arg form (execScript adds the parentheses on the Grid).
1679
1792
  await execScript(client, session, 'seetest:client.clearLocation', []);
1793
+ session.geolocationSet = false;
1680
1794
  return;
1681
1795
  }
1682
1796
  const script = session.platform === 'ios' ? 'mobile: resetSimulatedLocation' : 'mobile: resetGeolocation';
1683
1797
  await execScript(client, session, script, [{}]);
1798
+ session.geolocationSet = false;
1684
1799
  }
1685
1800
  /** Alert text and, on iOS Appium Server, its button labels (`mobile: alert getButtons` → ["Yes","No"] live 2026-10-18). */
1686
1801
  export async function getAlertInfo(handle) {
@@ -1828,7 +1943,7 @@ export async function sessionCapture(handle, kind, action, name) {
1828
1943
  try {
1829
1944
  const { listFiles } = await import('./repository.js');
1830
1945
  for (let i = 0; i < 5 && !repositoryFile; i++) {
1831
- const hit = (await listFiles()).find((f) => f.uniqueName === file);
1946
+ const hit = (await listFiles({ uniqueName: file })).find((f) => f.uniqueName === file); // a miss re-fetches (cache)
1832
1947
  if (hit)
1833
1948
  repositoryFile = { id: hit.id, size: Number(hit.size ?? 0) };
1834
1949
  else
@@ -1986,6 +2101,26 @@ export async function accessibilityAudit(handle) {
1986
2101
  const r = await execScript(makeClient(), session, 'mobile: performAccessibilityAudit', [{}], 60_000);
1987
2102
  return Array.isArray(r.data.value) ? r.data.value : [];
1988
2103
  }
2104
+ /**
2105
+ * Run an adb shell command on an Android Appium Server session (`mobile: shell`, verified live 2026-11-12). The Grid's
2106
+ * execute layer accepts only seetest:client.* (and seetest:client.run is "not implemented" on Appium Server), and iOS
2107
+ * has no shell. Callers must classify the command first (src/utils/adb-shell.ts) — this function does not guard.
2108
+ */
2109
+ export async function adbShell(handle, command, args = [], timeoutMs = 60_000) {
2110
+ const session = requireSession(handle);
2111
+ if (session.platform !== 'android')
2112
+ throw new Error('shell is Android only — iOS devices have no adb shell.');
2113
+ if (session.sessionFormat !== 'w3c') {
2114
+ throw new Error('shell needs an Appium Server project: the Appium Grid only runs seetest:client commands. Use get_remote_debug_command for a full adb connection instead.');
2115
+ }
2116
+ try {
2117
+ const r = await execScript(makeClient(), session, 'mobile: shell', [{ command, args, timeout: timeoutMs }], timeoutMs + 5_000);
2118
+ return typeof r.data.value === 'string' ? r.data.value : JSON.stringify(r.data.value ?? '');
2119
+ }
2120
+ catch (e) {
2121
+ throw new Error(`adb shell "${[command, ...args].join(' ')}" failed: ${describeWdError(e)}`);
2122
+ }
2123
+ }
1989
2124
  export function isWebviewContext(session) {
1990
2125
  return !!session.currentContext && session.currentContext !== 'NATIVE_APP';
1991
2126
  }
@@ -2128,6 +2263,23 @@ export async function getForegroundActivity(handle) {
2128
2263
  return null;
2129
2264
  }
2130
2265
  }
2266
+ /** The Android package in the foreground right now, or null when it cannot be read (never fatal). */
2267
+ export async function getForegroundPackage(handle) {
2268
+ const session = requireSession(handle);
2269
+ if (session.platform !== 'android')
2270
+ return null;
2271
+ const client = makeClient();
2272
+ try {
2273
+ const r = session.sessionFormat === 'w3c'
2274
+ ? await execScript(client, session, 'mobile: getCurrentPackage')
2275
+ : await client.get(`/session/${session.gridSessionId}/appium/device/current_package`, { timeout: 15_000 });
2276
+ const pkg = r.data?.value;
2277
+ return typeof pkg === 'string' && pkg ? pkg : null;
2278
+ }
2279
+ catch {
2280
+ return null;
2281
+ }
2282
+ }
2131
2283
  /** True when `current` is the activity the caller asked for — `.LoginActivity` vs `com.x.app.LoginActivity` are the same screen. */
2132
2284
  export function isSameActivity(requested, current) {
2133
2285
  const tail = (a) => a.split(/[./]/).filter(Boolean).pop()?.toLowerCase() ?? '';