Skip to content

Commit e49b157

Browse files
surishubhamsurishubham
committed
Merge pull request #2068 from RushilK7/stage
Stage
1 parent 8523f68 commit e49b157

File tree

2 files changed

+203
-7
lines changed

2 files changed

+203
-7
lines changed

‎docs/smartui-appium-hooks.md‎

Lines changed: 128 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ keywords:
1515
- Visual Regression Testing Environment
1616
- How to Run Visual Regression Tests
1717

18-
url: https://www.lambdatest.com/support/docs/smartui-appium-hooks/
18+
url: https://www.lambdatest.com/support/docs/smartui-appium-hooks/
1919
site_name: LambdaTest
2020
slug: smartui-appium-hooks
2121
---
@@ -255,6 +255,129 @@ By leveraging machine learning algorithms, it accurately detects and crops the s
255255

256256
<img loading="lazy" src={require('../assets/images/smart-visual-testing/cropped_ss.jpg').default} alt="Profile" width="1360" height="603" className="doc_img"/>
257257

258+
## Region-Based Ignore/Select for Dynamic Content (Advanced)
259+
260+
To handle dynamic content like timestamps, user names, ads, or banners that cause false positives in visual comparisons, SmartUI supports region-based ignore and select functionality using **XPath locators**.
261+
262+
You can either:
263+
- **Ignore specific regions** during comparison using `ignoreBoxes`
264+
- **Compare only specific regions** using `selectBoxes`
265+
266+
This is especially useful for enterprise applications where certain UI elements change dynamically between test runs.
267+
268+
### Usage in Node.js (Primary Example)
269+
270+
```javascript title="Example: Ignoring Dynamic Elements in Node.js"
271+
let config = {
272+
screenshotName: 'Home Screen',
273+
ignoreBoxes: JSON.stringify({
274+
xpath: [
275+
"//*[@text='Backpack']",
276+
"//*[@text='Onesie']",
277+
"//*[@text='PRODUCTS']",
278+
"//*[@text='Terms of Service | Privacy Policy']"
279+
]
280+
})
281+
};
282+
283+
await driver.execute("smartui.takeScreenshot", config);
284+
```
285+
286+
```javascript title="Example: Selecting Only Critical Regions in Node.js"
287+
let config = {
288+
screenshotName: 'Checkout Form',
289+
selectBoxes: JSON.stringify({
290+
xpath: [
291+
"//*[@resource-id='checkout-form']",
292+
"//*[@resource-id='total-amount']"
293+
]
294+
})
295+
};
296+
297+
await driver.execute("smartui.takeScreenshot", config);
298+
```
299+
300+
### Cross-Framework Examples
301+
302+
<Tabs className="docs__val" groupId="language">
303+
<TabItem value="nodejs" label="NodeJS" default>
304+
305+
```javascript
306+
let config = {
307+
screenshotName: '<Your Screenshot Name>',
308+
ignoreBoxes: JSON.stringify({
309+
xpath: ["//*[@text='Dynamic Ad']", "//*[@id='timestamp']"]
310+
})
311+
};
312+
await driver.execute("smartui.takeScreenshot", config);
313+
```
314+
315+
</TabItem>
316+
317+
<TabItem value="python" label="Python">
318+
319+
```python
320+
config = {
321+
'screenshotName': '<Your Screenshot Name>',
322+
'ignoreBoxes': '{"xpath": ["//*[@text=\'Dynamic Ad\']", "//*[@id=\'timestamp\']"]}'
323+
}
324+
driver.execute("smartui.takeScreenshot", config)
325+
```
326+
327+
</TabItem>
328+
329+
<TabItem value="java" label="Java">
330+
331+
```java
332+
Map<String, Object> config = new HashMap<>();
333+
config.put("screenshotName", "<Your Screenshot Name>");
334+
config.put("ignoreBoxes", "{\"xpath\": [\"//*[@text='Dynamic Ad']\", \"//*[@id='timestamp']\"]}");
335+
336+
((JavascriptExecutor) driver).executeScript("smartui.takeScreenshot", config);
337+
```
338+
339+
</TabItem>
340+
341+
<TabItem value="csharp" label="C#">
342+
343+
```csharp
344+
var config = new Dictionary<string, object> {
345+
{"screenshotName", "<Your Screenshot Name>"},
346+
{"ignoreBoxes", "{\"xpath\": [\"//*[@text='Dynamic Ad']\", \"//*[@id='timestamp']\"]}"}
347+
};
348+
driver.ExecuteScript("smartui.takeScreenshot", config);
349+
```
350+
351+
</TabItem>
352+
353+
<TabItem value="ruby" label="Ruby">
354+
355+
```ruby
356+
config = {
357+
'screenshotName' => '<Your Screenshot Name>',
358+
'ignoreBoxes' => '{"xpath": ["//*[@text=\'Dynamic Ad\']", "//*[@id=\'timestamp\']"]}'
359+
}
360+
driver.execute_script("smartui.takeScreenshot", config)
361+
```
362+
363+
</TabItem>
364+
</Tabs>
365+
366+
### Configuration Keys
367+
368+
| Key | Type | Description | Required |
369+
|-----|------|-------------|----------|
370+
| `ignoreBoxes` | JSON String | Defines regions to ignore during visual comparison. Accepts XPath locators. | No |
371+
| `selectBoxes` | JSON String | Defines regions to include in visual comparison. Accepts XPath locators. | No |
372+
373+
:::note Best Practices
374+
- Use `ignoreBoxes` for elements that change frequently (e.g., ads, timestamps, user avatars).
375+
- Use `selectBoxes` when you want to focus comparison only on critical UI sections.
376+
- Avoid using both `ignoreBoxes` and `selectBoxes` in the same config — they are mutually exclusive.
377+
- Ensure XPath expressions are unique and stable across test runs.
378+
- Test your XPath locators using Appium Inspector or similar tools before integrating.
379+
:::
380+
258381
## Running Tests on Other Languages and Frameworks
259382

