digital-ai-testing-mcp 2.1.1 → 2.2.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 (79) hide show
  1. package/README.md +18 -13
  2. package/dist/api/webdriver.d.ts +61 -3
  3. package/dist/api/webdriver.d.ts.map +1 -1
  4. package/dist/api/webdriver.js +673 -33
  5. package/dist/api/webdriver.js.map +1 -1
  6. package/dist/index.js +1 -0
  7. package/dist/index.js.map +1 -1
  8. package/dist/tools/boilerplate-tools.d.ts +1 -1
  9. package/dist/tools/boilerplate-tools.d.ts.map +1 -1
  10. package/dist/tools/boilerplate-tools.js +217 -78
  11. package/dist/tools/boilerplate-tools.js.map +1 -1
  12. package/dist/tools/device-tools.d.ts +11 -0
  13. package/dist/tools/device-tools.d.ts.map +1 -1
  14. package/dist/tools/device-tools.js +25 -2
  15. package/dist/tools/device-tools.js.map +1 -1
  16. package/dist/tools/inspection-tools.d.ts.map +1 -1
  17. package/dist/tools/inspection-tools.js +219 -23
  18. package/dist/tools/inspection-tools.js.map +1 -1
  19. package/dist/tools/meta-tools.d.ts +1 -1
  20. package/dist/tools/meta-tools.d.ts.map +1 -1
  21. package/dist/tools/meta-tools.js +12 -1
  22. package/dist/tools/meta-tools.js.map +1 -1
  23. package/dist/tools/performance-tools.d.ts.map +1 -1
  24. package/dist/tools/performance-tools.js +6 -1
  25. package/dist/tools/performance-tools.js.map +1 -1
  26. package/dist/tools/reporting-tools.d.ts.map +1 -1
  27. package/dist/tools/reporting-tools.js +19 -1
  28. package/dist/tools/reporting-tools.js.map +1 -1
  29. package/dist/types/digital-ai.d.ts +10 -0
  30. package/dist/types/digital-ai.d.ts.map +1 -1
  31. package/dist/utils/test-orchestrator.d.ts +2 -0
  32. package/dist/utils/test-orchestrator.d.ts.map +1 -1
  33. package/dist/utils/test-orchestrator.js +2 -0
  34. package/dist/utils/test-orchestrator.js.map +1 -1
  35. package/package.json +3 -1
  36. package/resources/boilerplate/Android-Native/Java JUnit5/AndroidNative-oss-po.java +50 -0
  37. package/resources/boilerplate/Android-Native/Java JUnit5/AndroidNative-oss.java +23 -13
  38. package/resources/boilerplate/Android-Native/Java JUnit5/AndroidNative.java +19 -10
  39. package/resources/boilerplate/Android-Native/Java JUnit5/gradle-oss +4 -1
  40. package/resources/boilerplate/Android-Native/Java JUnit5/maven-oss +7 -1
  41. package/resources/boilerplate/Android-Native/NodeJS (WebDriver)/AndroidNative-po.js +13 -0
  42. package/resources/boilerplate/Android-Native/NodeJS (WebDriver)/AndroidNative.js +17 -11
  43. package/resources/boilerplate/Android-Native/NodeJS (WebDriver)/wdio-oss.conf.js +7 -2
  44. package/resources/boilerplate/Android-Native/NodeJS (WebDriver)/wdio.conf.js +10 -4
  45. package/resources/boilerplate/Android-Native/Python/AndroidNative-oss.py +30 -14
  46. package/resources/boilerplate/Android-Native/Python/AndroidNative.py +21 -5
  47. package/resources/boilerplate/Android-Native/Robot Framework/AndroidNative-oss.robot +28 -11
  48. package/resources/boilerplate/Android-Native/java TestNG/AndroidNative-oss-po.java +50 -0
  49. package/resources/boilerplate/Android-Native/java TestNG/AndroidNative-oss.java +23 -13
  50. package/resources/boilerplate/Android-Native/java TestNG/AndroidNative.java +19 -10
  51. package/resources/boilerplate/Android-Native/java TestNG/gradle-oss +4 -1
  52. package/resources/boilerplate/Android-Native/java TestNG/maven-oss +7 -1
  53. package/resources/boilerplate/iOS-Native/NodeJS (WebDriver)/iOSNative-po.js +13 -0
  54. package/resources/boilerplate/iOS-Native/NodeJS (WebDriver)/iOSNative.js +17 -11
  55. package/resources/boilerplate/iOS-Native/NodeJS (WebDriver)/wdio-oss.conf.js +4 -1
  56. package/resources/boilerplate/iOS-Native/NodeJS (WebDriver)/wdio.conf.js +2 -0
  57. package/resources/boilerplate/iOS-Native/Python/iOSNative-oss.py +31 -14
  58. package/resources/boilerplate/iOS-Native/Python/iOSNative.py +36 -15
  59. package/resources/boilerplate/iOS-Native/Robot Framework/iOSNative-oss.robot +28 -11
  60. package/resources/boilerplate/iOS-Native/java-JUnit5/gradle-oss +4 -1
  61. package/resources/boilerplate/iOS-Native/java-JUnit5/iOSNative-oss-po.java +47 -0
  62. package/resources/boilerplate/iOS-Native/java-JUnit5/iOSNative-oss.java +24 -13
  63. package/resources/boilerplate/iOS-Native/java-JUnit5/iOSNative.java +21 -11
  64. package/resources/boilerplate/iOS-Native/java-JUnit5/maven-oss +7 -1
  65. package/resources/boilerplate/iOS-Native/java-TestNG/gradle-oss +4 -1
  66. package/resources/boilerplate/iOS-Native/java-TestNG/iOSNative-oss-po.java +47 -0
  67. package/resources/boilerplate/iOS-Native/java-TestNG/iOSNative-oss.java +24 -13
  68. package/resources/boilerplate/iOS-Native/java-TestNG/iOSNative.java +21 -11
  69. package/resources/boilerplate/iOS-Native/java-TestNG/maven-oss +7 -1
  70. package/resources/boilerplate/shared/java-screens/AppScreen.java +29 -0
  71. package/resources/boilerplate/shared/java-screens/BaseScreen.java +42 -0
  72. package/resources/boilerplate/shared/java-screens/DashboardScreen.java +18 -0
  73. package/resources/boilerplate/shared/java-screens/LoginScreen.java +23 -0
  74. package/resources/boilerplate/shared/java-screens/PaymentScreen.java +34 -0
  75. package/resources/boilerplate/shared/node-screens/AppScreen.js +27 -0
  76. package/resources/boilerplate/shared/node-screens/DashboardScreen.js +13 -0
  77. package/resources/boilerplate/shared/node-screens/LoginScreen.js +18 -0
  78. package/resources/boilerplate/shared/node-screens/PaymentScreen.js +28 -0
  79. 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}screens/${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,7 +602,38 @@ function substitute(content, language, platform, vars) {
541
602
  result = injectCapabilities(result, language, !!vars.isAppiumOss, vars.extraCaps);
542
603
  return result;
543
604
  }
544
- function setupNote(language, isAppiumOss, projectType) {
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
+ }
625
+ /**
626
+ * Node projects: the folder layout and the mkdir line come from the files actually emitted — page objects add
627
+ * test/screenobjects/, and a hardcoded "test/specs only" layout left the spec's require() pointing at a folder the user
628
+ * never created (debug-mode intake 2026-10-19).
629
+ */
630
+ function nodeLayout(filenames) {
631
+ const listed = filenames.filter((f) => !f.endsWith('.sh'));
632
+ const layout = listed.map((f) => (f.includes('/') ? ` ${f}` : ` ${f.padEnd(22)}← project root`)).join('\n');
633
+ const dirs = [...new Set(listed.filter((f) => f.includes('/')).map((f) => f.slice(0, f.lastIndexOf('/'))))];
634
+ return { layout, dirs };
635
+ }
636
+ function setupNote(language, isAppiumOss, projectType, emitted = []) {
545
637
  switch (language) {
546
638
  case 'java-junit5':
547
639
  case 'java-testng':
@@ -570,28 +662,30 @@ function setupNote(language, isAppiumOss, projectType) {
570
662
  ' - Root settings.gradle: add include \':e2e-tests\'\n' +
571
663
  ' - Place files under e2e-tests/src/test/java/ and e2e-tests/build.gradle\n' +
572
664
  ' (Use projectType: android-gradle-submodule to generate paths pre-scoped to e2e-tests/.)');
573
- case 'nodejs':
665
+ case 'nodejs': {
666
+ const { layout, dirs } = emitted.length
667
+ ? nodeLayout(emitted)
668
+ : { layout: ' package.json ← project root\n wdio.conf.js ← project root\n test/specs/<TestFile>.js', dirs: ['test/specs'] };
669
+ const head = 'Create a project folder and save the provided files in this layout:\n' +
670
+ `${layout}\n` +
671
+ `(create the folders first: mkdir -p ${dirs.join(' ')})\n\n`;
574
672
  if (isAppiumOss) {
575
- return ('Create a project folder and save the provided files in this layout:\n' +
576
- ' package.json ← project root\n' +
577
- ' wdio.conf.js ← project root\n' +
578
- ' test/specs/<TestFile>.js\n\n' +
673
+ return (head +
579
674
  'Then run:\n' +
580
675
  ' npm install && npm run wdio');
581
676
  }
582
- return ('Create a project folder and save the provided files in this layout:\n' +
583
- ' package.json ← project root\n' +
584
- ' wdio.conf.js ← project root\n' +
585
- ' test/specs/<TestFile>.js\n\n' +
677
+ return (head +
586
678
  'Then run:\n' +
587
679
  ' npm install && npm run wdio\n\n' +
588
680
  'IMPORTANT: Do NOT run npm init wdio — it installs wdio v9, which this project\'s Appium Grid rejects\n' +
589
681
  ' ("Cant run Appium Grid with Appium client 8+"). The Grid requires the legacy desiredCapabilities in the\n' +
590
682
  ' session request; wdio v8+ sends W3C capabilities only. The package.json above pins wdio v7.40.0, the last\n' +
591
683
  ' release that still sends them (verified live: v9 refused, v7.40 runs). Appium Server projects use wdio v9.');
684
+ }
592
685
  case 'python':
593
686
  return isAppiumOss
594
687
  ? 'Install the dependency with: pip install -r requirements.txt (Appium-Python-Client>=4.0.0), then run: python -m pytest\n\n' +
688
+ '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
689
  'Parallel execution (recommended on device farms — each test gets its own device):\n' +
596
690
  ' pip install pytest-xdist\n' +
597
691
  ' pytest -n auto -v # spawns one worker per test method; each creates its own Appium session'
@@ -757,6 +851,15 @@ export function registerBoilerplateTools(server) {
757
851
  .string()
758
852
  .optional()
759
853
  .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.'),
854
+ structure: z
855
+ .enum(['flat', 'page-objects'])
856
+ .optional()
857
+ .describe("Test layout. 'flat' (default): one test method with inline steps. 'page-objects': one class per screen " +
858
+ '(BaseScreen with the explicit-wait helpers and a per-platform locator chooser, so ONE screen class serves ' +
859
+ 'Android and iOS) plus a test that reads as the user flow — the shape to use once a suite grows past one ' +
860
+ 'test. Available for java-junit5 / java-testng on Appium Server projects and for nodejs (both modes); other ' +
861
+ 'combinations fall back to flat with a note. With a real app the screen class is a placeholder with <…> ' +
862
+ 'locators that validate_test_script flags until they are replaced from a live inspection.'),
760
863
  projectType: z
761
864
  .enum(['standalone-gradle', 'standalone-maven', 'android-gradle-submodule'])
762
865
  .optional()
@@ -806,7 +909,7 @@ export function registerBoilerplateTools(server) {
806
909
  .default(true)
807
910
  .describe('Default true. Wraps the test steps so the platform report shows the REAL outcome: a failure sets the report to ' +
808
911
  '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. ' +
912
+ '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
913
  'Set false only when the user wants the bare steps.'),
811
914
  appiumVersion: z
812
915
  .string()
@@ -867,7 +970,7 @@ export function registerBoilerplateTools(server) {
867
970
  .describe('Orchestrated projects only: run.maxRetryAttempts in the agent config. Default 2 — or 0 when the test body is ' +
868
971
  'a placeholder (fails by design) or includePerformanceTransactions is set (retries would skew samples).'),
869
972
  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 }) => {
973
+ }, async ({ platform, language, appId, deviceCategory, testName, packageName, mainActivity, bundleIdentifier, structure, projectType, region, includePerformanceTransactions, includeAxeScan, reportStatus, appiumVersion, newSessionWaitTimeout, reportKeys, automotiveProjection, confirmSelectorsVerified, orchestration, orchestrationMaxRetries, outputFormat }) => {
871
974
  // ── Inspection gate (v42) ────────────────────────────────────────────────
872
975
  // Advisory guards (warning text, a requiresVerifiedSelectors flag, an in-code
873
976
  // fail() guard) all lost to task-completion momentum: the agent stripped the
@@ -1012,6 +1115,13 @@ export function registerBoilerplateTools(server) {
1012
1115
  }
1013
1116
  // Clear demo steps whenever a custom (non-ExperiBank) app is specified.
1014
1117
  const clearTestBody = Boolean(platform === 'android' ? resolvedPackageName : resolvedBundleIdentifier);
1118
+ const pageObjectsRequested = structure === 'page-objects';
1119
+ const pageObjectsApplied = pageObjectsRequested && (language === 'nodejs' || ((language === 'java-junit5' || language === 'java-testng') && isAppiumOss));
1120
+ const structureNote = pageObjectsRequested && !pageObjectsApplied
1121
+ ? (language === 'python' || language === 'robot'
1122
+ ? `structure: "page-objects" is available for Java (Appium Server) and nodejs only — ${language} is generated flat.`
1123
+ : 'structure: "page-objects" needs an Appium Server project for Java (java-client 11 / Selenium 4); this Grid project is generated flat.')
1124
+ : undefined;
1015
1125
  const vars = {
1016
1126
  accessKey,
1017
1127
  instanceUrl: rawBaseUrl,
@@ -1030,8 +1140,9 @@ export function registerBoilerplateTools(server) {
1030
1140
  automotiveProjection: automotive?.applied ? automotive.resolution : undefined,
1031
1141
  reportStatus: reportStatus !== false,
1032
1142
  extraCaps,
1143
+ pageObjects: pageObjectsApplied,
1033
1144
  };
1034
- const files = getFilesForVariant(platform, language, isAppiumOss, projectType);
1145
+ const files = getFilesForVariant(platform, language, isAppiumOss, projectType, pageObjectsApplied ? 'page-objects' : 'flat', clearTestBody);
1035
1146
  // Grid scripts carry non-obvious workarounds (pinned clients, JWP capability
1036
1147
  // format, element wrappers). Once the file leaves this response, the
1037
1148
  // serverModeNote leaves with it — so the explanation must live IN the source.
@@ -1056,13 +1167,22 @@ export function registerBoilerplateTools(server) {
1056
1167
  };
1057
1168
  try {
1058
1169
  const resolved = files.map(f => {
1059
- const raw = readBoilerplateFile(platform, language, f.diskName);
1170
+ const raw = readBoilerplateFile(platform, language, f.diskName, f.sharedDir);
1060
1171
  const substituted = substitute(raw, language, platform, vars);
1061
1172
  const content = f.diskName.startsWith('gradle')
1062
1173
  ? adaptGradleForProjectType(substituted, projectType)
1063
1174
  : substituted;
1064
1175
  return { ...f, content: gridHeader(f.filename) + content };
1065
1176
  });
1177
+ if (language === 'nodejs') {
1178
+ const emittedNames = resolved.filter((f) => !f.isInstructions).map((f) => f.filename);
1179
+ const { layout, dirs } = nodeLayout(emittedNames);
1180
+ for (const f of resolved.filter((x) => x.isInstructions)) {
1181
+ f.content = f.content
1182
+ .replace(/# 2\. Save the provided files into this layout:\n(?:#[^\n]*\n)+/, `# 2. Save the provided files into this layout:\n${layout.split('\n').map((l) => `# ${l}`).join('\n')}\n`)
1183
+ .replace(/mkdir -p test\/specs/, `mkdir -p ${dirs.join(' ')}`);
1184
+ }
1185
+ }
1066
1186
  // ── Test Orchestrator (default ON for Java on Appium Server) ─────────────
1067
1187
  const decision = decideOrchestration({ mode: orchestration, language, isAppiumOss: detectedAppiumOss });
1068
1188
  let orchestrationInfo = { enabled: false, mode: orchestration, reason: decision.reason };
@@ -1116,7 +1236,7 @@ export function registerBoilerplateTools(server) {
1116
1236
  'orchestrator/rendered/, which is git-ignored, never into a tracked file). Otherwise the project builds and runs exactly like the classic boilerplate.',
1117
1237
  runCommands: { gradle: 'gradle test', maven: 'mvn test' },
1118
1238
  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).',
1239
+ 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
1240
  jdkTrustNote: JDK_TRUST_NOTE,
1121
1241
  gitignore: GITIGNORE_ADVICE,
1122
1242
  logs: 'smart-agent/<run-id>/smartagent-main.log — add smart-agent/ to your .gitignore.',
@@ -1128,7 +1248,7 @@ export function registerBoilerplateTools(server) {
1128
1248
  serverMode: isAppiumOss ? 'oss' : 'grid',
1129
1249
  serverModeNote: isAppiumOss
1130
1250
  ? 'Appium Server (OSS) — standard W3C WebDriver protocol. ' +
1131
- 'Java: java-client 8.x, Java 11+, UiAutomator2Options/XCUITestOptions (no DesiredCapabilities). ' +
1251
+ 'Java: java-client 11.x + selenium-java 4.51 (Java 17+), UiAutomator2Options/XCUITestOptions, AppiumBy, URI.create(...).toURL() (no DesiredCapabilities, no MobileBy). ' +
1132
1252
  'Python: appium-python-client 4.x+, AppiumOptions. ' +
1133
1253
  'If you need Grid mode, switch to a Grid-enabled profile and regenerate — the APIs are incompatible.'
1134
1254
  : 'Appium Grid (legacy) — Digital.ai JWP-era protocol, NOT standard Appium Server. ' +
@@ -1143,15 +1263,15 @@ export function registerBoilerplateTools(server) {
1143
1263
  : "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
1264
  testName,
1145
1265
  projectType: projectType ?? 'standalone-gradle',
1266
+ structure: pageObjectsApplied ? 'page-objects' : 'flat',
1267
+ ...(structureNote ? { structureNote } : {}),
1146
1268
  files: resolved.map(f => ({ filename: f.filename, content: f.content })),
1147
1269
  orchestration: orchestrationInfo,
1148
1270
  ...(automotive ? { automotive } : {}),
1149
1271
  ...(capNotes.length ? { capabilityNotes: capNotes } : {}),
1150
- setupNote: setupNote(language, isAppiumOss, projectType),
1272
+ setupNote: setupNote(language, isAppiumOss, projectType, resolved.filter((f) => !f.isInstructions).map((f) => f.filename)),
1151
1273
  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,
1274
+ parallelNote: parallelNote(language, isAppiumOss),
1155
1275
  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
1276
  // v38: when a custom app is targeted the test body is a placeholder, NOT a finished test.
1157
1277
  requiresVerifiedSelectors: clearTestBody,
@@ -1176,7 +1296,7 @@ export function registerBoilerplateTools(server) {
1176
1296
  const lines = [
1177
1297
  `# ${platformLabel} — ${langLabel[language]} Boilerplate (${serverModeLabel})`,
1178
1298
  '',
1179
- `> **Setup:** ${setupNote(language, isAppiumOss, projectType)}`,
1299
+ `> **Setup:** ${setupNote(language, isAppiumOss, projectType, resolved.filter((f) => !f.isInstructions).map((f) => f.filename))}`,
1180
1300
  `> **App:** ${appNote(platform, vars.packageName, vars.bundleIdentifier, vars.mainActivity, resolvedFromAppId)}`,
1181
1301
  `> **Device query:** ${regionLabel}${region ? '' : ' — re-call with region=<value> from find_available_device to scope to healthy devices only.'}`,
1182
1302
  `> ⚠️ **Security:** These files contain a live credential — move the access key to an environment variable (\`DIGITAL_AI_ACCESS_KEY\`) before committing to source control.`,
@@ -1326,6 +1446,9 @@ export function registerBoilerplateTools(server) {
1326
1446
  '<…> placeholder selectors, the deliberate scaffold fail-guard, placeholder/fabricated credentials, ' +
1327
1447
  'and resource IDs from a known prior fabrication incident. Returns isError when any high-severity ' +
1328
1448
  'pattern is found — a test that fails this is NOT runnable and must not be delivered as finished. ' +
1449
+ 'It also WARNS (never blocks) on flakiness patterns: fixed sleeps, index-based XPath, a static/suite-level ' +
1450
+ 'shared driver, implicit + explicit waits mixed, iOS //*[@name=] XPath where accessibility id is the same match, ' +
1451
+ 'and client APIs removed from the current Appium clients (correct only for Appium Grid projects). ' +
1329
1452
  'This catches the case the get_test_boilerplate gate cannot: a script you wrote yourself with guessed ' +
1330
1453
  'selectors. A clean result is necessary but not sufficient — it cannot confirm selectors are REAL, only ' +
1331
1454
  'that obvious placeholders are gone; the authoritative source for selectors is still a live inspection.', {
@@ -1340,6 +1463,7 @@ export function registerBoilerplateTools(server) {
1340
1463
  const structured = {
1341
1464
  verdict,
1342
1465
  highSeverityCount: high.length,
1466
+ warningCount: issues.filter((i) => i.severity === 'warn').length,
1343
1467
  issues,
1344
1468
  guidance: high.length > 0
1345
1469
  ? 'Do NOT present this script as a finished test. Replace every flagged placeholder with element IDs ' +
@@ -1352,7 +1476,7 @@ export function registerBoilerplateTools(server) {
1352
1476
  `${verdict === 'fail' ? '⛔ FAIL' : '✅ PASS'} — validate_test_script${label}`,
1353
1477
  '',
1354
1478
  ...(issues.length
1355
- ? issues.map((i) => ` ${i.severity === 'high' ? '⛔' : 'ℹ️'} [${i.label}] ${i.detail}`)
1479
+ ? issues.map((i) => ` ${i.severity === 'high' ? '⛔' : i.severity === 'warn' ? '⚠️' : 'ℹ️'} [${i.label}] ${i.detail}`)
1356
1480
  : [' No issues detected.']),
1357
1481
  '',
1358
1482
  structured.guidance,
@@ -1495,18 +1619,18 @@ export function registerBoilerplateTools(server) {
1495
1619
  examples = [
1496
1620
  `${indent}${c} Example shape — replace <…> with selectors from get_page_dom / find_web_elements:`,
1497
1621
  `${indent}${c} driver.get(${nav});`,
1498
- `${indent}${c} driver.findElement(By.cssSelector("<CSS selector from find_web_elements>")).click();`,
1499
- `${indent}${c} driver.findElement(By.cssSelector("input[name='<name attr>']")).sendKeys("<value>");`,
1500
- `${indent}${c} driver.findElement(By.id("<id from get_page_dom>")).click();`,
1622
+ `${indent}${c} find(By.cssSelector("<CSS selector from find_web_elements>")).click();`,
1623
+ `${indent}${c} find(By.cssSelector("input[name='<name attr>']")).sendKeys("<value>");`,
1624
+ `${indent}${c} find(By.id("<id from get_page_dom>")).click(); // find() waits up to 20 s — never add sleeps`,
1501
1625
  ].join('\n');
1502
1626
  }
1503
1627
  else if (lang === 'python') {
1504
1628
  examples = [
1505
1629
  `${indent}${c} Example shape — replace <…> with selectors from get_page_dom / find_web_elements:`,
1506
1630
  `${indent}${c} self.driver.get(${nav})`,
1507
- `${indent}${c} self.driver.find_element(By.CSS_SELECTOR, "<CSS selector from find_web_elements>").click()`,
1508
- `${indent}${c} self.driver.find_element(By.CSS_SELECTOR, "input[name='<name attr>']").send_keys("<value>")`,
1509
- `${indent}${c} self.driver.find_element(By.ID, "<id from get_page_dom>").click()`,
1631
+ `${indent}${c} self.find(By.CSS_SELECTOR, "<CSS selector from find_web_elements>").click()`,
1632
+ `${indent}${c} self.find(By.CSS_SELECTOR, "input[name='<name attr>']").send_keys("<value>")`,
1633
+ `${indent}${c} self.find(By.ID, "<id from get_page_dom>").click() # find() waits up to 20 s — never add sleeps`,
1510
1634
  ].join('\n');
1511
1635
  }
1512
1636
  else {
@@ -1604,8 +1728,10 @@ export function registerBoilerplateTools(server) {
1604
1728
  const framework = language === 'java-junit5' ? 'junit5' : 'testng';
1605
1729
  filename = `${testClass}.java`;
1606
1730
  const isJunit5 = language === 'java-junit5';
1607
- const beforeAnn = isJunit5 ? '@BeforeAll' : '@BeforeClass';
1608
- const afterAnn = isJunit5 ? '@AfterAll' : '@AfterClass';
1731
+ // TestNG: one session per test method (@BeforeMethod, instance methods). The old static @BeforeClass referenced the
1732
+ // instance driver and never compiled (found compiling the generated project, 2026-10-19).
1733
+ const beforeAnn = isJunit5 ? '@BeforeAll' : '@BeforeMethod';
1734
+ const afterAnn = isJunit5 ? '@AfterAll' : '@AfterMethod';
1609
1735
  const testAnn = '@Test';
1610
1736
  const lifecycle = isJunit5 ? '@TestInstance(TestInstance.Lifecycle.PER_CLASS)\n' : '';
1611
1737
  const assertion = isJunit5 ? 'import org.junit.jupiter.api.*;' : 'import org.testng.annotations.*;';
@@ -1622,6 +1748,8 @@ export function registerBoilerplateTools(server) {
1622
1748
  `import org.openqa.selenium.JavascriptExecutor;`,
1623
1749
  `import org.openqa.selenium.WebElement;`,
1624
1750
  `import org.openqa.selenium.remote.RemoteWebDriver;`,
1751
+ `import org.openqa.selenium.support.ui.ExpectedConditions;`,
1752
+ `import org.openqa.selenium.support.ui.WebDriverWait;`,
1625
1753
  `${browserImp}`,
1626
1754
  ``,
1627
1755
  `import java.net.MalformedURLException;`,
@@ -1636,18 +1764,23 @@ export function registerBoilerplateTools(server) {
1636
1764
  ` private static final String GRID_URL = "${gridUrl}";`,
1637
1765
  ``,
1638
1766
  ` ${beforeAnn}`,
1639
- ` ${isJunit5 ? '' : 'public static '}void setUp() throws MalformedURLException {`,
1767
+ ` ${isJunit5 ? '' : 'public '}void setUp() throws MalformedURLException {`,
1640
1768
  `${browserCap}`,
1641
1769
  ` caps.setCapability("digitalai:accessKey", ACCESS_KEY);`,
1642
1770
  ` caps.setCapability("digitalai:testName", "${testName}");`,
1643
1771
  ``,
1644
1772
  ` driver = new RemoteWebDriver(new URL(GRID_URL), caps);`,
1645
- ` driver.manage().timeouts().implicitlyWait(Duration.ofSeconds(10));`,
1646
1773
  ` driver.manage().window().maximize();`,
1647
1774
  ` }`,
1648
1775
  ``,
1776
+ ` // Explicit wait (20 s) until the element is visible, then return it. There is no implicit wait — adding one`,
1777
+ ` // would make every miss wait both timeouts. Use find(...) for every step.`,
1778
+ ` private WebElement find(By by) {`,
1779
+ ` return new WebDriverWait(driver, Duration.ofSeconds(20)).until(ExpectedConditions.visibilityOfElementLocated(by));`,
1780
+ ` }`,
1781
+ ``,
1649
1782
  ` ${afterAnn}`,
1650
- ` ${isJunit5 ? '' : 'public static '}void tearDown() {`,
1783
+ ` ${isJunit5 ? '' : 'public '}void tearDown() {`,
1651
1784
  ` if (driver != null) driver.quit();`,
1652
1785
  ` }${shadowHelper}`,
1653
1786
  ``,
@@ -1668,7 +1801,7 @@ export function registerBoilerplateTools(server) {
1668
1801
  ` <dependency>`,
1669
1802
  ` <groupId>org.seleniumhq.selenium</groupId>`,
1670
1803
  ` <artifactId>selenium-java</artifactId>`,
1671
- ` <version>4.20.0</version>`,
1804
+ ` <version>4.51.0</version>`,
1672
1805
  ` </dependency>`,
1673
1806
  framework === 'junit5' ? [
1674
1807
  ` <dependency>`,
@@ -1739,6 +1872,8 @@ export function registerBoilerplateTools(server) {
1739
1872
  `from selenium import webdriver`,
1740
1873
  `from selenium.webdriver.common.by import By`,
1741
1874
  `from selenium.webdriver.common.options import ArgOptions`,
1875
+ `from selenium.webdriver.support.ui import WebDriverWait`,
1876
+ `from selenium.webdriver.support import expected_conditions as EC`,
1742
1877
  ``,
1743
1878
  ``,
1744
1879
  `class ${testClass}(unittest.TestCase):`,
@@ -1757,9 +1892,13 @@ export function registerBoilerplateTools(server) {
1757
1892
  ` for name, value in caps.items():`,
1758
1893
  ` options.set_capability(name, value)`,
1759
1894
  ` self.driver = webdriver.Remote(command_executor=self.GRID_URL, options=options)`,
1760
- ` self.driver.implicitly_wait(10)`,
1761
1895
  ` self.driver.maximize_window()`,
1762
1896
  ``,
1897
+ ` def find(self, by, locator, timeout=20):`,
1898
+ ` # Explicit wait until the element is visible. There is no implicit wait — adding one would make every`,
1899
+ ` # miss wait both timeouts. Use self.find(...) for every step.`,
1900
+ ` return WebDriverWait(self.driver, timeout).until(EC.visibility_of_element_located((by, locator)))`,
1901
+ ``,
1763
1902
  ` def tearDown(self):`,
1764
1903
  ` if self.driver:`,
1765
1904
  ` self.driver.quit()${shadowHelper}`,
@@ -1772,7 +1911,7 @@ export function registerBoilerplateTools(server) {
1772
1911
  ` unittest.main()`,
1773
1912
  ].join('\n');
1774
1913
  const requirements = [
1775
- `selenium>=4.20.0`,
1914
+ `selenium>=4.51.0,<5`,
1776
1915
  ].join('\n');
1777
1916
  const structured = {
1778
1917
  language,