docs: refresh the complete SHAFT user guide (#915)

Refresh guide content, property references, examples, and documentation quality checks.

Author: MohabMohie

docs/features/test-automation-pillars.mdx

@@ -108,9 +108,13 @@ attachFullLog=true
 Use explicit waits for application states that the browser cannot infer:
 
 ```java title="ReliableStateWait.java"
+import org.openqa.selenium.By;
+import org.openqa.selenium.support.ui.ExpectedConditions;
+
 driver.browser().navigateToURL("https://example.test/orders");
 driver.element().click("Refresh orders");
-driver.element().waitUntilElementTextToBe(By.id("sync-status"), "Complete");
+driver.element().waitUntil(ExpectedConditions.textToBePresentInElementLocated(
+    By.id("sync-status"), "Complete"));
 driver.assertThat(By.id("order-count")).text().isEqualTo("25");
 ```
 

docs/integrations/visual.md

@@ -130,24 +130,24 @@ and image-file operations continue to work.
 | `STRICT_EYES` | High-sensitivity comparison with minor tolerance | UI components |
 | `CONTENT_EYES` | Compares content while ignoring minor rendering differences | Text-heavy pages |
 | `LAYOUT_EYES` | Compares layout structure, ignores content changes | Page layout regression |
-| `OPENCV` | Uses OpenCV for flexible image matching | Complex scenarios, partial matching |
+| `EXACT_OPENCV` | Uses OpenCV for image comparison | OpenCV-based visual checks |
 
 ```java title="VisualTesting.java"
-import com.shaft.enums.internal.VisualValidationEngine;
+import com.shaft.validation.ValidationEnums;
 
 // Assert element matches a reference image (stores baseline on first run)
 driver.element().assertThat(By.id("logo")).matchesReferenceImage();
 
 // Layout comparison — ignores content, checks structure
 driver.element().assertThat(By.id("productCard"))
-      .matchesReferenceImage(VisualValidationEngine.LAYOUT_EYES);
+      .matchesReferenceImage(ValidationEnums.VisualValidationEngine.LAYOUT_EYES);
 ```
 
 When an intentional UI change is made, delete the relevant baseline image from `src/test/resources/DynamicObjectRepository/` and run the test once to regenerate it. Run visual tests in a consistent environment (same OS, browser version, screen resolution) to avoid false positives, and avoid mixing headless and headed baselines.
 
 ## matchesScreenshot()
 
-`matchesScreenshot()` is a lighter-weight, OpenCV-only pixel-diff assertion built into `shaft-engine` (no `shaft-visual` dependency required). Like every other SHAFT assertion it runs immediately — no `perform()` is needed. Pass a `VisualComparisonOptions` object to tune the diff budget and masks, mirroring Playwright's `toHaveScreenshot()` options:
+`matchesScreenshot()` is an OpenCV-only pixel-diff assertion built into `shaft-engine`, so it does not require `shaft-visual`. It runs when you call it. Pass a `VisualComparisonOptions` object to tune the diff budget and masks, mirroring Playwright's `toHaveScreenshot()` options:
 
 ```java title="ScreenshotBaseline.java"
 driver.element().assertThat(By.id("logo"))

docs/reference/actions/API/API_Authentication.md

@@ -2,12 +2,12 @@
 id: API_Authentication
 title: API Authentication
 sidebar_label: API Authentication
-description: "Configure BASIC, DIGEST, OAuth2, API Key, cookie, and session authentication for API tests in SHAFT Engine using setAuthentication and addHeader."
-keywords: [SHAFT, API authentication, basic auth, digest auth, OAuth2, bearer token, API key, cookie auth, REST API]
+description: "Configure BASIC, FORM, OAuth2, API Key, cookie, and session authentication for API tests in SHAFT Engine using setAuthentication and addHeader."
+keywords: [SHAFT, API authentication, basic auth, form auth, OAuth2, bearer token, API key, cookie auth, REST API]
 tags: [api, authentication, security, rest-assured]
 ---
 
-SHAFT Engine supports multiple API authentication strategies through `setAuthentication()` and the fluent request builder. All authentication methods work with the existing `SHAFT.API` request-building API.
+Use `setAuthentication()` for BASIC or FORM authentication. For bearer tokens, API keys, and cookies, add the relevant header before sending the request.
 
 ---
 
@@ -17,25 +17,14 @@ Pass a username and password using `AuthenticationType.BASIC`:
 
 ```java title="APIAuthentication.java"
 import com.shaft.driver.SHAFT;
-import com.shaft.api.RestActions.AuthenticationType;
+import com.shaft.api.RequestBuilder.AuthenticationType;
 
 SHAFT.API api = new SHAFT.API("https://api.example.com");
 
 api.get("/secure/data")
    .setAuthentication("username", "password", AuthenticationType.BASIC)
-   .setTargetStatusCode(200);
-```
-
----
-
-## DIGEST Authentication
-
-Use `AuthenticationType.DIGEST` for digest-challenge protected endpoints:
-
-```java title="APIAuthentication.java"
-api.get("/digest-auth/data")
-   .setAuthentication("user", "pass", AuthenticationType.DIGEST)
-   .setTargetStatusCode(200);
+   .setTargetStatusCode(200)
+   ;
 ```
 
 ---
@@ -47,7 +36,8 @@ Submit credentials as form parameters using `AuthenticationType.FORM`:
 ```java title="APIAuthentication.java"
 api.post("/login")
    .setAuthentication("user@example.com", "password123", AuthenticationType.FORM)
-   .setTargetStatusCode(200);
+   .setTargetStatusCode(200)
+   ;
 ```
 
 ---
@@ -59,7 +49,8 @@ Add the `Authorization` header with a `Bearer` token prefix:
 ```java title="APIAuthentication.java"
 api.get("/oauth/resource")
    .addHeader("Authorization", "Bearer your-oauth-token")
-   .setTargetStatusCode(200);
+   .setTargetStatusCode(200)
+   ;
 ```
 
 ---
@@ -71,15 +62,17 @@ api.get("/oauth/resource")
 ```java title="APIAuthentication.java"
 api.get("/data")
    .addHeader("X-API-Key", "your-api-key")
-   .setTargetStatusCode(200);
+   .setTargetStatusCode(200)
+   ;
 ```
 
 ### API Key in Query Parameter
 
 ```java title="APIAuthentication.java"
 api.get("/data")
-   .addUrlParameter("api_key", "your-api-key")
-   .setTargetStatusCode(200);
+   .setUrlArguments("api_key=your-api-key")
+   .setTargetStatusCode(200)
+   ;
 ```
 
 ---
@@ -91,26 +84,22 @@ Pass a session cookie using `addHeader`:
 ```java title="APIAuthentication.java"
 api.get("/profile")
    .addHeader("Cookie", "session_id=abc123xyz; token=your-session-token")
-   .setTargetStatusCode(200);
+   .setTargetStatusCode(200)
+   ;
 ```
 
 ---
 
-## Persistent Session Authentication
+## Persistent headers and cookies
 
-When `setAuthentication()` is called, the credentials are saved for all subsequent requests in the same `SHAFT.API` session:
+Use `addHeader()` or `addCookie()` on `SHAFT.API` when a token or cookie should be sent with later requests:
 
 ```java title="APIAuthentication.java"
 SHAFT.API api = new SHAFT.API("https://api.example.com");
 
-// Authenticate once — credentials reused for all subsequent requests
-api.get("/login")
-   .setAuthentication("user", "password", AuthenticationType.BASIC);
-
-// These requests automatically include the authentication credentials
+api.addHeader("Authorization", "Bearer your-oauth-token");
+api.addCookie("session_id", "your-session-id");
 api.get("/users").setTargetStatusCode(200);
-api.get("/orders").setTargetStatusCode(200);
-api.get("/profile").setTargetStatusCode(200);
 ```
 
 ---
@@ -119,7 +108,7 @@ api.get("/profile").setTargetStatusCode(200);
 
 ```java title="APIAuthTest.java"
 import com.shaft.driver.SHAFT;
-import com.shaft.api.RestActions.AuthenticationType;
+import com.shaft.api.RequestBuilder.AuthenticationType;
 import org.testng.annotations.Test;
 
 public class APIAuthTest {
@@ -129,10 +118,11 @@ public class APIAuthTest {
         SHAFT.API api = new SHAFT.API("https://httpbin.org");
         api.get("/basic-auth/user/pass")
            .setAuthentication("user", "pass", AuthenticationType.BASIC)
-           .setTargetStatusCode(200);
+           .setTargetStatusCode(200)
+           ;
 
         api.assertThatResponse()
-           .extractedJsonValue("authenticated")
+           .extractedJsonValue("$.authenticated")
            .isEqualTo("true");
     }
 
@@ -141,7 +131,8 @@ public class APIAuthTest {
         SHAFT.API api = new SHAFT.API("https://api.example.com");
         api.get("/protected")
            .addHeader("Authorization", "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...")
-           .setTargetStatusCode(200);
+           .setTargetStatusCode(200)
+           ;
     }
 }
 ```

docs/reference/actions/API/GraphQL_Testing.md

@@ -7,7 +7,7 @@ keywords: [SHAFT, GraphQL, API testing, GraphQL query, variables, fragments, mut
 tags: [api, graphql, rest-assured]
 ---
 
-SHAFT Engine provides first-class GraphQL support through `SHAFT.API.sendGraphQlRequest()`. It returns the normal request builder, so **queries**, **mutations**, variables, fragments, authentication headers, status checks, and response assertions all use the same fluent API as REST requests.
+Use `SHAFT.API.sendGraphQlRequest()` for GraphQL queries and mutations. It returns the normal request builder, so variables, fragments, headers, status checks, and response assertions use the same fluent API as REST requests.
 
 ---
 
@@ -26,7 +26,7 @@ api.sendGraphQlRequest(
 );
 
 // Assert response content
-api.assertThatResponse().extractedJsonValue("data.users").isNotNull();
+api.assertThatResponse().extractedJsonValue("$.data.users").isNotNull();
 ```
 
 ---
@@ -104,7 +104,7 @@ public class GraphQLTest {
 
         api.sendGraphQlRequest("/graphql", "{ users { id name email } }");
 
-        api.assertThatResponse().extractedJsonValue("data.users").isNotNull();
+        api.assertThatResponse().extractedJsonValue("$.data.users").isNotNull();
     }
 
     @Test
@@ -115,7 +115,7 @@ public class GraphQLTest {
 
         api.sendGraphQlRequest("/graphql", query, variables);
 
-        api.assertThatResponse().extractedJsonValue("data.user.email").isNotNull();
+        api.assertThatResponse().extractedJsonValue("$.data.user.email").isNotNull();
     }
 
     @Test
@@ -127,7 +127,7 @@ public class GraphQLTest {
 
         api.sendGraphQlRequest("/graphql", mutation, variables);
 
-        api.assertThatResponse().extractedJsonValue("data.createUser.id").isNotNull();
+        api.assertThatResponse().extractedJsonValue("$.data.createUser.id").isNotNull();
     }
 }
 ```
@@ -146,10 +146,11 @@ SHAFT.API api = new SHAFT.API("https://api.example.com");
 api.post("/graphql")
    .setRequestBody("{\"query\": \"{ users { id name } }\"}")
    .addHeader("Content-Type", "application/json")
-   .setTargetStatusCode(200);
+   .setTargetStatusCode(200)
+   ;
 
 api.assertThatResponse()
-   .extractedJsonValue("data.users[0].name")
+   .extractedJsonValue("$.data.users[0].name")
    .isEqualTo("John Doe");
 ```