diff --git a/README.md b/README.md index 2f181f3..2b4e698 100644 --- a/README.md +++ b/README.md @@ -1,233 +1,413 @@ -# Run SmartUI Tests With TestNG On LambdaTest +# SmartUI SDK Sample for Selenium Java (TestNG) -![image](https://user-images.githubusercontent.com/70570645/171934563-4806efd2-1154-494c-a01d-1def95657383.png) +Welcome to the SmartUI SDK sample for Selenium Java with TestNG. This repository demonstrates how to integrate SmartUI visual regression testing with Selenium Java using TestNG framework. -

- Blog -   ⋅   - Docs -   ⋅   - Learning Hub -   ⋅   - Newsletter -   ⋅   - Certifications -   ⋅   - YouTube -

-  -  -  +## Repository Structure -_Learn how to use TestNG framework to configure and run your Java automation testing scripts on the LambdaTest platform_ - -[](https://accounts.lambdatest.com/register?utm_source=github&utm_medium=repo&utm_campaign=Java-TestNG-Selenium) - -## Table Of Contents +``` +smartui-java-testng-sample/ +├── src/ +│ └── test/ +│ └── java/ +│ └── com/ +│ └── lambdatest/ +│ └── sdk/ +│ ├── SmartUISDKCloud.java # Cloud test +│ └── SmartUISDKLocal.java # Local test +├── sdk-cloud.xml # TestNG suite for Cloud +├── sdk-local.xml # TestNG suite for Local +├── pom.xml # Maven dependencies +└── smartui-web.json # SmartUI config (create with npx smartui config:create) +``` -- [Pre-requisites](#pre-requisites) -- [Run Your First Test](#run-your-first-test) -- [Parallel Testing With TestNG](#executing-parallel-tests-using-testng) -- [Local Testing With TestNG](#testing-locally-hosted-or-privately-hosted-projects) +## 1. Prerequisites and Environment Setup -## Pre-requisites +### Prerequisites -Before you can start performing Java automation testing with Selenium, you would need to: +- Java JDK 1.6 or higher (latest version recommended) +- Maven 3.6 or higher +- Node.js (for SmartUI CLI) +- LambdaTest account credentials (for Cloud tests) +- Chrome browser (for Local tests) -- Install the latest **Java development environment** i.e. **JDK 1.6** or higher. We recommend using the latest version. +### Environment Setup -- Download the latest **Selenium Client** and its **WebDriver bindings** from the [official website](https://www.selenium.dev/downloads/). Latest versions of Selenium Client and WebDriver are ideal for running your automation script on LambdaTest Selenium cloud grid. +**For Cloud:** +```bash +export LT_USERNAME='your_username' +export LT_ACCESS_KEY='your_access_key' +export PROJECT_TOKEN='your_project_token' +``` -- Install **Maven** which supports **JUnit** framework out of the box. **Maven** can be downloaded and installed following the steps from [the official website](https://maven.apache.org/). Maven can also be installed easily on **Linux/MacOS** using [Homebrew](https://brew.sh/) package manager. +**For Local:** +```bash +export PROJECT_TOKEN='your_project_token' +``` -### Cloning Repo And Installing Dependencies +## 2. Initial Setup and Dependencies -**Step 1:** Clone the LambdaTest’s Java-TestNG-Selenium repository and navigate to the code directory as shown below: +### Clone the Repository ```bash git clone https://github.com/LambdaTest/smartui-java-testng-sample cd smartui-java-testng-sample ``` -You can also run the command below to check for outdated dependencies. +### Install Dependencies + +The repository already includes the required dependencies in `pom.xml`. Build the project to download dependencies: ```bash mvn clean compile ``` -### Setting Up Your Authentication +**Dependencies included:** +- `io.github.lambdatest:lambdatest-java-sdk` - SmartUI SDK for Selenium Java +- `org.testng:testng` - TestNG testing framework +- `org.seleniumhq.selenium:selenium-java` - Selenium WebDriver -Make sure you have your LambdaTest credentials with you to run test automation scripts. You can get these credentials from the [LambdaTest Automation Dashboard](https://automation.lambdatest.com/build?utm_source=github&utm_medium=repo&utm_campaign=Java-TestNG-Selenium) or by your [LambdaTest Profile](https://accounts.lambdatest.com/login?utm_source=github&utm_medium=repo&utm_campaign=Java-TestNG-Selenium). +### Install SmartUI CLI -**Step 2:** Set LambdaTest **Username** and **Access Key** in environment variables. - -- For **Linux/macOS**: - - ```bash - export PROJECT_TOKEN="xxxxx#java-sdk-testing" - export LT_USERNAME="YOUR_USERNAME" - export LT_ACCESS_KEY="YOUR ACCESS KEY" - ``` +```bash +npm i @lambdatest/smartui-cli +``` - - For **Windows**: +### Create SmartUI Configuration - ```bash - set PROJECT_TOKEN="xxxxx#java-sdk-testing" - set LT_USERNAME="YOUR_USERNAME" - set LT_ACCESS_KEY="YOUR ACCESS KEY" - ``` +```bash +npx smartui config:create smartui-web.json +``` -### Execute SmartUI Java Tests using smartui-cli +## 3. Steps to Integrate Screenshot Commands into Codebase +The SmartUI screenshot function is already implemented in the repository. -#### Install the smartui-cli dependencies -```bash -npm i @lambdatest/smartui-cli +**Cloud Test** (`src/test/java/com/lambdatest/sdk/SmartUISDKCloud.java`): +```java +driver.get("https://www.lambdatest.com"); +SmartUISnapshot.smartuiSnapshot(driver, "screenshot"); ``` -#### Create and Configure SmartUI Config -```bash -npx smartui config:create smartui-web.json +**Local Test** (`src/test/java/com/lambdatest/sdk/SmartUISDKLocal.java`): +```java +driver.get("https://www.lambdatest.com"); +SmartUISnapshot.smartuiSnapshot(driver, "screenshot"); ``` -#### Use Local Hub +**Note**: The code is already configured and ready to use. You can modify the URL and screenshot name if needed. + +## 4. Execution and Commands + +### Local Execution + ```bash npx smartui exec -- mvn test -D suite=sdk-local.xml ``` -#### Use Lambdatest Cloud Hub +### Cloud Execution + ```bash npx smartui exec -- mvn test -D suite=sdk-cloud.xml ``` -Your test results would be displayed on the test console (or command-line interface if you are using terminal/cmd) and on SmartUI dashboard. +## Test Files + +### Cloud Test (`SmartUISDKCloud.java`) + +- Connects to LambdaTest Cloud using Selenium Remote WebDriver +- Reads credentials from environment variables (`LT_USERNAME`, `LT_ACCESS_KEY`) +- Uses TestNG framework +- Takes screenshot with name: `screenshot` + +### Local Test (`SmartUISDKLocal.java`) + +- Runs Selenium locally using Chrome +- Requires Chrome browser installed +- Uses TestNG framework +- Takes screenshot with name: `screenshot` + +## Configuration + +### Maven Config (`pom.xml`) + +The Maven configuration file includes all necessary dependencies for SmartUI and TestNG. -### Executing SmartUI Test on Lambdatest Hub without smartui-cli +### TestNG Suites -The tests can be executed in the terminal using the following command. +- `sdk-cloud.xml` - TestNG suite for Cloud execution +- `sdk-local.xml` - TestNG suite for Local execution +### SmartUI Config (`smartui-web.json`) + +Create the SmartUI configuration file using: ```bash -mvn test -D suite=smartui.xml +npx smartui config:create smartui-web.json ``` -Your test results would be displayed on the test console (or command-line interface if you are using terminal/cmd) and on LambdaTest automation dashboard. - -## Run Parallel SmartUI Tests Using TestNG +## Parallel Testing -### Executing Parallel Tests Using TestNG +To run parallel tests using TestNG: -To run parallel tests using **TestNG**, we would have to execute the below commands in the terminal: ```bash mvn test -D suite=smartui-parallel.xml ``` -### Execute SmartUI Real Device Tests +## Testing Locally Hosted Projects -The tests can be executed in the terminal using the following command. +You can test locally hosted or privately hosted projects with LambdaTest Selenium grid using LambdaTest Tunnel. Refer to the [LambdaTest Tunnel documentation](https://www.lambdatest.com/support/docs/testing-locally-hosted-pages/) for more information. -```bash -mvn test -D suite=smartui-mobile.xml +## Best Practices + +### Screenshot Naming + +- Use descriptive, unique names for each screenshot +- Include test context and state (e.g., `homepage-logged-in`, `checkout-step-2`) +- Follow Java naming conventions (camelCase) +- Avoid special characters + +### When to Take Screenshots + +- After critical user interactions +- Before and after form submissions +- At different stages of multi-step processes +- After page state changes + +### Java-Specific Tips + +- Use explicit waits before taking screenshots +- Handle exceptions properly +- Use TestNG annotations for better test organization +- Leverage TestNG groups for parallel execution + +### Example: Screenshot with Waits + +```java +WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10)); +wait.until(ExpectedConditions.presenceOfElementLocated(By.id("main-content"))); +SmartUISnapshot.smartuiSnapshot(driver, "homepage"); +``` + +## Common Use Cases + +### Multi-Step Flow Testing + +```java +@Test +public void testCheckoutFlow() { + driver.get("https://example.com/checkout"); + SmartUISnapshot.smartuiSnapshot(driver, "checkout-step-1"); + + driver.findElement(By.id("next-step")).click(); + WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(5)); + wait.until(ExpectedConditions.elementToBeClickable(By.id("complete"))); + SmartUISnapshot.smartuiSnapshot(driver, "checkout-step-2"); +} ``` -## Testing Locally Hosted Or Privately Hosted Projects +### Conditional Screenshots -You can test your locally hosted or privately hosted projects with LambdaTest Selenium grid using LambdaTest Tunnel. All you would have to do is set up an SSH tunnel using tunnel and pass toggle `tunnel = True` via desired capabilities. LambdaTest Tunnel establishes a secure SSH protocol based tunnel that allows you in testing your locally hosted or privately hosted pages, even before they are live. +```java +@Test +public void testConditionalScreenshot() { + driver.get("https://example.com"); + + List userMenu = driver.findElements(By.className("user-menu")); + if (!userMenu.isEmpty()) { + SmartUISnapshot.smartuiSnapshot(driver, "homepage-logged-in"); + } else { + SmartUISnapshot.smartuiSnapshot(driver, "homepage-guest"); + } +} +``` -Refer our [LambdaTest Tunnel documentation](https://www.lambdatest.com/support/docs/testing-locally-hosted-pages/?utm_source=github&utm_medium=repo&utm_campaign=Java-TestNG-Selenium) for more information. +## CI/CD Integration + +### GitHub Actions Example + +```yaml +name: Java SmartUI Tests + +on: [push, pull_request] + +jobs: + visual-tests: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + + - name: Setup Java + uses: actions/setup-java@v3 + with: + java-version: '17' + distribution: 'temurin' + + - name: Setup Node.js + uses: actions/setup-node@v3 + with: + node-version: '18' + + - name: Install SmartUI CLI + run: npm install -g @lambdatest/smartui-cli + + - name: Build with Maven + run: mvn clean compile + + - name: Run SmartUI tests + env: + PROJECT_TOKEN: ${{ secrets.SMARTUI_PROJECT_TOKEN }} + LT_USERNAME: ${{ secrets.LT_USERNAME }} + LT_ACCESS_KEY: ${{ secrets.LT_ACCESS_KEY }} + run: | + npx smartui exec -- mvn test -D suite=sdk-cloud.xml +``` -Here’s how you can establish LambdaTest Tunnel. +### Jenkins Pipeline Example + +```groovy +pipeline { + agent any + + tools { + maven 'Maven-3.8' + jdk 'JDK-17' + } + + environment { + PROJECT_TOKEN = credentials('smartui-project-token') + LT_USERNAME = credentials('lambdatest-username') + LT_ACCESS_KEY = credentials('lambdatest-access-key') + } + + stages { + stage('Build') { + steps { + sh 'mvn clean compile' + } + } + + stage('Visual Tests') { + steps { + sh 'npm install -g @lambdatest/smartui-cli' + sh 'npx smartui exec -- mvn test -D suite=sdk-cloud.xml' + } + } + } +} +``` -Download the binary file of: +## Troubleshooting -- [LambdaTest Tunnel for Windows](https://downloads.lambdatest.com/tunnel/v3/windows/64bit/LT_Windows.zip) -- [LambdaTest Tunnel for macOS](https://downloads.lambdatest.com/tunnel/v3/mac/64bit/LT_Mac.zip) -- [LambdaTest Tunnel for Linux](https://downloads.lambdatest.com/tunnel/v3/linux/64bit/LT_Linux.zip) +### Issue: `Error: SmartUI Config already exists: smartui-web.json` -Open command prompt and navigate to the binary folder. +**Solution**: This is informational. The config file already exists. You can proceed or delete and recreate it. -Run the following command: +### Issue: `PROJECT_TOKEN is required` +**Solution**: Ensure the environment variable is set: ```bash -LT -user {user’s login email} -key {user’s access key} +export PROJECT_TOKEN='your_project_token' +# Verify +echo $PROJECT_TOKEN ``` -So if your user name is lambdatest@example.com and key is 123456, the command would be: +### Issue: `Could not find or load main class` +**Solution**: Build the project first: ```bash -LT -user lambdatest@example.com -key 123456 +mvn clean compile ``` -Once you are able to connect **LambdaTest Tunnel** successfully, you would just have to pass on tunnel capabilities in the code shown below : +### Issue: `ChromeDriver version mismatch` (Local) -**Tunnel Capability** +**Solution**: +1. Update ChromeDriver in `pom.xml` +2. Ensure Chrome browser is up to date +3. Use WebDriverManager for automatic driver management -```java -DesiredCapabilities capabilities = new DesiredCapabilities(); - capabilities.setCapability("tunnel", true); -``` +### Issue: `Unauthorized` error (Cloud) -## Tutorials 📙 +**Solution**: +1. Verify `LT_USERNAME` and `LT_ACCESS_KEY` are set correctly +2. Check credentials in [LambdaTest Profile Settings](https://accounts.lambdatest.com/profile) +3. Ensure no extra spaces in environment variables -Check out our latest tutorials on TestNG automation testing 👇 +### Issue: TestNG suite not found -- [JUnit 5 vs TestNG: Choosing the Right Framework for Automation Testing](https://www.lambdatest.com/blog/junit-5-vs-testng/?utm_source=github&utm_medium=repo&utm_campaign=Java-TestNG-Selenium) -- [How To Install TestNG?](https://www.lambdatest.com/blog/how-to-install-testng-in-eclipse-step-by-step-guide/?utm_source=github&utm_medium=repo&utm_campaign=Java-TestNG-Selenium) -- [Create TestNG Project in Eclipse & Run Selenium Test Script](https://www.lambdatest.com/blog/create-testng-project-in-eclipse-run-selenium-test-script/?utm_source=github&utm_medium=repo&utm_campaign=Java-TestNG-Selenium) -- [A Complete Guide for Your First TestNG Automation Script](https://www.lambdatest.com/blog/a-complete-guide-for-your-first-testng-automation-script/?utm_source=github&utm_medium=repo&utm_campaign=Java-TestNG-Selenium) -- [How to Automate using TestNG in Selenium?](https://www.lambdatest.com/blog/testng-in-selenium/?utm_source=github&utm_medium=repo&utm_campaign=Java-TestNG-Selenium) -- [How to Perform Parallel Test Execution in TestNG with Selenium](https://www.lambdatest.com/blog/parallel-test-execution-in-testng/?utm_source=github&utm_medium=repo&utm_campaign=Java-TestNG-Selenium) -- [Creating TestNG XML File & Execute Parallel Testing](https://www.lambdatest.com/blog/create-testng-xml-file-execute-parallel-testing/?utm_source=github&utm_medium=repo&utm_campaign=Java-TestNG-Selenium) -- [Speed Up Automated Parallel Testing in Selenium with TestNG](https://www.lambdatest.com/blog/speed-up-automated-parallel-testing-in-selenium-with-testng/?utm_source=github&utm_medium=repo&utm_campaign=Java-TestNG-Selenium) -- [Automation Testing With Selenium, Cucumber & TestNG](https://www.lambdatest.com/blog/automation-testing-with-selenium-cucumber-testng/?utm_source=github&utm_medium=repo&utm_campaign=Java-TestNG-Selenium) -- [How to Run JUnit Selenium Tests using TestNG](https://www.lambdatest.com/blog/test-example-junit-and-testng-in-selenium/?utm_source=github&utm_medium=repo&utm_campaign=Java-TestNG-Selenium) -- [How to Group Test Cases in TestNG [With Examples]](https://www.lambdatest.com/blog/grouping-test-cases-in-testng/?utm_source=github&utm_medium=repo&utm_campaign=Java-TestNG-Selenium) -- [How to Set Test Case Priority in TestNG with Selenium](https://www.lambdatest.com/blog/prioritizing-tests-in-testng-with-selenium/?utm_source=github&utm_medium=repo&utm_campaign=Java-TestNG-Selenium) -- [How to Use Assertions in TestNG with Selenium](https://www.lambdatest.com/blog/asserts-in-testng/?utm_source=github&utm_medium=repo&utm_campaign=Java-TestNG-Selenium) -- [How to Use DataProviders in TestNG [With Examples]](https://www.lambdatest.com/blog/how-to-use-dataproviders-in-testng-with-examples/?utm_source=github&utm_medium=repo&utm_campaign=Java-TestNG-Selenium) -- [Parameterization in TestNG - DataProvider and TestNG XML [With Examples]](https://www.lambdatest.com/blog/parameterization-in-testng-dataprovider-and-testng-xml-examples/?utm_source=github&utm_medium=repo&utm_campaign=Java-TestNG-Selenium) -- [TestNG Listeners in Selenium WebDriver [With Examples]](https://www.lambdatest.com/blog/testng-listeners-in-selenium-webdriver-with-examples/?utm_source=github&utm_medium=repo&utm_campaign=Java-TestNG-Selenium) -- [TestNG Annotations Tutorial with Examples for Selenium Automation](https://www.lambdatest.com/blog/complete-guide-on-testng-annotations-for-selenium-webdriver/?utm_source=github&utm_medium=repo&utm_campaign=Java-TestNG-Selenium) -- [How to Use TestNG Reporter Log in Selenium](https://www.lambdatest.com/blog/how-to-use-testng-reporter-log-in-selenium/?utm_source=github&utm_medium=repo&utm_campaign=Java-TestNG-Selenium) -- [How to Generate TestNG Reports in Jenkins](https://www.lambdatest.com/blog/how-to-generate-testng-reports-in-jenkins/?utm_source=github&utm_medium=repo&utm_campaign=Java-TestNG-Selenium) +**Solution**: Verify the suite XML file exists and path is correct: +```bash +ls -la sdk-*.xml +mvn test -D suite=sdk-cloud.xml +``` -## Documentation & Resources :books: +## Configuration Tips -Visit the following links to learn more about LambdaTest's features, setup and tutorials around test automation, mobile app testing, responsive testing, and manual testing. +### TestNG Suite Configuration -- [LambdaTest Documentation](https://www.lambdatest.com/support/docs/?utm_source=github&utm_medium=repo&utm_campaign=Java-TestNG-Selenium) -- [LambdaTest Blog](https://www.lambdatest.com/blog/?utm_source=github&utm_medium=repo&utm_campaign=Java-TestNG-Selenium) -- [LambdaTest Learning Hub](https://www.lambdatest.com/learning-hub/?utm_source=github&utm_medium=repo&utm_campaign=Java-TestNG-Selenium) +**For Cloud** (`sdk-cloud.xml`): +```xml + + + + + + + +``` -## LambdaTest Community :busts_in_silhouette: +**For Local** (`sdk-local.xml`): +```xml + + + + + + + +``` -The [LambdaTest Community](https://community.lambdatest.com/?utm_source=github&utm_medium=repo&utm_campaign=Java-TestNG-Selenium) allows people to interact with tech enthusiasts. Connect, ask questions, and learn from tech-savvy people. Discuss best practises in web development, testing, and DevOps with professionals from across the globe 🌎 +### Maven Configuration Tips -## What's New At LambdaTest ❓ +Add to `pom.xml` for better dependency management: +```xml + + 17 + 17 + UTF-8 + +``` -To stay updated with the latest features and product add-ons, visit [Changelog](https://changelog.lambdatest.com) +## Parallel Testing -## About LambdaTest +### Running Parallel Tests -[LambdaTest](https://www.lambdatest.com/?utm_source=github&utm_medium=repo&utm_campaign=Java-TestNG-Selenium) is a leading test execution and orchestration platform that is fast, reliable, scalable, and secure. It allows users to run both manual and automated testing of web and mobile apps across 3000+ different browsers, operating systems, and real device combinations. Using LambdaTest, businesses can ensure quicker developer feedback and hence achieve faster go to market. Over 500 enterprises and 1 Million + users across 130+ countries rely on LambdaTest for their testing needs. +```bash +mvn test -D suite=smartui-parallel.xml +``` -### Features +Configure parallel execution in TestNG suite XML: +```xml + + + + + + + + +``` -- Run Selenium, Cypress, Puppeteer, Playwright, and Appium automation tests across 3000+ real desktop and mobile environments. -- Real-time cross browser testing on 3000+ environments. -- Test on Real device cloud -- Blazing fast test automation with HyperExecute -- Accelerate testing, shorten job times and get faster feedback on code changes with Test At Scale. -- Smart Visual Regression Testing on cloud -- 120+ third-party integrations with your favorite tool for CI/CD, Project Management, Codeless Automation, and more. -- Automated Screenshot testing across multiple browsers in a single click. -- Local testing of web and mobile apps. -- Online Accessibility Testing across 3000+ desktop and mobile browsers, browser versions, and operating systems. -- Geolocation testing of web and mobile apps across 53+ countries. -- LT Browser - for responsive testing across 50+ pre-installed mobile, tablets, desktop, and laptop viewports +## View Results -[](https://accounts.lambdatest.com/register?utm_source=github&utm_medium=repo&utm_campaign=Java-TestNG-Selenium) +After running the tests, visit your SmartUI project dashboard to view the captured screenshots and compare them with baseline builds. -## We are here to help you :headphones: +## Additional Resources -- Got a query? we are available 24x7 to help. [Contact Us](mailto:support@lambdatest.com) -- For more info, visit - [LambdaTest](https://www.lambdatest.com?utm_source=github&utm_medium=repo&utm_campaign=Java-TestNG-Selenium) +- [SmartUI Selenium Java Onboarding Guide](https://www.lambdatest.com/support/docs/smartui-onboarding-selenium-java/) +- [LambdaTest Selenium Java Documentation](https://www.lambdatest.com/support/docs/selenium-java/) +- [TestNG Documentation](https://testng.org/doc/documentation-main.html) +- [Maven Documentation](https://maven.apache.org/guides/) +- [SmartUI Dashboard](https://smartui.lambdatest.com/) +- [LambdaTest Automation Dashboard](https://automation.lambdatest.com/) +- [LambdaTest Community](https://community.lambdatest.com/) +- [LambdaTest Blog](https://www.lambdatest.com/blog/) +- [LambdaTest Learning Hub](https://www.lambdatest.com/learning-hub/) diff --git a/smartui-web.json b/smartui-web.json new file mode 100644 index 0000000..ba4a344 --- /dev/null +++ b/smartui-web.json @@ -0,0 +1,27 @@ +{ + "web": { + "browsers": [ + "chrome", + "firefox", + "safari", + "edge" + ], + "viewports": [ + [1920, 1080], + [1366, 768], + [360, 640] + ], + "waitForPageRender": 50000 + }, + "mobile": { + "devices": [ + "iPhone 14", + "Galaxy S24" + ], + "fullPage": true, + "orientation": "portrait" + }, + "waitForTimeout": 1000, + "enableJavaScript": false, + "allowedHostnames": [] +}