Implement fact request specification in BrowserSessionStateExtraction…

CHANGES.md

@@ -1,4 +1,8 @@
 # Changelog
+## [0.64] - 2025-09-11
+### New Features
+- `BrowserSessionStateExtractionConfig` does now accept an optional list of `requestedFacts` that can be used to trigger analysis plugins ("fact agents)".
+
 ## [0.63] - 2025-07-29
 ### Fixes
 - Add ArtifactAssociationType for TestMailAccount

src/main/java/com/testfabrik/webmate/javasdk/browsersession/BrowserSessionClient.java

@@ -30,7 +30,7 @@ public class BrowserSessionClient {
 
     // Sane default Config, extracting DOM and taking non fullpage Screenshots. Otherwise take Webmate Defaults.
     private static final BrowserSessionStateExtractionConfig DefaultStateExtractionConfig = new BrowserSessionStateExtractionConfig(null, null, null, null, null, true,
-                                                                                                                                       new BrowserSessionScreenshotExtractionConfig(true, false), null);
+            new BrowserSessionScreenshotExtractionConfig(true, false), null);
     public interface ActionFunc<T> {
         T op(ActionDelegate action);
     }
@@ -80,7 +80,7 @@ private static class BrowserSessionApiClient extends WebmateApiClient {
         /**
          * Creates an webmate api client.
          *
-         * @param authInfo The authentication information needed for the API interaction
+         * @param authInfo    The authentication information needed for the API interaction
          * @param environment The environment the client should be used in, i.e which urls to use for communication
          */
         public BrowserSessionApiClient(WebmateAuthInfo authInfo, WebmateEnvironment environment) {
@@ -91,8 +91,8 @@ public BrowserSessionApiClient(WebmateAuthInfo authInfo, WebmateEnvironment envi
         /**
          * Creates an webmate api client using a custom HttpClientBuilder, which allows the use of proxies.
          *
-         * @param authInfo The authentication information needed for the API interaction
-         * @param environment The environment the client should be used in, i.e which urls to use for communication
+         * @param authInfo          The authentication information needed for the API interaction
+         * @param environment       The environment the client should be used in, i.e which urls to use for communication
          * @param httpClientBuilder The HttpClientBuilder that is used for the underlying connection.
          */
         public BrowserSessionApiClient(WebmateAuthInfo authInfo, WebmateEnvironment environment, HttpClientBuilder httpClientBuilder) {
@@ -103,22 +103,22 @@ public BrowserSessionApiClient(WebmateAuthInfo authInfo, WebmateEnvironment envi
          * Creates a State for a Browsersession with a matching id. The extraction parameters are set to default.
          *
          * @param browserSessionId The Browsersession Id for which the state should be associated with.
-         * @param matchingId The Id for the state. Used for matching.
+         * @param matchingId       The Id for the state. Used for matching.
          */
         public BrowserSessionStateId createState(BrowserSessionId browserSessionId, String matchingId, BrowserSessionStateExtractionConfig browserSessionStateExtractionConfig) {
-            Map<String, Object>  params = ImmutableMap.of("optMatchingId", matchingId, "extractionConfig", browserSessionStateExtractionConfig);
+            Map<String, Object> params = ImmutableMap.of("optMatchingId", matchingId, "extractionConfig", browserSessionStateExtractionConfig);
             JsonNode body = JsonUtils.getJsonFromData(params, JsonInclude.Include.NON_NULL);
             Optional<HttpResponse> optHttpResponse = sendPOST(createStateTemplate, ImmutableMap.of("browserSessionId", browserSessionId.toString()), body).getOptHttpResponse();
             return HttpHelpers.getObjectFromJsonEntity(optHttpResponse.get(), BrowserSessionStateId.class);
         }
 
         public void startAction(BrowserSessionId expeditionId, StartStoryActionAddArtifactData art) {
-            Map<String, String>  params = ImmutableMap.of("expeditionId", expeditionId.getValueAsString());
+            Map<String, String> params = ImmutableMap.of("expeditionId", expeditionId.getValueAsString());
             sendPOST(addArtifactTemplate, params, JsonUtils.getJsonFromData(art)).getOptHttpResponse();
         }
 
         public void finishAction(BrowserSessionId expeditionId, FinishStoryActionAddArtifactData art) {
-            Map<String, String>  params = ImmutableMap.of("expeditionId", expeditionId.getValueAsString());
+            Map<String, String> params = ImmutableMap.of("expeditionId", expeditionId.getValueAsString());
             sendPOST(addArtifactTemplate, params, JsonUtils.getJsonFromData(art)).getOptHttpResponse();
         }
 
@@ -141,7 +141,7 @@ public BrowserSessionClient(WebmateAPISession session) {
     /**
      * Creates a BrowserSessionClient based on a WebmateApiSession and a custom HttpClientBuilder.
      *
-     * @param session The WebmateApiSession the BrowserSessionClient is supposed to be based on
+     * @param session           The WebmateApiSession the BrowserSessionClient is supposed to be based on
      * @param httpClientBuilder The HttpClientBuilder that is used for building the underlying connection
      */
     public BrowserSessionClient(WebmateAPISession session, HttpClientBuilder httpClientBuilder) {
@@ -165,7 +165,7 @@ public BrowserSessionRef getBrowserSessionForSeleniumSession(String opaqueSeleni
     /**
      * Create a new State for the BrowserSession registered in webmate session (there must be only one).
      *
-     * @param matchingId Label for state (should be unique for BrowserSession, otherwise some tests could get confused).
+     * @param matchingId                          Label for state (should be unique for BrowserSession, otherwise some tests could get confused).
      * @param browserSessionStateExtractionConfig configuration controlling the state extraction process. See {@link BrowserSessionStateExtractionConfig}.
      * @throws WebmateApiClientException if an error occurs while requesting state extraction or if the timeout is exceeded.
      */
@@ -200,7 +200,7 @@ public BrowserSessionStateId createState(String matchingId) {
      * Create a new State for the given BrowserSession.
      *
      * @param browserSessionId BrowserSession, in which the state should be extracted.
-     * @param matchingId Label for state (should be unique for BrowserSession, otherwise some tests could get confused).
+     * @param matchingId       Label for state (should be unique for BrowserSession, otherwise some tests could get confused).
      * @throws WebmateApiClientException if an error occurs while requesting state extraction or if the timeout is exceeded.
      */
     public BrowserSessionStateId createState(BrowserSessionId browserSessionId, String matchingId) {
@@ -210,8 +210,8 @@ public BrowserSessionStateId createState(BrowserSessionId browserSessionId, Stri
     /**
      * Create a new State for the given BrowserSession.
      *
-     * @param browserSessionId BrowserSession, in which the state should be extracted.
-     * @param matchingId Label for state (should be unique for BrowserSession, otherwise some tests could get confused).
+     * @param browserSessionId                    BrowserSession, in which the state should be extracted.
+     * @param matchingId                          Label for state (should be unique for BrowserSession, otherwise some tests could get confused).
      * @param browserSessionStateExtractionConfig configuration controlling the state extraction process. See {@link BrowserSessionStateExtractionConfig}.
      * @throws WebmateApiClientException if an error occurs while requesting state extraction or if the timeout is exceeded.
      */
@@ -394,17 +394,15 @@ public void finishAction() {
     }
 
     /**
-     * @deprecated
-     * This method is deprecated.
+     * @deprecated This method is deprecated.
      * Use {@link BrowserSessionClient#finishAction() finishAction} instead.
      */
     public void finishActionAsSuccessIgnoreNoneActive() {
         finishAction();
     }
 
     /**
-     * @deprecated
-     * This method is deprecated.
+     * @deprecated This method is deprecated.
      * Use {@link BrowserSessionClient#finishActionAsFailure(String) finishActionAsFailure} instead.
      */
     public void finishActionAsFailureIgnoreNoneActive(String errorMessage) {
@@ -426,10 +424,9 @@ public void finishActionAsFailure(String errorMessage) {
     }
 
     /**
-     * @deprecated
-     * This method is deprecated.
-     * It is no longer possible to manually terminate browser sessions.
      * @return False (because no browser session is being terminated successfully).
+     * @deprecated This method is deprecated.
+     * It is no longer possible to manually terminate browser sessions.
      */
     public boolean terminateBrowsersession(BrowserSessionId browserSessionId) {
         LOG.warn("Deprecated method terminateBrowsersession used: it is no longer possible to manually terminate browser sessions");
@@ -438,6 +435,7 @@ public boolean terminateBrowsersession(BrowserSessionId browserSessionId) {
 
     /**
      * Retrieves info for this BrowserSession
+     *
      * @param id The id of the BrowserSession that info should be retrieved for
      * @return BrowserSessionInfo for this BrowserSession
      */

src/main/java/com/testfabrik/webmate/javasdk/browsersession/BrowserSessionStateExtractionConfig.java

@@ -1,18 +1,23 @@
 package com.testfabrik.webmate.javasdk.browsersession;
 
+import com.fasterxml.jackson.annotation.JsonInclude;
 import com.testfabrik.webmate.javasdk.commonutils.Dimension;
 
+import java.util.List;
+
 /**
  * A Wrapper class for proper state extraction Configuration. The different parameters determine the behaviour during
  * state extraction. If parameters are set to null, the default value will be taken. NOTE: In some cases, this means
  * that specific operations are not done, e.g if the warmUpConfig parameter is set to null, the state extraction will
  * not perform a warmup before extracting the state. For further information, please refer to the online documentation.
  */
+@JsonInclude(JsonInclude.Include.NON_NULL)
 public class BrowserSessionStateExtractionConfig {
 
     private BrowserSessionStateId stateId;
     private Integer extractionDelay;
     private Integer extractionCooldown;
+    private List<FactRequest> requestedFacts;
     private Dimension optViewportDimension;
     private Integer maxAdditionWaitingTimeForStateExtraction;
     private Boolean extractDomStateData;
@@ -23,7 +28,7 @@ public class BrowserSessionStateExtractionConfig {
      * Creates a BrowserSessionStateExtractionConfig with all parameters set to null, i.e the choice of parameters is the webmate default.
      */
     public BrowserSessionStateExtractionConfig() {
-        this(null, null, null, null, null, null, null, null);
+        this(null, null, null, null, null, null, null, null, null);
     }
 
     /**
@@ -36,24 +41,49 @@ public BrowserSessionStateExtractionConfig() {
      * @param maxAdditionWaitingTimeForStateExtraction How much additional time the state extraction should get, after the projected end time is reached.
      * @param extractDomStateData wether DOM data should be extracted or not.
      * @param screenShotConfig The configuration for the screenshot extraction. If set to null, the default behaviour is chosen (Take no screenshot)
+     * @param requestedFacts The facts that should be extracted. If set to null, the default behaviour is chosen.
      * @param warmUpConfig The configuration for the warmup. If set to null, the default behaviour is chosen (Do not warm up)
      */
     public BrowserSessionStateExtractionConfig(BrowserSessionStateId stateId, Integer extractionDelay,
                                                Integer extractionCooldown, Dimension optViewportDimension,
                                                Integer maxAdditionWaitingTimeForStateExtraction,
                                                Boolean extractDomStateData,
+                                               List<FactRequest> requestedFacts,
                                                BrowserSessionScreenshotExtractionConfig screenShotConfig,
                                                BrowserSessionWarmUpConfig warmUpConfig) {
         this.stateId = stateId;
         this.extractionDelay = extractionDelay;
         this.extractionCooldown = extractionCooldown;
         this.optViewportDimension = optViewportDimension;
+        this.requestedFacts = requestedFacts;
         this.maxAdditionWaitingTimeForStateExtraction = maxAdditionWaitingTimeForStateExtraction;
         this.extractDomStateData = extractDomStateData;
         this.screenShotConfig = screenShotConfig;
         this.warmUpConfig = warmUpConfig;
     }
 
+    /**
+     * Creates a new StateExtractionConfig.
+     *
+     * @param stateId The Session Id the state should belong to.
+     * @param extractionDelay The delay before state extraction is triggered.
+     * @param extractionCooldown The delay after state extraction is finished.
+     * @param optViewportDimension The dimensions the viewport should be resized to.
+     * @param maxAdditionWaitingTimeForStateExtraction How much additional time the state extraction should get, after the projected end time is reached.
+     * @param extractDomStateData wether DOM data should be extracted or not.
+     * @param screenShotConfig The configuration for the screenshot extraction. If set to null, the default behaviour is chosen (Take no screenshot)
+     * @param warmUpConfig The configuration for the warmup. If set to null, the default behaviour is chosen (Do not warm up)
+     */
+    public BrowserSessionStateExtractionConfig(BrowserSessionStateId stateId, Integer extractionDelay,
+                                                   Integer extractionCooldown, Dimension optViewportDimension,
+                                                   Integer maxAdditionWaitingTimeForStateExtraction,
+                                                   Boolean extractDomStateData,
+                                                   BrowserSessionScreenshotExtractionConfig screenShotConfig,
+                                                   BrowserSessionWarmUpConfig warmUpConfig) {
+        this(stateId, extractionDelay, extractionCooldown, optViewportDimension, maxAdditionWaitingTimeForStateExtraction,
+                extractDomStateData, null, screenShotConfig, warmUpConfig);
+    }
+
     public BrowserSessionStateId getStateId() {
         return stateId;
     }
@@ -94,6 +124,14 @@ public void setMaxAdditionWaitingTimeForStateExtraction(Integer maxAdditionWaiti
         this.maxAdditionWaitingTimeForStateExtraction = maxAdditionWaitingTimeForStateExtraction;
     }
 
+    public List<FactRequest> getRequestedFacts() {
+        return requestedFacts;
+    }
+
+    public void setRequestedFacts(List<FactRequest> requestedFacts) {
+        this.requestedFacts = requestedFacts;
+    }
+
     public Boolean isExtractDomStateData() {
         return extractDomStateData;
     }

src/main/java/com/testfabrik/webmate/javasdk/browsersession/FactParams.java

@@ -0,0 +1,19 @@
+package com.testfabrik.webmate.javasdk.browsersession;
+
+import com.fasterxml.jackson.databind.JsonNode;
+
+public class FactParams {
+    private JsonNode value;
+
+    public FactParams(JsonNode value) {
+        this.value = value;
+    }
+
+    public JsonNode getValue() {
+        return value;
+    }
+
+    public void setValue(JsonNode value) {
+        this.value = value;
+    }
+}

src/main/java/com/testfabrik/webmate/javasdk/browsersession/FactRequest.java

@@ -1,10 +1,41 @@
 package com.testfabrik.webmate.javasdk.browsersession;
 
 public class FactRequest {
-    private FactType type;
+    private FactType factType;
+    private FactParams params;
 
     public FactRequest(FactType type) {
+        this.factType = type;
+    }
+
+    public FactRequest(FactType type, FactParams params) {
+        this.factType = type;
+        this.params = params;
+    }
+
+    public FactType getFactType() {
+        return factType;
+    }
+
+    public void setFactType(FactType type) {
+        this.factType = type;
+    }
 
-        this.type = type;
+    public FactParams getParams() {
+        return params;
     }
+
+    public void setParams(FactParams params) {
+        this.params = params;
+    }
+
+    @Override
+    public String toString() {
+        return "FactRequest{" +
+                "type=" + factType +
+                ", params=" + params +
+                '}';
+    }
+
+
 }

src/main/java/com/testfabrik/webmate/javasdk/browsersession/FactType.java

@@ -1,9 +1,49 @@
 package com.testfabrik.webmate.javasdk.browsersession;
 
+import com.fasterxml.jackson.annotation.JsonCreator;
+import com.fasterxml.jackson.annotation.JsonValue;
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.node.ObjectNode;
+import com.testfabrik.webmate.javasdk.JacksonMapper;
+
 public class FactType {
-    private String name;
+    private String artifactType;
+    private String findingType;
+
+    private FactType(final String artifactTypeName, final String findingTypeName) {
+        this.artifactType = artifactTypeName;
+        this.findingType = findingTypeName;
+    }
+
+    public static FactType fromArtifactType(String artifactTypeName) {
+        return new FactType(artifactTypeName, null);
+    }
+
+    public static FactType fromFindingType(String findingType) {
+        return new FactType(null, findingType);
+    }
+
+    @JsonValue
+    JsonNode toJson() {
+        ObjectMapper om = JacksonMapper.getInstance();
+        ObjectNode root = om.createObjectNode();
+        if (this.artifactType != null) {
+            root.put("artifactType", this.artifactType);
+        } else if (this.findingType != null) {
+            root.put("findingType", this.findingType);
+        }
+        return root;
+    }
 
-    public FactType(final String name) {
-        this.name = name;
+    @JsonCreator
+    static FactType fromJson(JsonNode node) {
+        if (node.has("artifactType")) {
+            return FactType.fromArtifactType(node.get("artifactType").asText());
+        } else if (node.has("findingType")) {
+            return FactType.fromFindingType(node.get("findingType").asText());
+        } else {
+            throw new IllegalArgumentException("Invalid FactType JSON: " + node.toString());
+        }
     }
 }