digital-ai-testing-mcp 1.2.8 → 2.0.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 (191) hide show
  1. package/README.md +148 -46
  2. package/dist/api/browser-inspection.d.ts.map +1 -1
  3. package/dist/api/browser-inspection.js +14 -15
  4. package/dist/api/browser-inspection.js.map +1 -1
  5. package/dist/api/client.d.ts +7 -0
  6. package/dist/api/client.d.ts.map +1 -1
  7. package/dist/api/client.js +9 -0
  8. package/dist/api/client.js.map +1 -1
  9. package/dist/api/projects.d.ts +16 -3
  10. package/dist/api/projects.d.ts.map +1 -1
  11. package/dist/api/projects.js +60 -18
  12. package/dist/api/projects.js.map +1 -1
  13. package/dist/api/reporting.d.ts +91 -0
  14. package/dist/api/reporting.d.ts.map +1 -1
  15. package/dist/api/reporting.js +182 -8
  16. package/dist/api/reporting.js.map +1 -1
  17. package/dist/api/test-orchestrator.d.ts +59 -0
  18. package/dist/api/test-orchestrator.d.ts.map +1 -0
  19. package/dist/api/test-orchestrator.js +126 -0
  20. package/dist/api/test-orchestrator.js.map +1 -0
  21. package/dist/api/test-runs.d.ts +80 -0
  22. package/dist/api/test-runs.d.ts.map +1 -0
  23. package/dist/api/test-runs.js +209 -0
  24. package/dist/api/test-runs.js.map +1 -0
  25. package/dist/api/test-views.d.ts.map +1 -1
  26. package/dist/api/test-views.js +5 -1
  27. package/dist/api/test-views.js.map +1 -1
  28. package/dist/api/transactions.d.ts +6 -0
  29. package/dist/api/transactions.d.ts.map +1 -1
  30. package/dist/api/transactions.js +19 -3
  31. package/dist/api/transactions.js.map +1 -1
  32. package/dist/api/usage-reports.d.ts.map +1 -1
  33. package/dist/api/usage-reports.js +3 -3
  34. package/dist/api/usage-reports.js.map +1 -1
  35. package/dist/api/webdriver.d.ts +44 -1
  36. package/dist/api/webdriver.d.ts.map +1 -1
  37. package/dist/api/webdriver.js +194 -67
  38. package/dist/api/webdriver.js.map +1 -1
  39. package/dist/index.js +80 -32
  40. package/dist/index.js.map +1 -1
  41. package/dist/tools/agent-tools.js +2 -2
  42. package/dist/tools/agent-tools.js.map +1 -1
  43. package/dist/tools/application-tools.d.ts.map +1 -1
  44. package/dist/tools/application-tools.js +5 -4
  45. package/dist/tools/application-tools.js.map +1 -1
  46. package/dist/tools/boilerplate-tools.d.ts +3 -0
  47. package/dist/tools/boilerplate-tools.d.ts.map +1 -1
  48. package/dist/tools/boilerplate-tools.js +301 -20
  49. package/dist/tools/boilerplate-tools.js.map +1 -1
  50. package/dist/tools/browser-tools.d.ts.map +1 -1
  51. package/dist/tools/browser-tools.js +8 -5
  52. package/dist/tools/browser-tools.js.map +1 -1
  53. package/dist/tools/device-group-tools.js +5 -5
  54. package/dist/tools/device-group-tools.js.map +1 -1
  55. package/dist/tools/device-tools.d.ts.map +1 -1
  56. package/dist/tools/device-tools.js +5 -4
  57. package/dist/tools/device-tools.js.map +1 -1
  58. package/dist/tools/health-tools.d.ts.map +1 -1
  59. package/dist/tools/health-tools.js +5 -4
  60. package/dist/tools/health-tools.js.map +1 -1
  61. package/dist/tools/inspection-tools.d.ts.map +1 -1
  62. package/dist/tools/inspection-tools.js +112 -10
  63. package/dist/tools/inspection-tools.js.map +1 -1
  64. package/dist/tools/meta-tools.d.ts +4 -1
  65. package/dist/tools/meta-tools.d.ts.map +1 -1
  66. package/dist/tools/meta-tools.js +62 -36
  67. package/dist/tools/meta-tools.js.map +1 -1
  68. package/dist/tools/performance-tools.d.ts.map +1 -1
  69. package/dist/tools/performance-tools.js +1 -7
  70. package/dist/tools/performance-tools.js.map +1 -1
  71. package/dist/tools/project-tools.d.ts.map +1 -1
  72. package/dist/tools/project-tools.js +38 -19
  73. package/dist/tools/project-tools.js.map +1 -1
  74. package/dist/tools/provisioning-profile-tools.d.ts.map +1 -1
  75. package/dist/tools/provisioning-profile-tools.js +5 -4
  76. package/dist/tools/provisioning-profile-tools.js.map +1 -1
  77. package/dist/tools/remediation-tools.d.ts +7 -0
  78. package/dist/tools/remediation-tools.d.ts.map +1 -0
  79. package/dist/tools/remediation-tools.js +50 -0
  80. package/dist/tools/remediation-tools.js.map +1 -0
  81. package/dist/tools/reporting-tools.d.ts.map +1 -1
  82. package/dist/tools/reporting-tools.js +369 -136
  83. package/dist/tools/reporting-tools.js.map +1 -1
  84. package/dist/tools/repository-tools.d.ts.map +1 -1
  85. package/dist/tools/repository-tools.js +5 -4
  86. package/dist/tools/repository-tools.js.map +1 -1
  87. package/dist/tools/reservation-tools.js +2 -2
  88. package/dist/tools/reservation-tools.js.map +1 -1
  89. package/dist/tools/test-run-tools.d.ts +3 -0
  90. package/dist/tools/test-run-tools.d.ts.map +1 -0
  91. package/dist/tools/test-run-tools.js +284 -0
  92. package/dist/tools/test-run-tools.js.map +1 -0
  93. package/dist/tools/test-view-tools.d.ts.map +1 -1
  94. package/dist/tools/test-view-tools.js +11 -11
  95. package/dist/tools/test-view-tools.js.map +1 -1
  96. package/dist/tools/toolset-tools.d.ts +8 -0
  97. package/dist/tools/toolset-tools.d.ts.map +1 -0
  98. package/dist/tools/toolset-tools.js +40 -0
  99. package/dist/tools/toolset-tools.js.map +1 -0
  100. package/dist/tools/transaction-tools.d.ts.map +1 -1
  101. package/dist/tools/transaction-tools.js +17 -7
  102. package/dist/tools/transaction-tools.js.map +1 -1
  103. package/dist/tools/usage-report-tools.d.ts.map +1 -1
  104. package/dist/tools/usage-report-tools.js +43 -15
  105. package/dist/tools/usage-report-tools.js.map +1 -1
  106. package/dist/tools/user-tools.js +2 -2
  107. package/dist/tools/user-tools.js.map +1 -1
  108. package/dist/tools/web-inspection-tools.d.ts.map +1 -1
  109. package/dist/tools/web-inspection-tools.js +39 -26
  110. package/dist/tools/web-inspection-tools.js.map +1 -1
  111. package/dist/tools/workflow-tools.js +1 -1
  112. package/dist/types/digital-ai.d.ts +18 -3
  113. package/dist/types/digital-ai.d.ts.map +1 -1
  114. package/dist/utils/browser-name.d.ts +2 -0
  115. package/dist/utils/browser-name.d.ts.map +1 -0
  116. package/dist/utils/browser-name.js +19 -0
  117. package/dist/utils/browser-name.js.map +1 -0
  118. package/dist/utils/command-payload.d.ts +19 -0
  119. package/dist/utils/command-payload.d.ts.map +1 -0
  120. package/dist/utils/command-payload.js +13 -0
  121. package/dist/utils/command-payload.js.map +1 -0
  122. package/dist/utils/csv.d.ts +6 -0
  123. package/dist/utils/csv.d.ts.map +1 -1
  124. package/dist/utils/csv.js +28 -2
  125. package/dist/utils/csv.js.map +1 -1
  126. package/dist/utils/locality.d.ts +7 -0
  127. package/dist/utils/locality.d.ts.map +1 -1
  128. package/dist/utils/locality.js +19 -0
  129. package/dist/utils/locality.js.map +1 -1
  130. package/dist/utils/maestro-flow.d.ts +38 -0
  131. package/dist/utils/maestro-flow.d.ts.map +1 -0
  132. package/dist/utils/maestro-flow.js +114 -0
  133. package/dist/utils/maestro-flow.js.map +1 -0
  134. package/dist/utils/metric-semantics.d.ts +22 -0
  135. package/dist/utils/metric-semantics.d.ts.map +1 -0
  136. package/dist/utils/metric-semantics.js +24 -0
  137. package/dist/utils/metric-semantics.js.map +1 -0
  138. package/dist/utils/pagination.d.ts +11 -0
  139. package/dist/utils/pagination.d.ts.map +1 -1
  140. package/dist/utils/pagination.js +16 -0
  141. package/dist/utils/pagination.js.map +1 -1
  142. package/dist/utils/remediation.d.ts +130 -0
  143. package/dist/utils/remediation.d.ts.map +1 -0
  144. package/dist/utils/remediation.js +424 -0
  145. package/dist/utils/remediation.js.map +1 -0
  146. package/dist/utils/report-ref.d.ts +23 -0
  147. package/dist/utils/report-ref.d.ts.map +1 -0
  148. package/dist/utils/report-ref.js +31 -0
  149. package/dist/utils/report-ref.js.map +1 -0
  150. package/dist/utils/response-formatter.d.ts +2 -1
  151. package/dist/utils/response-formatter.d.ts.map +1 -1
  152. package/dist/utils/response-formatter.js +32 -21
  153. package/dist/utils/response-formatter.js.map +1 -1
  154. package/dist/utils/test-orchestrator.d.ts +102 -0
  155. package/dist/utils/test-orchestrator.d.ts.map +1 -0
  156. package/dist/utils/test-orchestrator.js +236 -0
  157. package/dist/utils/test-orchestrator.js.map +1 -0
  158. package/dist/utils/test-status.d.ts +48 -0
  159. package/dist/utils/test-status.d.ts.map +1 -0
  160. package/dist/utils/test-status.js +92 -0
  161. package/dist/utils/test-status.js.map +1 -0
  162. package/dist/utils/tool-catalog.d.ts +6 -0
  163. package/dist/utils/tool-catalog.d.ts.map +1 -0
  164. package/dist/utils/tool-catalog.js +15 -0
  165. package/dist/utils/tool-catalog.js.map +1 -0
  166. package/dist/utils/toolsets.d.ts +79 -0
  167. package/dist/utils/toolsets.d.ts.map +1 -0
  168. package/dist/utils/toolsets.js +156 -0
  169. package/dist/utils/toolsets.js.map +1 -0
  170. package/dist/utils/usage-report-guard.d.ts +7 -0
  171. package/dist/utils/usage-report-guard.d.ts.map +1 -1
  172. package/dist/utils/usage-report-guard.js +18 -1
  173. package/dist/utils/usage-report-guard.js.map +1 -1
  174. package/dist/utils/usage-report-summary.d.ts +12 -0
  175. package/dist/utils/usage-report-summary.d.ts.map +1 -1
  176. package/dist/utils/usage-report-summary.js +25 -6
  177. package/dist/utils/usage-report-summary.js.map +1 -1
  178. package/package.json +41 -4
  179. package/resources/boilerplate/Android-Native/Java JUnit5/gradle +6 -1
  180. package/resources/boilerplate/Android-Native/Java JUnit5/gradle-oss +6 -1
  181. package/resources/boilerplate/Android-Native/java TestNG/AndroidNative-oss.java +2 -2
  182. package/resources/boilerplate/Android-Native/java TestNG/AndroidNative.java +2 -2
  183. package/resources/boilerplate/Android-Native/java TestNG/gradle +1 -1
  184. package/resources/boilerplate/Android-Native/java TestNG/gradle-oss +1 -1
  185. package/resources/boilerplate/iOS-Native/java-JUnit5/gradle +6 -1
  186. package/resources/boilerplate/iOS-Native/java-JUnit5/gradle-oss +6 -1
  187. package/resources/boilerplate/iOS-Native/java-TestNG/gradle +1 -1
  188. package/resources/boilerplate/iOS-Native/java-TestNG/gradle-oss +1 -1
  189. package/resources/boilerplate/iOS-Native/java-TestNG/iOSNative-oss.java +2 -2
  190. package/resources/boilerplate/iOS-Native/java-TestNG/iOSNative.java +2 -2
  191. package/resources/test-orchestrator/agent.json +19 -0
