diff --git a/.github/workflows/dotnet.yml b/.github/workflows/dotnet.yml index 4c6dd736..924b9494 100644 --- a/.github/workflows/dotnet.yml +++ b/.github/workflows/dotnet.yml @@ -29,14 +29,17 @@ jobs: - name: Checkout code uses: actions/checkout@v4 - - name: Build NUnit example - uses: docker/build-push-action@v4 + - name: Build XUnit example + uses: docker/build-push-action@v6 with: context: ./dotnet-xunit file: ./dotnet-xunit/Dockerfile push: false secrets: | "dotenv=${{ secrets.DOTENV }}" + build-args: | + GITHUB_RUN_ID=${{ github.run_id }} + GITHUB_RUN_ATTEMPT=${{ github.run_attempt }} nunit: runs-on: ubuntu-latest @@ -46,10 +49,13 @@ jobs: uses: actions/checkout@v4 - name: Build NUnit example - uses: docker/build-push-action@v4 + uses: docker/build-push-action@v6 with: context: ./dotnet-nunit file: ./dotnet-nunit/Dockerfile push: false secrets: | - "dotenv=${{ secrets.DOTENV }}" \ No newline at end of file + "dotenv=${{ secrets.DOTENV }}" + build-args: | + GITHUB_RUN_ID=${{ github.run_id }} + GITHUB_RUN_ATTEMPT=${{ github.run_attempt }} diff --git a/cypress/README.md b/cypress/README.md index 194fc00d..9ddeb610 100644 --- a/cypress/README.md +++ b/cypress/README.md @@ -67,11 +67,13 @@ npm run sauce-visual-check Alternatively, you can run your tests on Sauce Labs. - Install `saucectl` + ```sh { name=npm-install-saucectl} npm install saucectl ``` - Install the plugin in your `.sauce/config.yml` + ```yml [...] @@ -83,6 +85,7 @@ npm: ``` - Run saucectl + ```sh { name=saucectl-run } npx saucectl run ``` @@ -91,197 +94,13 @@ npx saucectl run - Accept all diffs, so they become new baselines. - Run saucectl (with a modified screen) + ```sh { name=saucectl-run-visual-check } VISUAL_CHECK=true npx saucectl run ``` - Go to https://app.saucelabs.com/visual/builds to review changes. -## How to add visual testing to your setup - -- Add plugin to your Cypress project - -```sh -npm install --save @saucelabs/cypress-visual-plugin -``` - -- Add plugin in the project configuration, at the top of the file: -```ts -import { CypressSauceVisual } from '@saucelabs/cypress-visual-plugin'; - -export default defineConfig({ - e2e: { - [...] - setupNodeEvents(on, config) { - CypressSauceVisual.register(on, config); - }, - }, -}) -``` - -- Register Sauce Visual for Cypress commands. Add the following line in your `cypress/support/e2e.ts`: -```ts -import '@saucelabs/cypress-visual-plugin/commands'; -``` - -- Capture screenshot in one of your tests: - -```ts -context('Sauce Demo', () => { - it('.type() - type into a DOM element', () => { - cy.visit('https://www.saucedemo.com/') - - cy.visualCheck('visual: my-homepage'); - }) -}); -``` - -- Configure with your Sauce credentials from https://app.saucelabs.com/user-settings. - -```sh -export SAUCE_USERNAME=__YOUR_SAUCE_USER_NAME__ -export SAUCE_ACCESS_KEY=__YOUR_SAUCE_ACCESS_KEY__ -``` - -- Run the test the way you are used to. - - -## Advanced usage - -### Test results summary - -`cy.sauceVisualResults()` can be used to obtain a summary of test results. The command will make the test wait until the results are calculated and return a summary in format: -```ts - { - QUEUED: number; // Diffs that are pending for processing. Should be 0 in case the test is completed without any timeouts - EQUAL: number; // Diffs that have no changes detected - UNAPPROVED: number; // Diffs that have detected changes and waiting for action - APPROVED: number; // Diffs that have detected changes and have been approved - REJECTED: number; // Diffs that have detected changes and have been rejected - } -``` - -`cy.sauceVisualResults()` is particularly useful for composing assertions on the result of each visual test. - -Example: -```ts - const EXPECTED_TOTAL_UNAPPROVED_DIFFS = 0; - - cy.sauceVisualResults().its("UNAPPROVED").should("eq", EXPECTED_TOTAL_UNAPPROVED_DIFFS); -``` - -### Build name - -`buildName` can be defined in the `cypress.config.js` configuration file. - -Example -```javascript -export default defineConfig({ - e2e: { - [...] - saucelabs: { - buildName: 'SauceDemo - Cypress', - }, - [...] - } -} -``` - -### Project - -`project` can be defined in the `cypress.config.js` configuration file. - -Example -```javascript -export default defineConfig({ - e2e: { - [...] - saucelabs: { - project: process.env.GITHUB_REPOSITORY, - }, - [...] - } -} -``` - -### Branch - -`branch` can be defined in the `cypress.config.js` configuration file. - -Example -```javascript -export default defineConfig({ - e2e: { - [...] - saucelabs: { - branch: process.env.GITHUB_REF_NAME, - }, - [...] - } -} -``` - -### Region - -By default, visual tests are uploaded to `us-west-1` region. \ -This value can be overridden in the `cypress.config.js` configuration file. - -Example -```javascript -export default defineConfig({ - e2e: { - [...] - saucelabs: { - region: 'eu-central-1', - }, - [...] - } -} -``` - -### 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: - -```javascript - cy.visualCheck('login-page', { ignoredRegions: [ - cy.get('[data-test="username"]'), - ] }); -``` - -#### 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* - -Example: - -```javascript - cy.visualCheck('login-page', { ignoredRegions: [ - { - x: 240, - y: 800, - width: 1520, - height: 408 - } - ] }); -``` - -## Limitations - -Sauce Visual plugin for Cypress **DOES NOT** support `cypress open`. +## Installation & Usage -Screenshots will be captured and sent to Sauce Labs only when `cypress run` is executed. +View installation and usage instructions on the [Sauce Docs website](https://docs.saucelabs.com/visual-testing/integrations/cypress/). diff --git a/dotnet-nunit/Dockerfile b/dotnet-nunit/Dockerfile index 28f373a8..b9d41532 100644 --- a/dotnet-nunit/Dockerfile +++ b/dotnet-nunit/Dockerfile @@ -21,5 +21,9 @@ WORKDIR /workspace COPY . . +ARG GITHUB_RUN_ID +ARG GITHUB_RUN_ATTEMPT +ARG SAUCE_VISUAL_BRANCH_NAME=${GITHUB_RUN_ID}${GITHUB_RUN_ATTEMPT} + RUN --mount=type=secret,id=dotenv,target=/workspace/.env env $(cat /workspace/.env | xargs) runme run dotnet-test RUN --mount=type=secret,id=dotenv,target=/workspace/.env env $(cat /workspace/.env | xargs) runme run dotnet-test-modified diff --git a/dotnet-nunit/README.md b/dotnet-nunit/README.md index d3ce3e71..ecfc3db5 100644 --- a/dotnet-nunit/README.md +++ b/dotnet-nunit/README.md @@ -37,159 +37,6 @@ MODIFIED=true dotnet test - Open the test or go to https://app.saucelabs.com/visual/builds to review changes. -## How to add visual testing to your setup +## Installation & Usage -- Add [sauce visual](https://www.nuget.org/packages/SauceLabs.Visual/) dependency -```powershell {"id":"01HHQ3FQDWBD7ZSD2PQKG2AKDZ"} -dotnet add package SauceLabs.Visual -``` - -- Declare a RemoteWebDriver and a VisualApi instance as class variables - -```csharp {"id":"01HHQ3FQDWBD7ZSD2PQQ2E5HSZ"} -using OpenQA.Selenium.Remote; -using SauceLabs.Visual; - -private RemoteWebDriver Driver { get; set; } -private VisualClient VisualClient { get; set; } -``` - -- Initialize WebDriver and VisualApi in `[OneTimeSetUp]` method - -```csharp {"id":"01HHQ3FQDWBD7ZSD2PQTRQSGV3"} - [OneTimeSetUp] - public async Task Setup() - { - var capabilities = GetCapabilities(); - - Driver = new RemoteWebDriver(sauceUrl, capabilities); - VisualClient = await VisualClient.Create(Driver, Region.UsWest1); - // Enable other options - VisualClient.CaptureDom = true; - } -``` - -- Add a check to one of your tests: - -```csharp {"id":"01HHQ3FQDWBD7ZSD2PQZQMJRH1"} -await VisualClient.VisualCheck("My login page") -``` - -- Don't forget to quit the WebDriver in @AfterAll section - -```csharp {"id":"01HHQ3FQDWBD7ZSD2PR1PW1V54"} - [OneTimeTearDown] - public async Task Teardown() - { - Driver?.Quit(); - VisualClient.Dispose(); - } -``` - -- Create a `SetUpFixture` class that will take care of closing your Visual build: - -```csharp {"id":"01HHQ3FQDWBD7ZSD2PR1PW1V54"} - [SetUpFixture] - public class SetupFixture - { - [OneTimeTearDown] - public async Task RunAfterAnyTests() - { - await VisualClient.Finish(); - } - } -``` - -- Configure with your Sauce credentials from https://app.saucelabs.com/user-settings. - -```sh {"id":"01HHQ3FQDWBD7ZSD2PR4Y27KEQ"} -export SAUCE_USERNAME=__YOUR_SAUCE_USERNAME__ -export SAUCE_ACCESS_KEY=__YOUR_SAUCE_ACCESS_KEY__ -``` - -- Run the test the way you are used to. - -## Advanced usage - -### Test results summary - -`VisualClient.VisualResults()` returns a summary of test results in `Dictionnary` 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 - -Sample usage: - -```csharp -var expectedTotalUnapprovedDiffs = 0; - -var results = await VisualClient.VisualResults(); -Assert.AreEqual(expectedTotalUnapprovedDiffs, results[DiffStatus.Unapproved]); -``` - -### Build attributes - -When creating the `VisualClient` client, 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 a `CreateBuildOptions` object. - -Properties available: -- `string? Name`: The name of the build -- `string? Project`: The name of the project -- `string? Branch`: The name of the branch -- `string? CustomId`: A customId to be able to retrieve the current build -- `string? DefaultBranch`: The name of the default branch - -Example: - -```csharp - VisualClient = await VisualClient.Create(Driver, Region.UsWest1, - new CreateBuildOptions() { Name = "My Visual Build", Project = "csharp-project", Branch = "feature-branch" }); -``` - -### 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: - -```csharp -var btnAction = Driver.FindElement(By.CssSelector(".app_logo")); - -await VisualClient.VisualCheck("Inventory Page", - new VisualCheckOptions() - { - IgnoreElements = new[] { btnAction } - }); -``` - -#### 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_ - -Example: - -```csharp -await VisualClient.VisualCheck("Inventory Page", - new VisualCheckOptions() - { - IgnoreRegions = new[] { new IgnoreRegion(10, 10, 100, 100) } - }); -``` - -[Follow me](/wd-java/src/test/java/com/example/InventoryIgnoreRegionsTest.java#L38-L50) to see complete working example \ No newline at end of file +View installation and usage instructions on the [Sauce Docs website](https://docs.saucelabs.com/visual-testing/integrations/csharp/). diff --git a/dotnet-nunit/SauceLabs.Visual.Example/SauceDemo.cs b/dotnet-nunit/SauceLabs.Visual.Example/SauceDemo.cs index 64b39fed..0521cc89 100644 --- a/dotnet-nunit/SauceLabs.Visual.Example/SauceDemo.cs +++ b/dotnet-nunit/SauceLabs.Visual.Example/SauceDemo.cs @@ -30,7 +30,7 @@ public async Task Setup() { Name = "My Visual Build", Project = "csharp-project", - Branch = "csharp-branch" + Branch = Environment.GetEnvironmentVariable("SAUCE_VISUAL_BRANCH_NAME") ?? "main" }); VisualClient.CaptureDom = true; TestContext.Progress.WriteLine($"Build: {VisualClient.Build.Url}"); diff --git a/dotnet-xunit/Dockerfile b/dotnet-xunit/Dockerfile index 28f373a8..b9d41532 100644 --- a/dotnet-xunit/Dockerfile +++ b/dotnet-xunit/Dockerfile @@ -21,5 +21,9 @@ WORKDIR /workspace COPY . . +ARG GITHUB_RUN_ID +ARG GITHUB_RUN_ATTEMPT +ARG SAUCE_VISUAL_BRANCH_NAME=${GITHUB_RUN_ID}${GITHUB_RUN_ATTEMPT} + RUN --mount=type=secret,id=dotenv,target=/workspace/.env env $(cat /workspace/.env | xargs) runme run dotnet-test RUN --mount=type=secret,id=dotenv,target=/workspace/.env env $(cat /workspace/.env | xargs) runme run dotnet-test-modified diff --git a/dotnet-xunit/README.md b/dotnet-xunit/README.md index ddd69302..6105e4c2 100644 --- a/dotnet-xunit/README.md +++ b/dotnet-xunit/README.md @@ -37,182 +37,6 @@ MODIFIED=true dotnet test - Open the test or go to https://app.saucelabs.com/visual/builds to review changes. -## How to add visual testing to your setup +## Installation & Usage -- Add [sauce visual](https://www.nuget.org/packages/SauceLabs.Visual/) dependency -```powershell {"id":"01HHQ3FQDWBD7ZSD2PQKG2AKDZ"} -dotnet add package SauceLabs.Visual -``` - -- Declare a RemoteWebDriver and a VisualApi instance as class variables - -```csharp {"id":"01HHQ3FQDWBD7ZSD2PQQ2E5HSZ"} -using OpenQA.Selenium.Remote; -using SauceLabs.Visual; - -private RemoteWebDriver Driver { get; set; } -private VisualClient VisualClient { get; set; } -``` - -- Initialize WebDriver and VisualApi in `[OneTimeSetUp]` method - -```csharp {"id":"01HHQ3FQDWBD7ZSD2PQTRQSGV3"} - public async Task InitializeAsync() - { - var browserOptions = Utils.GetBrowserOptions(); - var sauceOptions = Utils.GetSauceOptions(); - browserOptions.AddAdditionalOption("sauce:options", sauceOptions); - - var sauceUrl = Utils.GetOnDemandURL(); - Driver = new RemoteWebDriver(sauceUrl, browserOptions); - Driver.ExecuteScript("sauce:job-name=xUnit C#/.Net Visual Session"); - - VisualClient = await VisualClient.Create(Driver, Region.UsWest1, new CreateBuildOptions() - { - Name = "My Visual Build", - Project = "csharp-project", - Branch = "csharp-branch" - }); - // Enable other options - VisualClient.CaptureDom = true; - } -``` - -- Add a check to one of your tests: - -```csharp {"id":"01HHQ3FQDWBD7ZSD2PQZQMJRH1"} -await VisualClient.VisualCheck("My login page") -``` - -- Don't forget to quit the WebDriver in the `DisposeAsync` method - -```csharp {"id":"01HHQ3FQDWBD7ZSD2PR1PW1V54"} - public async Task DisposeAsync() - { - Driver?.Quit(); - VisualClient.Dispose(); - } -``` - -- To ensure all builds are closed after all your tests were run, a xUnit collection fixture has to be created. -```csharp {"id":"01HHQ3FQDWBD7ZSD2PR1PW1V54"} - public class HasVisualScreenshot : IAsyncLifetime - { - public Task InitializeAsync() - { - return Task.CompletedTask; - } - - public async Task DisposeAsync() - { - await VisualClient.Finish(); - } - } - - [CollectionDefinition("HasVisualScreenshot")] - public class HasVisualScreenshotCollection : ICollectionFixture - { - } -``` -Then, your test classes needs attached to that collection: -```csharp {"id":"01HHQ3FQDWBD7ZSD2PR1PW1V54"} - [Collection("HasVisualScreenshot")] - public class SauceDemo : IAsyncLifetime - { - [...] - } -``` - -- Configure with your Sauce credentials from https://app.saucelabs.com/user-settings. - -```sh {"id":"01HHQ3FQDWBD7ZSD2PR4Y27KEQ"} -export SAUCE_USERNAME=__YOUR_SAUCE_USERNAME__ -export SAUCE_ACCESS_KEY=__YOUR_SAUCE_ACCESS_KEY__ -``` - -- Run the test the way you are used to. - -## Advanced usage - -### Test results summary - -`VisualClient.VisualResults()` returns a summary of test results in `Dictionnary` 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 - -Sample usage: - -```csharp -var expectedTotalUnapprovedDiffs = 0; - -var results = await VisualClient.VisualResults(); -Assert.AreEqual(expectedTotalUnapprovedDiffs, results[DiffStatus.Unapproved]); -``` - -### 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 a `CreateBuildOptions` object. - -Properties available: -- `string? Name`: The name of the build -- `string? Project`: The name of the project -- `string? Branch`: The name of the branch -- `string? CustomId`: A customId to be able to retrieve the current build -- `string? DefaultBranch`: The name of the default branch - -Example: - -```csharp - VisualClient = await VisualClient.Create(Driver, Region.UsWest1, - new CreateBuildOptions() { Name = "My Visual Build", Project = "csharp-project", Branch = "feature-branch" }); -``` - -### 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: - -```csharp -var btnAction = Driver.FindElement(By.CssSelector(".app_logo")); - -await VisualClient.VisualCheck("Inventory Page", - new VisualCheckOptions() - { - IgnoreElements = new[] { btnAction } - }); -``` - -#### 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_ - -Example: - -```csharp -await VisualClient.VisualCheck("Inventory Page", - new VisualCheckOptions() - { - IgnoreRegions = new[] { new IgnoreRegion(10, 10, 100, 100) } - }); -``` - -[Follow me](/wd-java/src/test/java/com/example/InventoryIgnoreRegionsTest.java#L38-L50) to see complete working example \ No newline at end of file +View installation and usage instructions on the [Sauce Docs website](https://docs.saucelabs.com/visual-testing/integrations/csharp/). diff --git a/dotnet-xunit/SauceLabs.Visual.Example/SauceDemo.cs b/dotnet-xunit/SauceLabs.Visual.Example/SauceDemo.cs index 3eb80f57..240ec4bd 100644 --- a/dotnet-xunit/SauceLabs.Visual.Example/SauceDemo.cs +++ b/dotnet-xunit/SauceLabs.Visual.Example/SauceDemo.cs @@ -38,7 +38,7 @@ public async Task InitializeAsync() { Name = "My Visual Build", Project = "csharp-project", - Branch = "csharp-branch" + Branch = Environment.GetEnvironmentVariable("SAUCE_VISUAL_BRANCH_NAME") ?? "main" }); VisualClient.CaptureDom = true; } diff --git a/nightwatch/cucumberjs/README.md b/nightwatch/cucumberjs/README.md index b2b8b3f9..24eea717 100644 --- a/nightwatch/cucumberjs/README.md +++ b/nightwatch/cucumberjs/README.md @@ -78,69 +78,6 @@ SAUCE_REGION=eu-central-1 npm run sauce-visual-check - Open the test or go to https://app.saucelabs.com/visual/builds to review changes. -## How to add visual testing to your setup +## Installation & Usage -- Add sauce visual dependency - -```sh -npm install --save @saucelabs/nightwatch-sauce-visual-service -``` - -- Add the SauceVisualService to your `nightwatch.conf.(js|ts)`: - _Build name can be set through the `buildName` attribute._ - -```ts -module.exports = { - // ... - // Add the service - plugins: [ - // ... other plugins - '@saucelabs/nightwatch-sauce-visual-service', - ], - // ... - test_settings: { - // ... - default: { - // ... - sauceVisualService: { - buildName: 'Nightwatch Visual Demo Test', - project: 'Nightwatch Project', - branch: 'main', - }, - // ... - }, - // ... - }, - // ... -}; -``` - -- Add a check to one of your tests: - -```js -const { Given, When } = require('@cucumber/cucumber'); - -Given(/^I am on the login page$/, function () { - return browser.navigateTo('https://www.saucedemo.com'); -}); - -When(/^I check the page before login$/, function () { - return browser.sauceVisualCheck('Before Login'); -}); -// ... -``` - -- Configure with your Sauce credentials from https://app.saucelabs.com/user-settings. - -```sh -export SAUCE_USERNAME=__YOUR_SAUCE_USER_NAME__ -export SAUCE_ACCESS_KEY=__YOUR_SAUCE_ACCESS_KEY__ -``` - -- Run the test the way you are used to. - -## Docs - -- [Nightwatch](https://nightwatchjs.org/) -- [Sauce Labs Visual](https://docs.saucelabs.com/visual-testing) -- [Nightwatch Sauce Visual Service](https://docs.saucelabs.com/visual-testing/integrations/nightwatch) +View installation and usage instructions on the [Sauce Docs website](https://docs.saucelabs.com/visual-testing/integrations/nightwatch/). diff --git a/nightwatch/default/README.md b/nightwatch/default/README.md index 5e099217..a4a381d4 100644 --- a/nightwatch/default/README.md +++ b/nightwatch/default/README.md @@ -78,68 +78,6 @@ SAUCE_REGION=eu-central-1 npm run sauce-visual-check - Open the test or go to https://app.saucelabs.com/visual/builds to review changes. -## How to add visual testing to your setup +## Installation & Usage -- Add sauce visual dependency - -```sh -npm install --save @saucelabs/nightwatch-sauce-visual-service -``` - -- Add the SauceVisualService to your `nightwatch.conf.(js|ts)`: - _Build name can be set through the `buildName` attribute._ - -```ts -module.exports = { - // ... - // Add the service - plugins: [ - // ... other plugins - '@saucelabs/nightwatch-sauce-visual-service', - ], - // ... - test_settings: { - // ... - default: { - // ... - sauceVisualService: { - buildName: 'Nightwatch Visual Demo Test', - project: 'Nightwatch Project', - branch: 'main', - }, - // ... - }, - // ... - }, - // ... -}; -``` - -- Add a check to one of your tests: - -```ts -import { NightwatchTests } from 'nightwatch'; - -const home: NightwatchTests = { - 'Sauce Demo test': () => { - browser.url('https://saucedemo.com').sauceVisualCheck('Home Page').end(); - }, -}; - -export default home; -``` - -- Configure with your Sauce credentials from https://app.saucelabs.com/user-settings. - -```sh -export SAUCE_USERNAME=__YOUR_SAUCE_USER_NAME__ -export SAUCE_ACCESS_KEY=__YOUR_SAUCE_ACCESS_KEY__ -``` - -- Run the test the way you are used to. - -## Docs - -- [Nightwatch](https://nightwatchjs.org/) -- [Sauce Labs Visual](https://docs.saucelabs.com/visual-testing) -- [Nightwatch Sauce Visual Service](https://docs.saucelabs.com/visual-testing/integrations/nightwatch) +View installation and usage instructions on the [Sauce Docs website](https://docs.saucelabs.com/visual-testing/integrations/nightwatch/). diff --git a/nightwatch/mocha/README.md b/nightwatch/mocha/README.md index fc1753c1..b7f5c46a 100644 --- a/nightwatch/mocha/README.md +++ b/nightwatch/mocha/README.md @@ -78,68 +78,6 @@ SAUCE_REGION=eu-central-1 npm run sauce-visual-check - Open the test or go to https://app.saucelabs.com/visual/builds to review changes. -## How to add visual testing to your setup +## Installation & Usage -- Add sauce visual dependency - -```sh -npm install --save @saucelabs/nightwatch-sauce-visual-service -``` - -- Add the SauceVisualService to your `nightwatch.conf.(js|ts)`: - _Build name can be set through the `buildName` attribute._ - -```ts -module.exports = { - // ... - // Add the service - plugins: [ - // ... other plugins - '@saucelabs/nightwatch-sauce-visual-service', - ], - // ... - test_settings: { - // ... - default: { - // ... - sauceVisualService: { - buildName: 'Nightwatch Visual Demo Test', - project: 'Nightwatch Project', - branch: 'main', - }, - // ... - }, - // ... - }, - // ... -}; -``` - -- Add a check to one of your tests: - -```js -describe('Saucedemo example', function () { - it('Check Home Page - 1', (browser) => { - browser - .url('https://saucedemo.com') - // NOTE: adding the `this` context is required for the service - // to properly pass the suite and test name to Sauce Labs Visual - .sauceVisualCheck('Home Page - 1', this); - }); -}); -``` - -- Configure with your Sauce credentials from https://app.saucelabs.com/user-settings. - -```sh -export SAUCE_USERNAME=__YOUR_SAUCE_USER_NAME__ -export SAUCE_ACCESS_KEY=__YOUR_SAUCE_ACCESS_KEY__ -``` - -- Run the test the way you are used to. - -## Docs - -- [Nightwatch](https://nightwatchjs.org/) -- [Sauce Labs Visual](https://docs.saucelabs.com/visual-testing) -- [Nightwatch Sauce Visual Service](https://docs.saucelabs.com/visual-testing/integrations/nightwatch) +View installation and usage instructions on the [Sauce Docs website](https://docs.saucelabs.com/visual-testing/integrations/nightwatch/). diff --git a/python/no-framework/README.md b/python/no-framework/README.md index 8da44f13..01c1f386 100644 --- a/python/no-framework/README.md +++ b/python/no-framework/README.md @@ -49,3 +49,7 @@ VISUAL_CHECK=1 python test.py - Open the test or go to https://app.saucelabs.com/visual/builds to review changes. - It should detect changes and display differences between the two runs of the inventory page test + +## Installation & Usage + +View installation and usage instructions on the [Sauce Docs website](https://docs.saucelabs.com/visual-testing/integrations/python/). diff --git a/python/robot-framework/README.md b/python/robot-framework/README.md index 3046c9dd..10ae0ee1 100644 --- a/python/robot-framework/README.md +++ b/python/robot-framework/README.md @@ -47,3 +47,7 @@ VISUAL_CHECK=1 robot tests - Open the test or go to https://app.saucelabs.com/visual/builds to review changes. - It should detect changes and display differences between the two runs of the inventory page test + +## Installation & Usage + +View installation and usage instructions on the [Sauce Docs website](https://docs.saucelabs.com/visual-testing/integrations/python-robot-framework/). diff --git a/storybook/Dockerfile b/storybook/Dockerfile index 05feaec1..73996239 100644 --- a/storybook/Dockerfile +++ b/storybook/Dockerfile @@ -32,5 +32,5 @@ COPY . . # The storybook test-runner will exit with a non-zero code on a failed test. This is intended, but # a positive response is required for docker builds -RUN --mount=type=secret,id=dotenv,target=/workspace/.env env $(cat /workspace/.env | xargs) npm run test-storybook:ci +RUN --mount=type=secret,id=dotenv,target=/workspace/.env env $(cat /workspace/.env | xargs) npm run test-storybook:ci || true RUN --mount=type=secret,id=dotenv,target=/workspace/.env env $(cat /workspace/.env | xargs) VISUAL_CHECK=1 npm run test-storybook:ci || true diff --git a/storybook/README.md b/storybook/README.md index 66a61d2a..37b609cf 100644 --- a/storybook/README.md +++ b/storybook/README.md @@ -26,8 +26,8 @@ npm run storybook ```sh { name=set-credentials } export SAUCE_USERNAME=__YOUR_SAUCE_USER_NAME__ export SAUCE_ACCESS_KEY=__YOUR_SAUCE_ACCESS_KEY__ -# You can change the region to upload to via the SAUCE_REGION env variable. See the -# @saucelabs/visual-storybook README for more details on how to customize your run. +# You can change the region to upload to via the SAUCE_REGION env variable. See the +# @saucelabs/visual-storybook README for more details on how to customize your run. ``` - Run the test @@ -44,38 +44,6 @@ npm run test-storybook - Open the test or go to https://app.saucelabs.com/visual/builds to review changes. - It should detect changes and display differences between the two runs of the various stories -### Using different browsers +## Installation & Usage -By default, the tests will be executed on Chromium. If you want to run them on Firefox or Webkit, then please alter [`test-runner-jest.config.js`](./test-runner-jest.config.js) as following - -```ts -const { getJestConfig } = require('@storybook/test-runner'); -const { getVisualTestConfig } = require('@saucelabs/visual-storybook'); - -/** - * @type {import('@jest/types').Config.InitialOptions} - */ -module.exports = { - // The default configuration comes from @storybook/test-runner - ...getJestConfig(), - // The configuration for Sauce Lab's Visual Integration - ...getVisualTestConfig(), - /** Add your own overrides below - * @see https://jestjs.io/docs/configuration - * @see https://github.com/playwright-community/jest-playwright#configuration - */ - // Add this to your configuration to run tests in Chromium, Firefox and Webkit - testEnvironmentOptions: { - 'jest-playwright': { - browsers: ['chromium', 'firefox', 'webkit'], - }, - }, -}; - - -``` - -## How to add visual testing to your setup - -Please consult our `@saucelabs/visual-storybook` documentation on how to set up a Sauce Visual Testing for Storybook. For more details, visit [@saucelabs/visual-storybook -](https://www.npmjs.com/package/@saucelabs/visual-storybook). \ No newline at end of file +View installation and usage instructions on the [Sauce Docs website](https://docs.saucelabs.com/visual-testing/integrations/storybook/). diff --git a/wd-java-testng/README.md b/wd-java-testng/README.md index e804c7e2..315321ad 100644 --- a/wd-java-testng/README.md +++ b/wd-java-testng/README.md @@ -59,166 +59,6 @@ PLATFORM_NAME=ANDROID_EMULATOR ./mvnw clean test - Open the test or go to https://app.saucelabs.com/visual/builds to review changes. -## How to add visual testing to your setup - -- Add [sauce visual](https://central.sonatype.com/artifact/com.saucelabs.visual/java-client) dependency - to your pom.xml - -```xml {"id":"01HHQ3F23DXXD7K4KP6VJ4Z5G4"} - - com.saucelabs.visual - java-client - LATEST VERSION - test - -``` -*Latest available version can be found [here](https://central.sonatype.com/artifact/com.saucelabs.visual/java-client)* - -- Declare a RemoteWebDriver and a VisualApi instance as class variables - -```java {"id":"01HHQ3F23DXXD7K4KP6WQM2PR0"} -private static VisualApi visual; -private static RemoteWebDriver driver; -``` - -- Initialize WebDriver and VisualApi in @BeforeSuite section - -```java {"id":"01HHQ3F23DXXD7K4KP6YG44X4D"} - @BeforeSuite - public static void init() { - driver = new RemoteWebDriver(webDriverUrl, capabilities); - visual = new VisualApi.Builder(driver, sauceUsername, sauceAccessKey, DataCenter.US_WEST_1).build(); - } -``` - -- Add the test meta info listener to your test classes - -```java {"id":"01HHQ3F23DXXD7K4KP6YK3595X"} -import com.saucelabs.visual.testng.TestMetaInfoListener; -import org.testng.annotations.Listeners; - -@Listeners({TestMetaInfoListener.class}) -public class MyTestNGTestClass { - ... -} -``` - -- Add a check to one of your tests: - -```java {"id":"01HHQ3F23DXXD7K4KP71EZ6YBA"} -visual.sauceVisualCheck("My login page") -``` - -- Don't forget to quit the WebDriver in @AfterSuite section - -```java {"id":"01HHQ3F23DXXD7K4KP71STN3PF"} - @AfterSuite - public static void tearDown() { - if (driver != null) { - driver.quit(); - } - } -``` - -- Configure with your Sauce credentials from https://app.saucelabs.com/user-settings. - -```sh {"id":"01HHQ3F23DXXD7K4KP756WJ21R"} -export SAUCE_USERNAME=__YOUR_SAUCE_USERNAME__ -export SAUCE_ACCESS_KEY=__YOUR_SAUCE_ACCESS_KEY__ -``` - -- Run the test the way you are used to. - -## Advanced usage - -### Test results summary - -`VisualApi#sauceVisualResults()` can be used to obtain a summary of test results. The command will make the test wait until the results are calculated and return a summary of `Map` 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 - -`VisualApi#sauceVisualResults()` is particularly useful for composing assertions on the result of each visual test. - -Example: - -```java {"id":"01HHQ3F23DXXD7K4KP76DQRFMY"} - import static org.testng.Assert.assertEquals; - [...] - - var EXPECTED_TOTAL_UNAPPROVED_DIFFS = 0; - - assertEquals(visual.sauceVisualResults().get(DiffStatus.UNAPPROVED), EXPECTED_TOTAL_UNAPPROVED_DIFFS); -``` - -### Build attributes - -When creating the service in `VisualApi`, extra fields can be set to define the context. - -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 {"id":"01HHQ3F23DXXD7K4KP787YF7NF"} - visual = new Builder(driver, sauceUsername, sauceAccessKey, DataCenter.US_WEST_1) - .withBuild("Sauce Demo Test") - .withBranch("main") - .withProject("TestNG + WebDriver examples for " + System.getenv("SAUCE_USERNAME")) - .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 {"id":"01HHQ3F23DXXD7K4KP7B8GA05P"} - Options options = new Options(); - options.setIgnoreElements(List.of( - // AddBackpackToCartButton will be ignored - inventoryPage.getAddBackpackToCartButton() - )); - visual.sauceVisualCheck("Inventory Page", options); -``` - -#### 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* - -Example: - -```java {"id":"01HHQ3F23DXXD7K4KP7F5Y6STP"} - Options options = new Options(); - IgnoreRegion ignoreRegion = new IgnoreRegion( - 100, // x - 100, // y - 200, // width - 200 // height - ); - options.setIgnoreRegions(List.of(ignoreRegion)); - visual.sauceVisualCheck("Before Login", options); -``` +## Installation & Usage -[Follow me](/wd-java-testng/src/test/java/com/example/InventoryIgnoreRegionsTest.java#L38-L50) to see complete working example \ No newline at end of file +View installation and usage instructions on the [Sauce Docs website](https://docs.saucelabs.com/visual-testing/integrations/java/). diff --git a/wd-java/README.md b/wd-java/README.md index 59e375cd..e8a01e80 100644 --- a/wd-java/README.md +++ b/wd-java/README.md @@ -59,198 +59,6 @@ PLATFORM_NAME=ANDROID_EMULATOR ./mvnw clean test - Open the test or go to https://app.saucelabs.com/visual/builds to review changes. -## How to add visual testing to your setup +## Installation & Usage -- Add [sauce visual](https://central.sonatype.com/artifact/com.saucelabs.visual/java-client) dependency - to your pom.xml - -```xml {"id":"01HHQ3FQDWBD7ZSD2PQKG2AKDZ"} - - com.saucelabs.visual - java-client - LATEST VERSION - test - -``` -*Latest available version can be found [here](https://central.sonatype.com/artifact/com.saucelabs.visual/java-client)* - -- Declare a RemoteWebDriver and a VisualApi instance as class variables - -```java {"id":"01HHQ3FQDWBD7ZSD2PQQ2E5HSZ"} -private static VisualApi visual; -private static RemoteWebDriver driver; -``` - -- Initialize WebDriver and VisualApi in @BeforeAll section - -```java {"id":"01HHQ3FQDWBD7ZSD2PQTRQSGV3"} - @BeforeAll - public static void init() { - driver = new RemoteWebDriver(webDriverUrl, capabilities); - visual = new VisualApi.Builder(driver, sauceUsername, sauceAccessKey, DataCenter.US_WEST_1).build(); - } -``` - -- Add the test meta info extension to your test classes - -```java {"id":"01HHQ3FQDWBD7ZSD2PQYF7S96P"} -import com.saucelabs.visual.junit5.TestMetaInfoExtension; -import org.junit.jupiter.api.extension.ExtendWith; - -@ExtendWith({TestMetaInfoExtension.class}) -public class MyJunitTestClass { - ... -} -``` - -- Add a check to one of your tests: - -```java {"id":"01HHQ3FQDWBD7ZSD2PQZQMJRH1"} -visual.sauceVisualCheck("My login page") -``` - -- Don't forget to quit the WebDriver in @AfterAll section - -```java {"id":"01HHQ3FQDWBD7ZSD2PR1PW1V54"} - @AfterAll - public static void tearDown() { - if (driver != null) { - driver.quit(); - } - } -``` - -- Configure with your Sauce credentials from https://app.saucelabs.com/user-settings. - -```sh {"id":"01HHQ3FQDWBD7ZSD2PR4Y27KEQ"} -export SAUCE_USERNAME=__YOUR_SAUCE_USERNAME__ -export SAUCE_ACCESS_KEY=__YOUR_SAUCE_ACCESS_KEY__ -``` - -- Run the test the way you are used to. - -## Advanced usage - -### Test results summary - -`VisualApi#sauceVisualResults()` can be used to obtain a summary of test results. The command will make the test wait until the results are calculated and return a summary of `Map` 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 - -`VisualApi#sauceVisualResults()` is particularly useful for composing assertions on the result of each visual test. - -Example: - -```java {"id":"01HHQ3FQDWBD7ZSD2PR880Q4BH"} - import static org.junit.jupiter.api.Assertions.assertEquals; - [...] - - var EXPECTED_TOTAL_UNAPPROVED_DIFFS = 0 - - assertEquals(EXPECTED_TOTAL_UNAPPROVED_DIFFS, visual.sauceVisualResults().get(DiffStatus.UNAPPROVED)); -``` - -### Build attributes - -When creating the service in `VisualApi`, extra fields can be set to define the context. - -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 {"id":"01HHQ3FQDXM30MYSM6ZCXNMPA1"} - visual = new Builder(driver, sauceUsername, sauceAccessKey, DataCenter.US_WEST_1) - .withBuild("Sauce Demo Test") - .withBranch("main") - .withProject("JUnit + WebDriver 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 {"id":"01HHQ3FQDXM30MYSM6ZDRDA55R"} - Options options = new Options(); - options.setIgnoreElements(List.of( - // AddBackpackToCartButton will be ignored - inventoryPage.getAddBackpackToCartButton() - )); - visual.sauceVisualCheck("Inventory Page", options); -``` - -#### 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* - -Example: - -```java {"id":"01HHQ3FQDXM30MYSM6ZG0N2GHW"} - Options options = new Options(); - IgnoreRegion ignoreRegion = new IgnoreRegion( - 100, // x - 100, // y - 200, // width - 200 // height - ); - options.setIgnoreRegions(List.of(ignoreRegion)); - visual.sauceVisualCheck("Before Login", options); -``` - -[Follow me](./src/test/java/com/example/InventoryIgnoreRegionsTest.java) to see complete working example - -#### Full page screenshots - -If you want to see more than what's on the screen, you can take a full-page screenshot. It'll capture everything by scrolling and stitching it together. - -Options: -- `delayAfterScrollMs`: Delay in ms after scrolling and before taking screenshots (helps with lazy loading content) -- `hideAfterFirstScroll`: Hide elements on the page after first scroll (uses css selectors) - -Examples: - -```java {"id":"01HHQ3FQDXM30MYSM6ZG0N2GHW"} -import com.saucelabs.visual.CheckOptions; - -CheckOptions options = new CheckOptions(); -options.enableFullPageScreenshots(); -visual.sauceVisualCheck("Long content page", options); -``` - -```java {"id":"01HHQ3FQDXM30MYSM6ZG0N2GHW"} -import com.saucelabs.visual.CheckOptions; -import com.saucelabs.visual.model.FullPageScreenshotConfig; - -CheckOptions options = new CheckOptions(); -FullPageScreenshotConfig config = new FullPageScreenshotConfig.Builder() - .withDelayAfterScrollMs(500) - .withHideAfterFirstScroll("#header") - .build(); -options.enableFullPageScreenshots(config); -visual.sauceVisualCheck("Long content page", options); -``` -[Follow me](./src/test/java/com/example/InventoryFullPageTest.java) to see complete working example +View installation and usage instructions on the [Sauce Docs website](https://docs.saucelabs.com/visual-testing/integrations/cypress/). diff --git a/wdio-cucumber/README.md b/wdio-cucumber/README.md index 2a70644a..ee1aa2ac 100644 --- a/wdio-cucumber/README.md +++ b/wdio-cucumber/README.md @@ -90,157 +90,6 @@ SAUCE_REGION=eu-central- npm run sauce-visual-check - Open the test or go to https://app.saucelabs.com/visual/builds to review changes. -## How to add visual testing to your setup +## Installation & Usage -- Add sauce visual dependency - -```sh -npm install --save @saucelabs/wdio-sauce-visual-service -``` - -- Add the SauceVisualService to your `wdio.conf.(js|ts)`: - _Build name can be set through the `buildName` attribute._ - -```ts -... -export const config: Options.Testrunner = { -... - services: [ - // - // This service is needed for WDIO to make sure it can connect to Sauce Labs to: - // - automatically update the names - // - automatically update the status (passed/failed) - // - automatically send the stacktrace in case of a failure - // Install it with `npm install --save-dev @wdio/sauce-service` - // - 'sauce', - // - // This service is needed for the Sauce Visual service to work - // - [ - '@saucelabs/wdio-sauce-visual-service', - { - buildName: 'Sauce Demo Test', - }, - ], - ], -... -} -``` - -- Add a check to one of your tests: - -```ts - describe('Login Flow', () => { - it('should login with valid credentials', async () => { - ... - await browser.sauceVisualCheck('My Login Page') - ... - }); - }) -``` - -- Configure with your Sauce credentials from https://app.saucelabs.com/user-settings. - -```sh -export SAUCE_USERNAME=__YOUR_SAUCE_USER_NAME__ -export SAUCE_ACCESS_KEY=__YOUR_SAUCE_ACCESS_KEY__ -``` - -- Run the test the way you are used to. - -## Advanced Usage - -### Test results summary - -`browser.sauceVisualResults()` can be used to obtain a summary of test results. The command will make the test wait until the results are calculated and return a summary in format: - -```ts -{ - QUEUED: number; // Diffs that are pending for processing. Should be 0 in case the test is completed without any timeouts - EQUAL: number; // Diffs that have no changes detected - UNAPPROVED: number; // Diffs that have detected changes and waiting for action - APPROVED: number; // Diffs that have detected changes and have been approved - REJECTED: number; // Diffs that have detected changes and have been rejected -} -``` - -`browser.sauceVisualResults()` is particularly useful for composing assertions on the result of each visual test. - -Example: - -```ts -const EXPECTED_TOTAL_UNAPPROVED_DIFFS = 0; - -expect((await browser.sauceVisualResults()).UNAPPROVED).toBe( - EXPECTED_TOTAL_UNAPPROVED_DIFFS -); -``` - -### Build attributes - -`buildName`, `branch` and `project` can be defined when adding `SauceVisualService` to your WebdriverIO project, through the `options` parameter. - -Example: - -```ts - services: [ - 'sauce', - [ - '@saucelabs/wdio-sauce-visual-service', - { - buildName: 'Sauce Demo Test', - branch: 'main', - project: 'WDIO examples' - }, - ], - ], -``` - -### 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: - -```ts -await browser.sauceVisualCheck('Inventory Page', { - ignore: [ - // addBackPackToCartButton will be ignored - InventoryPage.addBackPackToCartButton, - ], -}); -``` - -#### 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_ - -Example: - -```ts -await browser.sauceVisualCheck('Before Login', { - ignore: [ - { - x: 100, - y: 100, - width: 200, - height: 200, - }, - ], -}); -``` - -[Follow me](./tests/step-definitions/steps.ts#L30-L47) to see a complete working example +View installation and usage instructions on the [Sauce Docs website](https://docs.saucelabs.com/visual-testing/integrations/webdriverio/). diff --git a/wdio-jasmine/README.md b/wdio-jasmine/README.md index 6a01ff05..78510e0d 100644 --- a/wdio-jasmine/README.md +++ b/wdio-jasmine/README.md @@ -90,157 +90,6 @@ SAUCE_REGION=eu-central-1 npm run sauce-visual-check - Open the test or go to https://app.saucelabs.com/visual/builds to review changes. -## How to add visual testing to your setup +## Installation & Usage -- Add sauce visual dependency - -```sh -npm install --save @saucelabs/wdio-sauce-visual-service -``` - -- Add the SauceVisualService to your `wdio.conf.(js|ts)`: - _Build name can be set through the `buildName` attribute._ - -```ts -... -export const config: Options.Testrunner = { -... - services: [ - // - // This service is needed for WDIO to make sure it can connect to Sauce Labs to: - // - automatically update the names - // - automatically update the status (passed/failed) - // - automatically send the stacktrace in case of a failure - // Install it with `npm install --save-dev @wdio/sauce-service` - // - 'sauce', - // - // This service is needed for the Sauce Visual service to work - // - [ - '@saucelabs/wdio-sauce-visual-service', - { - buildName: 'Sauce Demo Test', - }, - ], - ], -... -} -``` - -- Add a check to one of your tests: - -```ts - describe('Login Flow', () => { - it('should login with valid credentials', async () => { - ... - await browser.sauceVisualCheck('My Login Page') - ... - }); - }) -``` - -- Configure with your Sauce credentials from https://app.saucelabs.com/user-settings. - -```sh -export SAUCE_USERNAME=__YOUR_SAUCE_USER_NAME__ -export SAUCE_ACCESS_KEY=__YOUR_SAUCE_ACCESS_KEY__ -``` - -- Run the test the way you are used to. - -## Advanced Usage - -### Test results summary - -`browser.sauceVisualResults()` can be used to obtain a summary of test results. The command will make the test wait until the results are calculated and return a summary in format: - -```ts -{ - QUEUED: number; // Diffs that are pending for processing. Should be 0 in case the test is completed without any timeouts - EQUAL: number; // Diffs that have no changes detected - UNAPPROVED: number; // Diffs that have detected changes and waiting for action - APPROVED: number; // Diffs that have detected changes and have been approved - REJECTED: number; // Diffs that have detected changes and have been rejected -} -``` - -`browser.sauceVisualResults()` is particularly useful for composing assertions on the result of each visual test. - -Example: - -```ts -const EXPECTED_TOTAL_UNAPPROVED_DIFFS = 0; - -expect((await browser.sauceVisualResults()).UNAPPROVED).toBe( - EXPECTED_TOTAL_UNAPPROVED_DIFFS -); -``` - -### Build attributes - -`buildName`, `branch` and `project` can be defined when adding `SauceVisualService` to your WebdriverIO project, through the `options` parameter. - -Example: - -```ts - services: [ - 'sauce', - [ - '@saucelabs/wdio-sauce-visual-service', - { - buildName: 'Sauce Demo Test', - branch: 'main', - project: 'WDIO Jasmine examples' - }, - ], - ], -``` - -### 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: - -```ts -await browser.sauceVisualCheck('Inventory Page', { - ignore: [ - // addBackPackToCartButton will be ignored - InventoryPage.addBackPackToCartButton, - ], -}); -``` - -#### 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_ - -Example: - -```ts -await browser.sauceVisualCheck('Before Login', { - ignore: [ - { - x: 100, - y: 100, - width: 200, - height: 200, - }, - ], -}); -``` - -[Follow me](./tests/step-definitions/steps.ts#L30-L47) to see a complete working example +View installation and usage instructions on the [Sauce Docs website](https://docs.saucelabs.com/visual-testing/integrations/webdriverio/). diff --git a/wdio/README.md b/wdio/README.md index c5b35b86..d04df7fc 100644 --- a/wdio/README.md +++ b/wdio/README.md @@ -90,158 +90,6 @@ SAUCE_REGION=eu-central-1 npm run sauce-visual-check - Open the test or go to https://app.saucelabs.com/visual/builds to review changes. -## How to add visual testing to your setup +## Installation & Usage -- Add sauce visual dependency - -```sh -npm install --save @saucelabs/wdio-sauce-visual-service -``` - -- Add the SauceVisualService to your `wdio.conf.(js|ts)`: - _Build name can be set through the `buildName` attribute._ - -```ts -... -export const config: Options.Testrunner = { -... - services: [ - // - // This service is needed for WDIO to make sure it can connect to Sauce Labs to: - // - automatically update the names - // - automatically update the status (passed/failed) - // - automatically send the stacktrace in case of a failure - // Install it with `npm install --save-dev @wdio/sauce-service` - // - 'sauce', - // - // This service is needed for the Sauce Visual service to work - // - [ - '@saucelabs/wdio-sauce-visual-service', - { - buildName: 'Sauce Demo Test', - }, - ], - ], -... -} -``` - -- Add a check to one of your tests: - -```ts - describe('Login Flow', () => { - it('should login with valid credentials', async () => { - ... - await browser.sauceVisualCheck('My Login Page') - ... - }); - }) -``` - -- Configure with your Sauce credentials from https://app.saucelabs.com/user-settings. - -```sh -export SAUCE_USERNAME=__YOUR_SAUCE_USER_NAME__ -export SAUCE_ACCESS_KEY=__YOUR_SAUCE_ACCESS_KEY__ -``` - -- Run the test the way you are used to. - -## Advanced Usage - -### Test results summary - -`browser.sauceVisualResults()` can be used to obtain a summary of test results. The command will make the test wait until the results are calculated and return a summary in format: - -```ts -{ - QUEUED: number; // Diffs that are pending for processing. Should be 0 in case the test is completed without any timeouts - EQUAL: number; // Diffs that have no changes detected - UNAPPROVED: number; // Diffs that have detected changes and waiting for action - APPROVED: number; // Diffs that have detected changes and have been approved - REJECTED: number; // Diffs that have detected changes and have been rejected -} -``` - -`browser.sauceVisualResults()` is particularly useful for composing assertions on the result of each visual test. - -Example: - -```ts -const EXPECTED_TOTAL_UNAPPROVED_DIFFS = 0; - -expect((await browser.sauceVisualResults()).UNAPPROVED).toBe( - EXPECTED_TOTAL_UNAPPROVED_DIFFS -); -``` - -### Build attributes - -`buildName`, `branch` and `project` can be defined when adding `SauceVisualService` to your WebdriverIO project, through the `options` parameter. - -Example: - -```ts - services: [ - 'sauce', - [ - '@saucelabs/wdio-sauce-visual-service', - { - buildName: 'Sauce Demo Test', - branch: 'main', - project: 'WDIO examples' - }, - ], - ], -``` - -### 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: - -```ts -await browser.sauceVisualCheck('Inventory Page', { - regions: [ - // All changes will be ignored for addBackPackToCartButton - { - element: InventoryPage.addBackPackToCartButton, - enableOnly: [], - }, - ], -}); -``` - -#### 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_ - -Example: - -```ts -await browser.sauceVisualCheck('Before Login', { - regions: [ - { - element: { x: 100, y: 100, width: 200, height: 200 }, - enableOnly: [], - }, - ], -}); -``` - -[Follow me](/wdio/tests/specs/inventory-ignore-regions.spec.ts#L12-L18) to see a complete working example +View installation and usage instructions on the [Sauce Docs website](https://docs.saucelabs.com/visual-testing/integrations/webdriverio/).