appium-mcp 1.98.0 → 1.99.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 (54) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/README.md +30 -0
  3. package/dist/locators/element-filter.d.ts +3 -1
  4. package/dist/locators/element-filter.d.ts.map +1 -1
  5. package/dist/locators/element-filter.js +44 -14
  6. package/dist/locators/element-filter.js.map +1 -1
  7. package/dist/locators/generate-all-locators.d.ts +6 -1
  8. package/dist/locators/generate-all-locators.d.ts.map +1 -1
  9. package/dist/locators/generate-all-locators.js +1 -1
  10. package/dist/locators/generate-all-locators.js.map +1 -1
  11. package/dist/locators/locator-generation.d.ts +4 -3
  12. package/dist/locators/locator-generation.d.ts.map +1 -1
  13. package/dist/locators/locator-generation.js +31 -10
  14. package/dist/locators/locator-generation.js.map +1 -1
  15. package/dist/locators/types.d.ts +3 -0
  16. package/dist/locators/types.d.ts.map +1 -0
  17. package/dist/locators/types.js +2 -0
  18. package/dist/locators/types.js.map +1 -0
  19. package/dist/tools/gestures/schema.d.ts.map +1 -1
  20. package/dist/tools/gestures/schema.js +7 -15
  21. package/dist/tools/gestures/schema.js.map +1 -1
  22. package/dist/tools/interactions/screen-recording.d.ts.map +1 -1
  23. package/dist/tools/interactions/screen-recording.js +4 -1
  24. package/dist/tools/interactions/screen-recording.js.map +1 -1
  25. package/dist/tools/test-generation/locators.d.ts.map +1 -1
  26. package/dist/tools/test-generation/locators.js +19 -5
  27. package/dist/tools/test-generation/locators.js.map +1 -1
  28. package/dist/ui/inspector-screenshot-script.d.ts +3 -0
  29. package/dist/ui/inspector-screenshot-script.d.ts.map +1 -0
  30. package/dist/ui/inspector-screenshot-script.js +164 -0
  31. package/dist/ui/inspector-screenshot-script.js.map +1 -0
  32. package/dist/ui/mcp-ui-utils.d.ts.map +1 -1
  33. package/dist/ui/mcp-ui-utils.js +14 -73
  34. package/dist/ui/mcp-ui-utils.js.map +1 -1
  35. package/dist/ui/page-source-inspector-app.d.ts.map +1 -1
  36. package/dist/ui/page-source-inspector-app.js +79 -75
  37. package/dist/ui/page-source-inspector-app.js.map +1 -1
  38. package/dist/ui/xml-inspector-scripts.d.ts +4 -0
  39. package/dist/ui/xml-inspector-scripts.d.ts.map +1 -0
  40. package/dist/ui/xml-inspector-scripts.js +91 -0
  41. package/dist/ui/xml-inspector-scripts.js.map +1 -0
  42. package/package.json +1 -1
  43. package/server.json +2 -2
  44. package/src/locators/element-filter.ts +50 -16
  45. package/src/locators/generate-all-locators.ts +13 -7
  46. package/src/locators/locator-generation.ts +43 -10
  47. package/src/locators/types.ts +2 -0
  48. package/src/tools/gestures/schema.ts +7 -17
  49. package/src/tools/interactions/screen-recording.ts +4 -1
  50. package/src/tools/test-generation/locators.ts +31 -7
  51. package/src/ui/inspector-screenshot-script.ts +163 -0
  52. package/src/ui/mcp-ui-utils.ts +15 -73
  53. package/src/ui/page-source-inspector-app.ts +80 -75
  54. package/src/ui/xml-inspector-scripts.ts +91 -0
