diff --git a/docs/appium-visual-regression.md b/docs/appium-visual-regression.md index 96c143cfb..69202e43f 100644 --- a/docs/appium-visual-regression.md +++ b/docs/appium-visual-regression.md @@ -1,7 +1,7 @@ --- id: appium-visual-regression title: Getting Started With Visual Regression Testing Using Appium On SmartUI Real Devices (NodeJS) -sidebar_label: Appium +sidebar_label: Appium Hooks description: Explore our Appium Visual Regression support documentation for step-by-step guidance! Conduct visual testing, manage apps, and ensure your mobile apps are flawless before launch. keywords: - Visual Regression diff --git a/docs/smartui-app-sdk.md b/docs/smartui-app-sdk.md new file mode 100644 index 000000000..1bef52b83 --- /dev/null +++ b/docs/smartui-app-sdk.md @@ -0,0 +1,246 @@ +--- +id: smartui-app-sdk +title: SmartUI App SDK Integration Guide +sidebar_label: Appium Java SDK +description: Learn how to integrate SmartUI App SDK with your existing mobile app testing framework to perform visual regression testing on any cloud provider. +keywords: + - Visual Regression + - Visual Regression Testing Guide + - Visual Regression Test Automation + - Visual Regression Automation Testing + - Running Visual Regression Tests + - Visual Regression Testing Online + - Run Visual Regression + - Visual Regression Run Specific Test + - Visual Regression Testing Environment + - How to Run Visual Regression Tests + - Mobile App Testing + - App Visual Testing + +url: https://www.lambdatest.com/support/docs/smartui-app-sdk/ +slug: smartui-app-sdk/ +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import NewTag from '../src/component/newTag'; + +--- + + + +SmartUI App SDK enables you to perform visual regression testing on your mobile applications using any cloud testing provider. This guide will help you integrate SmartUI App SDK with your existing mobile app testing framework. + +## Prerequisites + +- Basic understanding of mobile app testing and Appium +- Login to [LambdaTest SmartUI](https://smartui.lambdatest.com/) with your credentials +- An active [subscription](https://www.lambdatest.com/pricing) plan with valid screenshots limit + +## Create a SmartUI Project + +The first step is to create a project that will contain all your builds. To create a SmartUI Project: + +1. Go to [Projects page](https://smartui.lambdatest.com/) +2. Click on the `new project` button +3. Select the platform as CLI for executing your `SDK` tests +4. Add name of the project, approvers for the changes found, and tags for filtering +5. Click on **Submit** + +## Steps to Run Your First Test + +### Step 1: Add the SmartUI SDK Dependency + +Add the following dependency to your `pom.xml` file: + +```xml + + io.github.lambdatest + lambdatest-java-sdk + 1.0.8 + +``` + +### Step 2: Configure Your Project Token + +You can configure your project token in one of two ways: + +1. **Using Environment Variables**: + + + + +```bash +export PROJECT_TOKEN="123456#1234abcd-****-****-****-************" +``` + + + + +```bash +set PROJECT_TOKEN="123456#1234abcd-****-****-****-************" +``` + + + + +2. **Directly in the Configuration**: +You can pass the project token directly in your test configuration as shown in Step 3. + +### Step 3: Integrate SmartUI in Your Test Script + +Import the required SmartUI class and add the screenshot capture code where needed: + +```java +import io.github.lambdatest.SmartUIAppSnapshot; + +public class YourTestClass { + @Test + public void testMethod() { + // Initialize SmartUI + SmartUIAppSnapshot SmartUI = new SmartUIAppSnapshot(); + + // Configure screenshot settings + Map ssConfig = new HashMap<>(); + // Either use environment variable + // ssConfig.put("projectToken", "your-project-token-here"); // Use this if you are not setting the project token in environment variable + ssConfig.put("deviceName", "iPhone 15"); // Required, you can use the variables that you are setting in the cloud capabilities + ssConfig.put("buildName", "First Build"); // Optional + ssConfig.put("platform", "iOS"); // Optional,you can use the variables that you are setting in the cloud capabilities + + try { + // Start SmartUI session + SmartUI.start(ssConfig); + + // Your test code here +// Your test code here - Example of native app interactions + driver.findElement(MobileBy.AccessibilityId("username-input")).sendKeys("test@example.com"); + driver.findElement(MobileBy.AccessibilityId("password-input")).sendKeys("password123"); + + // Take screenshot of login form + SmartUI.smartuiAppSnapshot(driver, "Login Form", ssConfig); + + driver.findElement(MobileBy.AccessibilityId("login-button")).click(); + + // Wait for home screen to load + WebDriverWait wait = new WebDriverWait(driver, 10); + wait.until(ExpectedConditions.presenceOfElementLocated(MobileBy.AccessibilityId("home-screen"))); + + // Take screenshot of home screen + SmartUI.smartuiAppSnapshot(driver, "Home Screen", ssConfig); + + // More test steps... + + } finally { + // Stop SmartUI session + SmartUI.stop(); + } + } +} +``` + +### Step 4: Execute the Tests + +Run your tests as you normally would with your cloud provider. SmartUI will automatically capture and process the screenshots for visual regression testing. + +```bash +mvn test +``` + +## Configuration Options + +### Screenshot Configuration Options + +| Key | Description | Required | +|-----|-------------|----------| +| projectToken | Your SmartUI project token | Yes | +| deviceName | Name of the device being tested | Yes | +| buildName | Custom name for your build | No | +| platform | Platform being tested (iOS/Android) | No | + +### Supported Platforms and Devices + +The `deviceName` and `platform` parameters in SmartUI App SDK are used as metadata to ensure consistent screenshot comparison across builds. You can use any device name and platform that matches your cloud provider's capabilities: + +```java +ssConfig.put("deviceName", "iPhone 15"); +ssConfig.put("platform", "iOS"); +``` + +#### Important Notes: +- It is adviced to use the same `deviceName` and `platform` combination across builds to compare screenshots of the same device +- These parameters are metadata tags and don't affect the actual device selection on your cloud provider + +Example configurations for different cloud providers: + +```java +// For an iOS test on LambdaTest +ssConfig.put("deviceName", "iPhone 12"); +ssConfig.put("platform", "iOS"); + +// For an Android test on BrowserStack +ssConfig.put("deviceName", "Samsung Galaxy S22"); +ssConfig.put("platform", "Android"); + +// For a custom device on any cloud provider +ssConfig.put("deviceName", "Custom Device Name"); // Use the same name consistently +ssConfig.put("platform", "iOS/Android"); // Use the actual platform +``` + +:::note +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. +::: + +## View SmartUI Results + +After test execution, visit your SmartUI project dashboard to: + +1. View all captured screenshots +2. Compare against baseline images +3. Identify visual regressions +4. Approve or reject changes +5. Manage baseline images + +SmartUI Results + +For additional information about SmartUI APIs, please explore the documentation [here](https://www.lambdatest.com/support/api-doc/) + + diff --git a/docs/smartui-cli-env-variables.md b/docs/smartui-cli-env-variables.md index 9722a3e5d..d78de74fc 100644 --- a/docs/smartui-cli-env-variables.md +++ b/docs/smartui-cli-env-variables.md @@ -152,13 +152,13 @@ In case you are accessing your network using corporate proxies, set the proxies ```bash -export HTTP_PROXY="Required branch" +export HTTP_PROXY="http://:@:/" ``` ```bash -set HTTP_PROXY="Required branch" +set HTTP_PROXY="http://:@:/" ``` diff --git a/docs/smartui-cli-exec.md b/docs/smartui-cli-exec.md new file mode 100644 index 000000000..794db42fb --- /dev/null +++ b/docs/smartui-cli-exec.md @@ -0,0 +1,214 @@ +--- +id: smartui-cli-exec +title: SmartUI CLI Exec Command +sidebar_label: Exec Command +description: Learn how to use SmartUI CLI exec commands to manage snapshot servers and execute tests +keywords: + - Visual Regression + - Visual Regression Testing Guide + - Visual Regression Test Automation + - Visual Regression Automation Testing + - Running Visual Regression Tests + - Visual Regression Testing Online + - Run Visual Regression + - Visual Regression Run Specific Test + - Visual Regression Testing Environment + - How to Run Visual Regression Tests + +url: https://www.lambdatest.com/support/docs/smartui-cli-exec/ +slug: smartui-cli-exec/ +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +SmartUI CLI exec command offers you various options to manage snapshot server and execute your visual testing scripts. This guide will walk you through the available commands and their usage. + +## Prerequisites + +- Basic understanding of Command Line Interface +- SmartUI CLI version 4.0.21 or higher installed for the start, stop and ping commands +- A properly configured SmartUI CLI project + +## Available Commands + +SmartUI CLI offers the following exec commands: + +- `npx smartui exec` - Execute a command with SmartUI server running +- `npx smartui exec:start` - Start the SmartUI snapshot server +- `npx smartui exec:stop` - Stop the SmartUI snapshot server +- `npx smartui exec:ping` - Check if the SmartUI server is running + +## Using the Exec Command + +The `npx smartui exec` command allows you to run your tests with various configuration options. Here's the basic syntax: + +```bash +npx smartui exec [options] -- +``` + +### Available Options + +| Option | Description | +|--------|-------------| +| `-P, --port ` | Specify a custom port number for the server (default: 49152) | +| `--fetch-results [filename]` | Fetch test results and save to a JSON file (default: results.json) | +| `--buildName ` | Specify a custom build name for the test run | +| `--config ` | Specify a configuration file to use | +| `-h, --help` | Display help information | + +### Examples + +1. Running with a custom port: +```bash +npx smartui exec -P 5000 -- npm test +``` + +2. Fetching results with custom filename: +```bash +npx smartui exec --fetch-results custom-results.json -- npm test +``` + +3. Specifying a build name: +```bash +npx smartui exec --buildName "Release-1.0" -- npm test +``` + +4. Using a configuration file: +```bash +npx smartui exec --config smartui-config.json -- npm test +``` + +5. Combining multiple options: +```bash +npx smartui exec -P 5000 --buildName "Release-1.0" --config smartui-config.json --fetch-results -- npm test +``` + +## Starting the Server + +To start the SmartUI snapshot server: + +```bash +npx smartui exec:start +``` + +This will start a local server that handles snapshot requests. By default, the server runs on port 49152. + +## Stopping the Server + +To properly stop the SmartUI snapshot server: + +```bash +npx smartui exec:stop +``` + +> **Important:** It's recommended to use the `exec:stop` command rather than using Ctrl+C to terminate the server. Using Ctrl+C will cause the build to stop after 12 minutes of running. + +## Checking Server Status + +To verify if the SmartUI server is running: + +```bash +npx smartui exec:ping +``` + +## Running Tests with the Server + +### Step 1: Configure Server Address + +For most test frameworks (except Selenium Java and JavaScript), you'll need to set the server address: + + + + +```bash +export SMARTUI_SERVER_ADDRESS='http://localhost:49152' +``` + + + + +```bash +set SMARTUI_SERVER_ADDRESS='http://localhost:49152' +``` + + + + +```bash +$Env:SMARTUI_SERVER_ADDRESS='http://localhost:49152' +``` + + + +### Step 2: Execute Your Tests + +You can run your tests using your preferred test runner: + +```bash +# Using npm +npm test + +# Using Maven +mvn test + +# Using other test runners +your-test-command +``` + +### IDE Configuration + +When running tests from IDEs like IntelliJ: +1. Ensure the `SMARTUI_SERVER_ADDRESS` environment variable is set in your IDE's run configuration +2. Configure the run configuration to use the appropriate test command + +## Taking Snapshots in Scripts + +You can capture snapshots in your test scripts using the SmartUI snapshot method. Here's a basic example: + +```javascript +// JavaScript example +smartui.takeScreenshot("homepage"); + +// With options +smartui.takeScreenshot("homepage", { + fullPage: true, + screenshotName: "custom-name" +}); +``` + + +## Best Practices + +1. Always use `exec:stop` to properly terminate the server +2. Set appropriate timeouts for your tests +3. Use meaningful names for your snapshots +4. Configure environment variables before starting your IDE +5. Consider using configuration files for complex setups + +## Troubleshooting + +If you encounter issues: + +1. Verify the server is running using `exec:ping` +2. Check if the server address is correctly configured +3. Ensure no other process is using the default port +4. Review the server logs for error messages + + \ No newline at end of file diff --git a/docs/smartui-sdk-caps.md b/docs/smartui-sdk-caps.md new file mode 100644 index 000000000..b8a77aa2c --- /dev/null +++ b/docs/smartui-sdk-caps.md @@ -0,0 +1,95 @@ +--- +id: smartui-sdk-capabilities +title: SmartUI SDK Capabilities +sidebar_label: SmartUI SDK Capabilities +description: Learn about the various capabilities available in SmartUI SDK for configuring your visual regression tests +keywords: + - Visual Regression + - SmartUI SDK + - Capabilities + - Configuration + - Visual Testing +url: https://www.lambdatest.com/support/docs/smartui-sdk-capabilities/ +slug: smartui-sdk-capabilities/ +--- + +# SmartUI SDK Capabilities + +SmartUI SDK provides several capabilities that allow you to configure your visual regression tests. These capabilities can be added to your test configuration to control various aspects of the testing process. + +:::warning Important +These capabilities only work when running tests on the LambdaTest Automation Grid. For local test executions, please refer to the standard authentication methods using project token or project name in the [Running your first project](/support/docs/smartui-running-your-first-project//) documentation. +::: + +## Prerequisites + +Before using SmartUI SDK capabilities, ensure you have the following minimum versions installed: + +- SmartUI CLI version >= 4.1.0 +- For Java SDK: SmartUI SDK version >= 1.0.7 +- For JavaScript: Selenium WebDriver version >= 1.0.7 + +## Available Capabilities + +### For JavaScript + +```javascript +let capabilities = { + platform: "catalina", + browserName: "chrome", + version: "latest", + "LT:Options": { + username: USERNAME, + accessKey: KEY, + project: "ElementSS-MobileConfig", + w3c: true, + name: "Test Name", // name of the test + build: "Automation Build Name", // name of the build + // highlight-next-line + "smartUI.project": "YOUR_PROJECT_NAME", + // highlight-next-line + "smartUI.build": "YOUR_BUILD_NAME", + // highlight-next-line + "smartUI.baseline": true, + }, +}; +``` + +### For Java + +```java +DesiredCapabilities capabilities = new DesiredCapabilities(); +capabilities.setCapability("platform", "Windows 10"); +capabilities.setCapability("browserName", "chrome"); +capabilities.setCapability("version", "latest"); + +HashMap ltOptions = new HashMap(); +ltOptions.put("username", "YOUR_USERNAME"); +ltOptions.put("accessKey", "YOUR_ACCESS_KEY"); +ltOptions.put("w3c", true); +ltOptions.put("name", "Test Name"); +ltOptions.put("build", "Automation Build Name"); +// highlight-next-line +ltOptions.put("smartUI.project", "YOUR_PROJECT_NAME"); +// highlight-next-line +ltOptions.put("smartUI.build", "SmartUI_BUILD_NAME"); +// highlight-next-line +ltOptions.put("smartUI.baseline", true); + +capabilities.setCapability("LT:Options", ltOptions); +``` + +## Capability Descriptions + +### smartUI.project +This capability specifies the project Name where your screenshots will be stored and compared. You can add an existing project name or create a new project name. + +### smartUI.build +This capability allows you to group your screenshots into specific builds. This is particularly useful when you want to organize your screenshots and compare them against specific baselines. The build name should be unique and descriptive to help identify the purpose of that particular test run. + +### smartUI.baseline +This boolean capability determines whether the current build should be set as the baseline for future comparisons. When set to `true`, the build will be automatically approved and set as the baseline build. This capability works in conjunction with the [Git branching strategy](/support/docs/smartui-cli-git-branching-strategy/), meaning it will also update the baseline branch accordingly. + +:::info Note +If you need capabilities' support for SDKs other than Selenium Java and JavaScript, please contact support@lambdatest.com. Our team will be happy to assist you with integrating SmartUI capabilities into your preferred testing framework. +::: diff --git a/docs/smartui-selenium-java-sdk.md b/docs/smartui-selenium-java-sdk.md index 5569353f8..8429cfc7a 100644 --- a/docs/smartui-selenium-java-sdk.md +++ b/docs/smartui-selenium-java-sdk.md @@ -90,7 +90,7 @@ git clone https://github.com/LambdaTest/smartui-java-testng-sample io.github.lambdatest lambdatest-java-sdk - 1.0.2 + 1.0.8 ``` diff --git a/sidebars.js b/sidebars.js index 2982d7242..99d881c67 100644 --- a/sidebars.js +++ b/sidebars.js @@ -2838,9 +2838,17 @@ module.exports = { "smart-ui-cypress", "playwright-visual-regression", "puppeteer-visual-regression", - "smartui-k6-setup", + "smartui-k6-setup" + ] + }, + { + type: "category", + collapsed: true, + label: "Visually Test Your Native Apps", + items: [ "appium-visual-regression", - "espresso-visual-regression", + "smartui-app-sdk", + "espresso-visual-regression" ] }, ] @@ -2856,6 +2864,8 @@ module.exports = { "smartui-sdk-config-options", "smartui-multiple-assets-hosts", "smartui-shadow-dom", + "smartui-cli-exec", + "smartui-sdk-capabilities", { type: "category", collapsed: true,