260383
---
@@ -285,7 +408,7 @@ driver.execute("smartui.takeScreenshot=<Your Screenshot Name>")
285408
</TabItem>
286409
<TabItem value="ruby" label="Ruby" default>
287410

288-
```python
411+
```ruby
289412
driver.execute("smartui.takeScreenshot=<Your Screenshot Name>")
290413
```
291414

@@ -300,7 +423,7 @@ driver.Execute("smartui.takeScreenshot=<Your Screenshot Name>");
300423
<TabItem value="java" label="Java" default>
301424

302425
```java
303-
((JavascriptExecutor)driver).execute("smartui.takeScreenshot=<Your Screenshot Name>");
426+
((JavascriptExecutor)driver).executeScript("smartui.takeScreenshot=<Your Screenshot Name>");
304427
```
305428

306429
</TabItem>
@@ -367,7 +490,7 @@ Map<String, Object> config = new HashMap<>();
367490
config.put("screenshotName", "<Your Screenshot Name>");
368491
config.put("fullPage", true);
369492
config.put("pageCount", 15); // Enter the number of pages for the Full Page screenshot (Minimum 1, Maximum 20)
370-
((JavascriptExecutor)driver).execute("smartui.takeScreenshot", config);
493+
((JavascriptExecutor)driver).executeScript("smartui.takeScreenshot", config);
371494
```
372495

373496
</TabItem>
@@ -377,7 +500,7 @@ config.put("pageCount", 15); // Enter the number of pages for the Full Page scre
377500
Please note that this webhook is only applicable to <b>native app screenshots</b> and has known limitations. You can use an optimized value of page count (between 1 and 20) to get the best results of your full page screenshots, according to your use case.
378501
:::
379502

