digital-ai-testing-mcp 2.1.0 → 2.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (85) hide show
  1. package/README.md +18 -13
  2. package/dist/api/browser-inspection.d.ts.map +1 -1
  3. package/dist/api/browser-inspection.js +7 -1
  4. package/dist/api/browser-inspection.js.map +1 -1
  5. package/dist/api/reporting.d.ts +10 -1
  6. package/dist/api/reporting.d.ts.map +1 -1
  7. package/dist/api/reporting.js +30 -9
  8. package/dist/api/reporting.js.map +1 -1
  9. package/dist/api/webdriver.d.ts +61 -3
  10. package/dist/api/webdriver.d.ts.map +1 -1
  11. package/dist/api/webdriver.js +659 -33
  12. package/dist/api/webdriver.js.map +1 -1
  13. package/dist/index.js +1 -0
  14. package/dist/index.js.map +1 -1
  15. package/dist/tools/boilerplate-tools.d.ts +1 -1
  16. package/dist/tools/boilerplate-tools.d.ts.map +1 -1
  17. package/dist/tools/boilerplate-tools.js +155 -52
  18. package/dist/tools/boilerplate-tools.js.map +1 -1
  19. package/dist/tools/inspection-tools.d.ts.map +1 -1
  20. package/dist/tools/inspection-tools.js +217 -23
  21. package/dist/tools/inspection-tools.js.map +1 -1
  22. package/dist/tools/meta-tools.d.ts +7 -1
  23. package/dist/tools/meta-tools.d.ts.map +1 -1
  24. package/dist/tools/meta-tools.js +21 -7
  25. package/dist/tools/meta-tools.js.map +1 -1
  26. package/dist/tools/performance-tools.d.ts.map +1 -1
  27. package/dist/tools/performance-tools.js +6 -1
  28. package/dist/tools/performance-tools.js.map +1 -1
  29. package/dist/tools/reporting-tools.d.ts.map +1 -1
  30. package/dist/tools/reporting-tools.js +4 -2
  31. package/dist/tools/reporting-tools.js.map +1 -1
  32. package/dist/tools/transaction-tools.d.ts.map +1 -1
  33. package/dist/tools/transaction-tools.js +24 -5
  34. package/dist/tools/transaction-tools.js.map +1 -1
  35. package/dist/types/digital-ai.d.ts +8 -0
  36. package/dist/types/digital-ai.d.ts.map +1 -1
  37. package/dist/utils/test-orchestrator.d.ts +2 -0
  38. package/dist/utils/test-orchestrator.d.ts.map +1 -1
  39. package/dist/utils/test-orchestrator.js +2 -0
  40. package/dist/utils/test-orchestrator.js.map +1 -1
  41. package/package.json +3 -1
  42. package/resources/boilerplate/Android-Native/Java JUnit5/AndroidNative-oss-po.java +48 -0
  43. package/resources/boilerplate/Android-Native/Java JUnit5/AndroidNative-oss.java +23 -13
  44. package/resources/boilerplate/Android-Native/Java JUnit5/AndroidNative.java +19 -10
  45. package/resources/boilerplate/Android-Native/Java JUnit5/gradle-oss +4 -1
  46. package/resources/boilerplate/Android-Native/Java JUnit5/maven-oss +7 -1
  47. package/resources/boilerplate/Android-Native/NodeJS (WebDriver)/AndroidNative-po.js +13 -0
  48. package/resources/boilerplate/Android-Native/NodeJS (WebDriver)/AndroidNative.js +17 -11
  49. package/resources/boilerplate/Android-Native/NodeJS (WebDriver)/wdio-oss.conf.js +7 -2
  50. package/resources/boilerplate/Android-Native/NodeJS (WebDriver)/wdio.conf.js +10 -4
  51. package/resources/boilerplate/Android-Native/Python/AndroidNative-oss.py +30 -14
  52. package/resources/boilerplate/Android-Native/Python/AndroidNative.py +21 -5
  53. package/resources/boilerplate/Android-Native/Robot Framework/AndroidNative-oss.robot +28 -11
  54. package/resources/boilerplate/Android-Native/java TestNG/AndroidNative-oss-po.java +48 -0
  55. package/resources/boilerplate/Android-Native/java TestNG/AndroidNative-oss.java +23 -13
  56. package/resources/boilerplate/Android-Native/java TestNG/AndroidNative.java +19 -10
  57. package/resources/boilerplate/Android-Native/java TestNG/gradle-oss +4 -1
  58. package/resources/boilerplate/Android-Native/java TestNG/maven-oss +7 -1
  59. package/resources/boilerplate/iOS-Native/NodeJS (WebDriver)/iOSNative-po.js +13 -0
  60. package/resources/boilerplate/iOS-Native/NodeJS (WebDriver)/iOSNative.js +17 -11
  61. package/resources/boilerplate/iOS-Native/NodeJS (WebDriver)/wdio-oss.conf.js +4 -1
  62. package/resources/boilerplate/iOS-Native/NodeJS (WebDriver)/wdio.conf.js +2 -0
  63. package/resources/boilerplate/iOS-Native/Python/iOSNative-oss.py +31 -14
  64. package/resources/boilerplate/iOS-Native/Python/iOSNative.py +36 -15
  65. package/resources/boilerplate/iOS-Native/Robot Framework/iOSNative-oss.robot +28 -11
  66. package/resources/boilerplate/iOS-Native/java-JUnit5/gradle-oss +4 -1
  67. package/resources/boilerplate/iOS-Native/java-JUnit5/iOSNative-oss-po.java +45 -0
  68. package/resources/boilerplate/iOS-Native/java-JUnit5/iOSNative-oss.java +24 -13
  69. package/resources/boilerplate/iOS-Native/java-JUnit5/iOSNative.java +21 -11
  70. package/resources/boilerplate/iOS-Native/java-JUnit5/maven-oss +7 -1
  71. package/resources/boilerplate/iOS-Native/java-TestNG/gradle-oss +4 -1
  72. package/resources/boilerplate/iOS-Native/java-TestNG/iOSNative-oss-po.java +45 -0
  73. package/resources/boilerplate/iOS-Native/java-TestNG/iOSNative-oss.java +24 -13
  74. package/resources/boilerplate/iOS-Native/java-TestNG/iOSNative.java +21 -11
  75. package/resources/boilerplate/iOS-Native/java-TestNG/maven-oss +7 -1
  76. package/resources/boilerplate/shared/java-screens/AppScreen.java +27 -0
  77. package/resources/boilerplate/shared/java-screens/BaseScreen.java +40 -0
  78. package/resources/boilerplate/shared/java-screens/DashboardScreen.java +16 -0
  79. package/resources/boilerplate/shared/java-screens/LoginScreen.java +21 -0
  80. package/resources/boilerplate/shared/java-screens/PaymentScreen.java +32 -0
  81. package/resources/boilerplate/shared/node-screens/AppScreen.js +27 -0
  82. package/resources/boilerplate/shared/node-screens/DashboardScreen.js +13 -0
  83. package/resources/boilerplate/shared/node-screens/LoginScreen.js +18 -0
  84. package/resources/boilerplate/shared/node-screens/PaymentScreen.js +28 -0
  85. package/resources/boilerplate/shared/node-screens/PlaceholderScreen.js +21 -0
