digital-ai-testing-mcp 2.2.1 → 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.
- package/README.md +28 -16
- package/dist/api/browser-events.d.ts +48 -0
- package/dist/api/browser-events.d.ts.map +1 -0
- package/dist/api/browser-events.js +155 -0
- package/dist/api/browser-events.js.map +1 -0
- package/dist/api/browser-inspection.d.ts +21 -0
- package/dist/api/browser-inspection.d.ts.map +1 -1
- package/dist/api/browser-inspection.js +113 -20
- package/dist/api/browser-inspection.js.map +1 -1
- package/dist/api/playwright-runs.d.ts +42 -0
- package/dist/api/playwright-runs.d.ts.map +1 -0
- package/dist/api/playwright-runs.js +207 -0
- package/dist/api/playwright-runs.js.map +1 -0
- package/dist/api/reporting.d.ts.map +1 -1
- package/dist/api/reporting.js +4 -2
- package/dist/api/reporting.js.map +1 -1
- package/dist/api/repository.d.ts +13 -1
- package/dist/api/repository.d.ts.map +1 -1
- package/dist/api/repository.js +39 -4
- package/dist/api/repository.js.map +1 -1
- package/dist/api/test-runs.d.ts +5 -0
- package/dist/api/test-runs.d.ts.map +1 -1
- package/dist/api/test-runs.js.map +1 -1
- package/dist/api/webdriver.d.ts +23 -2
- package/dist/api/webdriver.d.ts.map +1 -1
- package/dist/api/webdriver.js +142 -13
- package/dist/api/webdriver.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/tools/boilerplate-tools.d.ts +22 -0
- package/dist/tools/boilerplate-tools.d.ts.map +1 -1
- package/dist/tools/boilerplate-tools.js +323 -44
- package/dist/tools/boilerplate-tools.js.map +1 -1
- package/dist/tools/device-group-tools.js +2 -2
- package/dist/tools/device-group-tools.js.map +1 -1
- package/dist/tools/device-tools.js +3 -3
- package/dist/tools/device-tools.js.map +1 -1
- package/dist/tools/inspection-tools.d.ts +24 -0
- package/dist/tools/inspection-tools.d.ts.map +1 -1
- package/dist/tools/inspection-tools.js +129 -13
- package/dist/tools/inspection-tools.js.map +1 -1
- package/dist/tools/meta-tools.d.ts +1 -1
- package/dist/tools/meta-tools.d.ts.map +1 -1
- package/dist/tools/meta-tools.js +3 -2
- package/dist/tools/meta-tools.js.map +1 -1
- package/dist/tools/prompt-tools.d.ts.map +1 -1
- package/dist/tools/prompt-tools.js +4 -0
- package/dist/tools/prompt-tools.js.map +1 -1
- package/dist/tools/reporting-tools.d.ts.map +1 -1
- package/dist/tools/reporting-tools.js +27 -8
- package/dist/tools/reporting-tools.js.map +1 -1
- package/dist/tools/repository-tools.d.ts.map +1 -1
- package/dist/tools/repository-tools.js +5 -3
- package/dist/tools/repository-tools.js.map +1 -1
- package/dist/tools/test-run-tools.d.ts.map +1 -1
- package/dist/tools/test-run-tools.js +107 -6
- package/dist/tools/test-run-tools.js.map +1 -1
- package/dist/tools/usage-report-tools.d.ts.map +1 -1
- package/dist/tools/usage-report-tools.js +6 -4
- package/dist/tools/usage-report-tools.js.map +1 -1
- package/dist/tools/web-inspection-tools.d.ts.map +1 -1
- package/dist/tools/web-inspection-tools.js +116 -13
- package/dist/tools/web-inspection-tools.js.map +1 -1
- package/dist/types/digital-ai.d.ts +6 -1
- package/dist/types/digital-ai.d.ts.map +1 -1
- package/dist/utils/adb-shell.d.ts +25 -0
- package/dist/utils/adb-shell.d.ts.map +1 -0
- package/dist/utils/adb-shell.js +87 -0
- package/dist/utils/adb-shell.js.map +1 -0
- package/dist/utils/credential-env.d.ts +36 -0
- package/dist/utils/credential-env.d.ts.map +1 -0
- package/dist/utils/credential-env.js +57 -0
- package/dist/utils/credential-env.js.map +1 -0
- package/dist/utils/failure-triage.d.ts +13 -0
- package/dist/utils/failure-triage.d.ts.map +1 -0
- package/dist/utils/failure-triage.js +53 -0
- package/dist/utils/failure-triage.js.map +1 -0
- package/dist/utils/locator-recommend.d.ts +27 -0
- package/dist/utils/locator-recommend.d.ts.map +1 -0
- package/dist/utils/locator-recommend.js +59 -0
- package/dist/utils/locator-recommend.js.map +1 -0
- package/dist/utils/response-formatter.d.ts +8 -0
- package/dist/utils/response-formatter.d.ts.map +1 -1
- package/dist/utils/response-formatter.js +26 -0
- package/dist/utils/response-formatter.js.map +1 -1
- package/dist/utils/usage-report-summary.d.ts +2 -0
- package/dist/utils/usage-report-summary.d.ts.map +1 -1
- package/dist/utils/usage-report-summary.js +5 -1
- package/dist/utils/usage-report-summary.js.map +1 -1
- package/package.json +13 -6
- package/resources/boilerplate/Android-Native/NodeJS (WebDriver)/wdio-oss.conf.js +1 -0
- package/resources/boilerplate/Android-Native/Python/AndroidNative-oss.py +3 -2
- package/resources/boilerplate/Android-Native/Python/pip-oss +1 -1
- package/resources/boilerplate/Android-Native/Robot Framework/AndroidNative-oss.robot +1 -1
- package/resources/boilerplate/iOS-Native/NodeJS (WebDriver)/wdio-oss.conf.js +1 -0
- package/resources/boilerplate/iOS-Native/Python/iOSNative-oss.py +3 -2
- package/resources/boilerplate/iOS-Native/Python/pip-oss.txt +1 -1
- package/resources/boilerplate/iOS-Native/Robot Framework/iOSNative-oss.robot +1 -1
|
@@ -1,3 +1,27 @@
|
|
|
1
1
|
import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
|
|
2
|
+
interface ParsedElement {
|
|
3
|
+
className: string;
|
|
4
|
+
resourceId: string | null;
|
|
5
|
+
contentDesc: string | null;
|
|
6
|
+
text: string | null;
|
|
7
|
+
bounds: string | null;
|
|
8
|
+
clickable: boolean;
|
|
9
|
+
enabled: boolean;
|
|
10
|
+
fullResourceId: string | null;
|
|
11
|
+
name: string | null;
|
|
12
|
+
label: string | null;
|
|
13
|
+
value: string | null;
|
|
14
|
+
}
|
|
15
|
+
declare function parseElementTree(xml: string, platform: 'android' | 'ios'): {
|
|
16
|
+
elements: ParsedElement[];
|
|
17
|
+
totalNodes: number;
|
|
18
|
+
};
|
|
19
|
+
declare function formatElementTable(elements: ParsedElement[], totalNodes: number, platform: 'android' | 'ios'): string;
|
|
20
|
+
/** Test seam: the element-table pipeline get_element_tree uses. */
|
|
21
|
+
export declare const __elementTreeForTests: {
|
|
22
|
+
parseElementTree: typeof parseElementTree;
|
|
23
|
+
formatElementTable: typeof formatElementTable;
|
|
24
|
+
};
|
|
2
25
|
export declare function registerInspectionTools(server: McpServer): void;
|
|
26
|
+
export {};
|
|
3
27
|
//# sourceMappingURL=inspection-tools.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"inspection-tools.d.ts","sourceRoot":"","sources":["../../src/tools/inspection-tools.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;
|
|
1
|
+
{"version":3,"file":"inspection-tools.d.ts","sourceRoot":"","sources":["../../src/tools/inspection-tools.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAkJzE,UAAU,aAAa;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAE9B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,iBAAS,gBAAgB,CACvB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,SAAS,GAAG,KAAK,GAC1B;IACD,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;CACpB,CAqEA;AAqBD,iBAAS,kBAAkB,CACzB,QAAQ,EAAE,aAAa,EAAE,EACzB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,SAAS,GAAG,KAAK,GAC1B,MAAM,CA6DR;AAED,mEAAmE;AACnE,eAAO,MAAM,qBAAqB;;;CAA2C,CAAC;AAI9E,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA6kD/D"}
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { z } from 'zod';
|
|
2
2
|
import { caseInsensitiveEnum } from '../utils/schema.js';
|
|
3
|
-
import { createInspectionSession, quitInspectionSession, captureScreenshot, getPageSource, findElements, tapElement, typeIntoElement, clearElement, swipeScreen, getWindowSize, launchApp, pressBack, longPress, doubleTap, dragAndDrop, pinchZoom, scrollToElement, pressKey, isKeyboardShown, hideKeyboard, appControl, getOrientation, setOrientation, getClipboard, setClipboard, setGeolocation, resetGeolocation, handleAlert, pushFileToDevice, pullFileFromDevice, mockAuthentication, requireSession, findFirstElementId, listActiveSessions, getPendingReportIds, sweepTimedOutStarts, deleteAllTrackedReports, automotiveControl, audioControl, AUTOMOTIVE_RESOLUTIONS, INSTRUMENT_CLUSTER_CONTENT, getForegroundActivity, isSameActivity, listContexts, switchContext, getDeviceLog, getAlertInfo, isWebviewContext, sessionCapture, networkConnection, setNetworkConditions, injectCameraImage, clearWebCache, deviceDiagnostics, setAppearance, accessibilityAudit } from '../api/webdriver.js';
|
|
3
|
+
import { createInspectionSession, quitInspectionSession, captureScreenshot, getPageSource, findElements, tapElement, typeIntoElement, clearElement, swipeScreen, getWindowSize, launchApp, pressBack, longPress, doubleTap, tapAt, appPermissions, dragAndDrop, pinchZoom, scrollToElement, pressKey, isKeyboardShown, hideKeyboard, appControl, getOrientation, setOrientation, getClipboard, setClipboard, setGeolocation, resetGeolocation, handleAlert, pushFileToDevice, pullFileFromDevice, mockAuthentication, requireSession, findFirstElementId, listActiveSessions, getPendingReportIds, sweepTimedOutStarts, deleteAllTrackedReports, automotiveControl, audioControl, AUTOMOTIVE_RESOLUTIONS, INSTRUMENT_CLUSTER_CONTENT, getForegroundActivity, isSameActivity, listContexts, switchContext, getDeviceLog, getAlertInfo, isWebviewContext, sessionCapture, networkConnection, setNetworkConditions, injectCameraImage, clearWebCache, deviceDiagnostics, setAppearance, accessibilityAudit, adbShell } from '../api/webdriver.js';
|
|
4
4
|
import { checkDestructiveGuard } from '../utils/destructive-guard.js';
|
|
5
5
|
import { getActiveUrl } from '../api/client.js';
|
|
6
6
|
import { checkDeleteAllowed } from '../api/access-level.js';
|
|
@@ -10,11 +10,15 @@ import { listFiles } from '../api/repository.js';
|
|
|
10
10
|
import { validateInputPath, validateOutputPath } from '../utils/path-guard.js';
|
|
11
11
|
import { readFileSync, writeFileSync } from 'fs';
|
|
12
12
|
import { getDeploymentMode } from '../utils/deployment-mode.js';
|
|
13
|
+
import { classifyShellCommand, shellGuardMessage, capShellOutput, shellCommandProblem } from '../utils/adb-shell.js';
|
|
14
|
+
import { recommendLocators, formatRecommendation } from '../utils/locator-recommend.js';
|
|
13
15
|
// '-ios predicate string' is XCUITest's NSPredicate locator (e.g. "type == 'XCUIElementTypeButton' AND label == 'Login'")
|
|
14
16
|
// — faster and less brittle than xpath on iOS, and the form the Mobile Studio iOS Test Recorder emits. iOS on Appium
|
|
15
17
|
// Server only: the Appium Grid rejects it ("Locator Strategy '-ios predicate string' is not supported for this
|
|
16
18
|
// session", verified live 2026-10-09 on an iPhone 13 Pro Max) — use xpath or accessibility id there.
|
|
17
|
-
|
|
19
|
+
// '-android uiautomator' is UiAutomator2's UiSelector locator (e.g. 'new UiSelector().resourceIdMatches(".*login")') —
|
|
20
|
+
// regex / partial matches xpath can't express cheaply. Verified live 2026-11-12 on Appium Server (OnePlus 6, Android 9).
|
|
21
|
+
const LOCATOR_STRATEGIES = ['xpath', 'id', 'accessibility id', 'class name', '-ios predicate string', '-android uiautomator', 'css selector'];
|
|
18
22
|
// ─── Helpers ─────────────────────────────────────────────────────────────────
|
|
19
23
|
// Returns an error result if the session is a browser (web) session — used to
|
|
20
24
|
// guard mobile-only tools so they produce a clear message instead of a protocol error.
|
|
@@ -129,6 +133,25 @@ function parseElementTree(xml, platform) {
|
|
|
129
133
|
}
|
|
130
134
|
return { elements, totalNodes };
|
|
131
135
|
}
|
|
136
|
+
/** The locator ladder applied to this screen — one recommended selector per listed element (src/utils/locator-recommend.ts). */
|
|
137
|
+
function recommendationLines(all, shown, platform) {
|
|
138
|
+
const recs = recommendLocators(all, platform);
|
|
139
|
+
const byElement = new Map(all.map((e, i) => [e, recs[i]]));
|
|
140
|
+
const MAX = 40;
|
|
141
|
+
const lines = [
|
|
142
|
+
'',
|
|
143
|
+
`Recommended locator per element (${platform === 'ios' ? 'accessibility id → @label xpath' : 'resource-id → accessibility id → @text xpath'}; unique on this screen — copy these into find_elements and the test):`,
|
|
144
|
+
];
|
|
145
|
+
for (const e of shown.slice(0, MAX)) {
|
|
146
|
+
const what = platform === 'ios'
|
|
147
|
+
? `${shortClass(e.className).replace(/^XCUIElementType/, '')} "${(e.label ?? e.name ?? e.value ?? '').slice(0, 30)}"`
|
|
148
|
+
: `${shortClass(e.className)} "${(e.text ?? e.contentDesc ?? (e.resourceId ? shortId(e.resourceId) : '')).slice(0, 30)}"`;
|
|
149
|
+
lines.push(` ${what} → ${formatRecommendation(byElement.get(e) ?? null)}`);
|
|
150
|
+
}
|
|
151
|
+
if (shown.length > MAX)
|
|
152
|
+
lines.push(` … ${shown.length - MAX} more — use find_elements to narrow.`);
|
|
153
|
+
return lines;
|
|
154
|
+
}
|
|
132
155
|
function formatElementTable(elements, totalNodes, platform) {
|
|
133
156
|
if (platform === 'ios') {
|
|
134
157
|
const interesting = elements.filter((e) => e.name || e.label || e.value);
|
|
@@ -149,6 +172,9 @@ function formatElementTable(elements, totalNodes, platform) {
|
|
|
149
172
|
if (interesting.length === 0) {
|
|
150
173
|
lines.push(' (no elements with name, label, or value found on this screen)');
|
|
151
174
|
}
|
|
175
|
+
else {
|
|
176
|
+
lines.push(...recommendationLines(elements, interesting, 'ios'));
|
|
177
|
+
}
|
|
152
178
|
lines.push('', "Locate iOS elements with: strategy 'accessibility id' (matches name), xpath like //*[@label='...'] or //XCUIElementTypeButton, or on Appium Server projects '-ios predicate string' like \"label == '...'\".");
|
|
153
179
|
return lines.join('\n');
|
|
154
180
|
}
|
|
@@ -171,8 +197,20 @@ function formatElementTable(elements, totalNodes, platform) {
|
|
|
171
197
|
if (interesting.length === 0) {
|
|
172
198
|
lines.push(' (no elements with resource-id, content-desc, or text found on this screen)');
|
|
173
199
|
}
|
|
200
|
+
else {
|
|
201
|
+
lines.push(...recommendationLines(elements, interesting, 'android'));
|
|
202
|
+
// Jetpack Compose exposes Modifier.testTag as resource-id only when the app opts in — a screen of texts with no ids
|
|
203
|
+
// is the usual sign. The fix is in the app, not the test.
|
|
204
|
+
if (interesting.length >= 3 && !interesting.some((e) => e.resourceId)) {
|
|
205
|
+
lines.push('', 'No element on this screen has a resource-id. If this is a Jetpack Compose app, ask its developers to set ' +
|
|
206
|
+
'testTagsAsResourceId = true (Modifier.semantics) so Modifier.testTag values become resource-ids; until then ' +
|
|
207
|
+
'use accessibility id (contentDescription) or text.');
|
|
208
|
+
}
|
|
209
|
+
}
|
|
174
210
|
return lines.join('\n');
|
|
175
211
|
}
|
|
212
|
+
/** Test seam: the element-table pipeline get_element_tree uses. */
|
|
213
|
+
export const __elementTreeForTests = { parseElementTree, formatElementTable };
|
|
176
214
|
// ─── Tool registration ────────────────────────────────────────────────────────
|
|
177
215
|
export function registerInspectionTools(server) {
|
|
178
216
|
// ── start_inspection_session ──────────────────────────────────────────────
|
|
@@ -408,7 +446,12 @@ export function registerInspectionTools(server) {
|
|
|
408
446
|
.describe('Preserve the session report (and its platform-recorded video) instead of deleting it. Default false.'),
|
|
409
447
|
}, async (args) => {
|
|
410
448
|
try {
|
|
411
|
-
const { reportDeleted, reportKept, canDeleteReport, reportTestId, reportUrl, reportDeleteError } = await quitInspectionSession(args.handle, args.keepReport ?? false);
|
|
449
|
+
const { reportDeleted, reportKept, canDeleteReport, reportTestId, reportUrl, reportDeleteError, geolocationReset } = await quitInspectionSession(args.handle, args.keepReport ?? false);
|
|
450
|
+
const geoNote = geolocationReset === true
|
|
451
|
+
? '\n🧭 The simulated location was reset before stopping, so the next user of this device gets its real location.'
|
|
452
|
+
: geolocationReset === false
|
|
453
|
+
? '\n⚠️ The simulated location could not be reset before stopping — the device may still report the simulated location.'
|
|
454
|
+
: '';
|
|
412
455
|
let text;
|
|
413
456
|
if (reportKept) {
|
|
414
457
|
text =
|
|
@@ -437,6 +480,7 @@ export function registerInspectionTools(server) {
|
|
|
437
480
|
else {
|
|
438
481
|
text = `✅ Session ${args.handle} stopped. Device released.`;
|
|
439
482
|
}
|
|
483
|
+
text += geoNote;
|
|
440
484
|
text +=
|
|
441
485
|
'\n\n📌 If you have the View URL open in a browser, please close that tab now — ' +
|
|
442
486
|
'the device has been released but the browser session may still appear connected.';
|
|
@@ -605,11 +649,16 @@ export function registerInspectionTools(server) {
|
|
|
605
649
|
'Strategies: "id" (Android resource-id, fastest), "accessibility id" (Android content-desc; on iOS it IS the name ' +
|
|
606
650
|
'attribute — identifier, else label — so it matches exactly what //*[@name=\'x\'] matches, without walking the tree; ' +
|
|
607
651
|
'works on the Grid too), "-ios predicate string" (iOS on Appium Server projects only — NSPredicate such as ' +
|
|
608
|
-
'"type == \'XCUIElementTypeButton\' AND label == \'Login\'"; the Appium Grid rejects it), "
|
|
652
|
+
'"type == \'XCUIElementTypeButton\' AND label == \'Login\'"; the Appium Grid rejects it), "-android uiautomator" ' +
|
|
653
|
+
'(Android on Appium Server — a UiSelector such as \'new UiSelector().resourceIdMatches(".*login")\' or ' +
|
|
654
|
+
'\'new UiSelector().textContains("Pay")\', for partial / regex matches), "class name" (by widget ' +
|
|
609
655
|
'type, often returns many), "xpath" (most flexible, slowest — attribute matches only, never positional [1]/[2]), ' +
|
|
610
656
|
'"css selector" (ONLY inside a WEBVIEW context — see webview_context). ' +
|
|
611
657
|
'Prefer them in that order and copy the strategy you used into the generated test. Attributes are fetched for the first ' +
|
|
612
|
-
'maxResults matches (default 20); the rest are listed by elementId — narrow the selector rather than raising it.'
|
|
658
|
+
'maxResults matches (default 20); the rest are listed by elementId — narrow the selector rather than raising it. ' +
|
|
659
|
+
'Android TOASTS: find xpath //android.widget.Toast[contains(@text,\'<part of the message>\')] straight after the action ' +
|
|
660
|
+
'that shows it — the text check must be IN the locator: the toast element goes stale at once (reading its text ' +
|
|
661
|
+
'afterwards fails) and the toast is gone within a few seconds (verified live, UiAutomator2).', {
|
|
613
662
|
handle: z
|
|
614
663
|
.string()
|
|
615
664
|
.describe("Session handle from start_inspection_session."),
|
|
@@ -693,6 +742,10 @@ export function registerInspectionTools(server) {
|
|
|
693
742
|
(args.strategy === '-ios predicate string' && /not supported/i.test(e.message)
|
|
694
743
|
? '\n\nThis session is on the Appium Grid, which does not support iOS predicates. Use xpath (e.g. ' +
|
|
695
744
|
'//XCUIElementTypeButton[@label=\'Login\']) or accessibility id instead.'
|
|
745
|
+
: '') +
|
|
746
|
+
(args.strategy === '-android uiautomator' && /not supported|invalid selector|unknown/i.test(e.message)
|
|
747
|
+
? '\n\n"-android uiautomator" needs an Android session on an Appium Server project. Use id, accessibility id ' +
|
|
748
|
+
'or an attribute xpath (e.g. //*[contains(@resource-id,\'login\')]) instead.'
|
|
696
749
|
: ''),
|
|
697
750
|
}],
|
|
698
751
|
isError: true,
|
|
@@ -731,8 +784,22 @@ export function registerInspectionTools(server) {
|
|
|
731
784
|
server.tool('tap_element', 'Tap (click) an element on the device screen. ' +
|
|
732
785
|
'Target it directly with strategy + selector (one call — the find happens internally), ' +
|
|
733
786
|
'or pass an elementId from a previous find_elements call. ' +
|
|
734
|
-
'
|
|
787
|
+
'x + y (instead of an element) tap a screen point — only for what has no element (a map, a canvas, a game); ' +
|
|
788
|
+
'coordinates break across screen sizes, so never put them in a generated test when an element exists. ' +
|
|
789
|
+
'After tapping, call take_inspection_screenshot to verify the result.', {
|
|
790
|
+
...targetParams,
|
|
791
|
+
x: z.number().int().min(0).optional().describe('Tap a screen point instead of an element: X in the session\'s own coordinates (see take_inspection_screenshot / the window size).'),
|
|
792
|
+
y: z.number().int().min(0).optional().describe('Y of the screen point (with x).'),
|
|
793
|
+
}, async (args) => {
|
|
735
794
|
try {
|
|
795
|
+
if (args.x != null || args.y != null) {
|
|
796
|
+
if (args.x == null || args.y == null)
|
|
797
|
+
return { content: [{ type: 'text', text: 'Error: a point tap needs both x and y.' }], isError: true };
|
|
798
|
+
if (args.elementId || args.selector)
|
|
799
|
+
return { content: [{ type: 'text', text: 'Error: pass either an element (elementId / strategy+selector) or x+y, not both.' }], isError: true };
|
|
800
|
+
await tapAt(args.handle, args.x, args.y);
|
|
801
|
+
return { content: [{ type: 'text', text: `✅ Tapped the point (${args.x}, ${args.y}).\n\nCall take_inspection_screenshot to verify the result.` }] };
|
|
802
|
+
}
|
|
736
803
|
const target = await resolveTargetElement(args);
|
|
737
804
|
if ('error' in target) {
|
|
738
805
|
return { content: [{ type: 'text', text: `Error: ${target.error}` }], isError: true };
|
|
@@ -899,12 +966,17 @@ export function registerInspectionTools(server) {
|
|
|
899
966
|
.string()
|
|
900
967
|
.optional()
|
|
901
968
|
.describe("Android launch activity, e.g. '.LoginActivity' — from get_application_info mainActivity; effectively required on Android Grid sessions. Ignored on iOS."),
|
|
969
|
+
launchArguments: z
|
|
970
|
+
.array(z.string())
|
|
971
|
+
.optional()
|
|
972
|
+
.describe('iOS, Appium Server only: process arguments for the app, e.g. ["-AppleLanguages", "(de)"] to open it in German, ' +
|
|
973
|
+
'or the app’s own feature-flag arguments. The app is terminated first — a running app ignores launch arguments.'),
|
|
902
974
|
}, async (args) => {
|
|
903
975
|
const mobileErr = requireMobileSession(args.handle, 'launch_app');
|
|
904
976
|
if (mobileErr)
|
|
905
977
|
return mobileErr;
|
|
906
978
|
try {
|
|
907
|
-
const result = await launchApp(args.handle, args.packageName, args.activity);
|
|
979
|
+
const result = await launchApp(args.handle, args.packageName, args.activity, args.launchArguments);
|
|
908
980
|
return {
|
|
909
981
|
content: [{
|
|
910
982
|
type: 'text',
|
|
@@ -1082,6 +1154,10 @@ export function registerInspectionTools(server) {
|
|
|
1082
1154
|
.optional()
|
|
1083
1155
|
.describe('Named key. Provide this OR keycode. iOS supports HOME, VOLUME_UP, VOLUME_DOWN, POWER.'),
|
|
1084
1156
|
keycode: z.number().int().optional().describe('Raw Android keycode (e.g. 66 = ENTER). Android only. Provide this OR key.'),
|
|
1157
|
+
longPress: z
|
|
1158
|
+
.boolean()
|
|
1159
|
+
.optional()
|
|
1160
|
+
.describe('Android, Appium Server only: hold the key instead of tapping it (e.g. a long HOME opens the assistant).'),
|
|
1085
1161
|
}, async (args) => {
|
|
1086
1162
|
const mobileErr = requireMobileSession(args.handle, 'press_key');
|
|
1087
1163
|
if (mobileErr)
|
|
@@ -1090,7 +1166,7 @@ export function registerInspectionTools(server) {
|
|
|
1090
1166
|
if (!args.key && args.keycode == null) {
|
|
1091
1167
|
return { content: [{ type: 'text', text: 'Error: provide either key (named) or keycode (number).' }], isError: true };
|
|
1092
1168
|
}
|
|
1093
|
-
const pressed = await pressKey(args.handle, args.key, args.keycode);
|
|
1169
|
+
const pressed = await pressKey(args.handle, args.key, args.keycode, args.longPress === true);
|
|
1094
1170
|
return {
|
|
1095
1171
|
content: [{ type: 'text', text: `✅ Pressed ${pressed}.\n\nCall take_inspection_screenshot to verify the result.` }],
|
|
1096
1172
|
};
|
|
@@ -1127,17 +1203,22 @@ export function registerInspectionTools(server) {
|
|
|
1127
1203
|
'is_installed (true/false for packageName), current (what is in the foreground: Android package + activity, iOS bundle id), ' +
|
|
1128
1204
|
'install (install a repository build mid-session from appRef "cloud:<package or bundle>" / "cloud:uniqueName=<name>" — Appium Server only; ' +
|
|
1129
1205
|
'this lifts the "install before the session" rule for Appium Server projects), ' +
|
|
1130
|
-
'clear_web_cache (seetest:client.hybridClearCache — drops the cache of the app\'s webviews; both modes)
|
|
1206
|
+
'clear_web_cache (seetest:client.hybridClearCache — drops the cache of the app\'s webviews; both modes), ' +
|
|
1207
|
+
'permissions (Android, Appium Server: list the app\'s requested / granted / denied runtime permissions; with ' +
|
|
1208
|
+
'permissionAction grant or revoke and permissions, change them first — only permissions the app declares can change, ' +
|
|
1209
|
+
'and revoking one makes Android kill the app, so relaunch it with launch_app afterwards). ' +
|
|
1131
1210
|
'NOTE on Grid sessions: query_state/current report only the foreground activity (Android) or are unavailable (iOS); deep_link is best-effort; ' +
|
|
1132
1211
|
'background, is_installed and install are Appium Server only. To relaunch after terminate, use launch_app.', {
|
|
1133
1212
|
handle: z.string().describe('Session handle from start_inspection_session.'),
|
|
1134
1213
|
action: z
|
|
1135
|
-
.enum(['terminate', 'clear_data', 'query_state', 'deep_link', 'background', 'is_installed', 'current', 'install', 'clear_web_cache'])
|
|
1214
|
+
.enum(['terminate', 'clear_data', 'query_state', 'deep_link', 'background', 'is_installed', 'current', 'install', 'clear_web_cache', 'permissions'])
|
|
1136
1215
|
.describe('Lifecycle action to perform.'),
|
|
1216
|
+
permissionAction: z.enum(['list', 'grant', 'revoke']).optional().describe('For permissions: list (default), grant or revoke.'),
|
|
1217
|
+
permissions: z.array(z.string()).optional().describe('For permissions grant/revoke: full names, e.g. ["android.permission.CAMERA"].'),
|
|
1137
1218
|
packageName: z
|
|
1138
1219
|
.string()
|
|
1139
1220
|
.optional()
|
|
1140
|
-
.describe('Android package name or iOS bundle identifier. Required for terminate, clear_data, query_state, is_installed;
|
|
1221
|
+
.describe('Android package name or iOS bundle identifier. Required for terminate, clear_data, query_state, is_installed; for deep_link: Android handler package, or the iOS bundle id that should open the URL — com.apple.mobilesafari opens a web URL straight in Safari (no address-bar typing).'),
|
|
1141
1222
|
url: z.string().optional().describe('URL or URI scheme for deep_link, e.g. "myapp://orders/42" or "https://...".'),
|
|
1142
1223
|
seconds: z.number().int().min(1).max(300).optional().describe('For background: how long to keep the app in the background. Default 3.'),
|
|
1143
1224
|
appRef: z.string().optional().describe('For install: repository reference — "cloud:com.example.app" (Android may add "/.MainActivity"), "cloud:uniqueName=<name>", or "cloud:<package>:releaseVersion=<v>:buildVersion=<b>".'),
|
|
@@ -1146,6 +1227,23 @@ export function registerInspectionTools(server) {
|
|
|
1146
1227
|
if (mobileErr)
|
|
1147
1228
|
return mobileErr;
|
|
1148
1229
|
try {
|
|
1230
|
+
if (args.action === 'permissions') {
|
|
1231
|
+
if (!args.packageName)
|
|
1232
|
+
return { content: [{ type: 'text', text: 'Error: permissions requires packageName (the app\'s Android package).' }], isError: true };
|
|
1233
|
+
const act = args.permissionAction ?? 'list';
|
|
1234
|
+
if (act !== 'list' && !args.permissions?.length) {
|
|
1235
|
+
return { content: [{ type: 'text', text: `Error: permissions ${act} requires permissions, e.g. ["android.permission.CAMERA"].` }], isError: true };
|
|
1236
|
+
}
|
|
1237
|
+
const p = await appPermissions(args.handle, act, args.packageName, args.permissions ?? []);
|
|
1238
|
+
const changed = act === 'list' ? '' : (args.permissions ?? []).map((x) => `${x}: ${p.granted.includes(x) ? 'granted' : p.requested.includes(x) ? 'not granted' : 'NOT DECLARED by the app — it cannot be changed'}`).join('\n') + '\n';
|
|
1239
|
+
return {
|
|
1240
|
+
content: [{
|
|
1241
|
+
type: 'text',
|
|
1242
|
+
text: `${changed}Granted: ${p.granted.join(', ') || '(none)'}\nDenied: ${p.denied.join(', ') || '(none)'}\nRequested: ${p.requested.join(', ') || '(none)'}` +
|
|
1243
|
+
(act === 'revoke' ? '\nAndroid kills an app when one of its permissions is revoked — relaunch it with launch_app.' : ''),
|
|
1244
|
+
}],
|
|
1245
|
+
};
|
|
1246
|
+
}
|
|
1149
1247
|
if (args.action === 'clear_web_cache') {
|
|
1150
1248
|
await clearWebCache(args.handle);
|
|
1151
1249
|
return { content: [{ type: 'text', text: '✅ Webview cache cleared (hybridClearCache).' }] };
|
|
@@ -1165,13 +1263,19 @@ export function registerInspectionTools(server) {
|
|
|
1165
1263
|
'device_info (one call: model, OS/API level, locale, time zone, battery, screen size/scale, system bars, lock state, ' +
|
|
1166
1264
|
'light/dark appearance — Appium Server), set_appearance (style dark|light: iOS appearance / Android night mode — ' +
|
|
1167
1265
|
'dark-mode screenshot checks), accessibility_audit (iOS: XCTest\'s built-in audit of the current screen, no extra ' +
|
|
1168
|
-
'dependency; Android: use includeAxeScan in get_test_boilerplate)
|
|
1266
|
+
'dependency; Android: use includeAxeScan in get_test_boilerplate), shell (Android Appium Server: adb shell ' +
|
|
1267
|
+
'command — getprop, dumpsys <service>, settings get, pm list/path, wm size run directly (device log: get_device_log); anything that can change ' +
|
|
1268
|
+
'the shared device, or uses shell operators, returns a preview until confirmChange: true). ' +
|
|
1169
1269
|
'Grid session limits: alerts and reset_geolocation are not supported, and iOS Grid devices reject clipboard ops ' +
|
|
1170
1270
|
'(clear errors explain alternatives). iOS file paths may require the @bundleId:container syntax.', {
|
|
1171
1271
|
handle: z.string().describe('Session handle from start_inspection_session.'),
|
|
1172
1272
|
action: z
|
|
1173
|
-
.enum(['get_orientation', 'set_orientation', 'get_clipboard', 'set_clipboard', 'set_geolocation', 'reset_geolocation', 'get_alert', 'accept_alert', 'dismiss_alert', 'push_file', 'pull_file', 'device_info', 'set_appearance', 'accessibility_audit'])
|
|
1273
|
+
.enum(['get_orientation', 'set_orientation', 'get_clipboard', 'set_clipboard', 'set_geolocation', 'reset_geolocation', 'get_alert', 'accept_alert', 'dismiss_alert', 'push_file', 'pull_file', 'device_info', 'set_appearance', 'accessibility_audit', 'shell'])
|
|
1174
1274
|
.describe('Device action to perform.'),
|
|
1275
|
+
command: z.string().optional().describe('For shell: the adb shell command, e.g. "dumpsys battery", "getprop ro.build.version.release", ' +
|
|
1276
|
+
'"settings get global airplane_mode_on". Put everything in this string (no separate args needed).'),
|
|
1277
|
+
confirmChange: z.boolean().optional().describe('For shell: set true only after the user agreed to a command that changes the device (the first call returns ' +
|
|
1278
|
+
'a preview saying why). Read-only commands never need it.'),
|
|
1175
1279
|
orientation: z.enum(['PORTRAIT', 'LANDSCAPE']).optional().describe('For set_orientation.'),
|
|
1176
1280
|
style: z.enum(['dark', 'light']).optional().describe('For set_appearance.'),
|
|
1177
1281
|
text: z.string().optional().describe('For set_clipboard: the text to place on the clipboard.'),
|
|
@@ -1239,6 +1343,18 @@ export function registerInspectionTools(server) {
|
|
|
1239
1343
|
const lines = findings.slice(0, 30).map((f, i) => `${i + 1}. ${String(f.type ?? f.auditType ?? 'issue')}: ${String(f.detailedDescription ?? f.compactDescription ?? f.elementDescription ?? '').split('\n')[0].slice(0, 200)}`);
|
|
1240
1344
|
return { content: [{ type: 'text', text: findings.length ? `${findings.length} accessibility finding(s) on this screen:\n${lines.join('\n')}${findings.length > 30 ? `\n… ${findings.length - 30} more` : ''}` : 'No accessibility findings on this screen.' }] };
|
|
1241
1345
|
}
|
|
1346
|
+
case 'shell': {
|
|
1347
|
+
if (!args.command?.trim())
|
|
1348
|
+
return { content: [{ type: 'text', text: 'Error: shell requires command, e.g. "dumpsys battery".' }], isError: true };
|
|
1349
|
+
const problem = shellCommandProblem(args.command);
|
|
1350
|
+
if (problem)
|
|
1351
|
+
return { content: [{ type: 'text', text: `Error: ${problem}` }], isError: true };
|
|
1352
|
+
const c = classifyShellCommand(args.command.trim());
|
|
1353
|
+
if (!c.readOnly && args.confirmChange !== true)
|
|
1354
|
+
return { content: [{ type: 'text', text: shellGuardMessage(c) }] };
|
|
1355
|
+
const out = await adbShell(args.handle, c.commandLine);
|
|
1356
|
+
return { content: [{ type: 'text', text: `$ adb shell ${c.commandLine}\n${capShellOutput(out.trimEnd()) || '(no output)'}` }] };
|
|
1357
|
+
}
|
|
1242
1358
|
case 'get_alert': {
|
|
1243
1359
|
const a = await getAlertInfo(args.handle);
|
|
1244
1360
|
return { content: [{ type: 'text', text: `Alert text: ${JSON.stringify(a.text)}${a.buttons ? `\nButtons: ${a.buttons.map((b) => `"${b}"`).join(', ')} — press one with accept_alert + buttonLabel` : ''}` }] };
|