Class FirestoreRestClient

java.lang.Object
com.shaft.tools.internal.FirestoreRestClient
public class FirestoreRestClient extends Object
FirestoreRestClient handles anonymous usage telemetry for SHAFT Engine.

Each test run sends one test_run event to Google Analytics (GA4) via the Measurement Protocol. The event captures per-test-method outcome counts (passed, failed, skipped, total), engine version, target platform, OS name, and anonymous geographic region — derived automatically by GA4 from the ip_override field, so no separate geo-lookup call is required.

Privacy: no personal data is collected. Only the client IP is forwarded to GA4 (via ip_override) to enable anonymous country-level reporting; the raw IP is not stored by SHAFT. Telemetry can be disabled by setting telemetry.enabled=false in custom.properties.

Identity model:

  • client_id / user_id — a static, persistent UUID stored on disk at src/test/resources/META-INF/services/uuid. It identifies the installation across test runs.
  • session_id (event param) — a dynamic value derived from the epoch-second timestamp at which the current test run started. It uniquely identifies a single test-run session and changes with every execution.

  • Constructor Summary

    Constructors
    Constructor
    Description
    FirestoreRestClient()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    static void
    createCounterDocument(String collectionId, String documentId)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Firestore counters are no longer used for telemetry; GA4 counts events natively.
    static void
    incrementCounter(String collectionId, String documentId)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Firestore counters are no longer used for telemetry; GA4 counts events natively.
    static void
    logEventToAnalytics(String eventName, long executionStartTime, long durationInMilliseconds, int passedTests, int failedTests, int skippedTests, int flakyTests)
    Sends one test_run event to the GA4 Measurement Protocol endpoint.
    static void
    readCounter(String collectionId, String documentId)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Firestore counters are no longer used for telemetry; GA4 counts events natively.
    static void
    sendTelemetry(long executionStartTime, long executionEndTime, int passedTests, int failedTests, int skippedTests, int flakyTests)
    Sends anonymous telemetry data if telemetry is enabled.

    Methods inherited from class Object

    equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • FirestoreRestClient

      public FirestoreRestClient()

  • Method Details

    • sendTelemetry

      public static void sendTelemetry(long executionStartTime, long executionEndTime, int passedTests, int failedTests, int skippedTests, int flakyTests)
      Sends anonymous telemetry data if telemetry is enabled. This method executes asynchronously and will not block test execution. One GA4 analytics event (test_run) is sent, carrying deduplicated per-method outcome counts and key environment dimensions. Network overhead is minimal: only two HTTP calls are made (one to resolve the client IP for geographic attribution, one to the GA4 Measurement Protocol endpoint).
      Parameters:
      executionStartTime - the epoch-millisecond timestamp when the test run began
      executionEndTime - the epoch-millisecond timestamp when the test run finished
      passedTests - the number of unique test methods that passed
      failedTests - the number of unique test methods that failed (never passed)
      skippedTests - the number of unique test methods that were skipped
      flakyTests - the number of test methods that failed on at least one attempt but eventually passed (i.e. retried to success); 0 if none

    • createCounterDocument

      @Deprecated(since="10.2.20260422", forRemoval=true) public static void createCounterDocument(String collectionId, String documentId) throws IOException, InterruptedException
      Deprecated, for removal: This API element is subject to removal in a future version.
      Firestore counters are no longer used for telemetry; GA4 counts events natively.
      Creates a new document with a counter field initialized to 0.
      Parameters:
      collectionId - The collection to create the document in.
      documentId - The ID for the new counter document.
      Throws:
      IOException - in case of a network or IO issue
      InterruptedException - if the operation is interrupted

    • incrementCounter

      @Deprecated(since="10.2.20260422", forRemoval=true) public static void incrementCounter(String collectionId, String documentId) throws IOException, InterruptedException
      Deprecated, for removal: This API element is subject to removal in a future version.
      Firestore counters are no longer used for telemetry; GA4 counts events natively.
      Atomically increments an integer field in a Firestore document.
      Parameters:
      collectionId - The collection containing the counter document.
      documentId - The ID of the counter document.
      Throws:
      IOException - in case of a network or IO issue
      InterruptedException - if the operation is interrupted

    • readCounter

      @Deprecated(since="10.2.20260422", forRemoval=true) public static void readCounter(String collectionId, String documentId) throws IOException, InterruptedException
      Deprecated, for removal: This API element is subject to removal in a future version.
      Firestore counters are no longer used for telemetry; GA4 counts events natively.
      Reads a document and returns its content.
      Parameters:
      collectionId - The collection containing the document.
      documentId - The ID of the document to read.
      Throws:
      IOException - in case of a network or IO issue
      InterruptedException - if the operation is interrupted

    • logEventToAnalytics

      public static void logEventToAnalytics(String eventName, long executionStartTime, long durationInMilliseconds, int passedTests, int failedTests, int skippedTests, int flakyTests) throws IOException, InterruptedException, org.json.JSONException
      Sends one test_run event to the GA4 Measurement Protocol endpoint.

      Network calls made (two total):

      1. checkip.amazonaws.com — resolves the outbound IP so GA4 can attribute the event to the correct country via ip_override.
      2. GA4 Measurement Protocol — posts the event payload.
      No separate geo-lookup service (e.g., ipinfo.io) is called; GA4 derives the country/city automatically from ip_override.

      Identity fields:

      • client_id / user_id — the static installation UUID (persisted on disk). Stable across runs; used for unique-user counting.
      • session_id (event param) — the dynamic epoch-second timestamp of the test-run start. Unique per execution; used for session-scoped analysis.
      Parameters:
      eventName - the name of the event to log (e.g., "test_run")
      executionStartTime - the epoch-millisecond timestamp when the test run began; divided by 1000 to produce the session_id
      durationInMilliseconds - the total execution duration in milliseconds
      passedTests - the number of unique test methods that passed
      failedTests - the number of unique test methods that failed (never passed)
      skippedTests - the number of unique test methods that were skipped
      flakyTests - the number of test methods that failed then passed on retry; 0 if none
      Throws:
      IOException - in case of a network or IO issue
      InterruptedException - if the operation is interrupted
      org.json.JSONException - if the JSON payload cannot be constructed