@@ -1,3 +1,4 @@
1
+ import { canonicalBrowserName } from '../utils/browser-name.js';
1
2
  import { z } from 'zod';
2
3
  import { readFileSync } from 'fs';
3
4
  import { join, dirname } from 'path';
@@ -5,9 +6,13 @@ import { fileURLToPath } from 'url';
5
6
  import { getMyAccountInfo } from '../api/users.js';
6
7
  import { getApplicationInfo } from '../api/applications.js';
7
8
  import { getActiveAccessKey, getActiveUrl } from '../api/client.js';
8
- import { listActiveSessions } from '../api/webdriver.js';
9
+ import { listActiveSessions, AUTOMOTIVE_RESOLUTIONS } from '../api/webdriver.js';
9
10
  import { outputFormatParam, respond } from '../utils/output-format.js';
10
- import { staleBuildRemedy } from '../utils/locality.js';
11
+ import { staleBuildRemedy, serverFsInstallNotice, serverFsProjectDirParam } from '../utils/locality.js';
12
+ import { isLocalFilesystem } from '../utils/deployment-mode.js';
13
+ import { validateOutputPath } from '../utils/path-guard.js';
14
+ import { AGENT_PROJECT_PATH, CONFIG_TEMPLATE_PATH, GITIGNORE_ADVICE, JDK_TRUST_NOTE, LIB_GITIGNORE, LIB_GITIGNORE_PATH, ORCHESTRATOR_GITIGNORE, ORCHESTRATOR_GITIGNORE_PATH, addOrchestrationToGradle, addOrchestrationToMaven, buildConfigTemplate, decideOrchestration, resolveMaxRetryAttempts, } from '../utils/test-orchestrator.js';
15
+ import { buildAgentDownloadCommands, installAgentIntoProject, resolveAgentSource, } from '../api/test-orchestrator.js';
11
16
  const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