@@ -1,3 +1,6 @@
1
+ import {INSPECTOR_SCREENSHOT_SCRIPT} from './inspector-screenshot-script.js';
2
+ import {XML_FORMAT_SCRIPT, XML_SEARCH_SCRIPT} from './xml-inspector-scripts.js';
3
+
1
4
  /**
2
5
  * Static MCP App used by appium_get_page_source.
3
6
  *
@@ -35,10 +38,19 @@ export function createPageSourceInspectorAppUI(): string {
35
38
  .viewer { height: 320px; min-height: 160px; resize: vertical; overflow: auto; padding: 20px; }
36
39
  .xml-content, .selector { margin: 0; font: 12px/1.75 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
37
40
  .xml-content { white-space: pre; color: #c5d3e7; }
41
+ mark[data-active] { outline: 2px solid #91baff; background: #ff963c; }
42
+ .search-status { padding: 6px 20px; color: var(--muted); font-size: 12px; }
43
+ .search-status:empty { display: none; }
38
44
  mark { border-radius: 3px; background: #eac77a; color: #252019; }
39
45
  .empty, .hint { color: var(--muted); }
40
46
  .empty { font-family: inherit; }
41
47
  .hint { margin: 6px 0 0; font-size: 12px; }
48
+ .screenshot-panel { border-top: 1px solid var(--line); padding: 20px; }
49
+ .screenshot-frame { position: relative; width: fit-content; max-width: 100%; margin: 12px auto; }
50
+ .screenshot-frame img { display: block; max-width: 100%; max-height: 480px; }
51
+ .element-overlay { position: absolute; border: 2px solid #ff963c; background: #ff963c33; pointer-events: none; }
52
+ #screenshotElement { width: 100%; margin: 10px 0; padding: 8px; background: var(--panel); color: var(--text); border: 1px solid var(--line); }
53
+ #selectedXmlElement { white-space: pre-wrap; overflow-wrap: anywhere; font-size: 12px; }
42
54
  .locators { border-top: 1px solid var(--line); padding: 20px; }
43
55
  h2 { margin: 0; font-size: 14px; font-weight: 600; }
44
56
  #locatorStatus { margin: 16px 0 10px; color: var(--accent); font-size: 12px; }
@@ -59,21 +71,38 @@ export function createPageSourceInspectorAppUI(): string {
59
71
  <span class="info" id="sourceInfo">Waiting for page source…</span>
60
72
  </summary>
61
73
  <div class="toolbar">
62
- <input type="search" class="search-box" id="searchBox" placeholder="Find in XML…" aria-label="Find in XML" title="Highlight matching text in the XML">
74
+ <input type="search" class="search-box" id="searchBox" placeholder="Search elements…" aria-label="Search elements" title="Highlight XML text and find locator candidates by element tag or attribute value">
63
75
  <div class="toolbar-right">
76
+ <button class="btn btn-secondary" id="takeScreenshotButton">Take screenshot</button>
64
77
  <button class="btn btn-secondary" id="formatButton">Format XML</button>
65
78
  <button class="btn btn-secondary" id="copyButton">Copy XML</button>
66
79
  </div>
67
80
  </div>
81
+ <div id="searchStatus" class="search-status" role="status" aria-live="polite"></div>
68
82
  <div class="viewer" title="Drag the bottom-right corner to resize vertically">
69
83
  <pre class="xml-content empty" id="xmlContent">Waiting for page source…</pre>
70
84
  </div>
85
+ <section id="screenshotPanel" class="screenshot-panel" hidden aria-label="Screenshot preview">
86
+ <h2>Screenshot &amp; XML elements</h2>
87
+ <p class="hint">Capture refreshes XML too. Select an element to overlay its bounds. Images and XML are captured sequentially; keep the screen still. Supports x/y/width/height and Android bounds.</p>
88
+ <p id="screenshotStatus" role="status" aria-live="polite"></p>
89
+ <div class="screenshot-frame">
90
+ <img id="inspectorScreenshot" alt="Device screenshot" hidden>
91
+ <div id="elementOverlay" class="element-overlay" hidden></div>
92
+ </div>
93
+ <label for="screenshotElement">XML element (filtered by Search)</label>
94
+ <select id="screenshotElement"><option value="">Select an XML element to highlight</option></select>
95
+ <pre id="selectedXmlElement"></pre>
96
+ </section>
71
97
  <section class="locators" aria-labelledby="locatorsHeading">
72
98
  <div class="section-header">
73
99
  <h2 id="locatorsHeading">Locator candidates</h2>
74
- <button class="btn" id="generateButton">Generate from current page</button>
100
+ <button class="btn" id="generateButton">Find locators</button>
75
101
  </div>
76
- <p class="hint">Fetches fresh XML from the device and generates candidates for supported element types, including hidden elements. XML search only highlights text above.</p>
102
+ <p class="hint">Find locators for elements matching the search text in their type or attributes (name, label, text, ID, etc.). Matches ignore case and may include hidden elements. Fetches fresh XML; leave search blank for the default candidate list.</p>
103
+ <label class="hint" for="xpathAttributes">Preferred XPath attributes (optional)</label>
104
+ <input type="text" class="search-box" id="xpathAttributes" placeholder="AutomationId, data-testid" aria-describedby="xpathAttributesHelp" style="display:block;width:100%;margin-top:6px">
105
+ <p class="hint" id="xpathAttributesHelp">Comma-separated attribute names, in priority order. Existing attributes remain as fallback.</p>
77
106
  <div id="locatorResults" hidden>
78
107
  <p id="locatorStatus" role="status" aria-live="polite"></p>
79
108
  <div class="locator-results" id="locatorOutput"></div>
@@ -82,6 +111,9 @@ export function createPageSourceInspectorAppUI(): string {
82
111
  </details>
83
112
  <script>
84
113
  (() => {
114
+ ${XML_FORMAT_SCRIPT}
115
+ ${XML_SEARCH_SCRIPT}
116
+ ${INSPECTOR_SCREENSHOT_SCRIPT}
85
117
  const PAGE_SOURCE_PREFIX = 'Page source retrieved successfully: \\n\\\`\\\`\\\`xml ';
86
118
  const xmlContent = document.getElementById('xmlContent');
87
119
  const sourceInfo = document.getElementById('sourceInfo');
@@ -90,11 +122,16 @@ export function createPageSourceInspectorAppUI(): string {
90
122
  const locatorResults = document.getElementById('locatorResults');
91
123
  const locatorStatus = document.getElementById('locatorStatus');
92
124
  const locatorOutput = document.getElementById('locatorOutput');
125
+ const xmlSearch = createXmlSearch(xmlContent, document.getElementById('searchStatus'));
93
126
  let source = '';
94
127
  let savedFile;
95
128
  let nextRequestId = 1;
96
129
  const pendingRequests = new Map();
97
130
 
131
+ const screenshotInspector = createScreenshotInspector(
132
+ (name, args) => sendRequest('tools/call', {name, arguments: args}), setSource, sourceFromToolResult,
133
+ );
134
+
98
135
  function sendRequest(method, params) {
99
136
  const id = nextRequestId++;
100
137
  window.parent.postMessage({jsonrpc: '2.0', id, method, params}, '*');
@@ -128,30 +165,9 @@ export function createPageSourceInspectorAppUI(): string {
128
165
  return text;
129
166
  }
130
167
 
131
- function appendHighlightedText(container, text, query) {
132
- const lowerText = text.toLowerCase();
133
- const lowerQuery = query.toLowerCase();
134
- let position = 0;
135
-
136
- while (position < text.length) {
137
- const matchIndex = lowerText.indexOf(lowerQuery, position);
138
- if (matchIndex === -1) {
139
- container.appendChild(document.createTextNode(text.slice(position)));
140
- return;
141
- }
142
- if (matchIndex > position) {
143
- container.appendChild(document.createTextNode(text.slice(position, matchIndex)));
144
- }
145
- const mark = document.createElement('mark');
146
- mark.textContent = text.slice(matchIndex, matchIndex + query.length);
147
- container.appendChild(mark);
148
- position = matchIndex + query.length;
149
- }
150
- }
151
-
152
168
  function renderSource() {
153
169
  const query = searchBox.value.trim();
154
- xmlContent.textContent = '';
170
+ xmlSearch.render('', '');
155
171
  xmlContent.classList.toggle('empty', source.length === 0);
156
172
  if (savedFile) {
157
173
  sourceInfo.textContent = savedFile.bytes + ' bytes saved';
@@ -160,59 +176,22 @@ export function createPageSourceInspectorAppUI(): string {
160
176
  }
161
177
  if (!source) {
162
178
  xmlContent.textContent = 'No page source was returned.';
163
- } else if (!query) {
164
- xmlContent.textContent = source;
165
179
  } else {
166
- appendHighlightedText(xmlContent, source, query);
180
+ xmlSearch.render(source, query);
167
181
  }
168
182
  sourceInfo.textContent = source.length + ' characters';
169
183
  }
170
184
 
171
185
  function setSource(nextSource) {
172
186
  source = nextSource;
187
+ screenshotInspector.updateSource(source);
173
188
  renderSource();
174
189
  }
175
190
 
176
191
  function formatXML() {
177
192
  if (!source) return;
178
193
  try {
179
- const parser = new DOMParser();
180
- const documentNode = parser.parseFromString(source, 'text/xml');
181
- if (!documentNode.documentElement || documentNode.getElementsByTagName('parsererror').length) {
182
- throw new Error('Invalid XML');
183
- }
184
-
185
- function indentElement(element, depth) {
186
- if (element.getAttribute('xml:space') === 'preserve') return;
187
- const children = Array.from(element.childNodes);
188
- const hasMixedContent = children.some((child) =>
189
- child.nodeType === 4 || (child.nodeType === 3 && (child.nodeValue || '').trim()),
190
- );
191
- if (hasMixedContent || !children.some((child) => child.nodeType === 1)) return;
192
-
193
- for (const child of children) {
194
- if (child.nodeType === 3) {
195
- element.removeChild(child);
196
- continue;
197
- }
198
- if (child.nodeType === 1) indentElement(child, depth + 1);
199
- element.insertBefore(documentNode.createTextNode('\\n' + ' '.repeat(depth + 1)), child);
200
- }
201
- element.appendChild(documentNode.createTextNode('\\n' + ' '.repeat(depth)));
202
- }
203
-
204
- indentElement(documentNode.documentElement, 0);
205
- const serializer = new XMLSerializer();
206
- let formattedSource = Array.from(documentNode.childNodes)
207
- .filter((node) => node.nodeType !== 3)
208
- .map((node) => serializer.serializeToString(node))
209
- .join('\\n');
210
- const declaration = source.match(/^\\s*(<\\?xml\\s[^?]*\\?>)/);
211
- if (declaration && !formattedSource.startsWith('<?xml ')) {
212
- formattedSource = declaration[1] + '\\n' + formattedSource;
213
- }
214
-
215
- source = formattedSource;
194
+ source = formatXml(source);
216
195
  renderSource();
217
196
  } catch {
218
197
  window.alert('Failed to format XML');
@@ -268,22 +247,44 @@ export function createPageSourceInspectorAppUI(): string {
268
247
  });
269
248
  }
270
249
 
250
+ function parseLocatorResult(result) {
251
+ const text = (result?.content || [])
252
+ .filter(item => item.type === 'text')
253
+ .map(item => item.text)
254
+ .join('\\n');
255
+ if (result?.isError) throw new Error(text || 'Tool returned an error');
256
+ const data = JSON.parse(text);
257
+ if (!Array.isArray(data.interactableElements)) throw new Error('No locator data returned');
258
+ return data.interactableElements;
259
+ }
260
+
261
+ function describeLocatorResults(count, query) {
262
+ if (query) {
263
+ const matches = count ? count + ' matching elements' : 'No matching elements';
264
+ return matches + ' for “' + query + '” in freshly fetched XML.';
265
+ }
266
+ if (!count) return 'No supported elements found in the fetched XML.';
267
+ return 'Candidates generated for ' + count + ' elements from freshly fetched XML.';
268
+ }
269
+
271
270
  async function generateLocators() {
272
271
  if (generateButton.disabled) return;
272
+ const query = searchBox.value.trim();
273
273
  generateButton.disabled = true;
274
274
  locatorResults.hidden = false;
275
275
  locatorStatus.textContent = 'Fetching XML and generating candidates…';
276
276
  locatorOutput.textContent = '';
277
277
  try {
278
- const result = await sendRequest('tools/call', {name: 'generate_locators', arguments: {}});
279
- const text = (result?.content || []).filter((item) => item.type === 'text').map((item) => item.text).join('\\n');
280
- if (result?.isError) throw new Error(text || 'Tool returned an error');
281
- const data = JSON.parse(text);
282
- if (!Array.isArray(data.interactableElements)) throw new Error('No locator data returned');
283
- const elements = data.interactableElements;
284
- locatorStatus.textContent = elements.length
285
- ? 'Candidates generated for ' + elements.length + ' elements from freshly fetched XML.'
286
- : 'No supported elements found in the fetched XML.';
278
+ const xpathAttributes = [...new Set((document.getElementById('xpathAttributes').value || '')
279
+ .split(',').map(name => name.trim()).filter(Boolean))];
280
+ if (xpathAttributes.length > 20 || xpathAttributes.some(name => !/^[A-Za-z_][A-Za-z0-9_.-]*$/.test(name))) {
281
+ throw new Error('Enter up to 20 attribute names, separated by commas (no XPath expressions or namespace prefixes).');
282
+ }
283
+ const args = query ? {query} : {};
284
+ if (xpathAttributes.length) args.xpathAttributes = xpathAttributes;
285
+ const result = await sendRequest('tools/call', {name: 'generate_locators', arguments: args});
286
+ const elements = parseLocatorResult(result);
287
+ locatorStatus.textContent = describeLocatorResults(elements.length, query);
287
288
  renderLocators(elements);
288
289
  } catch (error) {
289
290
  locatorStatus.textContent = 'Failed to generate locators: ' + error.message;
@@ -313,7 +314,11 @@ export function createPageSourceInspectorAppUI(): string {
313
314
  }
314
315
  });
315
316
 
316
- searchBox.addEventListener('input', renderSource);
317
+ searchBox.addEventListener('input', () => {
318
+ renderSource();
319
+ screenshotInspector.filter(searchBox.value);
320
+ });
321
+ searchBox.addEventListener('keydown', xmlSearch.handleKeyDown);
317
322
  document.getElementById('copyButton').addEventListener('click', copyToClipboard);
318
323
  document.getElementById('formatButton').addEventListener('click', formatXML);
319
324
  document.getElementById('generateButton').addEventListener('click', generateLocators);
@@ -0,0 +1,91 @@
1
+ /** Shared browser helpers embedded by both inspector transports. Keep these scripts data-free. */
2
+ export const XML_FORMAT_SCRIPT = String.raw`
3
+ function formatXml(source) {
4
+ const documentNode = new DOMParser().parseFromString(source, 'text/xml');
5
+ if (!documentNode.documentElement || documentNode.getElementsByTagName('parsererror').length) {
6
+ throw new Error('Invalid XML');
7
+ }
8
+
9
+ function indentElement(element, depth) {
10
+ // Whitespace can be meaningful in mixed content, CDATA and preserved subtrees.
11
+ if (element.getAttribute('xml:space') === 'preserve') return;
12
+ const children = Array.from(element.childNodes);
13
+ const hasText = children.some(child =>
14
+ child.nodeType === 4 || (child.nodeType === 3 && (child.nodeValue || '').trim())
15
+ );
16
+ if (hasText || !children.some(child => child.nodeType === 1)) return;
17
+ for (const child of children) {
18
+ if (child.nodeType === 3) {
19
+ element.removeChild(child);
20
+ continue;
21
+ }
22
+ if (child.nodeType === 1) indentElement(child, depth + 1);
23
+ element.insertBefore(documentNode.createTextNode('\n' + ' '.repeat(depth + 1)), child);
24
+ }
25
+ element.appendChild(documentNode.createTextNode('\n' + ' '.repeat(depth)));
26
+ }
27
+
28
+ indentElement(documentNode.documentElement, 0);
29
+ const serializer = new XMLSerializer();
30
+ let formatted = Array.from(documentNode.childNodes)
31
+ .filter(node => node.nodeType !== 3)
32
+ .map(node => serializer.serializeToString(node))
33
+ .join('\n');
34
+ const declaration = source.match(/^\s*(<\?xml\s[^?]*\?>)/);
35
+ if (declaration && !formatted.startsWith('<?xml ')) {
36
+ formatted = declaration[1] + '\n' + formatted;
37
+ }
38
+ return formatted;
39
+ }
40
+ `;
41
+
42
+ export const XML_SEARCH_SCRIPT = String.raw`
43
+ function createXmlSearch(container, status) {
44
+ let matches = [];
45
+ let activeIndex = -1;
46
+
47
+ function render(text, query) {
48
+ container.textContent = '';
49
+ matches = [];
50
+ activeIndex = -1;
51
+ query = query.trim();
52
+ status.textContent = '';
53
+ if (!query) {
54
+ container.textContent = text;
55
+ return;
56
+ }
57
+ const lowerText = text.toLowerCase();
58
+ const lowerQuery = query.toLowerCase();
59
+ let position = 0;
60
+ while (position < text.length) {
61
+ const index = lowerText.indexOf(lowerQuery, position);
62
+ if (index === -1) break;
63
+ container.appendChild(document.createTextNode(text.slice(position, index)));
64
+ const mark = document.createElement('mark');
65
+ mark.textContent = text.slice(index, index + query.length);
66
+ container.appendChild(mark);
67
+ matches.push(mark);
68
+ position = index + query.length;
69
+ }
70
+ container.appendChild(document.createTextNode(text.slice(position)));
71
+ status.textContent = matches.length ? matches.length + ' matches · Enter / Shift+Enter to navigate' : 'No matches';
72
+ }
73
+
74
+ function handleKeyDown(event) {
75
+ if (event.key !== 'Enter' || event.isComposing) return;
76
+ event.preventDefault();
77
+ if (!matches.length) return;
78
+ if (activeIndex >= 0) matches[activeIndex].removeAttribute('data-active');
79
+ const step = event.shiftKey ? -1 : 1;
80
+ activeIndex = activeIndex < 0
81
+ ? (event.shiftKey ? matches.length - 1 : 0)
82
+ : (activeIndex + step + matches.length) % matches.length;
83
+ const match = matches[activeIndex];
84
+ match.setAttribute('data-active', 'true');
85
+ match.scrollIntoView({block: 'nearest', inline: 'nearest'});
86
+ status.textContent = (activeIndex + 1) + ' / ' + matches.length + ' · Enter / Shift+Enter to navigate';
87
+ }
88
+
89
+ return {render, handleKeyDown};
90
+ }
91
+ `;