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.
- package/README.md +18 -13
- package/dist/api/webdriver.d.ts +61 -3
- package/dist/api/webdriver.d.ts.map +1 -1
- package/dist/api/webdriver.js +673 -33
- package/dist/api/webdriver.js.map +1 -1
- package/dist/index.js +1 -0
- package/dist/index.js.map +1 -1
- package/dist/tools/boilerplate-tools.d.ts +1 -1
- package/dist/tools/boilerplate-tools.d.ts.map +1 -1
- package/dist/tools/boilerplate-tools.js +217 -78
- package/dist/tools/boilerplate-tools.js.map +1 -1
- package/dist/tools/device-tools.d.ts +11 -0
- package/dist/tools/device-tools.d.ts.map +1 -1
- package/dist/tools/device-tools.js +25 -2
- package/dist/tools/device-tools.js.map +1 -1
- package/dist/tools/inspection-tools.d.ts.map +1 -1
- package/dist/tools/inspection-tools.js +219 -23
- package/dist/tools/inspection-tools.js.map +1 -1
- package/dist/tools/meta-tools.d.ts +1 -1
- package/dist/tools/meta-tools.d.ts.map +1 -1
- package/dist/tools/meta-tools.js +12 -1
- package/dist/tools/meta-tools.js.map +1 -1
- package/dist/tools/performance-tools.d.ts.map +1 -1
- package/dist/tools/performance-tools.js +6 -1
- package/dist/tools/performance-tools.js.map +1 -1
- package/dist/tools/reporting-tools.d.ts.map +1 -1
- package/dist/tools/reporting-tools.js +19 -1
- package/dist/tools/reporting-tools.js.map +1 -1
- package/dist/types/digital-ai.d.ts +10 -0
- package/dist/types/digital-ai.d.ts.map +1 -1
- package/dist/utils/test-orchestrator.d.ts +2 -0
- package/dist/utils/test-orchestrator.d.ts.map +1 -1
- package/dist/utils/test-orchestrator.js +2 -0
- package/dist/utils/test-orchestrator.js.map +1 -1
- package/package.json +3 -1
- package/resources/boilerplate/Android-Native/Java JUnit5/AndroidNative-oss-po.java +50 -0
- package/resources/boilerplate/Android-Native/Java JUnit5/AndroidNative-oss.java +23 -13
- package/resources/boilerplate/Android-Native/Java JUnit5/AndroidNative.java +19 -10
- package/resources/boilerplate/Android-Native/Java JUnit5/gradle-oss +4 -1
- package/resources/boilerplate/Android-Native/Java JUnit5/maven-oss +7 -1
- package/resources/boilerplate/Android-Native/NodeJS (WebDriver)/AndroidNative-po.js +13 -0
- package/resources/boilerplate/Android-Native/NodeJS (WebDriver)/AndroidNative.js +17 -11
- package/resources/boilerplate/Android-Native/NodeJS (WebDriver)/wdio-oss.conf.js +7 -2
- package/resources/boilerplate/Android-Native/NodeJS (WebDriver)/wdio.conf.js +10 -4
- package/resources/boilerplate/Android-Native/Python/AndroidNative-oss.py +30 -14
- package/resources/boilerplate/Android-Native/Python/AndroidNative.py +21 -5
- package/resources/boilerplate/Android-Native/Robot Framework/AndroidNative-oss.robot +28 -11
- package/resources/boilerplate/Android-Native/java TestNG/AndroidNative-oss-po.java +50 -0
- package/resources/boilerplate/Android-Native/java TestNG/AndroidNative-oss.java +23 -13
- package/resources/boilerplate/Android-Native/java TestNG/AndroidNative.java +19 -10
- package/resources/boilerplate/Android-Native/java TestNG/gradle-oss +4 -1
- package/resources/boilerplate/Android-Native/java TestNG/maven-oss +7 -1
- package/resources/boilerplate/iOS-Native/NodeJS (WebDriver)/iOSNative-po.js +13 -0
- package/resources/boilerplate/iOS-Native/NodeJS (WebDriver)/iOSNative.js +17 -11
- package/resources/boilerplate/iOS-Native/NodeJS (WebDriver)/wdio-oss.conf.js +4 -1
- package/resources/boilerplate/iOS-Native/NodeJS (WebDriver)/wdio.conf.js +2 -0
- package/resources/boilerplate/iOS-Native/Python/iOSNative-oss.py +31 -14
- package/resources/boilerplate/iOS-Native/Python/iOSNative.py +36 -15
- package/resources/boilerplate/iOS-Native/Robot Framework/iOSNative-oss.robot +28 -11
- package/resources/boilerplate/iOS-Native/java-JUnit5/gradle-oss +4 -1
- package/resources/boilerplate/iOS-Native/java-JUnit5/iOSNative-oss-po.java +47 -0
- package/resources/boilerplate/iOS-Native/java-JUnit5/iOSNative-oss.java +24 -13
- package/resources/boilerplate/iOS-Native/java-JUnit5/iOSNative.java +21 -11
- package/resources/boilerplate/iOS-Native/java-JUnit5/maven-oss +7 -1
- package/resources/boilerplate/iOS-Native/java-TestNG/gradle-oss +4 -1
- package/resources/boilerplate/iOS-Native/java-TestNG/iOSNative-oss-po.java +47 -0
- package/resources/boilerplate/iOS-Native/java-TestNG/iOSNative-oss.java +24 -13
- package/resources/boilerplate/iOS-Native/java-TestNG/iOSNative.java +21 -11
- package/resources/boilerplate/iOS-Native/java-TestNG/maven-oss +7 -1
- package/resources/boilerplate/shared/java-screens/AppScreen.java +29 -0
- package/resources/boilerplate/shared/java-screens/BaseScreen.java +42 -0
- package/resources/boilerplate/shared/java-screens/DashboardScreen.java +18 -0
- package/resources/boilerplate/shared/java-screens/LoginScreen.java +23 -0
- package/resources/boilerplate/shared/java-screens/PaymentScreen.java +34 -0
- package/resources/boilerplate/shared/node-screens/AppScreen.js +27 -0
- package/resources/boilerplate/shared/node-screens/DashboardScreen.js +13 -0
- package/resources/boilerplate/shared/node-screens/LoginScreen.js +18 -0
- package/resources/boilerplate/shared/node-screens/PaymentScreen.js +28 -0
- 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:
|
|
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:
|
|
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:
|
|
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.
|
|
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
|
-
* -
|
|
250
|
-
*
|
|
251
|
-
*
|
|
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
|
-
|
|
299
|
+
`${indent} driver.executeScript("seetest:client.startStepsGroup", "${group}");`,
|
|
264
300
|
inner,
|
|
265
|
-
|
|
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
|
-
|
|
314
|
+
`${indent} self.driver.execute_script("seetest:client.startStepsGroup", "${group}")`,
|
|
278
315
|
inner,
|
|
279
|
-
|
|
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
|
-
|
|
329
|
+
`${indent} await browser.execute('seetest:client.startStepsGroup', '${group}');`,
|
|
293
330
|
inner,
|
|
294
|
-
|
|
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>' :
|
|
382
|
-
const field = platform === 'android' ? 'id=<resource-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
|
|
386
|
-
`${indent}${c} Input
|
|
387
|
-
`${indent}${c}
|
|
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}
|
|
395
|
-
`${indent}${c}
|
|
396
|
-
`${indent}${c}
|
|
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
|
|
403
|
-
`${indent}${c} const field = await
|
|
404
|
-
`${indent}${c} await expect($('//*[@text="<visible text>"]')).
|
|
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
|
|
411
|
-
`${indent}${c} self
|
|
412
|
-
`${indent}${c} self
|
|
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}
|
|
421
|
-
`${indent}${c}
|
|
422
|
-
`${indent}${c}
|
|
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
|
|
429
|
-
`${indent}${c} const field = await
|
|
430
|
-
`${indent}${c} await expect($('//*[@label="<visible label>"]')).
|
|
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
|
|
437
|
-
`${indent}${c} self
|
|
438
|
-
`${indent}${c} self
|
|
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
|
-
|
|
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 (
|
|
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 (
|
|
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
|
|
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–
|
|
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
|
|
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
|
|
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}
|
|
1499
|
-
`${indent}${c}
|
|
1500
|
-
`${indent}${c}
|
|
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.
|
|
1508
|
-
`${indent}${c} self.
|
|
1509
|
-
`${indent}${c} self.
|
|
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
|
-
|
|
1608
|
-
|
|
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
|
|
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
|
|
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.
|
|
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.
|
|
1914
|
+
`selenium>=4.51.0,<5`,
|
|
1776
1915
|
].join('\n');
|
|
1777
1916
|
const structured = {
|
|
1778
1917
|
language,
|