feat(o11y): stamp testhubBuildUuid + buildProductMap on cypress build caps [SDK-7285]

Cypress is the only SDK line that stamps no TestHub capability at all: 0 of
16,629 sessions carry one across all 32 CLI versions. That leaves it with a
single route into Test Reporting & Analytics -- the BTCER session_hashed_id
fallback -- and that misses ~32.5% of its sessions, which are then counted
against ingestion stability with no build to attach to (2,917 sessions /
0.5882pp in the measured cohort, across 76 accounts).

caps() already runs after build start, so the uuid and the product map are both
in hand; getProductMap() is reused rather than reimplemented, and evaluating it
here reports the products still enabled after the accessibility/observability
gates rather than the ones requested.

Both keys are written unconditionally. The metric treats an absent key and an
empty string identically, so the empty string costs nothing and preserves the
distinction between a cap writer that ran with no build to name and no writer
running at all -- which for cypress is currently unobservable.

Verified end-to-end on production: the build-create POST carries
testhubBuildUuid=xcsouiygyettrxqdxyxmi18qnkyb6alfxqnj8x4z, matching the TestHub
build the run created.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: kamal-kaur04

bin/helpers/capabilityHelper.js

@@ -4,7 +4,8 @@ const { readCypressConfigFile } = require('./readCypressConfigUtil');
 
 const logger = require("./logger").winstonLogger,
   Constants = require("./constants"),
-  Utils = require("./utils");
+  Utils = require("./utils"),
+  testhubUtils = require("../testhub/utils");
 
 const caps = (bsConfig, zip) => {
   return new Promise(function (resolve, reject) {
@@ -131,6 +132,14 @@ const caps = (bsConfig, zip) => {
       obj.run_settings = JSON.stringify(bsConfig.run_settings);
     }
 
+    // The only route by which a cypress session can name its TestHub build: every session
+    // this build spawns inherits these caps. Written unconditionally so an empty uuid records
+    // that build start ran and had nothing to name, which an absent key cannot express.
+    obj.testhubBuildUuid = process.env.BROWSERSTACK_TESTHUB_UUID || "";
+    obj.buildProductMap = testhubUtils.getProductMap(bsConfig);
+
+    logger.debug(`TestHub build uuid stamped on caps: ${obj.testhubBuildUuid || "<empty>"}`);
+
     obj.cypress_cli_user_agent = Utils.getUserAgent();
 
     logger.info(`Cypress CLI User Agent: ${obj.cypress_cli_user_agent}`);

test/unit/bin/helpers/capabilityHelper.js

@@ -5,6 +5,7 @@ const chai = require("chai"),
 
 const capabilityHelper = require("../../../../bin/helpers/capabilityHelper"),
   Constants = require("../../../../bin/helpers/constants"),
+  testhubUtils = require("../../../../bin/testhub/utils"),
   logger = require("../../../../bin/helpers/logger").winstonLogger;
 
 chai.use(chaiAsPromised);
@@ -562,6 +563,70 @@ describe("capabilityHelper.js", () => {
           });
       });
     });
+
+    context("testhub build attribution", () => {
+      const bsConfig = {
+        auth: {
+          username: "random",
+          access_key: "random",
+        },
+        browsers: [
+          {
+            browser: "chrome",
+            os: "Windows 10",
+            versions: ["78"],
+          },
+        ],
+        run_settings: {},
+      };
+      const productMap = {
+        observability: true,
+        accessibility: false,
+        percy: false,
+        automate: true,
+        app_automate: false,
+      };
+      let productMapStub;
+      let originalTesthubUuid;
+
+      beforeEach(() => {
+        originalTesthubUuid = process.env.BROWSERSTACK_TESTHUB_UUID;
+        productMapStub = sinon.stub(testhubUtils, "getProductMap").returns(productMap);
+      });
+
+      afterEach(() => {
+        productMapStub.restore();
+        if (originalTesthubUuid === undefined) {
+          delete process.env.BROWSERSTACK_TESTHUB_UUID;
+        } else {
+          process.env.BROWSERSTACK_TESTHUB_UUID = originalTesthubUuid;
+        }
+      });
+
+      it("stamps the testhub build uuid and the product map on the caps", () => {
+        process.env.BROWSERSTACK_TESTHUB_UUID = "some-testhub-build-uuid";
+        return capabilityHelper
+          .caps(bsConfig, { zip_url: "bs://<random>" })
+          .then(function (data) {
+            let parsed_data = JSON.parse(data);
+            chai.assert.equal(parsed_data.testhubBuildUuid, "some-testhub-build-uuid");
+            chai.assert.deepEqual(parsed_data.buildProductMap, productMap);
+            sinon.assert.calledWith(productMapStub, bsConfig);
+          });
+      });
+
+      it("stamps an empty testhub build uuid when build start produced none", () => {
+        delete process.env.BROWSERSTACK_TESTHUB_UUID;
+        return capabilityHelper
+          .caps(bsConfig, { zip_url: "bs://<random>" })
+          .then(function (data) {
+            let parsed_data = JSON.parse(data);
+            chai.assert.equal(parsed_data.testhubBuildUuid, "");
+            chai.assert.isTrue(Object.prototype.hasOwnProperty.call(parsed_data, "testhubBuildUuid"));
+            chai.assert.deepEqual(parsed_data.buildProductMap, productMap);
+          });
+      });
+    });
   });
 
   describe("addCypressZipStartLocation", () => {