digital-ai-testing-mcp 2.2.2 → 2.3.0

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 (97) 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-runs.d.ts +5 -0
  22. package/dist/api/test-runs.d.ts.map +1 -1
  23. package/dist/api/test-runs.js.map +1 -1
  24. package/dist/api/webdriver.d.ts +23 -2
  25. package/dist/api/webdriver.d.ts.map +1 -1
  26. package/dist/api/webdriver.js +124 -9
  27. package/dist/api/webdriver.js.map +1 -1
  28. package/dist/index.js +1 -1
  29. package/dist/tools/boilerplate-tools.d.ts +22 -0
  30. package/dist/tools/boilerplate-tools.d.ts.map +1 -1
  31. package/dist/tools/boilerplate-tools.js +321 -43
  32. package/dist/tools/boilerplate-tools.js.map +1 -1
  33. package/dist/tools/device-group-tools.js +2 -2
  34. package/dist/tools/device-group-tools.js.map +1 -1
  35. package/dist/tools/device-tools.js +3 -3
  36. package/dist/tools/device-tools.js.map +1 -1
  37. package/dist/tools/inspection-tools.d.ts +24 -0
  38. package/dist/tools/inspection-tools.d.ts.map +1 -1
  39. package/dist/tools/inspection-tools.js +129 -13
  40. package/dist/tools/inspection-tools.js.map +1 -1
  41. package/dist/tools/meta-tools.d.ts +1 -1
  42. package/dist/tools/meta-tools.d.ts.map +1 -1
  43. package/dist/tools/meta-tools.js +3 -2
  44. package/dist/tools/meta-tools.js.map +1 -1
  45. package/dist/tools/prompt-tools.d.ts.map +1 -1
  46. package/dist/tools/prompt-tools.js +4 -0
  47. package/dist/tools/prompt-tools.js.map +1 -1
  48. package/dist/tools/reporting-tools.d.ts.map +1 -1
  49. package/dist/tools/reporting-tools.js +27 -8
  50. package/dist/tools/reporting-tools.js.map +1 -1
  51. package/dist/tools/repository-tools.d.ts.map +1 -1
  52. package/dist/tools/repository-tools.js +5 -3
  53. package/dist/tools/repository-tools.js.map +1 -1
  54. package/dist/tools/test-run-tools.d.ts.map +1 -1
  55. package/dist/tools/test-run-tools.js +107 -6
  56. package/dist/tools/test-run-tools.js.map +1 -1
  57. package/dist/tools/usage-report-tools.d.ts.map +1 -1
  58. package/dist/tools/usage-report-tools.js +6 -4
  59. package/dist/tools/usage-report-tools.js.map +1 -1
  60. package/dist/tools/web-inspection-tools.d.ts.map +1 -1
  61. package/dist/tools/web-inspection-tools.js +116 -13
  62. package/dist/tools/web-inspection-tools.js.map +1 -1
  63. package/dist/types/digital-ai.d.ts +6 -1
  64. package/dist/types/digital-ai.d.ts.map +1 -1
  65. package/dist/utils/adb-shell.d.ts +25 -0
  66. package/dist/utils/adb-shell.d.ts.map +1 -0
  67. package/dist/utils/adb-shell.js +87 -0
  68. package/dist/utils/adb-shell.js.map +1 -0
  69. package/dist/utils/credential-env.d.ts +36 -0
  70. package/dist/utils/credential-env.d.ts.map +1 -0
  71. package/dist/utils/credential-env.js +57 -0
  72. package/dist/utils/credential-env.js.map +1 -0
  73. package/dist/utils/failure-triage.d.ts +13 -0
  74. package/dist/utils/failure-triage.d.ts.map +1 -0
  75. package/dist/utils/failure-triage.js +53 -0
  76. package/dist/utils/failure-triage.js.map +1 -0
  77. package/dist/utils/locator-recommend.d.ts +27 -0
  78. package/dist/utils/locator-recommend.d.ts.map +1 -0
  79. package/dist/utils/locator-recommend.js +59 -0
  80. package/dist/utils/locator-recommend.js.map +1 -0
  81. package/dist/utils/response-formatter.d.ts +8 -0
  82. package/dist/utils/response-formatter.d.ts.map +1 -1
  83. package/dist/utils/response-formatter.js +26 -0
  84. package/dist/utils/response-formatter.js.map +1 -1
  85. package/dist/utils/usage-report-summary.d.ts +2 -0
  86. package/dist/utils/usage-report-summary.d.ts.map +1 -1
  87. package/dist/utils/usage-report-summary.js +5 -1
  88. package/dist/utils/usage-report-summary.js.map +1 -1
  89. package/package.json +8 -1
  90. package/resources/boilerplate/Android-Native/NodeJS (WebDriver)/wdio-oss.conf.js +1 -0
  91. package/resources/boilerplate/Android-Native/Python/AndroidNative-oss.py +3 -2
  92. package/resources/boilerplate/Android-Native/Python/pip-oss +1 -1
  93. package/resources/boilerplate/Android-Native/Robot Framework/AndroidNative-oss.robot +1 -1
  94. package/resources/boilerplate/iOS-Native/NodeJS (WebDriver)/wdio-oss.conf.js +1 -0
  95. package/resources/boilerplate/iOS-Native/Python/iOSNative-oss.py +3 -2
  96. package/resources/boilerplate/iOS-Native/Python/pip-oss.txt +1 -1
  97. 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 },
