Sauce Visual API lifecycle

docs/visual-testing/_partials/_environment-variables.md

@@ -6,6 +6,6 @@
 | `SAUCE_VISUAL_BUILD_NAME`      |          | The name you would like to appear in the Sauce Visual dashboard.                                                                                                                           |
 | `SAUCE_VISUAL_BRANCH`   |          | The branch name you would like to associate this build with. We recommend using your current VCS branch in CI.                                                                                                            |
 | `SAUCE_VISUAL_DEFAULT_BRANCH`      |          | The main branch name you would like to associate this build with. Usually `main` or `master` or alternatively the branch name your current branch was derived from. [Follow me to learn more](../workflows/ci.md) |
-| `SAUCE_VISUAL_PROJECT`  |          | The label / project you would like to associated this build with.                                                                                                                                                                |
+| `SAUCE_VISUAL_PROJECT`  |          | The label / project you would like to associate this build with.                                                                                                                                                                |
 | `SAUCE_VISUAL_BUILD_ID` |          | For advanced users, a user-supplied SauceLabs Visual build ID. Can be used to create builds in advance using the GraphQL API. This can be used to parallelize tests with multiple browsers, shard, or more. <br/> By default, this is not set and we create / finish a build during setup / teardown. |
 | `SAUCE_VISUAL_CUSTOM_ID` |          | 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.  |

docs/visual-testing/integrations/java.md

@@ -329,7 +329,7 @@ visual.sauceVisualCheck("Before Login", options);
 
 #### Screenshot-wide configuration
 
-<SelectiveDiffingGlobal />=
+<SelectiveDiffingGlobal />
 
 Example:
 