12
17
  const BOILERPLATE_DIR = join(PACKAGE_ROOT, 'resources', 'boilerplate');
13
18
  const PLATFORM_DIR = {
@@ -76,6 +81,15 @@ function getFilesForVariant(platform, language, isAppiumOss, projectType) {
76
81
  }
77
82
  }
78
83
  }
84
+ // Gradle templates declare `repositories { mavenCentral() }` so the default standalone project resolves its
85
+ // dependencies (without it every standalone build failed: "no repositories are defined"). Inside an existing
86
+ // Android project the module must NOT declare repositories: they are centralised in settings.gradle, often with
87
+ // RepositoriesMode.FAIL_ON_PROJECT_REPOS, which turns a module-level block into a build error.
88
+ export function adaptGradleForProjectType(content, projectType) {
89
+ if (projectType !== 'android-gradle-submodule')
90
+ return content;
91
+ return content.replace(/^\/\/ Standalone use only[^\n]*\r?\nrepositories \{ mavenCentral\(\) \}\r?\n(\r?\n)?/m, '');
92
+ }
79
93
  export function detectFabricationIssues(content) {
80
94
  const issues = [];
81
95
  const add = (severity, label, detail) => issues.push({ severity, label, detail });
@@ -185,6 +199,37 @@ function appendAxeScan(language, indent, apiKey) {
185
199
  `${indent}await browser.execute('mobile: axeScan', axeSettings);`,
186
200
  ].join('\n');
187
201
  }
202
+ // Android Auto / CarPlay head-unit check, appended after the test steps when automotiveProjection is set. The capability
203
+ // (injected separately) keeps projection on for the whole session — verified live as the reliable route (a Galaxy S10
204
+ // rejects mid-session digitalai:automotive.start but projects fine with the capability). No selectors are involved:
205
+ // it captures the head unit and leaves the tap as a commented template, so nothing fabricated is presented as a step.
206
+ function appendAutomotiveCheck(language, indent) {
207
+ if (language === 'java-junit5' || language === 'java-testng') {
208
+ return [
209
+ `${indent}// Android Auto / CarPlay head unit (digitalai:automotiveProjection is on for this whole session).`,
210
+ `${indent}// getScreenshot returns a base64 PNG of the projected display; tap takes head-unit coordinates.`,
211
+ `${indent}String headUnitPng = (String) driver.executeScript("digitalai:automotive.getScreenshot");`,
212
+ `${indent}System.out.println("Head unit screenshot: " + headUnitPng.length() + " base64 chars");`,
213
+ `${indent}// driver.executeScript("digitalai:automotive.tap", x, y); // coordinates within the projection resolution`,
214
+ ].join('\n');
215
+ }
216
+ if (language === 'python') {
217
+ return [
218
+ `${indent}# Android Auto / CarPlay head unit (digitalai:automotiveProjection is on for this whole session).`,
219
+ `${indent}# getScreenshot returns a base64 PNG of the projected display; tap takes head-unit coordinates.`,
220
+ `${indent}head_unit_png = self.driver.execute_script("digitalai:automotive.getScreenshot")`,
221
+ `${indent}print(f"Head unit screenshot: {len(head_unit_png)} base64 chars")`,
222
+ `${indent}# self.driver.execute_script("digitalai:automotive.tap", x, y) # coordinates within the projection resolution`,
223
+ ].join('\n');
224
+ }
225
+ return [
226
+ `${indent}// Android Auto / CarPlay head unit (digitalai:automotiveProjection is on for this whole session).`,
227
+ `${indent}// getScreenshot returns a base64 PNG of the projected display; tap takes head-unit coordinates.`,
228
+ `${indent}const headUnitPng = await browser.execute('digitalai:automotive.getScreenshot');`,
229
+ `${indent}console.log(\`Head unit screenshot: \${headUnitPng.length} base64 chars\`);`,
230
+ `${indent}// await browser.execute('digitalai:automotive.tap', x, y); // coordinates within the projection resolution`,
231
+ ].join('\n');
232
+ }
188
233
  // The cleared-body placeholder is a deliberate ANTI-fabrication guard (v38).
189
234
  // Three properties matter: (1) a loud banner so the scaffold is never mistaken
190
235
  // for a finished test; (2) an EXECUTABLE fail/raise as the first statement so a