@@ -810,10 +830,31 @@ export async function swipeScreen(handle, startX, startY, endX, endY, durationMs
810
830
  }, { timeout: 30_000 });
811
831
  return gestureWithFallback(session, w3c, jwp);
812
832
  }
813
- export async function launchApp(handle, packageName, activity) {
833
+ export async function launchApp(handle, packageName, activity, launchArguments) {
814
834
  const session = requireSession(handle);
815
835
  const client = makeClient();
816
836
  const sid = session.gridSessionId;
837
+ // iOS launch arguments (e.g. -AppleLanguages (de), feature flags) — XCUITest `mobile: launchApp {arguments}`. A RUNNING
838
+ // app ignores them (verified live 2026-11-12, iOS 26.6: Settings stayed French), so the app is terminated first;
839
+ // after the terminate the same call opened Settings in German. Appium Server only — the Grid has no equivalent.
840
+ if (launchArguments && launchArguments.length > 0) {
841
+ if (session.platform !== 'ios')
842
+ throw new Error('launchArguments is iOS only. On Android, pass extras through the activity intent or a deep link.');
843
+ if (session.sessionFormat !== 'w3c')
844
+ throw new Error('launchArguments needs an Appium Server session; Appium Grid has no launch-arguments command.');
845
+ try {
846
+ await client.post(`/session/${sid}/execute/sync`, { script: 'mobile: terminateApp', args: [{ bundleId: packageName }] }, { timeout: 30_000 });
847
+ }
848
+ catch { /* not running — fine */ }
849
+ try {
850
+ await client.post(`/session/${sid}/execute/sync`, { script: 'mobile: launchApp', args: [{ bundleId: packageName, arguments: launchArguments }] }, { timeout: 30_000 });
851
+ }
852
+ catch (e) {
853
+ // Same shape as the other launch paths: the driver's own message, not a bare "status code 500".
854
+ throw new Error(`Could not launch ${packageName} with arguments: mobile: launchApp → ${describeWdError(e)}`);
855
+ }
856
+ return `Relaunched ${packageName} with arguments ${JSON.stringify(launchArguments)} via mobile: launchApp (terminated first — a running app ignores launch arguments)`;
857
+ }
817
858
  const errors = [];
818
859
  const tryAll = async (mechanisms) => {
819
860
  for (const [desc, fn] of mechanisms) {
@@ -1198,6 +1239,46 @@ export async function doubleTap(handle, opts) {
1198
1239
  }, { timeout: 30_000 });
1199
1240
  await gestureWithFallback(session, w3c, jwp);
1200
1241
  }
1242
+ /** Single tap at a screen point — W3C pointer actions, JWP touch/perform on the Grid (same fallback as doubleTap). */
1243
+ export async function tapAt(handle, x, y) {
1244
+ const session = requireSession(handle);
1245
+ const client = makeClient();
1246
+ const sid = session.gridSessionId;
1247
+ const jwp = () => client.post(`/session/${sid}/touch/perform`, { actions: [{ action: 'tap', options: { x, y } }] }, { timeout: 30_000 });
1248
+ const w3c = () => client.post(`/session/${sid}/actions`, {
1249
+ actions: [{
1250
+ type: 'pointer', id: 'finger1', parameters: { pointerType: 'touch' },
1251
+ actions: [
1252
+ { type: 'pointerMove', duration: 0, x, y },
1253
+ { type: 'pointerDown', button: 0 },
1254
+ { type: 'pause', duration: 80 },
1255
+ { type: 'pointerUp', button: 0 },
1256
+ ],
1257
+ }],
1258
+ }, { timeout: 30_000 });
1259
+ await gestureWithFallback(session, w3c, jwp);
1260
+ }
1261
+ /**
1262
+ * Android app runtime permissions (Appium Server, UiAutomator2 — verified live 2026-11-12 on a Pixel 7 / Android 14):
1263
+ * mobile: getPermissions {type, appPackage} lists requested / granted / denied; mobile: changePermissions grants or
1264
+ * revokes. Only permissions the app declares can change (granting an undeclared CAMERA was a silent no-op), and
1265
+ * REVOKING kills the app process — Android does that to any app whose permission is revoked.
1266
+ */
1267
+ export async function appPermissions(handle, action, appPackage, permissions = []) {
1268
+ const session = requireSession(handle);
1269
+ if (session.platform !== 'android' || session.sessionFormat !== 'w3c') {
1270
+ 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.');
1271
+ }
1272
+ const client = makeClient();
1273
+ if (action !== 'list') {
1274
+ await execScript(client, session, 'mobile: changePermissions', [{ permissions, appPackage, action }], 30_000);
1275
+ }
1276
+ const get = async (type) => {
1277
+ const r = await execScript(client, session, 'mobile: getPermissions', [{ type, appPackage }], 30_000);
1278
+ return Array.isArray(r.data.value) ? r.data.value : [];
1279
+ };
1280
+ return { requested: await get('requested'), granted: await get('granted'), denied: await get('denied') };
1281
+ }
1201
1282
  export async function dragAndDrop(handle, startX, startY, endX, endY, holdMs = 600, moveMs = 1200) {
1202
1283
  const session = requireSession(handle);
1203
1284
  const client = makeClient();
@@ -1370,10 +1451,13 @@ const IOS_BUTTONS = {
1370
1451
  VOLUME_DOWN: { w3c: 'volumedown', grid: 'Volume Down' },
1371
1452
  POWER: { w3c: null, grid: 'Lock' },
1372
1453
  };
1373
- export async function pressKey(handle, key, keycode) {
1454
+ export async function pressKey(handle, key, keycode, longPress = false) {
1374
1455
  const session = requireSession(handle);
1375
1456
  const client = makeClient();
1376
1457
  const sid = session.gridSessionId;
1458
+ if (longPress && (session.platform === 'ios' || session.sessionFormat !== 'w3c')) {
1459
+ throw new Error('longPress is available on Android Appium Server sessions only (mobile: pressKey isLongPress).');
1460
+ }
1377
1461
  if (session.platform === 'ios') {
1378
1462
  const button = key ? IOS_BUTTONS[key] : undefined;
1379
1463
  if (!button) {
@@ -1411,7 +1495,12 @@ export async function pressKey(handle, key, keycode) {
1411
1495
  throw new Error('Provide a named key or an Android keycode.');
1412
1496
  // Confirmed live: the Grid routes the legacy press_keycode endpoint.
1413
1497
  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 }]);
1498
+ // isLongPress verified live 2026-11-12: a long HOME opened Google Assistant on a Galaxy S21 (Android 12).
1499
+ const w3c = () => execScript(client, session, 'mobile: pressKey', [longPress ? { keycode: code, isLongPress: true } : { keycode: code }]);
1500
+ if (longPress) {
1501
+ await w3c();
1502
+ return `${key ?? `keycode ${code}`} (long press)`;
1503
+ }
1415
1504
  const [primary, fallback] = session.sessionFormat === 'w3c' ? [w3c, jwp] : [jwp, w3c];
1416
1505
  try {
1417
1506
  await primary();
@@ -1589,9 +1678,11 @@ export async function appControl(handle, action, packageName, url, opts = {}) {
1589
1678
  throw new Error('deep_link requires url.');
1590
1679
  if (isW3c) {
1591
1680
  const args = { url };
1592
- // Android needs the handler package; iOS routes through the system.
1593
- if (packageName && !isIos)
1594
- args['package'] = packageName;
1681
+ // Android: the handler package. iOS: the bundle id of the app that should open it — com.apple.mobilesafari
1682
+ // opens a web URL straight in Safari with no "Open in …?" prompt (verified live 2026-11-12, iOS 26.6), so no
1683
+ // address-bar typing is needed.
1684
+ if (packageName)
1685
+ args[isIos ? 'bundleId' : 'package'] = packageName;
1595
1686
  await execScript(client, session, 'mobile: deepLink', [args]);
1596
1687
  return `Opened deep link ${url}.`;
1597
1688
  }
@@ -1663,6 +1754,7 @@ export async function setGeolocation(handle, latitude, longitude) {
1663
1754
  // setSimulatedLocation; UiAutomator2 uses setGeolocation — both confirmed live.
1664
1755
  const script = session.platform === 'ios' ? 'mobile: setSimulatedLocation' : 'mobile: setGeolocation';
1665
1756
  await execScript(client, session, script, [{ latitude, longitude }]);
1757
+ session.geolocationSet = true;
1666
1758
  return;
1667
1759
  }
1668
1760
  // Confirmed live on the Grid (both platforms): seetest:client.setLocation, string args.
@@ -1670,6 +1762,7 @@ export async function setGeolocation(handle, latitude, longitude) {
1670
1762
  String(latitude),
1671
1763
  String(longitude),
1672
1764
  ]);
1765
+ session.geolocationSet = true;
1673
1766
  }
1674
1767
  export async function resetGeolocation(handle) {
1675
1768
  const session = requireSession(handle);
@@ -1677,10 +1770,12 @@ export async function resetGeolocation(handle) {
1677
1770
  if (session.sessionFormat === 'jwp') {
1678
1771
  // seetest:client.clearLocation() — inline 0-arg form (execScript adds the parentheses on the Grid).
1679
1772
  await execScript(client, session, 'seetest:client.clearLocation', []);
1773
+ session.geolocationSet = false;
1680
1774
  return;
1681
1775
  }
1682
1776
  const script = session.platform === 'ios' ? 'mobile: resetSimulatedLocation' : 'mobile: resetGeolocation';
1683
1777
  await execScript(client, session, script, [{}]);
1778
+ session.geolocationSet = false;
1684
1779
  }
1685
1780
  /** Alert text and, on iOS Appium Server, its button labels (`mobile: alert getButtons` → ["Yes","No"] live 2026-10-18). */
1686
1781
  export async function getAlertInfo(handle) {
@@ -1828,7 +1923,7 @@ export async function sessionCapture(handle, kind, action, name) {
1828
1923
  try {
1829
1924
  const { listFiles } = await import('./repository.js');
1830
1925
  for (let i = 0; i < 5 && !repositoryFile; i++) {
1831
- const hit = (await listFiles()).find((f) => f.uniqueName === file);
1926
+ const hit = (await listFiles({ uniqueName: file })).find((f) => f.uniqueName === file); // a miss re-fetches (cache)
1832
1927
  if (hit)
1833
1928
  repositoryFile = { id: hit.id, size: Number(hit.size ?? 0) };
1834
1929
  else
@@ -1986,6 +2081,26 @@ export async function accessibilityAudit(handle) {
1986
2081
  const r = await execScript(makeClient(), session, 'mobile: performAccessibilityAudit', [{}], 60_000);
1987
2082
  return Array.isArray(r.data.value) ? r.data.value : [];
1988
2083
  }
2084
+ /**
2085
+ * Run an adb shell command on an Android Appium Server session (`mobile: shell`, verified live 2026-11-12). The Grid's
2086
+ * execute layer accepts only seetest:client.* (and seetest:client.run is "not implemented" on Appium Server), and iOS
2087
+ * has no shell. Callers must classify the command first (src/utils/adb-shell.ts) — this function does not guard.
2088
+ */
2089
+ export async function adbShell(handle, command, args = [], timeoutMs = 60_000) {
2090
+ const session = requireSession(handle);
2091
+ if (session.platform !== 'android')
2092
+ throw new Error('shell is Android only — iOS devices have no adb shell.');
2093
+ if (session.sessionFormat !== 'w3c') {
2094
+ 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.');
2095
+ }
2096
+ try {
2097
+ const r = await execScript(makeClient(), session, 'mobile: shell', [{ command, args, timeout: timeoutMs }], timeoutMs + 5_000);
2098
+ return typeof r.data.value === 'string' ? r.data.value : JSON.stringify(r.data.value ?? '');
2099
+ }
2100
+ catch (e) {
2101
+ throw new Error(`adb shell "${[command, ...args].join(' ')}" failed: ${describeWdError(e)}`);
2102
+ }
2103
+ }
1989
2104
  export function isWebviewContext(session) {
1990
2105
  return !!session.currentContext && session.currentContext !== 'NATIVE_APP';
1991
2106
  }