@@ -36,29 +36,39 @@ const LANGUAGE_SUBDIR = {
36
36
  'robot': 'Robot Framework',
37
37
  },
38
38
  };
39
- function getFilesForVariant(platform, language, isAppiumOss, projectType) {
39
+ function getFilesForVariant(platform, language, isAppiumOss, projectType, structure = 'flat', placeholder = false) {
40
40
  const testBase = platform === 'android' ? 'AndroidNative' : 'iOSNative';
41
41
  const ossSuffix = isAppiumOss ? '-oss' : '';
42
+ // Page objects: Java needs java-client 11 / Selenium 4 (Appium Server templates); Node works on both modes.
43
+ const po = structure === 'page-objects' && (language === 'nodejs' || ((language === 'java-junit5' || language === 'java-testng') && isAppiumOss));
44
+ const javaScreens = (dir) => (placeholder ? ['BaseScreen', 'AppScreen'] : ['BaseScreen', 'LoginScreen', 'DashboardScreen', 'PaymentScreen'])
45
+ .map((c) => ({ filename: `${dir}${c}.java`, diskName: `${c}.java`, lang: 'java', sharedDir: 'java-screens' }));
46
+ const nodeScreens = () => (placeholder ? ['AppScreen', 'PlaceholderScreen'] : ['AppScreen', 'LoginScreen', 'DashboardScreen', 'PaymentScreen'])
47
+ .map((c) => ({ filename: `test/screenobjects/${c}.js`, diskName: `${c}.js`, lang: 'javascript', sharedDir: 'node-screens' }));
42
48
  switch (language) {
43
49
  case 'java-junit5':
44
50
  case 'java-testng': {
45
51
  const javaClass = platform === 'android' ? 'LocalAndroidTest' : 'LocaliOSTest';
46
52
  const javaPath = `src/test/java/${javaClass}.java`;
53
+ const testDisk = `${testBase}${ossSuffix}${po ? '-po' : ''}.java`;
47
54
  if (projectType === 'android-gradle-submodule') {
48
55
  return [
49
- { filename: `e2e-tests/${javaPath}`, diskName: `${testBase}${ossSuffix}.java`, lang: 'java' },
56
+ { filename: `e2e-tests/${javaPath}`, diskName: testDisk, lang: 'java' },
57
+ ...(po ? javaScreens('e2e-tests/src/test/java/') : []),
50
58
  { filename: 'e2e-tests/build.gradle', diskName: `gradle${ossSuffix}`, lang: 'groovy' },
51
59
  ];
52
60
  }
53
61
  if (projectType === 'standalone-maven') {
54
62
  return [
55
- { filename: javaPath, diskName: `${testBase}${ossSuffix}.java`, lang: 'java' },
63
+ { filename: javaPath, diskName: testDisk, lang: 'java' },
64
+ ...(po ? javaScreens('src/test/java/') : []),
56
65
  { filename: 'pom.xml', diskName: `maven${ossSuffix}`, lang: 'xml' },
57
66
  ];
58
67
  }
59
68
  // standalone-gradle (default) — also return pom.xml so users have both options
60
69
  return [
61
- { filename: javaPath, diskName: `${testBase}${ossSuffix}.java`, lang: 'java' },
70
+ { filename: javaPath, diskName: testDisk, lang: 'java' },
71
+ ...(po ? javaScreens('src/test/java/') : []),
62
72
  { filename: 'build.gradle', diskName: `gradle${ossSuffix}`, lang: 'groovy' },
63
73
  { filename: 'pom.xml', diskName: `maven${ossSuffix}`, lang: 'xml' },
64
74
  ];
@@ -72,7 +82,8 @@ function getFilesForVariant(platform, language, isAppiumOss, projectType) {
72
82
  { filename: 'wdio.conf.js', diskName: isAppiumOss ? 'wdio-oss.conf.js' : 'wdio.conf.js', lang: 'javascript' },
73
83
  // Full path: wdio.conf.js loads ./test/specs/<Test>.js. A bare filename saved at the project root ran ZERO tests
74
84
  // ("0 spec files", no error) — hit while running the generated project live, 2026-10-16.
75
- { filename: `test/specs/${testBase}.js`, diskName: `${testBase}.js`, lang: 'javascript' },
85
+ { filename: `test/specs/${testBase}.js`, diskName: `${testBase}${po ? '-po' : ''}.js`, lang: 'javascript' },
86
+ ...(po ? nodeScreens() : []),
76
87
  { filename: 'setup-steps.sh', diskName: shellDisk, lang: 'sh', isInstructions: true },
77
88
  ];
78
89
  }
@@ -140,7 +151,32 @@ export function detectFabricationIssues(content) {
140
151
  const webPlaceholder = content.match(/#YOUR_SELECTOR|\.your-class|\[data-testid="placeholder"\]|\[data-testid='placeholder'\]|YOUR_ELEMENT_ID|YOUR_CSS_SELECTOR/gi);
141
152
  if (webPlaceholder)
142
153
  add('high', 'placeholder CSS selectors', `Unreplaced placeholder CSS selector(s): ${[...new Set(webPlaceholder)].slice(0, 4).join(', ')}`);
143
- // 6. Soft signal: no inspection session ran in this process — can't be a hard fail
154
+ // 6. Practices that make a runnable test flaky — warn (never block). Each one was confirmed against the Appium driver
155
+ // and client documentation and in live runs on the farm.
156
+ const sleeps = content.match(/\bThread\.sleep\s*\(|\btime\.sleep\s*\(|\b(?:browser|driver)\.pause\s*\(|^\s*Sleep\s{2,}\d/gim);
157
+ if (sleeps)
158
+ add('warn', 'fixed sleeps', `${sleeps.length} fixed sleep(s) (${[...new Set(sleeps.map((x) => x.trim()))].slice(0, 3).join(', ')}). Replace with an explicit wait on the element the next step needs (WebDriverWait / waitForDisplayed / Wait Until Element Is Visible).`);
159
+ // Only XPath literals (quoted, or Robot's xpath=…) — a bare `//` would also match every Java/JS line comment with [N].
160
+ const indexXpath = content.match(/(?<=['"`]|xpath=)\/\/[^'"`\n]*\[\d+\][^'"`\n]*/g);
161
+ if (indexXpath)
162
+ add('warn', 'index-based XPath', `Positional XPath (${[...new Set(indexXpath)].slice(0, 3).join(', ')}) breaks when siblings move or a header appears. Prefer accessibility id / resource-id, then an attribute match (@text, @label, @content-desc).`);
163
+ const sharedDriver = content.match(/\bstatic\s+(?:final\s+)?(?:Android|IOS|Appium|Remote|Web)Driver\b[^\n;]*\bdriver\b|@Before(?:All|Suite|Class)\b[\s\S]{0,400}?driver\s*=\s*new\s+(?:Android|IOS|Appium)Driver|def setUpClass[\s\S]{0,400}?webdriver\.Remote\(/g);
164
+ if (sharedDriver)
165
+ add('warn', 'shared driver', 'The driver is static or created once per suite/class. One session per test method (per thread) is the pattern that survives parallel runs — a shared driver is the most common cause of intermittent parallel failures.');
166
+ if (/implicitly_wait\s*\(|implicitlyWait\s*\(|setImplicitWaitTimeout|implicit:\s*\d/.test(content) && /WebDriverWait|waitForDisplayed|waitForExist|Wait Until Element/.test(content)) {
167
+ add('info', 'implicit + explicit waits', 'Both an implicit wait and explicit waits are set. Every miss then waits implicit + explicit and the real timeout is unpredictable — drop the implicit wait and keep the explicit ones.');
168
+ }
169
+ const removedApis = content.match(/\bTouchAction\b|\bMobileBy\b|\bAndroidElement\b|\bIOSElement\b|\bMobileElement\b|\.launch_app\s*\(|\.close_app\s*\(|\.reset\s*\(\)|\.start_activity\s*\(|\.launchApp\s*\(|\.closeApp\s*\(|\.resetApp\s*\(|\bdesired_capabilities\s*=|\bDesiredCapabilities\b/g);
170
+ if (removedApis) {
171
+ const names = [...new Set(removedApis.map((x) => x.replace(/\s*\(.*$/, '').replace(/^\./, '')))].slice(0, 5).join(', ');
172
+ add('info', 'legacy client API', `${names}: removed in the current Appium clients (java-client 9+/11, Appium-Python-Client 3+/6). Correct ONLY for an Appium Grid project pinned to java-client 7.x / Appium-Python-Client 2.2.0 (the generated Grid templates); on an Appium Server project use the Options classes, AppiumBy and mobile: commands.`);
173
+ }
174
+ const iosScript = /XCUITest|bundleId|IOSDriver|platformName['":\s]+['"]?iOS/i.test(content);
175
+ const nameXpath = content.match(/\/\/\*\[@name=/g);
176
+ if (iosScript && nameXpath && !/accessibility[ _]?id|AccessibilityId|ACCESSIBILITY_ID|\$\(['"]~/i.test(content)) {
177
+ add('warn', 'XPath for iOS names', `${nameXpath.length} locator(s) use //*[@name=...] XPath. On iOS "accessibility id" IS the name attribute (identifier, else label) — same match, no tree walk (the driver docs measure XPath as up to 10x slower). Use AppiumBy.accessibilityId / AppiumBy.ACCESSIBILITY_ID / $('~name') / accessibility_id=.`);
178
+ }
179
+ // 7. Soft signal: no inspection session ran in this process — can't be a hard fail
144
180
  // (selectors may be source-derived or captured in a since-closed session), but worth surfacing.
145
181
  if (listActiveSessions().length === 0) {
146
182
  add('info', 'no live inspection session', 'No inspection session is active in this MCP process. If the selectors here were not captured from an inspection or taken from authoritative app source, they are guesses — re-verify before delivering.');
@@ -246,9 +282,9 @@ function appendAutomotiveCheck(language, indent) {
246
282
  * Wrap the test steps so the platform report carries the real outcome (verified live 2026-10-16):
247
283
  * - a session with no WebDriver errors is reported Passed even when the test failed on its own assertion — so the
248
284
  * catch block sets Failed with the error message (seetest:client.setReportStatus works on Grid and Appium Server);
249
- * - on Appium Server the steps sit in a named steps group. The Grid cannot run stopStepsGroup (its execute parser
250
- * rejects 0-argument seetest commands), so Grid templates get the status only.
251
- * Arguments are passed separately, never inside the script string (the inline form fails silently).
285
+ * - the steps sit in a named steps group on both modes. The Grid parses arguments out of the script string, so its
286
+ * 0-argument stop is written inline — "seetest:client.stopStepsGroup()" (verified live 2026-10-19); Appium Server
287
+ * takes the bare command name. Commands WITH arguments pass them separately on both modes.
252
288
  */
253
289
  function wrapWithReporting(language, indent, core, isAppiumOss) {
254
290
  // Robot templates report through their own Test Teardown (Report Test Outcome) and steps-group keywords.
@@ -260,9 +296,10 @@ function wrapWithReporting(language, indent, core, isAppiumOss) {
260
296
  return [
261
297
  `${indent}// Report the real outcome: without this a failed assertion still shows as Passed in the platform report.`,
262
298
  `${indent}try {`,
263
- ...(isAppiumOss ? [`${indent} driver.executeScript("seetest:client.startStepsGroup", "${group}");`] : []),
299
+ `${indent} driver.executeScript("seetest:client.startStepsGroup", "${group}");`,
264
300
  inner,
265
- ...(isAppiumOss ? [`${indent} driver.executeScript("seetest:client.stopStepsGroup");`] : []),
301
+ // The Grid parses arguments out of the script string, so a 0-arg command is written inline there.
302
+ isAppiumOss ? `${indent} driver.executeScript("seetest:client.stopStepsGroup");` : `${indent} driver.executeScript("seetest:client.stopStepsGroup()");`,
266
303
  `${indent} driver.executeScript("seetest:client.setReportStatus", "Passed", "All steps completed");`,
267
304
  `${indent}} catch (RuntimeException | AssertionError e) {`,
268
305
  `${indent} try { driver.executeScript("seetest:client.setReportStatus", "Failed", String.valueOf(e.getMessage())); } catch (RuntimeException ignored) {}`,
@@ -274,9 +311,9 @@ function wrapWithReporting(language, indent, core, isAppiumOss) {
274
311
  return [
275
312
  `${indent}# Report the real outcome: without this a failed assertion still shows as Passed in the platform report.`,
276
313
  `${indent}try:`,
277
- ...(isAppiumOss ? [`${indent} self.driver.execute_script("seetest:client.startStepsGroup", "${group}")`] : []),
314
+ `${indent} self.driver.execute_script("seetest:client.startStepsGroup", "${group}")`,
278
315
  inner,
279
- ...(isAppiumOss ? [`${indent} self.driver.execute_script("seetest:client.stopStepsGroup")`] : []),
316
+ isAppiumOss ? `${indent} self.driver.execute_script("seetest:client.stopStepsGroup")` : `${indent} self.driver.execute_script("seetest:client.stopStepsGroup()")`,
280
317
  `${indent} self.driver.execute_script("seetest:client.setReportStatus", "Passed", "All steps completed")`,
281
318
  `${indent}except Exception as e:`,
282
319
  `${indent} try:`,
@@ -289,9 +326,9 @@ function wrapWithReporting(language, indent, core, isAppiumOss) {
289
326
  return [
290
327
  `${indent}// Report the real outcome: without this a failed assertion still shows as Passed in the platform report.`,
291
328
  `${indent}try {`,
292
- ...(isAppiumOss ? [`${indent} await browser.execute('seetest:client.startStepsGroup', '${group}');`] : []),
329
+ `${indent} await browser.execute('seetest:client.startStepsGroup', '${group}');`,
293
330
  inner,
294
- ...(isAppiumOss ? [`${indent} await browser.execute('seetest:client.stopStepsGroup');`] : []),
331
+ isAppiumOss ? `${indent} await browser.execute('seetest:client.stopStepsGroup');` : `${indent} await browser.execute('seetest:client.stopStepsGroup()');`,
295
332
  `${indent} await browser.execute('seetest:client.setReportStatus', 'Passed', 'All steps completed');`,
296
333
  `${indent}} catch (e) {`,
297
334
  `${indent} await browser.execute('seetest:client.setReportStatus', 'Failed', String(e && e.message).slice(0, 500)).catch(() => {});`,
@@ -360,8 +397,22 @@ function failGuard(language, indent) {
360
397
  return `${indent}Fail ${msg}`;
361
398
  }
362
399
  }
363
- function buildPlaceholder(language, platform, indent) {
400
+ function buildPlaceholder(language, platform, indent, isAppiumOss = true, pageObjects = false) {
364
401
  const c = language === 'python' || language === 'robot' ? '#' : '//';
402
+ if (pageObjects) {
403
+ const screen = language === 'nodejs' ? 'PlaceholderScreen' : 'AppScreen';
404
+ const lines = [
405
+ `${indent}${c} ⛔ PLACEHOLDER TEST BODY — NOT A RUNNABLE TEST. ${screen} holds <…> locators that are NOT real.`,
406
+ `${indent}${c} Replace them with values discovered LIVE (start_inspection_session -> get_element_tree / find_elements),`,
407
+ `${indent}${c} one screen class per screen, then write the flow here. NEVER guess a locator; NEVER invent credentials.`,
408
+ failGuard(language, indent),
409
+ `${indent}${c} Example shape only — every <…> inside ${screen} must be replaced first:`,
410
+ language === 'nodejs'
411
+ ? `${indent}${c} const screen = new ${screen}(); await screen.enterValue('<value the user gave you>'); await screen.tapPrimaryButton();`
412
+ : `${indent}${c} new ${screen}(driver).enterValue("<value the user gave you>").tapPrimaryButton();`,
413
+ ];
414
+ return lines.join('\n');
415
+ }
365
416
  const idTerm = platform === 'android' ? 'resource-id' : 'accessibility id';
366
417
  const banner = [
367
418
  `${indent}${c} ============================================================================`,
@@ -370,6 +421,11 @@ function buildPlaceholder(language, platform, indent) {
370
421
  `${indent}${c} Replace this entire block with steps built from selectors discovered LIVE:`,
371
422
  `${indent}${c} start_inspection_session -> get_element_tree / find_elements, or open_mobile_studio.`,
372
423
  `${indent}${c} NEVER guess a ${idTerm} from the package name or naming conventions.`,
424
+ ...(platform === 'ios'
425
+ ? [`${indent}${c} Locator ladder (iOS): accessibility id (= the name attribute: identifier, else label) -> `,
426
+ `${indent}${c} -ios predicate string on type/label (Appium Server only) -> attribute XPath last. Never index XPath.`]
427
+ : [`${indent}${c} Locator ladder (Android): resource-id -> accessibility id (content-desc) -> @text XPath last. Never index XPath.`]),
428
+ `${indent}${c} Every step goes through the find() helper above: it waits explicitly for the element — never add sleeps.`,
373
429
  `${indent}${c} NEVER invent credentials — ask the user for login details.`,
374
430
  `${indent}${c} The fail()/raise below is intentional: it stops this scaffold from being mistaken`,
375
431
  `${indent}${c} for a passing test until you replace it with verified steps.`,
@@ -378,38 +434,38 @@ function buildPlaceholder(language, platform, indent) {
378
434
  // Example shapes use <…> tokens so they read as obviously-unfilled, never as real selectors.
379
435
  let examples;
380
436
  if (language === 'robot') {
381
- const id = platform === 'android' ? 'id=<resource-id from get_element_tree>' : "xpath=//*[@name='<accessibility id from get_element_tree>']";
382
- const field = platform === 'android' ? 'id=<resource-id>' : "xpath=//*[@name='<accessibility id>']";
437
+ const id = platform === 'android' ? 'id=<resource-id from get_element_tree>' : 'accessibility_id=<accessibility id from get_element_tree>';
438
+ const field = platform === 'android' ? 'id=<resource-id>' : 'accessibility_id=<accessibility id>';
383
439
  examples = [
384
440
  `${indent}${c} Example shape only — every <…> must be replaced with a value from inspection:`,
385
- `${indent}${c} Click Element ${id}`,
386
- `${indent}${c} Input Text ${field} <value the user gave you>`,
387
- `${indent}${c} Page Should Contain Text <visible text>`,
441
+ `${indent}${c} Wait And Click ${id}`,
442
+ `${indent}${c} Wait And Input ${field} <value the user gave you>`,
443
+ `${indent}${c} Expect Text <visible text> visible timeout=20s`,
388
444
  ];
389
445
  }
390
446
  else if (platform === 'android') {
391
447
  if (language === 'java-junit5' || language === 'java-testng') {
392
448
  examples = [
393
449
  `${indent}${c} Example shape only — every <…> must be replaced with a value from inspection:`,
394
- `${indent}${c} driver.findElement(By.id("<resource-id from get_element_tree>")).click();`,
395
- `${indent}${c} driver.findElement(By.id("<resource-id>")).sendKeys("<value the user gave you>");`,
396
- `${indent}${c} driver.findElement(By.xpath("//*[@text='<visible text>']")); // assert visible`,
450
+ `${indent}${c} find(By.id("<resource-id from get_element_tree>")).click();`,
451
+ `${indent}${c} find(By.id("<resource-id>")).sendKeys("<value the user gave you>");`,
452
+ `${indent}${c} find(By.xpath("//*[@text='<visible text>']")); // waits until visible = the assertion`,
397
453
  ];
398
454
  }
399
455
  else if (language === 'nodejs') {
400
456
  examples = [
401
457
  `${indent}${c} Example shape only — every <…> must be replaced with a value from inspection:`,
402
- `${indent}${c} const btn = await $('id=<resource-id from get_element_tree>'); await btn.click();`,
403
- `${indent}${c} const field = await $('//*[@resource-id="<resource-id>"]'); await field.setValue('<value>');`,
404
- `${indent}${c} await expect($('//*[@text="<visible text>"]')).toBeExisting();`,
458
+ `${indent}${c} const btn = await find('id=<resource-id from get_element_tree>'); await btn.click();`,
459
+ `${indent}${c} const field = await find('id=<resource-id>'); await field.setValue('<value>');`,
460
+ `${indent}${c} await expect($('//*[@text="<visible text>"]')).toBeDisplayed();`,
405
461
  ];
406
462
  }
407
463
  else {
408
464
  examples = [
409
465
  `${indent}${c} Example shape only — every <…> must be replaced with a value from inspection:`,
410
- `${indent}${c} self.driver.find_element(By.ID, "<resource-id from get_element_tree>").click()`,
411
- `${indent}${c} self.driver.find_element(By.ID, "<resource-id>").send_keys('<value>')`,
412
- `${indent}${c} self.driver.find_element(By.XPATH, "//*[@text='<visible text>']") # assert visible`,
466
+ `${indent}${c} self.${isAppiumOss ? 'find(By.ID, ' : '_find("'}<resource-id from get_element_tree>${isAppiumOss ? '")' : '")'}.click()`,
467
+ `${indent}${c} self.${isAppiumOss ? 'find(By.ID, "' : '_find("'}<resource-id>").send_keys('<value>')`,
468
+ `${indent}${c} self.${isAppiumOss ? 'find(By.XPATH, ' : '_find_xpath('}"//*[@text='<visible text>']") # waits until visible = the assertion`,
413
469
  ];
414
470
  }
415
471
  }
@@ -417,32 +473,32 @@ function buildPlaceholder(language, platform, indent) {
417
473
  if (language === 'java-junit5' || language === 'java-testng') {
418
474
  examples = [
419
475
  `${indent}${c} Example shape only — every <…> must be replaced with a value from inspection:`,
420
- `${indent}${c} driver.findElement(By.xpath("//*[@name='<accessibility id from get_element_tree>']")).click();`,
421
- `${indent}${c} driver.findElement(By.xpath("//*[@name='<accessibility id>']")).sendKeys("<value the user gave you>");`,
422
- `${indent}${c} driver.findElement(By.xpath("//*[@label='<visible label>']")); // assert visible`,
476
+ `${indent}${c} find(${isAppiumOss ? 'AppiumBy.accessibilityId' : 'MobileBy.AccessibilityId'}("<accessibility id from get_element_tree>")).click();`,
477
+ `${indent}${c} find(${isAppiumOss ? 'AppiumBy.accessibilityId' : 'MobileBy.AccessibilityId'}("<accessibility id>")).sendKeys("<value the user gave you>");`,
478
+ `${indent}${c} find(By.xpath("//*[@label='<visible label>']")); // waits until visible = the assertion`,
423
479
  ];
424
480
  }
425
481
  else if (language === 'nodejs') {
426
482
  examples = [
427
483
  `${indent}${c} Example shape only — every <…> must be replaced with a value from inspection:`,
428
- `${indent}${c} const btn = await $('//*[@name="<accessibility id from get_element_tree>"]'); await btn.click();`,
429
- `${indent}${c} const field = await $('//*[@name="<accessibility id>"]'); await field.setValue('<value>');`,
430
- `${indent}${c} await expect($('//*[@label="<visible label>"]')).toBeExisting();`,
484
+ `${indent}${c} const btn = await find('~<accessibility id from get_element_tree>'); await btn.click();`,
485
+ `${indent}${c} const field = await find('~<accessibility id>'); await field.setValue('<value>');`,
486
+ `${indent}${c} await expect($('//*[@label="<visible label>"]')).toBeDisplayed();`,
431
487
  ];
432
488
  }
433
489
  else {
434
490
  examples = [
435
491
  `${indent}${c} Example shape only — every <…> must be replaced with a value from inspection:`,
436
- `${indent}${c} self.driver.find_element(By.XPATH, "//*[@name='<accessibility id from get_element_tree>']").click()`,
437
- `${indent}${c} self.driver.find_element(By.XPATH, "//*[@name='<accessibility id>']").send_keys('<value>')`,
438
- `${indent}${c} self.driver.find_element(By.XPATH, "//*[@label='<visible label>']") # assert visible`,
492
+ `${indent}${c} self.${isAppiumOss ? "find(AppiumBy.ACCESSIBILITY_ID, '" : '_find("'}<accessibility id from get_element_tree>${isAppiumOss ? "')" : '")'}.click()`,
493
+ `${indent}${c} self.${isAppiumOss ? "find(AppiumBy.ACCESSIBILITY_ID, '" : '_find("'}<accessibility id>${isAppiumOss ? "')" : '")'}.send_keys('<value>')`,
494
+ `${indent}${c} self.${isAppiumOss ? 'find(By.XPATH, ' : '_find_xpath('}"//*[@label='<visible label>']") # waits until visible = the assertion`,
439
495
  ];
440
496
  }
441
497
  }
442
498
  return [...banner, failGuard(language, indent), ...examples].join('\n');
443
499
  }
444
- function readBoilerplateFile(platform, language, diskName) {
445
- const dir = join(BOILERPLATE_DIR, PLATFORM_DIR[platform], LANGUAGE_SUBDIR[platform][language]);
500
+ function readBoilerplateFile(platform, language, diskName, sharedDir) {
501
+ const dir = sharedDir ? join(BOILERPLATE_DIR, 'shared', sharedDir) : join(BOILERPLATE_DIR, PLATFORM_DIR[platform], LANGUAGE_SUBDIR[platform][language]);
446
502
  // Normalize to LF: the marker/injection patterns (DEMO_STEP_PATTERN etc.) match "\n" only. Git stores the templates
447
503
  // with LF, but a Windows checkout with core.autocrlf materializes some as CRLF — and then, for those files, the
448
504
  // custom-app placeholder never replaced the ExperiBank demo steps (the anti-fabrication guard silently did nothing)
@@ -472,7 +528,12 @@ function substitute(content, language, platform, vars) {
472
528
  return content;
473
529
  };
474
530
  if (vars.clearTestBody) {
475
- result = result.replace(DEMO_STEP_PATTERN, () => decorate(buildPlaceholder(language, platform, indent)));
531
+ result = result.replace(DEMO_STEP_PATTERN, () => decorate(buildPlaceholder(language, platform, indent, vars.isAppiumOss !== false, vars.pageObjects === true)));
532
+ // Node page objects: the placeholder variant ships PlaceholderScreen instead of LoginScreen, so the spec must
533
+ // require the file that is actually generated (a missing module fails at load, before the fail-guard runs).
534
+ if (vars.pageObjects && language === 'nodejs') {
535
+ result = result.replace(/const LoginScreen = require\('\.\.\/screenobjects\/LoginScreen'\);/, "const PlaceholderScreen = require('../screenobjects/PlaceholderScreen');");
536
+ }
476
537
  }
477
538
  else {
478
539
  result = result.replace(DEMO_INNER_PATTERN, (inner) => decorate(inner));
@@ -541,6 +602,26 @@ function substitute(content, language, platform, vars) {
541
602
  result = injectCapabilities(result, language, !!vars.isAppiumOss, vars.extraCaps);
542
603
  return result;
543
604
  }
605
+ /**
606
+ * Every template already creates one session per test method (setUp/tearDown, @BeforeEach/@AfterEach, @BeforeMethod,
607
+ * a wdio session per spec, Robot Test Setup/Teardown) — the shape that survives parallel runs. A static or
608
+ * suite-level driver is the most common cause of intermittent parallel failures (validate_test_script warns on it).
609
+ */
610
+ function parallelNote(language, isAppiumOss) {
611
+ const cap = 'Check the project\'s concurrency limit first (get_project_admin_settings → maxDevelopmentLicense) and that enough matching devices are free (find_available_device): a worker that finds no device waits for newSessionWaitTimeout and then fails.';
612
+ switch (language) {
613
+ case 'python':
614
+ return `Each test method has its own setUp/tearDown session — no code changes needed. pip install pytest-xdist, then: pytest -n auto -v (one worker per test). ${cap}`;
615
+ case 'java-junit5':
616
+ return `Each @Test has its own @BeforeEach/@AfterEach session. Enable JUnit 5 parallelism with src/test/resources/junit-platform.properties: junit.jupiter.execution.parallel.enabled=true, junit.jupiter.execution.parallel.mode.default=concurrent, junit.jupiter.execution.parallel.config.strategy=fixed, junit.jupiter.execution.parallel.config.fixed.parallelism=<workers>. Never make the driver static. ${cap}`;
617
+ case 'java-testng':
618
+ return `Each @Test has its own @BeforeMethod/@AfterMethod session. Run methods in parallel with a TestNG suite file (<suite parallel="methods" thread-count="<workers>">) or Surefire's <parallel>methods</parallel> + <threadCount>; the driver must stay an instance field (one per thread). ${cap}`;
619
+ case 'nodejs':
620
+ return `WebdriverIO runs spec files in parallel: raise maxInstances in wdio.conf.js (one session per spec file) and split tests across spec files${isAppiumOss ? '' : ' (wdio 7 on the Grid behaves the same)'}. ${cap}`;
621
+ case 'robot':
622
+ return `pip install robotframework-pabot, then: pabot --processes <workers> --outputdir results tests/ (one session per suite file). ${cap}`;
623
+ }
624
+ }
544
625
  function setupNote(language, isAppiumOss, projectType) {
545
626
  switch (language) {
546
627
  case 'java-junit5':
@@ -592,6 +673,7 @@ function setupNote(language, isAppiumOss, projectType) {
592
673
  case 'python':
593
674
  return isAppiumOss
594
675
  ? 'Install the dependency with: pip install -r requirements.txt (Appium-Python-Client>=4.0.0), then run: python -m pytest\n\n' +
676
+ 'Waits: every step goes through find(), an explicit WebDriverWait — there is no implicit wait, and adding one would make every miss wait both timeouts.\n\n' +
595
677
  'Parallel execution (recommended on device farms — each test gets its own device):\n' +
596
678
  ' pip install pytest-xdist\n' +
597
679
  ' pytest -n auto -v # spawns one worker per test method; each creates its own Appium session'
@@ -757,6 +839,15 @@ export function registerBoilerplateTools(server) {
757
839
  .string()
758
840
  .optional()
759
841
  .describe('(iOS only) App bundle identifier, e.g. com.mycompany.app. Pre-fills the bundleId capability. Prefer appId — providing bundleIdentifier also clears the demo test body and inserts guided placeholders.'),
842
+ structure: z
843
+ .enum(['flat', 'page-objects'])
844
+ .optional()
845
+ .describe("Test layout. 'flat' (default): one test method with inline steps. 'page-objects': one class per screen " +
846
+ '(BaseScreen with the explicit-wait helpers and a per-platform locator chooser, so ONE screen class serves ' +
847
+ 'Android and iOS) plus a test that reads as the user flow — the shape to use once a suite grows past one ' +
848
+ 'test. Available for java-junit5 / java-testng on Appium Server projects and for nodejs (both modes); other ' +
849
+ 'combinations fall back to flat with a note. With a real app the screen class is a placeholder with <…> ' +
850
+ 'locators that validate_test_script flags until they are replaced from a live inspection.'),
760
851
  projectType: z
761
852
  .enum(['standalone-gradle', 'standalone-maven', 'android-gradle-submodule'])
762
853
  .optional()
@@ -806,7 +897,7 @@ export function registerBoilerplateTools(server) {
806
897
  .default(true)
807
898
  .describe('Default true. Wraps the test steps so the platform report shows the REAL outcome: a failure sets the report to ' +
808
899
  'Failed with the error message (without this, a session with no WebDriver errors is reported Passed even when ' +
809
- 'an assertion failed), and on Appium Server the steps are grouped in a named steps group. ' +
900
+ 'an assertion failed), and the steps are grouped in a named steps group (on the Grid the 0-argument group stop is written inline, "seetest:client.stopStepsGroup()"). ' +
810
901
  'Set false only when the user wants the bare steps.'),
811
902
  appiumVersion: z
812
903
  .string()
@@ -867,7 +958,7 @@ export function registerBoilerplateTools(server) {
867
958
  .describe('Orchestrated projects only: run.maxRetryAttempts in the agent config. Default 2 — or 0 when the test body is ' +
868
959
  'a placeholder (fails by design) or includePerformanceTransactions is set (retries would skew samples).'),
869
960
  outputFormat: outputFormatParam,
870
- }, async ({ platform, language, appId, deviceCategory, testName, packageName, mainActivity, bundleIdentifier, projectType, region, includePerformanceTransactions, includeAxeScan, reportStatus, appiumVersion, newSessionWaitTimeout, reportKeys, automotiveProjection, confirmSelectorsVerified, orchestration, orchestrationMaxRetries, outputFormat }) => {
961
+ }, async ({ platform, language, appId, deviceCategory, testName, packageName, mainActivity, bundleIdentifier, structure, projectType, region, includePerformanceTransactions, includeAxeScan, reportStatus, appiumVersion, newSessionWaitTimeout, reportKeys, automotiveProjection, confirmSelectorsVerified, orchestration, orchestrationMaxRetries, outputFormat }) => {
871
962
  // ── Inspection gate (v42) ────────────────────────────────────────────────
872
963
  // Advisory guards (warning text, a requiresVerifiedSelectors flag, an in-code
873
964
  // fail() guard) all lost to task-completion momentum: the agent stripped the
@@ -1012,6 +1103,13 @@ export function registerBoilerplateTools(server) {
1012
1103
  }
1013
1104
  // Clear demo steps whenever a custom (non-ExperiBank) app is specified.
1014
1105
  const clearTestBody = Boolean(platform === 'android' ? resolvedPackageName : resolvedBundleIdentifier);
1106
+ const pageObjectsRequested = structure === 'page-objects';
1107
+ const pageObjectsApplied = pageObjectsRequested && (language === 'nodejs' || ((language === 'java-junit5' || language === 'java-testng') && isAppiumOss));
1108
+ const structureNote = pageObjectsRequested && !pageObjectsApplied
1109
+ ? (language === 'python' || language === 'robot'
1110
+ ? `structure: "page-objects" is available for Java (Appium Server) and nodejs only — ${language} is generated flat.`
1111
+ : 'structure: "page-objects" needs an Appium Server project for Java (java-client 11 / Selenium 4); this Grid project is generated flat.')
1112
+ : undefined;
1015
1113
  const vars = {
1016
1114
  accessKey,
1017
1115
  instanceUrl: rawBaseUrl,
@@ -1030,8 +1128,9 @@ export function registerBoilerplateTools(server) {
1030
1128
  automotiveProjection: automotive?.applied ? automotive.resolution : undefined,
1031
1129
  reportStatus: reportStatus !== false,
1032
1130
  extraCaps,
1131
+ pageObjects: pageObjectsApplied,
1033
1132
  };
1034
- const files = getFilesForVariant(platform, language, isAppiumOss, projectType);
1133
+ const files = getFilesForVariant(platform, language, isAppiumOss, projectType, pageObjectsApplied ? 'page-objects' : 'flat', clearTestBody);
1035
1134
  // Grid scripts carry non-obvious workarounds (pinned clients, JWP capability
1036
1135
  // format, element wrappers). Once the file leaves this response, the
1037
1136
  // serverModeNote leaves with it — so the explanation must live IN the source.
@@ -1056,7 +1155,7 @@ export function registerBoilerplateTools(server) {
1056
1155
  };
1057
1156
  try {
1058
1157
  const resolved = files.map(f => {
1059
- const raw = readBoilerplateFile(platform, language, f.diskName);
1158
+ const raw = readBoilerplateFile(platform, language, f.diskName, f.sharedDir);
1060
1159
  const substituted = substitute(raw, language, platform, vars);
1061
1160
  const content = f.diskName.startsWith('gradle')
1062
1161
  ? adaptGradleForProjectType(substituted, projectType)
@@ -1116,7 +1215,7 @@ export function registerBoilerplateTools(server) {
1116
1215
  'orchestrator/rendered/, which is git-ignored, never into a tracked file). Otherwise the project builds and runs exactly like the classic boilerplate.',
1117
1216
  runCommands: { gradle: 'gradle test', maven: 'mvn test' },
1118
1217
  buildId: 'Set BUILD_ID (CI usually does) to group a build\'s results in Reporter; defaults to "local".',
1119
- requirements: 'When attached: Java 17 or 21 JDK; JUnit 5 / TestNG 7+; Appium java-client 8–10 (this boilerplate uses 8.6.0).',
1218
+ requirements: 'When attached: Java 17 or 21 JDK; JUnit 5 / TestNG 7+; Appium java-client 8–11 (this boilerplate uses 11.0.0 + selenium-java 4.51.0 — verified live with the agent 2026-10-18).',
1120
1219
  jdkTrustNote: JDK_TRUST_NOTE,
1121
1220
  gitignore: GITIGNORE_ADVICE,
1122
1221
  logs: 'smart-agent/<run-id>/smartagent-main.log — add smart-agent/ to your .gitignore.',
@@ -1128,7 +1227,7 @@ export function registerBoilerplateTools(server) {
1128
1227
  serverMode: isAppiumOss ? 'oss' : 'grid',
1129
1228
  serverModeNote: isAppiumOss
1130
1229
  ? 'Appium Server (OSS) — standard W3C WebDriver protocol. ' +
1131
- 'Java: java-client 8.x, Java 11+, UiAutomator2Options/XCUITestOptions (no DesiredCapabilities). ' +
1230
+ 'Java: java-client 11.x + selenium-java 4.51 (Java 17+), UiAutomator2Options/XCUITestOptions, AppiumBy, URI.create(...).toURL() (no DesiredCapabilities, no MobileBy). ' +
1132
1231
  'Python: appium-python-client 4.x+, AppiumOptions. ' +
1133
1232
  'If you need Grid mode, switch to a Grid-enabled profile and regenerate — the APIs are incompatible.'
1134
1233
  : 'Appium Grid (legacy) — Digital.ai JWP-era protocol, NOT standard Appium Server. ' +
@@ -1143,15 +1242,15 @@ export function registerBoilerplateTools(server) {
1143
1242
  : "deviceQuery is region-unscoped. Sessions may route to devices in any region, including devices that have been offline for extended periods. Call find_available_device first to get a healthy region, then re-call get_test_boilerplate with that region value.",
1144
1243
  testName,
1145
1244
  projectType: projectType ?? 'standalone-gradle',
1245
+ structure: pageObjectsApplied ? 'page-objects' : 'flat',
1246
+ ...(structureNote ? { structureNote } : {}),
1146
1247
  files: resolved.map(f => ({ filename: f.filename, content: f.content })),
1147
1248
  orchestration: orchestrationInfo,
1148
1249
  ...(automotive ? { automotive } : {}),
1149
1250
  ...(capNotes.length ? { capabilityNotes: capNotes } : {}),
1150
1251
  setupNote: setupNote(language, isAppiumOss, projectType),
1151
1252
  appNote: appNote(platform, vars.packageName, vars.bundleIdentifier, vars.mainActivity, resolvedFromAppId),
1152
- parallelNote: language === 'python'
1153
- ? 'Device farms support parallel test execution. Each test method already has its own setUp/tearDown session — no code changes needed. Install pytest-xdist (pip install pytest-xdist) and run: pytest -n auto -v. Check maxDevelopmentLicense via get_project_admin_settings to confirm your concurrency limit before scaling workers.'
1154
- : null,
1253
+ parallelNote: parallelNote(language, isAppiumOss),
1155
1254
  credentialWarning: '⚠️ SECURITY: The access key embedded in these files is a live credential. Move it to an environment variable (DIGITAL_AI_ACCESS_KEY) and reference it from code before committing to source control.',
1156
1255
  // v38: when a custom app is targeted the test body is a placeholder, NOT a finished test.
1157
1256
  requiresVerifiedSelectors: clearTestBody,
@@ -1326,6 +1425,9 @@ export function registerBoilerplateTools(server) {
1326
1425
  '<…> placeholder selectors, the deliberate scaffold fail-guard, placeholder/fabricated credentials, ' +
1327
1426
  'and resource IDs from a known prior fabrication incident. Returns isError when any high-severity ' +
1328
1427
  'pattern is found — a test that fails this is NOT runnable and must not be delivered as finished. ' +
1428
+ 'It also WARNS (never blocks) on flakiness patterns: fixed sleeps, index-based XPath, a static/suite-level ' +
1429
+ 'shared driver, implicit + explicit waits mixed, iOS //*[@name=] XPath where accessibility id is the same match, ' +
1430
+ 'and client APIs removed from the current Appium clients (correct only for Appium Grid projects). ' +
1329
1431
  'This catches the case the get_test_boilerplate gate cannot: a script you wrote yourself with guessed ' +
1330
1432
  'selectors. A clean result is necessary but not sufficient — it cannot confirm selectors are REAL, only ' +
1331
1433
  'that obvious placeholders are gone; the authoritative source for selectors is still a live inspection.', {
@@ -1340,6 +1442,7 @@ export function registerBoilerplateTools(server) {
1340
1442
  const structured = {
1341
1443
  verdict,
1342
1444
  highSeverityCount: high.length,
1445
+ warningCount: issues.filter((i) => i.severity === 'warn').length,
1343
1446
  issues,
1344
1447
  guidance: high.length > 0
1345
1448
  ? 'Do NOT present this script as a finished test. Replace every flagged placeholder with element IDs ' +
@@ -1352,7 +1455,7 @@ export function registerBoilerplateTools(server) {
1352
1455
  `${verdict === 'fail' ? '⛔ FAIL' : '✅ PASS'} — validate_test_script${label}`,
1353
1456
  '',
1354
1457
  ...(issues.length
1355
- ? issues.map((i) => ` ${i.severity === 'high' ? '⛔' : 'ℹ️'} [${i.label}] ${i.detail}`)
1458
+ ? issues.map((i) => ` ${i.severity === 'high' ? '⛔' : i.severity === 'warn' ? '⚠️' : 'ℹ️'} [${i.label}] ${i.detail}`)
1356
1459
  : [' No issues detected.']),
1357
1460
  '',
1358
1461
  structured.guidance,