From d48734f4dd9834f4945bfac5cb764dc02b093f70 Mon Sep 17 00:00:00 2001 From: Wim Selles Date: Thu, 9 Nov 2023 12:17:22 +0100 Subject: [PATCH] fix linting and JS npm scripts --- docs/visual-testing/integrations/cypress.md | 19 +- docs/visual-testing/integrations/java.md | 168 ++++++++++-------- docs/visual-testing/integrations/storybook.md | 2 +- .../integrations/webdriverio.md | 14 +- .../workflows/diff-generation.md | 9 +- docs/visual-testing/workflows/review.md | 2 - 6 files changed, 118 insertions(+), 96 deletions(-) diff --git a/docs/visual-testing/integrations/cypress.md b/docs/visual-testing/integrations/cypress.md index 7291aab627..75f1147ad8 100644 --- a/docs/visual-testing/integrations/cypress.md +++ b/docs/visual-testing/integrations/cypress.md @@ -20,6 +20,7 @@ You can alternatively take a look to our [example repository](#example). Sauce Visual provides an integration with [Cypress](https://cypress.io) through a plugin that you can add to any existing Cypress project. Sauce Labs Visual introduce a new Cypress command: + - `cy.sauceVisualCheck()`: Takes a screenshot and send it to Sauce Labs Visual for comparison. ## Quickstart @@ -29,19 +30,20 @@ Sauce Labs Visual introduce a new Cypress command: - Install the Sauce Visual for Cypress plugin in your current project. ```sh -npm install --save @saucelabs/cypress-visual-plugin +npm install --save-dev @saucelabs/cypress-visual-plugin ``` ### Step 2: Configure Cypress to use Sauce Visual for Cypress plugin - Import the plugin in Cypress project configuration, at the top of the file: + ```ts import { CypressSauceVisual } from '@saucelabs/cypress-visual-plugin'; ``` - Register the plugin to Cypress events in Cypress project configuration: -``` ts +```ts export default defineConfig({ e2e: { [...] @@ -53,6 +55,7 @@ export default defineConfig({ ``` - Register Sauce Visual for Cypress commands. Add the following line in your `cypress/support/e2e.ts`: + ```ts import '@saucelabs/cypress-visual-plugin/commands'; ``` @@ -69,7 +72,6 @@ context('Sauce Demo', () => { }); ``` - ### Step 4: Configure your Sauce Labs credentials Sauce Visual relies on environment variables for authentications.
@@ -95,6 +97,7 @@ Builds will appear on Sauce Labs platform as soon as they have been created by t Sauce Visual for Cypress plugin extends Cypress configuration, allowing to define the context, thus acting on which baselines new snapshots will be compared to. ([More info on baseline matching](/visual-testing/#baseline-matching)) Options: + - `region`: Sauce Labs Region where the new build will be created (default: `us-west-1`) - `buildName`: Name of the build (default: `Cypress Visual Testing`) - `project`: Name of the project (default: `None`) @@ -103,6 +106,7 @@ Options: They need to be set through the `saucelabs` attribute of `e2e` configuration. Example: + ```javascript export default defineConfig({ e2e: { @@ -127,13 +131,15 @@ Those ignored regions are specified when requesting a new snapshot. #### User-specified ignored region 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 heigh of the region to ignore -*Note: all values are pixels* +_Note: all values are pixels_ Example: + ```javascript cy.sauceVisualCheck('login-page', { ignoredRegions: [ @@ -154,6 +160,7 @@ Alternatively, an ignored region can be a specific element from the page. If the selectors matches multiple elements, all will be ignored. Example: + ```javascript cy.sauceVisualCheck('login-page', { ignoredRegions: [ @@ -169,6 +176,7 @@ Sauce Visual is relying on native screenshot feature from Cypress. As `cy.snapsh The field `cypress` from `options` will be transmitted as it to `cy.screenshot` command. Example: + ```javascript cy.sauceVisualCheck('login-page', { cypress: { @@ -185,5 +193,4 @@ Screenshots will be captured and sent to Sauce Labs only when `cypress run` is e ## Example - -An example project is available [here](https://github.com/saucelabs/visual-examples/tree/main/cypress). \ No newline at end of file +An example project is available [here](https://github.com/saucelabs/visual-examples/tree/main/cypress). diff --git a/docs/visual-testing/integrations/java.md b/docs/visual-testing/integrations/java.md index 97ef9d23ca..6a036411fb 100644 --- a/docs/visual-testing/integrations/java.md +++ b/docs/visual-testing/integrations/java.md @@ -20,6 +20,7 @@ You can alternatively take a look to our [example repository](#examples). Sauce Labs Visual provides an library allowing integration with [WebDriver](https://www.selenium.dev/documentation/webdriver/). Sauce Labs Visual plugin provides a library exposing a `VisualApi` object that provides actions: + - `visual.sauceVisualCheck()`: Takes a screenshot and send it to Sauce Labs Visual for comparison. - `visual.sauceVisualResults()`: Waits for all diff calculations to complete and returns a summary of results. See [Test results summary](#test-results-summary) for more details about summary format and sample usage. @@ -29,20 +30,22 @@ Sauce Labs Visual plugin provides a library exposing a `VisualApi` object that p ### Step 1: Add Sauce Labs Visual dependecy Add [Sauce Visual](https://central.sonatype.com/artifact/com.saucelabs.visual/java-client) dependency to your pom.xml - ```xml - - com.saucelabs.visual - java-client - 0.3.121 - test - - ``` -*Note: You can find the latest versions available [here](https://central.sonatype.com/search?q=com.saucelabs.visual).* +```xml + + com.saucelabs.visual + java-client + 0.3.121 + test + +``` + +_Note: You can find the latest versions available [here](https://central.sonatype.com/search?q=com.saucelabs.visual)._ ### Step 2: Configure Visual Testing integration Declare a RemoteWebDriver and a VisualApi instance as class variables + ```java import org.openqa.selenium.remote.RemoteWebDriver; import com.saucelabs.visual.VisualApi; @@ -54,111 +57,115 @@ Declare a RemoteWebDriver and a VisualApi instance as class variables Initialize `RemoteWebDriver` and `VisualApi` - - - ```java - import org.junit.jupiter.api.BeforeAll; - - @BeforeAll - public static void init() { - driver = new RemoteWebDriver(webDriverUrl, capabilities); - visual = new VisualApi.Builder(driver, sauceUsername, sauceAccessKey, DataCenter.US_WEST_1).build(); - } - ``` + + +```java +import org.junit.jupiter.api.BeforeAll; + +@BeforeAll +public static void init() { + driver = new RemoteWebDriver(webDriverUrl, capabilities); + visual = new VisualApi.Builder(driver, sauceUsername, sauceAccessKey, DataCenter.US_WEST_1).build(); +} +``` + - ```java - import org.testng.annotations.BeforeSuite; +```java +import org.testng.annotations.BeforeSuite; + +@BeforeSuite +public static void init() { + driver = new RemoteWebDriver(webDriverUrl, capabilities); + visual = new VisualApi.Builder(driver, sauceUsername, sauceAccessKey, DataCenter.US_WEST_1).build(); +} +``` - @BeforeSuite - public static void init() { - driver = new RemoteWebDriver(webDriverUrl, capabilities); - visual = new VisualApi.Builder(driver, sauceUsername, sauceAccessKey, DataCenter.US_WEST_1).build(); - } - ``` - Don't forget to quit the WebDriver - - - ```java - import org.junit.jupiter.api.AfterAll; - - @AfterAll - public static void tearDown() { - if (driver != null) { - driver.quit(); - } - } - ``` + + +```java +import org.junit.jupiter.api.AfterAll; + +@AfterAll +public static void tearDown() { + if (driver != null) { + driver.quit(); + } +} +``` + - ```java - import org.testng.annotations.AfterSuite; +```java +import org.testng.annotations.AfterSuite; + +@AfterSuite +public static void tearDown() { + if (driver != null) { + driver.quit(); + } +} +``` - @AfterSuite - public static void tearDown() { - if (driver != null) { - driver.quit(); - } - } - ``` - ### Step 3: Add visual tests in your tests Add a check to one of your tests: - + - ```java - import org.junit.jupiter.api.Test; +```java +import org.junit.jupiter.api.Test; - @Test - void checkLoginLooksTheSame() { - var loginPage = new LoginPage(driver); - loginPage.open(); +@Test +void checkLoginLooksTheSame() { + var loginPage = new LoginPage(driver); + loginPage.open(); + + visual.sauceVisualCheck("Before Login"); +} +``` - visual.sauceVisualCheck("Before Login"); - } - ``` - ```java - import org.testng.annotations.Test; - - @Test - void checkLoginLooksTheSame() { - var loginPage = new LoginPage(driver); - loginPage.open(); - - visual.sauceVisualCheck("Before Login"); - } - ``` +```java +import org.testng.annotations.Test; + +@Test +void checkLoginLooksTheSame() { + var loginPage = new LoginPage(driver); + loginPage.open(); + + visual.sauceVisualCheck("Before Login"); +} +``` + @@ -185,13 +192,15 @@ Builds will appear on Sauce Labs platform as soon as they have been created by t ### Test results summary `VisualApi#sauceVisualResults()` returns a summary of test results in `Map` format where `DiffStatus` is one of the following: + - `DiffStatus.QUEUED`: Diffs that are pending for processing. Should be 0 in case the test is completed without any timeouts - `DiffStatus.EQUAL`: Diffs that have no changes detected - `DiffStatus.UNAPPROVED`: Diffs that have detected changes and waiting for action - `DiffStatus.APPROVED`: Diffs that have detected changes and have been approved -- `DiffStatus.REJECTED`: Diffs that have detected changes and have been rejected +- `DiffStatus.REJECTED`: Diffs that have detected changes and have been rejected Sample usage: + ```java assertEquals(visual.sauceVisualResults().get(DiffStatus.UNAPPROVED), EXPECTED_TOTAL_UNAPPROVED_DIFFS); ``` @@ -203,11 +212,13 @@ When creating the service in `VisualApi`, extra fields can be set to define the It needs to be defined through the `VisualApi.Builder` object. Methods available: + - `withBuild(String build)`: Sets the name of the build - `withProject(String project)`: Sets the name of the project - `withBranch(String branch)`: Sets the name of the branch Example: + ```java visual = new Builder(driver, username, accessKey, DataCenter.US_WEST_1) .withBuild("Sauce Demo Test") @@ -227,6 +238,7 @@ An ignored component can be a specific element from the page. Those ignored components are specified when requesting a new snapshot. Example: + ```java Options options = new Options(); options.setIgnoreElements(List.of( @@ -244,9 +256,10 @@ Alternatively, ignored regions can be user-specified areas. A region is defined - `width`: The width of the region to ignore - `height`: The height of the region to ignore -*Note: all values are pixels* +_Note: all values are pixels_ Example: + ```java Options options = new Options(); IgnoreRegion ignoreRegion = new IgnoreRegion( @@ -262,5 +275,6 @@ Example: ## Examples Two examples are available: + - An example project [using Junit](https://github.com/saucelabs/visual-examples/tree/main/wd-java) - An example project [using TestNG](https://github.com/saucelabs/visual-examples/tree/main/wd-java-testng) diff --git a/docs/visual-testing/integrations/storybook.md b/docs/visual-testing/integrations/storybook.md index c295cd5b8f..24a4591257 100644 --- a/docs/visual-testing/integrations/storybook.md +++ b/docs/visual-testing/integrations/storybook.md @@ -32,7 +32,7 @@ This package leverage's Storybook's test-runner and metadata generation system f 2. Install this plugin in an existing project from the root: ```sh -npm i -D @saucelabs/visual-storybook +npm i --save-dev @saucelabs/visual-storybook ``` 3. Eject your test-runner config and append the Sauce Visual storybook configuration: diff --git a/docs/visual-testing/integrations/webdriverio.md b/docs/visual-testing/integrations/webdriverio.md index bb966d9d53..10ed2fc712 100644 --- a/docs/visual-testing/integrations/webdriverio.md +++ b/docs/visual-testing/integrations/webdriverio.md @@ -20,6 +20,7 @@ You can alternatively take a look to our [example repository](#example). Sauce Labs Visual provides an integration with [WebdriverIO](https://webdriver.io/) through a service that you can add to any existing WebdriverIO project. Sauce Labs Visual adds new commands to the WebdriverIO's `browser` object: + - `browser.sauceVisualCheck()`: Takes a screenshot and send it to Sauce Labs Visual for comparison. - `browser.sauceVisualResults()`: Waits for diff calculations to complete and returns a summary of results. See [Test results summary](#test-results-summary) for more details about summary format and sample usage. @@ -31,7 +32,7 @@ Sauce Labs Visual adds new commands to the WebdriverIO's `browser` object: Install the Sauce Labs Visual service in your current project. ```sh -npm install --save @saucelabs/wdio-sauce-visual-service +npm install --save-dev @saucelabs/wdio-sauce-visual-service ``` ### Step 2: Add SauceVisualService to your WebdriverIO configuration @@ -83,7 +84,8 @@ Builds will appear on Sauce Labs platform as soon as they have been created by t ### Test results summary -`browser.sauceVisualResults()` returns a summary of test results in format: +`browser.sauceVisualResults()` returns a summary of test results in format: + ```ts { QUEUED: number; // Diffs that are pending for processing. Should be 0 in case the test is completed without any timeouts @@ -95,11 +97,13 @@ Builds will appear on Sauce Labs platform as soon as they have been created by t ``` Sample output: + ```ts { APPROVED: 0, EQUAL: 0, UNAPPROVED: 2, REJECTED: 0, QUEUED: 0 } ``` Sample usage: + ```ts expect((await browser.sauceVisualResults()).UNAPPROVED).toBe(EXPECTED_TOTAL_UNAPPROVED_DIFFS); ``` @@ -109,6 +113,7 @@ expect((await browser.sauceVisualResults()).UNAPPROVED).toBe(EXPECTED_TOTAL_UNAP When creating the service in WebdriverIO's configuration, 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](../sauce-visual.md#baseline-matching)) Options: + - `buildName`: Name of the build - `project`: Name of the project - `branch`: Name of branch @@ -116,6 +121,7 @@ Options: They need to be set through the `options` parameter. Example: + ```ts services: ['sauce', ['@saucelabs/wdio-sauce-visual-service', { buildName: 'Sauce Demo Test', @@ -154,7 +160,7 @@ Alternatively, ignored regions can be user-specified areas. A region is defined - `width`: The width of the region to ignore - `height`: The heigh of the region to ignore -*Note: all values are pixels* +_Note: all values are pixels_ Example: @@ -173,4 +179,4 @@ await browser.sauceVisualCheck('Before Login', { ## Example -An example project is available [here](https://github.com/saucelabs/visual-examples/tree/main/wdio). \ No newline at end of file +An example project is available [here](https://github.com/saucelabs/visual-examples/tree/main/wdio). diff --git a/docs/visual-testing/workflows/diff-generation.md b/docs/visual-testing/workflows/diff-generation.md index 020ef35608..303578ab15 100644 --- a/docs/visual-testing/workflows/diff-generation.md +++ b/docs/visual-testing/workflows/diff-generation.md @@ -12,24 +12,23 @@ This workflow is responsible for generating snapshots (screenshots) of the websi Users new to visual testing often have an existing test suite in WebdriverIO, Cypress or a similar framework. With Sauce Visual testing existing test suites can be enhanced with a few extra "take a snapshot" statements and that is all it takes to implement this workflow. - ## E2E Testing Check out how to integrate Sauce Visual into an existing test suite: + - [Cypress Integration](../integrations/cypress.md) - [WebdriverIO Integration](../integrations/webdriverio.md) - [Java Integration](../integrations/java.md) Alternatively, [check out our examples](../../visual-testing.md#examples). - ## Component Testing Sauce Visual can be used with a component testing workflow: -- [Storybook Integration](../integrations/storybook.md) -Alternatively, [check out our examples](../../visual-testing.md#examples). +- [Storybook Integration](../integrations/storybook.md) +Alternatively, [check out our examples](../../visual-testing.md#examples). ## Baseline Matching @@ -55,5 +54,3 @@ In these cases, a default value (0, null or empty string) is used. The matching process happens as part of the snapshot creation (`createSnapshot` in the API). This means, that a baseline can only be considered for a diff if it existed before the `createSnapshot` call. - - diff --git a/docs/visual-testing/workflows/review.md b/docs/visual-testing/workflows/review.md index c52d6ae5a0..1757e35b4b 100644 --- a/docs/visual-testing/workflows/review.md +++ b/docs/visual-testing/workflows/review.md @@ -16,7 +16,6 @@ For many integrations, there will also be at least one automated job that genera **Note:** A "Visual Build" is currently not related to builds of automated jobs. - ## User Interface Selecting one of the builds allows you to get to the Diff Review Page, where you can Approve or Reject detected diffs. @@ -67,4 +66,3 @@ Visual uses different statuses: | For Review | There were either no baselines available to compare against your uploaded snapshot or some were different from their baselines. You are supposed to review those detected diffs. As long as those changes aren't accepted, they are considered a failure state. | | Accepted | All detected changes were accepted. This is considered a success state. | | Rejected | Some of your detected changes were rejected. This is considered a failure state. | -