diff --git a/docs/smartui-playwright-java-sdk.md b/docs/smartui-playwright-java-sdk.md new file mode 100644 index 000000000..81620d2ca --- /dev/null +++ b/docs/smartui-playwright-java-sdk.md @@ -0,0 +1,461 @@ +--- +id: smartui-playwright-java-sdk +title: Integrate SmartUI SDK with Playwright - Java +sidebar_label: Java +description: In this documentation, learn how integrate your Playwright Java automated tests with LambdaTest's SmartUI. +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-playwright-java-sdk/ +slug: smartui-playwright-java-sdk/ +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import NewTag from '../src/component/newTag'; +import CodeBlock from '@theme/CodeBlock'; +import {YOUR_LAMBDATEST_USERNAME, YOUR_LAMBDATEST_ACCESS_KEY} from "@site/src/component/keys"; + + +The SmartUI SDK is a powerful tool that simplifies the process of capturing, comparing, and analyzing screenshots across multiple browsers and resolutions. By combining the strengths of Playwright's automation capabilities with SmartUI's visual testing features, you can: + +- Ensure your application's UI is consistent across all supported environments. +- Detect and address visual discrepancies early in the development lifecycle. +- Streamline your testing process with minimal setup and maximum coverage. + +This documentation provides step-by-step instructions for developers and QA engineers to integrate the SmartUI SDK with Playwright-Java, enabling reliable and efficient visual regression testing. + +## Prerequisites + +- Basic understanding of Command Line Interface and Playwright is required. +- Login to [LambdaTest SmartUI](https://smartui.lambdatest.com/) with your credentials. + +## Steps to run your first test +Follow these steps to successfully run your first visual regression test on the LambdaTest platform with the SmartUI Playwright SDK integration. + +### Step 1: Create a SmartUI Project + +The first step is to create a project with the application in which we will combine all your builds run on the project. To create a SmartUI Project, follow these steps: + +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, tags for any filter or easy navigation. +5. Click on the **Submit**. + +### Step 2: Configure Your Test Suite + +You can use your own project to configure and test it. For demo purposes, we are using the sample repository. + +:::tip Sample repo +Download or Clone the code sample for the Java from the LambdaTest GitHub repository to run the tests on the SmartUI. + +Image View on GitHub +::: + +### Step 3: Install the Dependencies + +Update your dependencies in `pom.xml` file Install required modules for LambdaTest Smart UI SDK in your frontend project. + +```bash +npm i @lambdatest/smartui-cli @lambdatest/playwright-driver playwright +mvn clean compile +``` + +### Step 4: Setup your credentials + + + + + +
+ + {`export LT_USERNAME="${ YOUR_LAMBDATEST_USERNAME()}" +export LT_ACCESS_KEY="${ YOUR_LAMBDATEST_ACCESS_KEY()}" +export PROJECT_TOKEN="123456#1234abcd-****-****-****-************"`} + +
+ + + + + +
+ + {`set LT_USERNAME="${ YOUR_LAMBDATEST_USERNAME()}" +set LT_ACCESS_KEY="${ YOUR_LAMBDATEST_ACCESS_KEY()}" +set PROJECT_TOKEN="123456#1234abcd-****-****-****-************"`} + +
+ + + + + +
+ + {`$Env:LT_USERNAME="${ YOUR_LAMBDATEST_USERNAME()}" +$Env:LT_ACCESS_KEY="${ YOUR_LAMBDATEST_ACCESS_KEY()}" +$Env:PROJECT_TOKEN="123456#1234abcd-****-****-****-************"`} + + +
+ + + + + + +cmd + + +### Step 5: Create and Configure SmartUI Config + +You can now configure your project configurations on using various available options to run your tests with the SmartUI integration. To generate the configuration file, please execute the following command: + +```bash +npx smartui config:create smartui-web.json +``` + +Once, the configuration file will be created, you will be seeing the default configuration pre-filled in the configuration file: + +```json title="/smartui-sdk-project/.smartui.json" +{ + "web": { + "browsers": [ + "chrome", + "firefox", + "safari", + "edge" + ], + "viewports": [ + [ + 1920 + ], + [ + 1366 + ], + [ + 1028 + ] + ] // Full Page screenshots are captured by default for web viewports + }, + "mobile": { + "devices": [ + "iPhone 14", //iPhone 14 viewport + "Galaxy S24" //Galaxy S24 viewport + ], + "fullPage": true, //Full Page is true by default for mobile viewports + "orientation": "portrait" //Change to "landscape" for landscape snapshot + }, + "waitForTimeout": 1000, //Optional (Should only be used in case lazy-loading/async components are present) + "waitForPageRender": 50000, //Optional (Should only be used in case of websites which take more than 30s to load) + "enableJavaScript": false, //Enable javascript for all the screenshots of the project + "allowedHostnames": [] //Additional hostnames to capture assets from +} +``` +:::info Advanced options in SmartUI configuration +- For capturing fullpage or viewport screenshots, please refer to this [documentation](/docs/smartui-sdk-config-options/#12-viewports) +- For the list of available mobile viewports, please refer to this [documentation](/docs/smartui-sdk-config-options/#list-of-supported-device-viewports) +- For more information about SmartUI config global options, please refer to this [documentation](/docs/smartui-sdk-config-options/#3-global-options-optional). +::: + +### Step 6: Adding SmartUI function to take screenshot +You can incorporate SmartUI into your custom `Playwright` automation test (any platform) script by adding the `smartuiSnapshot` function in the required segment of Playwright script of which we would like to take the screenshot, as shown below: + +```java reference +https://github.com/LambdaTest/smartui-java-playwright-sample/blob/main/src/test/java/com/lambdatest/SmartUISDKPlaywrightCloud.java +``` + +### Step 6: Execute the Tests on SmartUI Cloud + +Execute visual regression tests on SmartUI using the following commands + +```bash +npx smartui exec -- mvn test -D suite=sdk-playwright-local-java.xml +``` + +:::note +You may use the `npx smartui --help` command in case you are facing issues during the execution of SmartUI commands in the CLI. +::: + +## View SmartUI Results + +You have successfully integrated SmartUI SDK with your Playwright tests. Visit your SmartUI project to view builds and compare snapshots between different test runs. + +You can see the Smart UI dashboard to view the results. This will help you identify the Mismatches from the existing `Baseline` build and do the required visual testing. + + +cmd + +## Arguments supported in the `smartUISnapshot` function + +The following are the different options which are currently supported: + +| Key | Description | +| ------------------------- | ------------------------------------------------------------------------------------------------------------------------- | +| `page` (instance) | The instance of page used in your tests. | +| `"Screenshot Name"` (string) | Specify a name for the screenshot in your tests to match the same screenshot with the name from your baseline. | +| `options` (object) | Specify one or a combination of selectors in the `ignoreDOM` or `selectDOM` objects. These selectors can be based on `HTML DOM IDs, CSS classes, CSS selectors, or XPaths` used by your webpage. They define elements that should be excluded from or included in the visual comparison.| + + +## Handling Dynamic Data in SmartUI SDK **** + +When conducting visual tests, you may encounter scenarios where certain elements within your application change between test runs. These changes might introduce inconsistencies in your test results.You can ignore / select specific element(s) to be removed from the comparison by parsing the options in the `smartuiSnapshot` function in the following way + + + + + +```js title="This is a sample for your configuration for Playwright to ignore by ID" +let options = { + ignoreDOM: { + id: ["ID-1", "ID-2"], + } + } + await page.goto('Required URL'); + await smartuiSnapshot.smartuiSnapshot(page, "Screenshot Name", options); +``` + + + + +```js title="This is a sample for your configuration for Playwright to ignore by Class" +let options = { + ignoreDOM: { + class: ["Class-1", "Class-2"], + } + } + await page.goto('Required URL'); + await smartuiSnapshot.smartuiSnapshot(page, "Screenshot Name", options); +``` + + + + +```js title="This is a sample for your configuration for Playwright to ignore by XPath" +let options = { + ignoreDOM: { + xpath: ["Xpath-1", "Xpath-2"], + } + } + await page.goto('Required URL'); + await smartuiSnapshot.smartuiSnapshot(page, "Screenshot Name", options); +``` + + + + + +```js title="This is a sample for your configuration for Playwright to ignore by CSS Selector" +let options = { + ignoreDOM: { + cssSelector: ["CSS-Selector-1", "CSS-Selector-2"], + } + } + await page.goto('Required URL'); + await smartuiSnapshot.smartuiSnapshot(page, "Screenshot Name", options); +``` + + + + + + + +```js title="This is a sample for your configuration for Playwright to select by ID." +let options = { + selectDOM: { + id: ["ID-1", "ID-2"], + } + } + await page.goto('Required URL'); + await smartuiSnapshot.smartuiSnapshot(page, "Screenshot Name", options); +``` + + + + +```js title="This is a sample for your configuration for Playwright to select by Class" +let options = { + selectDOM: { + class: ["Class-1", "Class-2"], + } + } + await page.goto('Required URL'); + await smartuiSnapshot.smartuiSnapshot(page, "Screenshot Name", options); +``` + + + + +```js title="This is a sample for your configuration for Playwright to select by XPath" +let options = { + selectDOM: { + xpath: ["Xpath-1", "Xpath-2"], + } + } + await page.goto('Required URL'); + await smartuiSnapshot.smartuiSnapshot(page, "Screenshot Name", options); +``` + + + + + +```js title="This is a sample for your webhook configuration for Playwright to select by CSS Selector" +let options = { + selectDOM: { + cssSelector: ["CSS-Selector-1", "CSS-Selector-2"], + } + } + await page.goto('Required URL'); + await smartuiSnapshot.smartuiSnapshot(page, "Screenshot Name", options); +``` + + + + +## For capturing the screenshot of a specific element + +You can capture screenshots of targeted elements by leveraging various locator mechanisms such as XPath, CSS ID, class, and selectors. This precision-driven approach ensures accurate and specific visual regression testing for your web application's components. + + + + + +```js title="This is a sample for your configuration for Playwright to capture an element by ID." +let options = { + element: { + id: 'Required ID', + } + }; + await page.goto('Required URL'); + await smartuiSnapshot.smartuiSnapshot(page, "Screenshot Name", options); +``` + + + + +```js title="This is a sample for your configuration for Playwright to capture an element by Class" +let options = { + element: { + class: 'Required Class', + } + }; + await page.goto('Required URL'); + await smartuiSnapshot.smartuiSnapshot(page, "Screenshot Name", options); +``` + + + + +```js title="This is a sample for your configuration for Playwright to capture an element by XPath" +let options = { + element: { + xpath: 'Required Xpath', + } + }; + await page.goto('Required URL'); + await smartuiSnapshot.smartuiSnapshot(page, "Screenshot Name", options); +``` + + + + + +```js title="This is a sample for your webhook configuration for Playwright to capture an element by CSS Selector" +let options = { + element: { + cssSelector: 'Required CSS Selector', + } + }; + await page.goto('Required URL'); + await smartuiSnapshot.smartuiSnapshot(page, "Screenshot Name", options); +``` + + + + +## For capturing interactive lazy loading elements + +If you encounter difficulties loading interactive elements that appear on scroll in full-page screenshots, consider functionally incorporating a full-page scroll into your script before capturing the screenshot. This approach ensures the elements load first, facilitating the screenshot processing. + +```js Example for scrolling to bottom for lazy elements +const { chromium } = require('playwright'); +const smartuiSnapshot = require('@lambdatest/playwright-driver'); + +(async () => { + const browser = await chromium.launch({ headless: false }); // Set headless: false to see the browser UI + const page = await browser.newPage(); + + try { + await page.goto('Required URL'); + + // Function to scroll to the bottom of the page + async function quickScrollToBottom(lastPageWait) { + await page.evaluate(async (lastPageWait) => { + const scrollToBottom = async (lastPageWait) => { + const getScrollHeight = () => document.body.scrollHeight; + let lastHeight = await getScrollHeight(); + let currentHeight = 0; + + while (currentHeight < lastHeight) { + window.scrollTo(0, lastHeight); + await new Promise(resolve => setTimeout(resolve, 1000)); // Wait for page to load + currentHeight = lastHeight; + lastHeight = await getScrollHeight(); + } + + if (lastPageWait) { + await new Promise(resolve => setTimeout(resolve, lastPageWait)); // Additional wait at the bottom + } + + // Scroll back to the top after reaching the bottom + window.scrollTo(0, 0); + await new Promise(resolve => setTimeout(resolve, 1000)); // Wait for scroll to top + }; + + await scrollToBottom(lastPageWait); + }, lastPageWait); + } + + await quickScrollToBottom(100); // Adjust wait time as needed + await smartuiSnapshot.smartuiSnapshot(page, "Screenshot Name"); + + } finally { + await browser.close(); + } +})(); +``` \ No newline at end of file diff --git a/docs/smartui-playwright-python-sdk.md b/docs/smartui-playwright-python-sdk.md index cbc5d2aa3..3b0a06b64 100644 --- a/docs/smartui-playwright-python-sdk.md +++ b/docs/smartui-playwright-python-sdk.md @@ -15,7 +15,7 @@ keywords: - Visual Regression Testing Environment - How to Run Visual Regression Tests -url: https://www.lambdatest.com/support/docs/smartui-cli/ +url: https://www.lambdatest.com/support/docs/smartui-playwright-python-sdk/ slug: smartui-playwright-python-sdk/ --- @@ -23,8 +23,6 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import NewTag from '../src/component/newTag'; ---- -