From eba143fff0ea41d56a5d8026c5f8bada4aa48719 Mon Sep 17 00:00:00 2001 From: Kerem Beygo Date: Wed, 23 Oct 2024 15:15:26 +0200 Subject: [PATCH 1/7] sauce visual espresso docs --- docs/visual-testing/integrations/espresso.md | 252 +++++++++++++++++++ 1 file changed, 252 insertions(+) create mode 100644 docs/visual-testing/integrations/espresso.md diff --git a/docs/visual-testing/integrations/espresso.md b/docs/visual-testing/integrations/espresso.md new file mode 100644 index 0000000000..63a6e35ab9 --- /dev/null +++ b/docs/visual-testing/integrations/espresso.md @@ -0,0 +1,252 @@ +--- +sidebar_label: Espresso +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import ClippingDescription from '../_partials/_clipping-description.md'; +import FullPageLimit from '../_partials/_fullpage-limit.md'; +import EnvironmentVariables from '../_partials/_environment-variables.md'; +import SelectiveDiffing from '../_partials/_selective-diffing.md'; +import SelectiveDiffingGlobal from '../_partials/_selective-diffing-global.md'; +import SelectiveDiffingRegion from '../_partials/_selective-diffing-region.md'; + +# Espresso Integration + +## Introduction + +This guide requires an existing Android JUnit setup. + +You can alternatively take a look to our [example repository](#examples). + +Sauce Visual Espresso plugin provides a library exposing a `VisualClient` object that provides the method +`sauceVisualCheck()` to take a screenshot and send it to Sauce Visual for comparison. + +## Quickstart + +### Step 1: Add Sauce Visual dependency + +Add [Sauce Visual](https://central.sonatype.com/artifact/com.saucelabs.visual/visual-espresso) dependency to your build.gradle + +```groovy reference +https://github.com/saucelabs/visual-examples/blob/main/espresso/app/build.gradle#L106 +``` + +_Note: You can find the latest versions available [here](https://central.sonatype.com/artifact/com.saucelabs.visual/visual-espresso)._ + +### Step 2: Configure Visual Testing integration + +Declare a VisualClient instance as class variable + +```java +import com.saucelabs.visual.VisualClient; + +static VisualClient visual = VisualClient.builder(sauceUsername, sauceAccessKey) + .buildName("Sauce Demo Test") + .build();; +``` + +To enhance efficiency in managing tests, it's important to provide a specific test name and suite name for each test. This practice allows Sauce Visual to effectively organize snapshots into coherent groups. As a result, it simplifies the review process, saving time and effort in navigating through test results and understanding the context of each snapshot. + +Moreover, our Espresso binding offers an automated solution to this process. By integrating the following code snippet into your tests, the Java Binding can automatically assign appropriate test names and suite names, streamlining your testing workflow. + +```java +import com.saucelabs.visual.junit.TestMetaInfoRule; + +import org.junit.Rule; + +public class MyJunitTestClass { + + @Rule + public TestMetaInfoRule testMetaInfoRule = new TestMetaInfoRule(); +} +``` + +Don't forget to finish the build + +```java +import org.junit.AfterClass; + +@AfterClass +public static void tearDown() { + if (visual != null) { + visual.finish(); + } +} +``` + +### Step 3: Add visual tests in your tests + +Add a check to one of your tests: + + +```java +import org.junit.Test; + +@Test +void checkAppCatalog() { + + visual.sauceVisualCheck("Before Login"); +} +``` + +### Step 4: Configure your Sauce Labs credentials + +Sauce Visual Espresso expects Sauce Labs username and access key to be passed when initiating the client. +It's recommended to define and pass your Sauce Labs credentials to `VisualClient` as custom `BuildConfig` fields. + +```groovy +android { + buildConfigField "String", "SAUCE_USERNAME", "YOUR_SAUCE_USERNAME" + buildConfigField "String", "SAUCE_ACCESS_KEY", "YOUR_SAUCE_ACCESS_KEY" + } +``` +Username and Access Key can be retrieved from https://app.saucelabs.com/user-settings. + +```java +import com.saucelabs.visual.VisualClient; + +static VisualClient visualClient = VisualClient.builder( + BuildConfig.SAUCE_USERNAME, + BuildConfig.SAUCE_ACCESS_KEY) + .buildName("Espresso Basic Sample") + .build(); +``` + +### Step 5: Run the test + +Upon executing your tests for the first time under this step, a visual baseline is automatically created in our system. This baseline serves as the standard for all subsequent WebDriver tests. As new tests are run, they are compared to this original baseline, with any deviations highlighted to signal visual changes. These comparisons are integral for detecting any unintended visual modifications early in your development cycle. All test builds, including the initial baseline and subsequent runs, can be monitored and managed through the Sauce Labs platform at [Sauce Visual Builds](https://app.saucelabs.com/visual/builds). + +Remember, the baseline is established during the initial run, and any subsequent visual differences detected will be marked for review. + +## Advanced usage + +### Customizing Your Build Lifecycle + +Following builder methods are available for `VisualClient` if you'd like to manage your build lifecyle externally. + +- `buildId(String buildId)`: For advanced users, a user-supplied Sauce Labs Visual build ID. Can be used to create builds in advance using the GraphQL API or CLI tool. This can be used to parallelize tests with multiple browsers, shard, or more. By default, this is not set and we create / finish a build during setup / teardown. +- `customId(String customId)`: For advanced users, a user-supplied custom ID to identify this build. Can be used in CI to identify / check / re-check the status of a single build. Usage suggestions: CI pipeline ID. + +### Build attributes + +When creating the service in `VisualClient`, extra fields can be set to define the context, thus acting on which baselines new snapshots will be compared to. ([More info on baseline matching](../../visual-testing.md#baseline-matching)) + +It needs to be defined through the `VisualApi.Builder` object. + +Methods available: + +- `buildName(String buildName)`: Sets the name of the build +- `projectName(String project)`: Sets the name of the project +- `branchName(String branch)`: Sets the name of the branch +- `defaultBranchName(String defaultBranch)`: Sets the name of the default branch + +Example: + +```java +import com.saucelabs.visual.VisualClient; + +visual = VisualClient.builder(username, accessKey) + .buildName("Sauce Demo Test") + .branchName("main") + .projectName("Java examples") + .build(); +``` + +### Ignored regions + +#### Component-based ignored region + +Sauce Visual provides a way to ignore a list of components. + +An ignored component can be a specific element from the page. + +Those ignored components are specified when requesting a new snapshot. + +Example: + +```java +import com.saucelabs.visual.VisualCheckOptions;; + +visualClient.sauceVisualCheck("Inventory Page", + VisualCheckOptions.builder() + .ignore(withId(R.id.changeTextBt)) + .build()); +``` + +#### User-specified ignored region + +Alternatively, ignored regions can be user-specified areas. A region is defined by four elements. + +- `x`, `y`: The location of the top-left corner of the ignored region +- `width`: The width of the region to ignore +- `height`: The height of the region to ignore + +_Note: all values are pixels_ + +You can also give a name to a region that will be visible in Sauce Visual UI using `name` + +Example: + +```java + +import com.saucelabs.visual.VisualCheckOptions; +import com.saucelabs.visual.model.Region; + +visualClient.sauceVisualCheck("Inventory Page", + VisualCheckOptions.builder() + .ignore(Region.builder() + .name("Demo region") + .x(100) + .y(100) + .width(200) + .height(200) + .build()) + .build()); +``` + +### Capturing the DOM snapshot + +Sauce Visual does not capture DOM snapshot by default. It can be changed in options. + +Example: +```java +import com.saucelabs.visual.VisualCheckOptions; + +static VisualClient visualClient = VisualClient.builder( + BuildConfig.SAUCE_USERNAME, + BuildConfig.SAUCE_ACCESS_KEY) + .buildName("Espresso Basic Sample") + .captureDom(true) + .build(); +``` + +You can alternatively enable DOM capturing when initating a visual check. + +```java +import com.saucelabs.visual.VisualCheckOptions; + +visualClient.sauceVisualCheck("Inventory Page", + VisualCheckOptions.builder() + .captureDom(true) + .build()); +``` + +### Clip to an Element + + + +Example: + +```java +import com.saucelabs.visual.VisualCheckOptions; + +visualClient.sauceVisualCheck("Visible Sale Banner", + VisualCheckOptions.builder() + .clipElement(withId(R.id.changeTextBt)) + .build()); +``` + +## Examples + +Click [here](https://github.com/saucelabs/visual-examples/tree/main/espresso) From 45d85048a78c32fc09d4bd028acdf2bf87df41fb Mon Sep 17 00:00:00 2001 From: Kerem Beygo Date: Wed, 23 Oct 2024 15:21:51 +0200 Subject: [PATCH 2/7] cleanup --- docs/visual-testing/integrations/espresso.md | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/docs/visual-testing/integrations/espresso.md b/docs/visual-testing/integrations/espresso.md index 63a6e35ab9..2125cbb71a 100644 --- a/docs/visual-testing/integrations/espresso.md +++ b/docs/visual-testing/integrations/espresso.md @@ -2,14 +2,7 @@ sidebar_label: Espresso --- -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; import ClippingDescription from '../_partials/_clipping-description.md'; -import FullPageLimit from '../_partials/_fullpage-limit.md'; -import EnvironmentVariables from '../_partials/_environment-variables.md'; -import SelectiveDiffing from '../_partials/_selective-diffing.md'; -import SelectiveDiffingGlobal from '../_partials/_selective-diffing-global.md'; -import SelectiveDiffingRegion from '../_partials/_selective-diffing-region.md'; # Espresso Integration @@ -249,4 +242,4 @@ visualClient.sauceVisualCheck("Visible Sale Banner", ## Examples -Click [here](https://github.com/saucelabs/visual-examples/tree/main/espresso) +Click [here](https://github.com/saucelabs/visual-examples/tree/main/espresso) to see the example project. From 1c2f7a4a4811f1b27f22fb870a15a88b3fd7614c Mon Sep 17 00:00:00 2001 From: Kerem Beygo Date: Wed, 23 Oct 2024 15:23:41 +0200 Subject: [PATCH 3/7] add to sidebar --- sidebars.js | 1 + 1 file changed, 1 insertion(+) diff --git a/sidebars.js b/sidebars.js index c5714396f7..88ad298775 100644 --- a/sidebars.js +++ b/sidebars.js @@ -1725,6 +1725,7 @@ module.exports = { 'visual-testing/integrations/python', 'visual-testing/integrations/python-robot-framework', 'visual-testing/integrations/playwright', + 'visual-testing/integrations/espresso' ], }, 'visual-testing/cli', From fd215e7c84c77c0b327a56d8176a9db68733226d Mon Sep 17 00:00:00 2001 From: Kerem Beygo Date: Wed, 23 Oct 2024 15:48:57 +0200 Subject: [PATCH 4/7] adjust section SL credentials --- docs/visual-testing/integrations/espresso.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/visual-testing/integrations/espresso.md b/docs/visual-testing/integrations/espresso.md index 2125cbb71a..96c4602ce9 100644 --- a/docs/visual-testing/integrations/espresso.md +++ b/docs/visual-testing/integrations/espresso.md @@ -86,7 +86,7 @@ void checkAppCatalog() { ### Step 4: Configure your Sauce Labs credentials Sauce Visual Espresso expects Sauce Labs username and access key to be passed when initiating the client. -It's recommended to define and pass your Sauce Labs credentials to `VisualClient` as custom `BuildConfig` fields. +It's recommended to define and pass your Sauce Labs credentials to `VisualClient` as custom `BuildConfig` fields. ```groovy android { @@ -94,7 +94,6 @@ android { buildConfigField "String", "SAUCE_ACCESS_KEY", "YOUR_SAUCE_ACCESS_KEY" } ``` -Username and Access Key can be retrieved from https://app.saucelabs.com/user-settings. ```java import com.saucelabs.visual.VisualClient; @@ -106,6 +105,8 @@ static VisualClient visualClient = VisualClient.builder( .build(); ``` +Username and Access Key can be retrieved from https://app.saucelabs.com/user-settings. + ### Step 5: Run the test Upon executing your tests for the first time under this step, a visual baseline is automatically created in our system. This baseline serves as the standard for all subsequent WebDriver tests. As new tests are run, they are compared to this original baseline, with any deviations highlighted to signal visual changes. These comparisons are integral for detecting any unintended visual modifications early in your development cycle. All test builds, including the initial baseline and subsequent runs, can be monitored and managed through the Sauce Labs platform at [Sauce Visual Builds](https://app.saucelabs.com/visual/builds). From 7c614a4fdf3747219e66c138723550fedbeac42e Mon Sep 17 00:00:00 2001 From: Kerem Beygo Date: Thu, 24 Oct 2024 13:37:48 +0200 Subject: [PATCH 5/7] CR remarks --- docs/visual-testing/integrations/espresso.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/visual-testing/integrations/espresso.md b/docs/visual-testing/integrations/espresso.md index 96c4602ce9..fc3171cede 100644 --- a/docs/visual-testing/integrations/espresso.md +++ b/docs/visual-testing/integrations/espresso.md @@ -36,7 +36,7 @@ import com.saucelabs.visual.VisualClient; static VisualClient visual = VisualClient.builder(sauceUsername, sauceAccessKey) .buildName("Sauce Demo Test") - .build();; + .build(); ``` To enhance efficiency in managing tests, it's important to provide a specific test name and suite name for each test. This practice allows Sauce Visual to effectively organize snapshots into coherent groups. As a result, it simplifies the review process, saving time and effort in navigating through test results and understanding the context of each snapshot. @@ -201,7 +201,7 @@ visualClient.sauceVisualCheck("Inventory Page", ### Capturing the DOM snapshot -Sauce Visual does not capture DOM snapshot by default. It can be changed in options. +Sauce Visual does not capture DOM snapshots by default. This setting can be changed globally via the build options. Example: ```java From 91a1dff2afe3967a3791f3f73556e907202f2b77 Mon Sep 17 00:00:00 2001 From: Kerem Beygo Date: Tue, 29 Oct 2024 10:41:46 +0100 Subject: [PATCH 6/7] CR remarks --- docs/visual-testing/integrations/espresso.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/visual-testing/integrations/espresso.md b/docs/visual-testing/integrations/espresso.md index fc3171cede..7f94f887dd 100644 --- a/docs/visual-testing/integrations/espresso.md +++ b/docs/visual-testing/integrations/espresso.md @@ -6,6 +6,8 @@ import ClippingDescription from '../_partials/_clipping-description.md'; # Espresso Integration +You can use the Sauce Visual Espresso plugin to set up an integration with the Sauce Labs platform and start comparing the visual snapshots generated during your tests. + ## Introduction This guide requires an existing Android JUnit setup. @@ -109,7 +111,7 @@ Username and Access Key can be retrieved from https://app.saucelabs.com/user-set ### Step 5: Run the test -Upon executing your tests for the first time under this step, a visual baseline is automatically created in our system. This baseline serves as the standard for all subsequent WebDriver tests. As new tests are run, they are compared to this original baseline, with any deviations highlighted to signal visual changes. These comparisons are integral for detecting any unintended visual modifications early in your development cycle. All test builds, including the initial baseline and subsequent runs, can be monitored and managed through the Sauce Labs platform at [Sauce Visual Builds](https://app.saucelabs.com/visual/builds). +Upon executing your tests for the first time under this step, a visual baseline is automatically created in our system. This baseline serves as the standard for all subsequent tests. As new tests are run, they are compared to this original baseline, with any deviations highlighted to signal visual changes. These comparisons are integral for detecting any unintended visual modifications early in your development cycle. All test builds, including the initial baseline and subsequent runs, can be monitored and managed through the Sauce Labs platform at [Sauce Visual Builds](https://app.saucelabs.com/visual/builds). Remember, the baseline is established during the initial run, and any subsequent visual differences detected will be marked for review. @@ -208,8 +210,8 @@ Example: import com.saucelabs.visual.VisualCheckOptions; static VisualClient visualClient = VisualClient.builder( - BuildConfig.SAUCE_USERNAME, - BuildConfig.SAUCE_ACCESS_KEY) + sauceUsername, + sauceAccessKey) .buildName("Espresso Basic Sample") .captureDom(true) .build(); From edfd02ae4f4cb75af42b8e697fe467dbe4af0cb5 Mon Sep 17 00:00:00 2001 From: Kerem Beygo Date: Wed, 30 Oct 2024 14:31:20 +0100 Subject: [PATCH 7/7] CR remarks --- docs/visual-testing/integrations/espresso.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/visual-testing/integrations/espresso.md b/docs/visual-testing/integrations/espresso.md index 7f94f887dd..ab5063efdb 100644 --- a/docs/visual-testing/integrations/espresso.md +++ b/docs/visual-testing/integrations/espresso.md @@ -79,7 +79,7 @@ Add a check to one of your tests: import org.junit.Test; @Test -void checkAppCatalog() { +void checkLogin() { visual.sauceVisualCheck("Before Login"); }