@@ -279,7 +324,12 @@ function buildPlaceholder(language, platform, indent) {
279
324
  }
280
325
  function readBoilerplateFile(platform, language, diskName) {
281
326
  const dir = join(BOILERPLATE_DIR, PLATFORM_DIR[platform], LANGUAGE_SUBDIR[platform][language]);
282
- return readFileSync(join(dir, diskName), 'utf-8');
327
+ // Normalize to LF: the marker/injection patterns (DEMO_STEP_PATTERN etc.) match "\n" only. Git stores the templates
328
+ // with LF, but a Windows checkout with core.autocrlf materializes some as CRLF — and then, for those files, the
329
+ // custom-app placeholder never replaced the ExperiBank demo steps (the anti-fabrication guard silently did nothing)
330
+ // and includeAxeScan / includePerformanceTransactions / automotiveProjection were no-ops. Affects local runs and any
331
+ // Docker image built from a Windows working tree.
332
+ return readFileSync(join(dir, diskName), 'utf-8').replace(/\r\n/g, '\n');
283
333
  }
284
334
  function substitute(content, language, platform, vars) {
285
335
  let result = content;
@@ -293,17 +343,23 @@ function substitute(content, language, platform, vars) {
293
343
  if (vars.axeScan) {
294
344
  placeholder += '\n' + appendAxeScan(language, indent, vars.axeApiKey ?? '');
295
345
  }
346
+ if (vars.automotiveProjection) {
347
+ placeholder += '\n' + appendAutomotiveCheck(language, indent);
348
+ }
296
349
  if (vars.performanceTransactions) {
297
350
  placeholder = wrapWithPerformanceTransaction(language, indent, placeholder);
298
351
  }
299
352
  result = result.replace(DEMO_STEP_PATTERN, placeholder);
300
353
  }
301
- else if (vars.performanceTransactions || vars.axeScan) {
354
+ else if (vars.performanceTransactions || vars.axeScan || vars.automotiveProjection) {
302
355
  result = result.replace(DEMO_INNER_PATTERN, (inner) => {
303
356
  let content = inner;
304
357
  if (vars.axeScan) {
305
358
  content += '\n' + appendAxeScan(language, indent, vars.axeApiKey ?? '');
306
359
  }
360
+ if (vars.automotiveProjection) {
361
+ content += '\n' + appendAutomotiveCheck(language, indent);
362
+ }
307
363
  return vars.performanceTransactions
308
364
  ? wrapWithPerformanceTransaction(language, indent, content)
309
365
  : content;
@@ -362,6 +418,18 @@ function substitute(content, language, platform, vars) {
362
418
  result = result.replace(/('digitalai:deviceQuery': [^\n]+)/, (match) => `${match}\n 'appium:automationName': '${automationName}',\n 'appiumVersion': '2.16.2',`);
363
419
  }
364
420
  }
421
+ if (vars.automotiveProjection) {
422
+ const res = vars.automotiveProjection;
423
+ if (language === 'java-junit5' || language === 'java-testng') {
424
+ result = result.replace(/\n( +)(driver = new (?:Android|iOS)Driver)/, (_m, sp, line) => `\n${sp}options.setCapability("digitalai:automotiveProjection", "${res}");\n${sp}${line}`);
425
+ }
426
+ else if (language === 'python') {
427
+ result = result.replace(/\n( +)(self\.driver = webdriver\.Remote\()/, (_m, sp, line) => `\n${sp}options.set_capability('digitalai:automotiveProjection', '${res}')\n${sp}${line}`);
428
+ }
429
+ else if (language === 'nodejs') {
430
+ result = result.replace(/('digitalai:deviceQuery': [^\n]+)/, (match) => `${match}\n 'digitalai:automotiveProjection': '${res}',`);
431
+ }
432
+ }
365
433
  return result;
366
434
  }
367
435
  function setupNote(language, isAppiumOss, projectType) {
@@ -408,9 +476,10 @@ function setupNote(language, isAppiumOss, projectType) {
408
476
  ' test/specs/<TestFile>.js\n\n' +
409
477
  'Then run:\n' +
410
478
  ' npm install && npm run wdio\n\n' +
411
- 'IMPORTANT: Do NOT run npm init wdio — it installs wdio v9 which is rejected by\n' +
412
- ' the Digital.ai Appium Grid ("Cant run Appium Grid with Appium client 8+").\n' +
413
- ' The package.json above pins wdio to v7.40.0, which is the last compatible version.');
479
+ 'IMPORTANT: Do NOT run npm init wdio — it installs wdio v9, which this project\'s Appium Grid rejects\n' +
480
+ ' ("Cant run Appium Grid with Appium client 8+"). The Grid requires the legacy desiredCapabilities in the\n' +
481
+ ' session request; wdio v8+ sends W3C capabilities only. The package.json above pins wdio v7.40.0, the last\n' +
482
+ ' release that still sends them (verified live: v9 refused, v7.40 runs). Appium Server projects use wdio v9.');
414
483
  case 'python':
415
484
  return isAppiumOss
416
485
  ? 'Install the dependency with: pip install -r requirements.txt (Appium-Python-Client>=4.0.0), then run: python -m pytest\n\n' +
@@ -601,21 +670,48 @@ export function registerBoilerplateTools(server) {
601
670
  .describe('Add a Deque Axe DevTools accessibility scan to the generated test. ' +
602
671
  'When enabled: (1) sets appium:automationName to AxeUiAutomator2 (Android) or AxeXCUITest (iOS) ' +
603
672
  'and appiumVersion to "2.16.2" in setUp — required for the Axe integration to function; ' +
673
+ 'do NOT raise appiumVersion to 3.3.0 or later — the Axe driver is unavailable on Appium Server >=3.3.0 (platform known issue, 26.6/26.7); ' +
604
674
  '(2) injects driver.executeScript("mobile: axeScan", settings) into the test body after the test steps. ' +
605
675
  'The Axe API key is read from AXE_DEVTOOLS_API_KEY in the MCP environment; if not set, a placeholder is used. ' +
606
676
  'Scan results appear in the Axe DevTools Mobile dashboard. ' +
607
677
  'Can be combined with includePerformanceTransactions — the scan runs inside the performance transaction boundary.'),
678
+ automotiveProjection: z
679
+ .enum(AUTOMOTIVE_RESOLUTIONS)
680
+ .optional()
681
+ .describe('Android Auto (Android) / CarPlay (iOS) projection test: sets digitalai:automotiveProjection to this head-unit resolution ' +
682
+ '(projection stays on for the whole session) and appends a head-unit screenshot step plus a commented tap template ' +
683
+ 'after the test steps. CarPlay supports 800x480 only. Appium Server projects only — on Appium Grid the classic ' +
684
+ 'boilerplate is returned with a note. Build head-unit steps from automotive_control screenshots in an inspection session.'),
608
685
  confirmSelectorsVerified: z
609
686
  .boolean()
610
687
  .optional()
611
688
  .describe('Escape hatch for the inspection gate. When you target a real app, this tool refuses to emit code unless a ' +
612
689
  'live inspection session exists — UNLESS you set this to true. Set it ONLY if you have ALREADY captured REAL ' +
613
690
  'element IDs for this app from a source other than a still-open session: an rdb/UIAutomator dump, ' +
614
- 'open_mobile_studio, get_automation_properties, or authoritative app source in the workspace. ' +
691
+ 'open_mobile_studio (including selectors recorded with its iOS Test Recorder), get_automation_properties, ' +
692
+ 'or authoritative app source in the workspace. ' +
615
693
  'Setting this WITHOUT real captured selectors produces a placeholder scaffold with invalid <…> selectors that ' +
616
694
  'fails at runtime, and violates the tool contract. When in doubt, do NOT set it — start_inspection_session instead.'),
695
+ orchestration: z
696
+ .enum(['auto', 'on', 'off'])
697
+ .optional()
698
+ .default('auto')
699
+ .describe('Digital.ai Test Orchestrator (a JVM agent: automatic retries of failed tests, Reporter status sync, test ' +
700
+ 'selection, fail-fast, Build/Run IDs — test code unchanged). "auto" (default): ON for Java (java-junit5 / ' +
701
+ 'java-testng) on an Appium Server project, OFF otherwise (Appium Grid, Python and NodeJS are not supported). ' +
702
+ '"off": the classic non-orchestrated boilerplate — use when the user explicitly asks for it. "on": require it ' +
703
+ '(an unsupported combination returns the classic output with an explanation). Orchestrated projects attach ' +
704
+ 'the agent only when lib/smart-agent.jar is present — install it with install_test_orchestrator_agent.'),
705
+ orchestrationMaxRetries: z
706
+ .number()
707
+ .int()
708
+ .min(0)
709
+ .max(5)
710
+ .optional()
711
+ .describe('Orchestrated projects only: run.maxRetryAttempts in the agent config. Default 2 — or 0 when the test body is ' +
712
+ 'a placeholder (fails by design) or includePerformanceTransactions is set (retries would skew samples).'),
617
713
  outputFormat: outputFormatParam,
618
- }, async ({ platform, language, appId, deviceCategory, testName, packageName, mainActivity, bundleIdentifier, projectType, region, includePerformanceTransactions, includeAxeScan, confirmSelectorsVerified, outputFormat }) => {
714
+ }, async ({ platform, language, appId, deviceCategory, testName, packageName, mainActivity, bundleIdentifier, projectType, region, includePerformanceTransactions, includeAxeScan, automotiveProjection, confirmSelectorsVerified, orchestration, orchestrationMaxRetries, outputFormat }) => {
619
715
  // ── Inspection gate (v42) ────────────────────────────────────────────────
620
716
  // Advisory guards (warning text, a requiresVerifiedSelectors flag, an in-code
621
717
  // fail() guard) all lost to task-completion momentum: the agent stripped the
@@ -671,13 +767,26 @@ export function registerBoilerplateTools(server) {
671
767
  // leave as raw value if URL parsing fails
672
768
  }
673
769
  // Auto-detect server mode via my-account-info — works for all user roles with Bearer Token.
674
- let isAppiumOss = false;
770
+ // undefined = lookup failed. Templates fall back to Grid (the conservative choice), but the orchestration
771
+ // decision must not then claim the project IS Grid — it reports that the mode could not be determined.
772
+ let detectedAppiumOss;
675
773
  try {
676
774
  const me = await getMyAccountInfo();
677
- isAppiumOss = me.project.isAppiumOss ?? false;
775
+ detectedAppiumOss = me.project.isAppiumOss ?? false;
678
776
  }
679
777
  catch {
680
- // leave as false — don't fail boilerplate generation on lookup error
778
+ // don't fail boilerplate generation on lookup error
779
+ }
780
+ const isAppiumOss = detectedAppiumOss ?? false;
781
+ // Automotive projection is verified on Appium Server only; Grid sessions run a different execute layer.
782
+ let automotive;
783
+ if (automotiveProjection) {
784
+ if (platform === 'ios' && automotiveProjection !== '800x480') {
785
+ return { content: [{ type: 'text', text: 'Error: CarPlay supports automotiveProjection "800x480" only.' }], isError: true };
786
+ }
787
+ automotive = isAppiumOss
788
+ ? { resolution: automotiveProjection, applied: true, note: `digitalai:automotiveProjection=${automotiveProjection} set; the test captures the ${platform === 'ios' ? 'CarPlay' : 'Android Auto'} head unit after its steps. Use automotive_control in an inspection session to explore the head unit and pick tap coordinates.` }
789
+ : { resolution: automotiveProjection, applied: false, note: detectedAppiumOss === undefined ? 'the project mode could not be determined, and projection is only supported here for Appium Server projects.' : 'this project runs on Appium Grid, which does not support projection commands (verified: the Grid execute layer runs digitalai:automotive.* as JavaScript and every command fails).' };
681
790
  }
682
791
  // Resolve app capabilities from appId if provided.
683
792
  let resolvedPackageName = packageName;
@@ -726,6 +835,7 @@ export function registerBoilerplateTools(server) {
726
835
  axeScan: includeAxeScan,
727
836
  axeApiKey: process.env.AXE_DEVTOOLS_API_KEY,
728
837
  isAppiumOss,
838
+ automotiveProjection: automotive?.applied ? automotive.resolution : undefined,
729
839
  };
730
840
  const files = getFilesForVariant(platform, language, isAppiumOss, projectType);
731
841
  // Grid scripts carry non-obvious workarounds (pinned clients, JWP capability
@@ -753,9 +863,71 @@ export function registerBoilerplateTools(server) {
753
863
  try {
754
864
  const resolved = files.map(f => {
755
865
  const raw = readBoilerplateFile(platform, language, f.diskName);
756
- const content = substitute(raw, language, platform, vars);
866
+ const substituted = substitute(raw, language, platform, vars);
867
+ const content = f.diskName.startsWith('gradle')
868
+ ? adaptGradleForProjectType(substituted, projectType)
869
+ : substituted;
757
870
  return { ...f, content: gridHeader(f.filename) + content };
758
871
  });
872
+ // ── Test Orchestrator (default ON for Java on Appium Server) ─────────────
873
+ const decision = decideOrchestration({ mode: orchestration, language, isAppiumOss: detectedAppiumOss });
874
+ let orchestrationInfo = { enabled: false, mode: orchestration, reason: decision.reason };
875
+ if (decision.enabled) {
876
+ const retries = resolveMaxRetryAttempts({
877
+ requested: orchestrationMaxRetries,
878
+ placeholderBody: clearTestBody,
879
+ performanceTransactions: includePerformanceTransactions === true,
880
+ });
881
+ const prefix = projectType === 'android-gradle-submodule' ? 'e2e-tests/' : '';
882
+ for (const f of resolved) {
883
+ if (f.diskName.startsWith('gradle'))
884
+ f.content = addOrchestrationToGradle(f.content);
885
+ else if (f.diskName.startsWith('maven'))
886
+ f.content = addOrchestrationToMaven(f.content);
887
+ }
888
+ // No root .gitignore is emitted (it would overwrite the user's). The two files that matter — the rendered
889
+ // key-bearing config and the agent JAR — are ignored by .gitignore files inside directories we own.
890
+ resolved.push({
891
+ filename: `${prefix}${CONFIG_TEMPLATE_PATH}`,
892
+ diskName: '(generated)',
893
+ lang: 'yaml',
894
+ content: buildConfigTemplate({ instanceUrl: rawBaseUrl, maxRetryAttempts: retries.value }),
895
+ }, { filename: `${prefix}${ORCHESTRATOR_GITIGNORE_PATH}`, diskName: '(generated)', lang: 'gitignore', content: ORCHESTRATOR_GITIGNORE }, { filename: `${prefix}${LIB_GITIGNORE_PATH}`, diskName: '(generated)', lang: 'gitignore', content: LIB_GITIGNORE });
896
+ // The agent manifest is only needed for a display string here — a missing/corrupt manifest must never sink
897
+ // the boilerplate itself (install_test_orchestrator_agent reports the real error when it is actually needed).
898
+ let agentSource = 'unknown — agent manifest unreadable; install_test_orchestrator_agent will report the cause';
899
+ try {
900
+ const src = resolveAgentSource();
901
+ agentSource = src.label;
902
+ }
903
+ catch {
904
+ // degrade to the label above
905
+ }
906
+ orchestrationInfo = {
907
+ enabled: true,
908
+ mode: orchestration,
909
+ reason: decision.reason,
910
+ maxRetryAttempts: retries.value,
911
+ ...(retries.note && { maxRetryAttemptsNote: retries.note }),
912
+ agent: {
913
+ projectPath: `${prefix}${AGENT_PROJECT_PATH}`,
914
+ installedByThisTool: false,
915
+ howToInstall: 'Call install_test_orchestrator_agent with this project\'s directory' +
916
+ (prefix ? ' (the e2e-tests directory, not the Android root)' : '') +
917
+ ` — it places the agent at ${prefix}${AGENT_PROJECT_PATH}. Until it is present the build runs WITHOUT orchestration (and says so).`,
918
+ source: agentSource,
919
+ },
920
+ activation: 'The agent attaches — and the Java 17 compile level applies — only when the JAR is present AND the DIGITAL_AI_ACCESS_KEY ' +
921
+ 'environment variable is set (the agent config requires the key; it is rendered from the env var at build time into ' +
922
+ 'orchestrator/rendered/, which is git-ignored, never into a tracked file). Otherwise the project builds and runs exactly like the classic boilerplate.',
923
+ runCommands: { gradle: 'gradle test', maven: 'mvn test' },
924
+ buildId: 'Set BUILD_ID (CI usually does) to group a build\'s results in Reporter; defaults to "local".',
925
+ requirements: 'When attached: Java 17 or 21 JDK; JUnit 5 / TestNG 7+; Appium java-client 8–10 (this boilerplate uses 8.6.0).',
926
+ jdkTrustNote: JDK_TRUST_NOTE,
927
+ gitignore: GITIGNORE_ADVICE,
928
+ logs: 'smart-agent/<run-id>/smartagent-main.log — add smart-agent/ to your .gitignore.',
929
+ };
930
+ }
759
931
  const structured = {
760
932
  platform,
761
933
  language,
@@ -778,6 +950,8 @@ export function registerBoilerplateTools(server) {
778
950
  testName,
779
951
  projectType: projectType ?? 'standalone-gradle',
780
952
  files: resolved.map(f => ({ filename: f.filename, content: f.content })),
953
+ orchestration: orchestrationInfo,
954
+ ...(automotive ? { automotive } : {}),
781
955
  setupNote: setupNote(language, isAppiumOss, projectType),
782
956
  appNote: appNote(platform, vars.packageName, vars.bundleIdentifier, vars.mainActivity, resolvedFromAppId),
783
957
  parallelNote: language === 'python'
@@ -812,6 +986,21 @@ export function registerBoilerplateTools(server) {
812
986
  `> ⚠️ **Security:** These files contain a live credential — move the access key to an environment variable (\`DIGITAL_AI_ACCESS_KEY\`) before committing to source control.`,
813
987
  '',
814
988
  ];
989
+ if (orchestrationInfo.enabled && orchestrationInfo.agent) {
990
+ lines.push(`> 🔁 **Test Orchestrator: ON** — retries failed tests up to ${orchestrationInfo.maxRetryAttempts}×, syncs real pass/fail to Reporter, ` +
991
+ `groups runs by Build ID. Install the agent with \`install_test_orchestrator_agent\` (→ \`${orchestrationInfo.agent.projectPath}\`) and ` +
992
+ 'set `DIGITAL_AI_ACCESS_KEY`; until both are in place the project builds and runs exactly like the classic boilerplate (Gradle prints why). ' +
993
+ 'Pass `orchestration: "off"` for the classic boilerplate.' + (orchestrationInfo.maxRetryAttemptsNote ? ` ${orchestrationInfo.maxRetryAttemptsNote}` : ''), '> **Java/TLS:** when attached, the agent needs Java 17/21 — use a current update. Older builds (e.g. 21.0.2) lack the cloud\'s root CA ' +
994
+ '("SSL.com TLS RSA Root CA 2022"), so the agent\'s Reporter status sync fails silently.', `> **.gitignore:** ${GITIGNORE_ADVICE}`, '');
995
+ }
996
+ else if (decision.requestedButNotApplied) {
997
+ lines.push(`> ⚠️ **Test Orchestrator requested but not applied:** ${decision.reason} Generated the classic boilerplate instead.`, '');
998
+ }
999
+ if (automotive) {
1000
+ lines.push(automotive.applied
1001
+ ? `> 🚗 **Automotive projection: ON** — ${automotive.note}`
1002
+ : `> ⚠️ **Automotive projection requested but not applied:** ${automotive.note} Generated the classic boilerplate instead.`, '');
1003
+ }
815
1004
  if (clearTestBody) {
816
1005
  lines.push('> ⛔ **NOT A FINISHED TEST.** The test body is a placeholder with a deliberate fail-guard and ' +
817
1006
  'non-real `<…>` example selectors. Replace it with steps using element IDs from a live inspection ' +
@@ -847,6 +1036,92 @@ export function registerBoilerplateTools(server) {
847
1036
  };
848
1037
  }
849
1038
  });
1039
+ // ── install_test_orchestrator_agent ──────────────────────────────────────────
1040
+ // The agent JAR is binary (~12 MB) and cannot travel inside get_test_boilerplate's text response. Under the
1041
+ // npm/local install the server can write it straight into the user's project; under Docker/remote it cannot
1042
+ // reach the user's filesystem, so it returns a checksum-verifying download command instead. Mode-dependent
1043
+ // wording comes from the shared locality builders (evaluated once, at registration).
1044
+ const localFs = isLocalFilesystem();
1045
+ server.tool('install_test_orchestrator_agent', 'Install the Digital.ai Test Orchestrator agent (smart-agent.jar) into a test project generated by ' +
1046
+ 'get_test_boilerplate with orchestration enabled — it belongs at <projectDir>/lib/smart-agent.jar, where the ' +
1047
+ 'generated Gradle/Maven wiring looks for it (for android-gradle-submodule that is the e2e-tests directory, NOT the ' +
1048
+ 'Android root). The JAR is not shipped with this server: it is downloaded on demand and always verified against a ' +
1049
+ 'pinned SHA-256 before it is used — by default from the Digital.ai sample repository at a fixed commit, or from ' +
1050
+ 'TEST_ORCHESTRATOR_JAR_URL + TEST_ORCHESTRATOR_JAR_SHA256 when configured. If the download fails, the response says ' +
1051
+ 'where to get the file and how to verify it; the generated project keeps working without it. ' + serverFsInstallNotice(), {
1052
+ projectDir: z.string().optional().describe(serverFsProjectDirParam()),
1053
+ outputFormat: outputFormatParam,
1054
+ }, async ({ projectDir, outputFormat }) => {
1055
+ let source;
1056
+ try {
1057
+ source = resolveAgentSource();
1058
+ }
1059
+ catch (e) {
1060
+ return { content: [{ type: 'text', text: `Error: cannot resolve the Test Orchestrator agent: ${e.message} ${staleBuildRemedy()}` }], isError: true };
1061
+ }
1062
+ if (!localFs) {
1063
+ const cmds = buildAgentDownloadCommands(source);
1064
+ const structured = {
1065
+ installed: false,
1066
+ reason: 'MCP server runs in Docker/remote — it cannot write to your filesystem.',
1067
+ source: source.kind,
1068
+ downloadUrl: source.downloadUrl,
1069
+ sha256: source.sha256,
1070
+ commands: cmds,
1071
+ target: AGENT_PROJECT_PATH,
1072
+ sourceLabel: source.label,
1073
+ ...(source.homepage && { homepage: source.homepage }),
1074
+ runFrom: 'the directory that must receive lib/smart-agent.jar: the generated test project root — for an android-gradle-submodule project, the e2e-tests directory, not the Android root.',
1075
+ };
1076
+ const human = [
1077
+ 'Run ONE of these from the directory that must receive lib/smart-agent.jar — the generated test project root',
1078
+ '(for an android-gradle-submodule project: the e2e-tests directory, NOT the Android root):',
1079
+ '',
1080
+ 'bash / Git Bash / macOS:',
1081
+ '```sh',
1082
+ cmds.bash,
1083
+ '```',
1084
+ 'PowerShell:',
1085
+ '```powershell',
1086
+ cmds.powershell,
1087
+ '```',
1088
+ `Both verify SHA-256 ${source.sha256} and delete the file on a mismatch, so an unverified JAR is never left where the build would attach it.`,
1089
+ `Source: ${source.label}${source.homepage ? ` — ${source.homepage}` : ''}. Without it the project still builds and runs, just without orchestration.`,
1090
+ ].join('\n');
1091
+ return respond(outputFormat, structured, human);
1092
+ }
1093
+ if (!projectDir) {
1094
+ return { content: [{ type: 'text', text: 'Error: projectDir is required — pass the absolute path of the generated project root (it must already exist).' }], isError: true };
1095
+ }
1096
+ const pathError = validateOutputPath(projectDir);
1097
+ if (pathError)
1098
+ return { content: [{ type: 'text', text: `Error: ${pathError}` }], isError: true };
1099
+ try {
1100
+ const result = await installAgentIntoProject(projectDir, source);
1101
+ const warning = result.buildFileFound
1102
+ ? undefined
1103
+ : `⚠️ No build.gradle / build.gradle.kts / pom.xml found in ${projectDir}. The agent was written, but the generated wiring only looks for lib/smart-agent.jar in the project root (for android-gradle-submodule: the e2e-tests directory). Check the path.`;
1104
+ const structured = {
1105
+ installed: true,
1106
+ path: result.path,
1107
+ bytes: result.bytes,
1108
+ sha256: result.sha256,
1109
+ replacedExisting: result.replaced,
1110
+ buildFileFound: result.buildFileFound,
1111
+ ...(warning && { warning }),
1112
+ source: { kind: source.kind, label: source.label, url: source.downloadUrl },
1113
+ nextStep: 'Set DIGITAL_AI_ACCESS_KEY in the environment, then run gradle test / mvn test — the agent attaches automatically.',
1114
+ };
1115
+ const human = `✅ Test Orchestrator agent ${result.replaced ? 'updated' : 'installed'}: ${result.path} (${(result.bytes / 1048576).toFixed(1)} MB, sha256 ${result.sha256}).\n` +
1116
+ `Source: ${source.label} (SHA-256 verified).\n` +
1117
+ (warning ? warning + '\n' : '') +
1118
+ 'Next: set DIGITAL_AI_ACCESS_KEY, then run `gradle test` or `mvn test`.';
1119
+ return respond(outputFormat, structured, human);
1120
+ }
1121
+ catch (e) {
1122
+ return { content: [{ type: 'text', text: `Error installing the Test Orchestrator agent: ${e.message}` }], isError: true };
1123
+ }
1124
+ });
850
1125
  // ── validate_test_script (v43 Fix D — delivery backstop) ───────────────────
851
1126
  server.tool('validate_test_script', 'Backstop check for a generated or hand-written mobile test BEFORE you present or save it. ' +
852
1127
  'Pass the full script content; this scans for the markers of a non-functional test: unreplaced ' +
@@ -913,7 +1188,8 @@ export function registerBoilerplateTools(server) {
913
1188
  targetBrowser: z
914
1189
  .string()
915
1190
  .optional()
916
- .describe('Generate browser-specific setup code for this browser (e.g. "chrome", "firefox", "MicrosoftEdge", "safari"). ' +
1191
+ .describe('Generate browser-specific setup code for this browser: "chrome", "firefox", "MicrosoftEdge", "safari" or "opera" ' +
1192
+ '(names as list_available_browsers returns them; "edge" is accepted for MicrosoftEdge). ' +
917
1193
  'If omitted (default), generates browser-neutral code using a BROWSER environment variable.'),
918
1194
  shadowDomSupport: z
919
1195
  .enum(['auto', 'always', 'never'])
@@ -933,7 +1209,10 @@ export function registerBoilerplateTools(server) {
933
1209
  const language = args.language;
934
1210
  const testName = args.testName ?? 'WebTest';
935
1211
  const targetUrl = args.url ?? '';
936
- const targetBrowser = args.targetBrowser?.toLowerCase();
1212
+ // The grid matches browserName case-sensitively: "microsoftedge" → 400 "No browser found matching the desired
1213
+ // capabilities" (verified live 2026-10-09), so a plain toLowerCase() broke Edge. Map to the names
1214
+ // list_available_browsers returns; anything else passes through unchanged.
1215
+ const targetBrowser = canonicalBrowserName(args.targetBrowser);
937
1216
  const shadowDomSupport = args.shadowDomSupport ?? 'auto';
938
1217
  // Gate: if a real URL is specified, require a live browser session or explicit selector confirmation.
939
1218
  const targetsRealSite = !!targetUrl;
@@ -1070,7 +1349,7 @@ export function registerBoilerplateTools(server) {
1070
1349
  if (!browser) {
1071
1350
  return [
1072
1351
  ` // BROWSER-NEUTRAL: reads browser name from BROWSER env var at runtime.`,
1073
- ` // Change BROWSER=chrome / firefox / MicrosoftEdge / safari without touching this file.`,
1352
+ ` // Change BROWSER=chrome / firefox / MicrosoftEdge / safari / opera without touching this file.`,
1074
1353
  ` String browserName = System.getenv().getOrDefault("BROWSER", "chrome");`,
1075
1354
  ` MutableCapabilities caps = new MutableCapabilities();`,
1076
1355
  ` caps.setCapability("browserName", browserName);`,
@@ -1110,9 +1389,11 @@ export function registerBoilerplateTools(server) {
1110
1389
  // ── Generate the template ───────────────────────────────────────────────
1111
1390
  let code;
1112
1391
  let filename;
1392
+ // "ExampleWebTest" must not become "ExampleWebTestTest" (UAT 2026-10-09) — add the suffix only when missing.
1393
+ const testClass = /Test$/.test(testName) ? testName : `${testName}Test`;
1113
1394
  if (language === 'java-junit5' || language === 'java-testng') {
1114
1395
  const framework = language === 'java-junit5' ? 'junit5' : 'testng';
1115
- filename = `${testName}Test.java`;
1396
+ filename = `${testClass}.java`;
1116
1397
  const isJunit5 = language === 'java-junit5';
1117
1398
  const beforeAnn = isJunit5 ? '@BeforeAll' : '@BeforeClass';
1118
1399
  const afterAnn = isJunit5 ? '@AfterAll' : '@AfterClass';
@@ -1138,7 +1419,7 @@ export function registerBoilerplateTools(server) {
1138
1419
  `import java.net.URL;`,
1139
1420
  `import java.time.Duration;`,
1140
1421
  ``,
1141
- `${lifecycle}public class ${testName}Test {`,
1422
+ `${lifecycle}public class ${testClass} {`,
1142
1423
  ``,
1143
1424
  ` private RemoteWebDriver driver;`,
1144
1425
  ``,
@@ -1249,7 +1530,7 @@ export function registerBoilerplateTools(server) {
1249
1530
  `from selenium.webdriver.remote.webdriver import WebDriver`,
1250
1531
  ``,
1251
1532
  ``,
1252
- `class ${testName}Test(unittest.TestCase):`,
1533
+ `class ${testClass}(unittest.TestCase):`,
1253
1534
  ``,
1254
1535
  ` ACCESS_KEY = "${accessKey}"`,
1255
1536
  ` GRID_URL = "${gridUrl}"`,
@@ -1292,7 +1573,7 @@ export function registerBoilerplateTools(server) {
1292
1573
  ],
1293
1574
  guidance: [
1294
1575
  'Replace the placeholder test body with selectors from get_page_dom / find_web_elements.',
1295
- 'Set BROWSER=chrome (or firefox/microsoftedge/safari) in your environment.',
1576
+ 'Set BROWSER=chrome (or firefox / MicrosoftEdge / safari / opera) in your environment.',
1296
1577
  `Grid URL: ${gridUrl}`,
1297
1578
  ],
1298
1579
  };