@@ -451,25 +451,6 @@ options.setClipSelector(".your-css-selector");
 visual.sauceVisualCheck("Visible Sale Banner", options);
 ```
 
-#### Selective Diffing (BETA)
-
-[Selective regions](../selective-diffing.md) are an even more powerful way to control diffing.
-
-```java
-EnumSet<DiffingFlag> visualChanges = EnumSet.of(DiffingFlag.Visual);
-
-visual.sauceVisualCheck(
-        "Before Login",
-        new CheckOptions.Builder()
-            .withDiffingMethod(DiffingMethod.BALANCED)
-            .disable(EnumSet.of(DiffingFlag.Position, DiffingFlag.Dimensions))
-            .enable(visualChanges, loginPage.getInputUsername())
-            .disable(visualChanges, loginPage.getInputUsername())
-            .build());
-```
-
-You can find the full example in our [examples repo](#examples).
-
 ## Examples
 
 Two examples are available:

docs/visual-testing/workflows/api-lifecycle.md

@@ -0,0 +1,207 @@
+---
+id: api-lifecycle
+title: API Lifecycle
+sidebar_label: API Lifecycle
+---
+
+# API Lifecycle
+
+This documentation provides a step-by-step guide on how to interact with Sauce Visual API. By following these steps, you'll be able to create builds, upload images, create snapshots, and finish builds. This guide is intended for users who wish to connect directly to the API or implement a binding on their own, including a link to our GraphQL API documentation for further reference.
+
+## What You'll Need
+
+- A Sauce Labs account ([Log in](https://accounts.saucelabs.com/am/XUI/#login/) or sign up for a [free trial license](https://saucelabs.com/sign-up))
+- Familiarity with GraphQL queries and mutations
+- Tools like Postman or cURL for testing API calls
+
+## Lifecycle Steps
+
+### 1. Create a Build
+
+To start, you need to create a build. This initializes the process and prepares the environment for subsequent steps.
+
+**GraphQL Mutation:**
+
+```graphql
+mutation {
+  createBuild(input: { name: "Your Build Name", branch: "Branch name", project: "Project name" }) {
+    id
+    name
+    status
+    url
+  }
+}
+```
+
+- `branch`: Branch name to associate the build with.
+- `project`: Label/project to associate the build with.
+
+**Expected Response:**
+
+```json
+{
+  "data": {
+    "createBuild": {
+      "id": "build-id-here",
+      "name": "Your Build Name",
+      "status": "RUNNING",
+      "url": "https://app.saucelabs.com/visual/builds/build-id-here"
+    }
+  }
+}
+```
+
+- `status`: As a newly created build without any snapshots, this will be `RUNNING`.
+- `url`: The URL that can be used any time to check the build on Sauce Labs.
+
+### 2. Upload Image
+
+Next, upload an image to the build. This is a two step process. 
+
+First, obtain a signed URL for uploading your image by using the `createSnapshotUpload` mutation.
+
+**GraphQL Mutation:**
+
+```graphql
+mutation {
+  createSnapshotUpload(input: {buildId: "build-id-here"}) {
+    id
+    uploadUrl
+    domUploadUrl
+  }
+}
+```
+
+- `buildId`: The ID of the build created in the previous step.
+
+**Expected Response:**
+
+```json
+{
+  "data": {
+    "createSnapshotUpload": {
+      "id": "upload-id-here",
+      "uploadUrl": "image-upload-url-here",
+      "domUploadUrl": "dom-upload-url-here"
+    }
+  }
+}
+```
+
+- `id`: Upload ID to use in the subsequent steps.
+- `uploadUrl`: The URL to upload the image in the next step.
+- `domUploadUrl`: The URL to upload the DOM to (if desired and available). Explained in the optional step below.
+
+Next, send a `PUT` request to `uploadUrl` with image file in the body of the request. Only **PNG** files are supported.
+
+**cURL Request:**
+
+```sh
+curl --request PUT \
+  --url 'upload-url-here' \
+  --header 'Content-MD5: base64-encoded-md5-hash' \
+  --header 'Content-Type: image/png' \
+  --data '@my-screenshot.png'
+```
+
+- `Content-MD5` header: Base64 encoded MD5 hash of the file (`my-screenshot.png`).
+- `Content-Type` header: Must be set to `image/png`. Not other extensions are supported.
+
+Optional: Upload DOM
+
+If desired (and available), DOM can be also uploaded to `domUploadUrl` obtained from `createSnapshotUpload` mutation.
+
+**cURL Request:**
+
+```sh
+curl --request PUT \
+  --url 'dom-upload-url-here' \
+  --header 'Content-MD5: base64-encoded-md5-hash' \
+  --header 'Content-Type: text/html' \
+  --data '@my-dom.html'
+```
+
+- `Content-MD5` header: Base64 encoded MD5 hash of the file (`my-dom.html`).
+- `Content-Type` header: Must be set to `text/html`. Not other extensions are supported.
+
+### 3. Create Snapshot
+
+After uploading your image, add your snapshot along with its metadata to your build.
+
+**GraphQL Mutation:**
+
+```graphql
+mutation {
+  createSnapshot(
+    input: {
+      buildUuid: "build-id-here", 
+      uploadId: "upload-id-here", 
+      name: "Your snapshot name", 
+      operatingSystem: OS,
+      operatingSystemVersion: "os-version",
+      browser: BROWSER,
+      browserVersion: "browser-version"
+    }
+  ) {
+    id
+    uploadId
+  }
+}
+```
+- `buildUuid`: Build ID that was used in previous steps.
+- `uploadId`: Upload ID acquired with `createSnapshotUpload` in the previous step.
+- `operatingSystem`: The operating system used to take the snapshot. Strongly advised to be filled in. Available options: `ANDROID`, `IOS`, `LINUX`, `MACOS`, `WINDOWS`.
+- `operatingSystemVersion`: The operating system version. e.g. "14.5" for `MACOS` or "11" for `WINDOWS`.
+- `browser`: The browser used to take the snapshot. Strongly advised to be filled in (if available). Available options: `CHROME`, `EDGE`, `FIREFOX`, `PLAYWRIGHT_WEBKIT`, `SAFARI`.
+- `browserVersion`: The browser version. e.g. "120.0.6099.318", "128.0.2".
+
+**Expected Response:**
+
+```json
+{
+  "data": {
+    "createSnapshot": {
+      "id": "snapshot-id-here",
+      "uploadId": "upload-id-here"
+    }
+  }
+}
+```
+
+- `id`: The ID of the snapshot that has been created.
+
+### 4. Finish Build
+
+Finally, finish the build to mark it as complete. Keep in mind that this is a necessary step and the build cannot be reused after it's finished.
+
+It's also worth noting that unfinished builds will be automatically closed and set to `ERRORED` state after a certain period of time (default: 3 hours).
+
+**GraphQL Mutation:**
+
+```graphql
+mutation {
+  finishBuild(input: {uuid: "build-id-here"}) {
+    id
+    status
+    url
+  }
+}
+```
+
+**Expected Response:**
+
+```json
+{
+  "data": {
+    "finishBuild": {
+      "id": "build-id-here",
+      "status": "UNAPPROVED",
+      "url": "https://app.saucelabs.com/visual/builds/build-id-here"
+    }
+  }
+}
+```
+
+## Additional Information
+
+For more detailed information about the available queries and mutations, refer to our [GraphQL API documentation](https://api.us-west-1.saucelabs.com/v1/visual/graphql).

docs/visual-testing/workflows/ci.md

@@ -8,14 +8,14 @@ import TabItem from '@theme/TabItem';
 
 # Continuous Integration
 
-To integrate Sauce Visual into your continuous integration workflow we recommend a two-step approach using the sauce visual cli. Sauce visual cli will work with all major CI systems (GitHub, Gitlab, Jenkins, CircleCI).
+To integrate Sauce Visual into your continuous integration workflow we recommend a two-step approach using the [Sauce Visual CLI](../cli.md). Sauce Visual CLI will work with all major CI systems (GitHub, Gitlab, Jenkins, CircleCI).
 
 <img src={useBaseUrl('img/sauce-visual/workflow-ci.png')} alt="Branch Review Pipeline" />
 
 To implement a merge/pull request flow which blocks the given request from merging when visual diffs are detected and not approved do the following:
 
-1. trigger test execution in your ci the way you do it locally. Make sure to pass a custom build id and do not fail your test when visual differences where detected.
-2. in a dedicated build step use the sauce visual cli to fetch the current state of the sauce visual build using the custom build id from step one. It will fail in case visual changes have been detected.
+1. trigger test execution in your CI the way you do it locally. Make sure to pass a custom build ID and do not fail your test when visual differences where detected.
+2. in a dedicated build step use the Sauce Visual CLI to fetch the current state of the Sauce Visual build using the custom build ID from step one. It will fail in case visual changes have been detected.
 
 ```
 # make sure nodejs and npx is available

sidebars.js

@@ -1694,6 +1694,7 @@ module.exports = {
                         'visual-testing/workflows/test-execution',
                         'visual-testing/workflows/review',
                         'visual-testing/workflows/ci',
+                        'visual-testing/workflows/api-lifecycle'
                     ],
                 },
                 {