Merge pull request #2249 from Ishavyas9/main

smart ui doc updated

Author: Ishavyas9

assets/images/web-scanner/visual-scan-advanced-settings.png

@@ -381,6 +381,165 @@ By leveraging machine learning algorithms, it accurately detects and crops the s
 |---------------------|--------------------|
 | <img loading="lazy" src={require('../assets/images/smart-visual-testing/screenshot.webp').default} alt="Profile" width="1360" height="603" className="doc_img"/> | <img loading="lazy" src={require('../assets/images/smart-visual-testing/cropped_ss.jpg').default} alt="Profile" width="1360" height="603" className="doc_img"/> |
 
+## Best Practices
+
+### 1. Project and Build Naming
+
+- Use descriptive, consistent names for projects and builds
+- Include app version or release info in build names
+- Avoid special characters that might cause issues
+- Use consistent naming conventions across test runs
+
+**Example:**
+```json
+{
+  "smartUI.project": "MyApp-VisualTests",
+  "smartUI.build": "Release-1.0.0"
+}
+```
+
+### 2. Device Selection
+
+- Test on devices that match your user base
+- Include multiple device configurations for comprehensive coverage
+- Use device patterns for consistent testing (e.g., `Galaxy.*`, `Pixel.*`)
+
+### 3. Smart Crop Configuration
+
+- Enable `cropStatusBar` to focus on core UI elements
+- Enable `cropNavigationBar` for Android devices
+- Test cropped screenshots to ensure important content isn't removed
+
+### 4. Test Organization
+
+- Use sharding for parallel test execution
+- Group related tests in same build
+- Use meaningful test names for better organization
+
+### 5. App and Test Suite Management
+
+- Upload apps and test suites before execution
+- Use app IDs (`lt://APP...`) for faster execution
+- Keep app and test suite versions synchronized
+
+## Troubleshooting
+
+### Common Issues
+
+#### Issue: Screenshots Not Captured
+
+**Symptoms**: Tests run but no screenshots appear in SmartUI dashboard
+
+**Possible Causes**:
+- `visual: true` not set in request
+- Incorrect project name
+- Network connectivity issues
+- Authentication issues
+
+**Solutions**:
+1. Verify `visual: true` is set in API request:
+   ```json
+   {
+     "visual": true,
+     "smartUI.project": "ProjectName"
+   }
+   ```
+
+2. Check project name matches exactly (case-sensitive)
+
+3. Verify authentication token is correct:
+   - Generate base64 encoded token from username:accesskey
+   - Ensure token is included in Authorization header
+
+4. Check network connectivity to LambdaTest
+
+#### Issue: "Project Not Found" Error
+
+**Symptoms**: Error indicating SmartUI project cannot be found
+
+**Possible Causes**:
+- Project name typo or mismatch
+- Project deleted
+- Wrong account credentials
+
+**Solutions**:
+1. Verify project exists in SmartUI dashboard
+2. Copy project name directly from dashboard
+3. Check credentials match the account with the project
+4. Ensure project name is in API request
+
+#### Issue: App Upload Fails
+
+**Symptoms**: App upload returns error or fails
+
+**Possible Causes**:
+- Invalid APK file
+- File size too large
+- Network issues
+- Authentication problems
+
+**Solutions**:
+1. Verify APK file is valid and not corrupted
+2. Check file size limits
+3. Retry upload with stable network connection
+4. Verify authentication credentials
+
+#### Issue: Test Execution Fails
+
+**Symptoms**: Test suite execution fails or times out
+
+**Possible Causes**:
+- Invalid test suite APK
+- Device not available
+- Timeout settings too low
+- Test suite errors
+
+**Solutions**:
+1. Verify test suite APK is valid
+2. Check device availability
+3. Increase `queueTimeout` and `IdleTimeout`:
+   ```json
+   {
+     "queueTimeout": 600,
+     "IdleTimeout": 60
+   }
+   ```
+
+4. Review device logs for test errors
+
+#### Issue: Screenshots Show Incorrect Content
+
+**Symptoms**: Screenshots captured but show wrong screen or state
+
+**Possible Causes**:
+- App state issues
+- Timing problems
+- Navigation issues
+
+**Solutions**:
+1. Ensure app is in correct state before test execution
+2. Add appropriate waits in test code
+3. Verify test navigation flow
+
+### Getting Help
+
+If you encounter issues not covered here:
+
+- Review the [Comprehensive Troubleshooting Guide](/support/docs/smartui-troubleshooting-guide) for detailed solutions
+- Check [SmartUI Configuration Options](/support/docs/smartui-sdk-config-options) documentation
+- See [Handling Dynamic Data](/support/docs/smartui-handle-dynamic-data) for dynamic content issues
+- Visit [LambdaTest Support](https://www.lambdatest.com/support) for additional resources
+- Contact support at [email protected] or use [24/7 Chat Support](https://www.lambdatest.com/support)
+
+## Additional Resources
+
+- [Comprehensive Troubleshooting Guide](/support/docs/smartui-troubleshooting-guide)
+- [SmartUI Configuration Options](/support/docs/smartui-sdk-config-options)
+- [Handling Dynamic Data](/support/docs/smartui-handle-dynamic-data)
+- [Baseline Management](/support/docs/smartui-baseline-management)
+- [Running Your First Project](/support/docs/smartui-running-your-first-project)
+- [Appium Hooks Documentation](/support/docs/smartui-appium-hooks)
+
 
 <nav aria-label="breadcrumbs">
   <ul className="breadcrumbs">

docs/espresso-visual-regression.md

@@ -251,6 +251,201 @@ For additional information about Playwright framework please explore the documen
 
   **Handling Dynamic Data** - In case if you have any dynamic elements that are not in the same position across test runs, you can ignore or select a specific area to be removed from the comparison. For accessing such HTML DOM Config and Options, click [here](/support/docs/html-dom-smartui-options/#configuration-for-playwright).
 
+## Best Practices
+
+### 1. Capability Configuration
+
+- Always set `visual: true` in your capabilities to enable SmartUI
+- Use consistent project and build names across test runs
+- Set meaningful test names for better organization
+
+**Example:**
+```javascript
+const capabilities = {
+  browserName: 'Chrome',
+  browserVersion: 'latest',
+  platformName: 'Windows 10',
+  'LT:Options': {
+    username: process.env.LT_USERNAME,
+    accessKey: process.env.LT_ACCESS_KEY,
+    visual: true,
+    name: 'Homepage Visual Test',
+    build: 'Release 1.0',
+    'smartUI.project': 'MyProject',
+    'smartUI.build': 'Build-1.0'
+  }
+};
+```
+
+### 2. Screenshot Timing
+
+- Wait for page elements to load before capturing screenshots
+- Use Playwright's wait methods for dynamic content
+- Consider page load time when setting up tests
+
+**Example:**
+```javascript
+await page.goto('https://example.com');
+await page.waitForSelector('.main-content', { state: 'visible' });
+await page.waitForLoadState('networkidle');
+```
+
+### 3. Screenshot Naming
+
+- Use descriptive, consistent names
+- Include context (page, component, state) in names
+- Avoid special characters
+
+### 4. Baseline Management
+
+- Establish baselines from stable builds
+- Review and approve baselines before using
+- Update baselines when intentional changes are made
+
+### 5. Viewport Selection
+
+- Test on viewports that match your user base
+- Include mobile, tablet, and desktop viewports
+- Consider both portrait and landscape orientations
+
+## Troubleshooting
+
+### Common Issues
+
+#### Issue: Screenshots Not Captured
+
+**Symptoms**: Tests run but no screenshots appear in SmartUI dashboard
+
+**Possible Causes**:
+- `visual: true` not set in capabilities
+- Incorrect project name
+- Network connectivity issues
+- Credentials not set correctly
+
+**Solutions**:
+1. Verify `visual: true` is set in capabilities:
+   ```javascript
+   'LT:Options': {
+     visual: true, // Must be set
+     // ... other options
+   }
+   ```
+
+2. Check project name matches exactly (case-sensitive):
+   ```javascript
+   'smartUI.project': 'ExactProjectName'
+   ```
+
+3. Verify credentials are set:
+   ```bash
+   echo $LT_USERNAME
+   echo $LT_ACCESS_KEY
+   ```
+
+4. Check network connectivity to LambdaTest
+
+#### Issue: "Project Not Found" Error
+
+**Symptoms**: Error indicating SmartUI project cannot be found
+
+**Possible Causes**:
+- Project name typo or mismatch
+- Project deleted
+- Wrong account credentials
+
+**Solutions**:
+1. Verify project exists in SmartUI dashboard
+2. Copy project name directly from dashboard
+3. Check credentials match the account with the project
+4. Ensure project name is in capabilities, not just in dashboard
+
+#### Issue: Screenshots Show Blank Pages
+
+**Symptoms**: Screenshots captured but show blank or incomplete content
+
+**Possible Causes**:
+- Page not fully loaded
+- JavaScript not executed
+- Timing issues
+- Viewport issues
+
+**Solutions**:
+1. Add explicit waits before screenshot:
+   ```javascript
+   await page.waitForSelector('#content', { state: 'visible' });
+   await page.waitForLoadState('networkidle');
+   ```
+
+2. Wait for specific elements to be visible:
+   ```javascript
+   await page.waitForSelector('.main-content', { state: 'visible' });
+   ```
+
+3. Increase wait time for slow-loading pages
+
+4. Check viewport size matches expected dimensions
+
+#### Issue: Build Name Conflicts
+
+**Symptoms**: Screenshots appear in wrong build or build name issues
+
+**Possible Causes**:
+- Build name not set consistently
+- Special characters in build name
+- Build name conflicts
+
+**Solutions**:
+1. Set build name in capabilities:
+   ```javascript
+   'smartUI.build': 'ConsistentBuildName'
+   ```
+
+2. Avoid special characters in build names
+
+3. Use consistent naming convention across team
+
+#### Issue: Mismatch Percentage Unexpected
+
+**Symptoms**: Mismatch percentage higher or lower than expected
+
+**Possible Causes**:
+- Threshold settings
+- Dynamic content not ignored
+- Rendering differences
+- Baseline issues
+
+**Solutions**:
+1. Review threshold settings in project settings
+
+2. Use `ignoreDOM` for dynamic content:
+   ```javascript
+   'smartUI.options': {
+     'ignoreDOM': {
+       'id': ['timestamp', 'user-id']
+     }
+   }
+   ```
+
+3. Check baseline is correct and up-to-date
+
+4. Review comparison settings in project
+
+### Getting Help
+
+If you encounter issues not covered here:
+
+- Review [SmartUI Build Options](/support/docs/build-options-for-visual-regression-testing) documentation
+- Check [Advanced Test Settings](https://www.lambdatest.com/support/docs/test-settings-options/) for comparison options
+- Visit [LambdaTest Support](https://www.lambdatest.com/support) for additional resources
+- Contact support at [email protected] or use [24/7 Chat Support](https://www.lambdatest.com/support)
+
+## Additional Resources
+
+- [SmartUI Build Options](/support/docs/build-options-for-visual-regression-testing)
+- [Advanced Test Settings](https://www.lambdatest.com/support/docs/test-settings-options/)
+- [Handling Dynamic Data](/support/docs/smartui-handle-dynamic-data)
+- [Project Settings](/support/docs/smartui-project-settings)
+
 <!-- <img loading="lazy" src={require('../assets/images/uploads/smart-ui-2.webp').default} alt="cmd" width="768" height="373" className="doc_img"/> -->
 
 <nav aria-label="breadcrumbs">