380-
For additional information about appium framework please explore the documentation [here](https://www.lambdatest.com/support/docs/getting-started-with-lambdatest-automation/)
503+
For additional information about appium framework please explore the documentation [here](https://www.lambdatest.com/support/docs/appium-nodejs/)
381504

382505

383506
<nav aria-label="breadcrumbs">

‎docs/smartui-appium-java-sdk.md‎

Lines changed: 75 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ keywords:
1717
- Mobile App Testing
1818
- App Visual Testing
1919

20-
url: https://www.lambdatest.com/support/docs/smartui-appium-java-sdk
20+
url: https://www.lambdatest.com/support/docs/smartui-appium-java-sdk
2121
slug: smartui-appium-java-sdk
2222
---
2323

@@ -214,6 +214,79 @@ ssConfig.put("platform", "iOS/Android"); // Use the actual platform
214214
The device name and platform you specify here are used only for screenshot organization and comparison. The actual device selection is handled by your cloud provider's capabilities configuration.
215215
:::
216216

217+
## Region-Based Ignore/Select Functionality for Dynamic Content
218+
219+
To handle dynamic content like timestamps, usernames, or ads that cause false positives in visual comparisons, SmartUI App SDK supports region-based ignore and select functionality using XPath locators.
220+
221+
You can either:
222+
- **Ignore specific regions** during comparison using `ignoreBoxes`
223+
- **Compare only specific regions** using `selectBoxes`
224+
225+
This feature requires the `Gson` library for JSON serialization. Add it to your `pom.xml` if not already present:
226+
227+
```xml
228+
<dependency>
229+
<groupId>com.google.code.gson</groupId>
230+
<artifactId>gson</artifactId>
231+
<version>2.10.1</version>
232+
</dependency>
233+
```
234+
235+
### Usage Examples
236+
237+
#### 1. Ignoring Regions (Recommended for Dynamic Content)
238+
239+
```java
240+
SmartUIAppSnapshot smartUI = new SmartUIAppSnapshot();
241+
242+
Map<String, String> config = new HashMap<>();
243+
config.put("projectToken", "your-project-token-here");
244+
config.put("deviceName", "Pixel 6");
245+
config.put("fullPage", "true");
246+
247+
// Define XPaths of elements to ignore
248+
List<String> ignoreXpath = Arrays.asList(
249+
"//*[@text=\"Backpack\"]",
250+
"//*[@text=\"Onesie\"]",
251+
"//*[@text=\"PRODUCTS\"]",
252+
"//*[@text=\"Terms of Service | Privacy Policy\"]"
253+
);
254+
255+
Map<String, Object> ignoreBoxesMap = new HashMap<>();
256+
ignoreBoxesMap.put("xpath", ignoreXpath);
257+
258+
Gson gson = new Gson();
259+
config.put("ignoreBoxes", gson.toJson(ignoreBoxesMap));
260+
261+
smartUI.start(config);
262+
smartUI.smartuiAppSnapshot(driver, "SmartUIAndroid", config);
263+
smartUI.stop();
264+
```
265+
266+
#### 2. Selecting Specific Regions for Comparison
267+
268+
```java
269+
// Replace "ignoreBoxes" with "selectBoxes" to compare only specified regions
270+
Map<String, Object> selectBoxesMap = new HashMap<>();
271+
selectBoxesMap.put("xpath", Arrays.asList("//*[@resource-id='primary-content']"));
272+
273+
config.put("selectBoxes", gson.toJson(selectBoxesMap));
274+
```
275+
276+
### Configuration Keys
277+
278+
| Key | Type | Description | Required |
279+
|-----|------|-------------|----------|
280+
| `ignoreBoxes` | JSON String | Defines regions to ignore during visual comparison. Accepts XPath locators. | No |
281+
| `selectBoxes` | JSON String | Defines regions to include in visual comparison. Accepts XPath locators. | No |
282+
283+
:::note Best Practices
284+
- Use `ignoreBoxes` for elements that change frequently (e.g., ads, timestamps, user avatars).
285+
- Use `selectBoxes` when you want to focus comparison only on critical UI sections.
286+
- Avoid using both `ignoreBoxes` and `selectBoxes` in the same config — they are mutually exclusive.
287+
- Ensure XPath expressions are unique and stable across test runs.
288+
:::
289+
217290
## View SmartUI Results
218291

219292
After test execution, visit your SmartUI project dashboard to:
@@ -244,4 +317,4 @@ For additional information about SmartUI APIs, please explore the documentation
244317
<span className="breadcrumbs__link">SmartUI App SDK</span>
245318
</li>
246319
</ul>
247-
</nav>
320+
</nav>

0 commit comments

Comments
 (0)