[@azure/playwright] Add sourceType option for browser session attribution (#38693)

Ek03ansh · EkanshMS03 · web-flow · commit 50d07d73ba5e · 2026-06-04T09:16:43.000Z
### Packages impacted by this PR

@azure/playwright

### Issues associated with this PR

None.

### Describe the problem that is addressed by this PR

Today, `@azure/playwright` always sends
`sourceType=PlaywrightWorkspacesTestRun` on the remote browser WebSocket
URL. The service accepts other `sourceType` values for attributing
browser sessions to the tool that initiated them, but there is no way
for callers to opt in.

This PR adds a public `sourceType` option to
`createAzurePlaywrightConfig` and `getConnectOptions`, so callers can
choose how their sessions are attributed.

### What are the possible designs available to address the problem? If
there are more than one possible design, why was the one in this PR
chosen?

**1. Strict typed union (chosen).** `sourceType?:
BrowserSessionSourceTypeValue` where the union exposes only the
customer-facing values (`PlaywrightWorkspacesTestRun`, `Others`). Typos
are caught at compile time. Default keeps existing behaviour.

**2. Widened union (`BrowserSessionSourceTypeValue | (string &amp; {})`).**
Would allow any string at compile time. Rejected because it makes the
public contract dishonest: customers could type any value, get no IDE
warning, and only see an HTTP 400 at runtime.

**3. Expose all service-side values publicly.** Would advertise internal
product names. Rejected as out of scope for a public type.

### Are there test cases added in this PR? _(If not, why?)_

Yes:
- `test/utils/utils.spec.ts` -- `getServiceWSEndpoint` with and without
`sourceType` arg.
- `test/common/playwrightServiceConfig.spec.ts` -- default field value
and `setOptions` override.
- `test/core/playwrightService.spec.ts` -- end-to-end plumb-through via
`createAzurePlaywrightConfig`, asserting the final `wsEndpoint` contains
the chosen `sourceType` and not the default.

All existing tests that assert `sourceType=PlaywrightWorkspacesTestRun`
in the URL continue to pass since that remains the default.

### Provide a list of related PRs _(if any)_

None.

### Command used to generate this PR:**_(Applicable only to SDK release
request PRs)_

N/A -- this is a feature PR, not a generated release PR.

### Checklists
- [x] Added impacted package name to the issue description
- [x] Does this PR needs any fixes in the SDK Generator? -- No,
hand-authored.
- [x] Added a changelog (if necessary)

### Summary of changes

**Public surface (additive, non-breaking):**
- `sourceType?: BrowserSessionSourceTypeValue` field on
`PlaywrightServiceAdditionalOptions`
- `BrowserSessionSourceTypeValue` exported type resolving to
`"PlaywrightWorkspacesTestRun" | "Others"`

**Behaviour:**
- Default value is `PlaywrightWorkspacesTestRun` -- existing callers see
no change.
- Honoured by both `createAzurePlaywrightConfig` and `getConnectOptions`
via the shared `PlaywrightServiceConfig` singleton.
- `getServiceWSEndpoint` gains a fourth `sourceType` parameter with a
default that preserves backward compatibility for in-tree callers.

**Samples:**
- `customising-service-parameters` (TS + JS) now lists `sourceType`.

Co-authored-by: Ekansh Lavania &lt;ekanshlnu@microsoft.com&gt;
diff --git a/sdk/loadtesting/playwright/CHANGELOG.md b/sdk/loadtesting/playwright/CHANGELOG.md
@@ -4,6 +4,11 @@
 
 ### Features Added
 
+- Added a `sourceType` option to `createAzurePlaywrightConfig` and `getConnectOptions`
+  that sets the `sourceType` query parameter on the remote browser WebSocket
+  endpoint. Supported values are `PlaywrightWorkspacesTestRun` (default) and
+  `Others`. Defaults remain unchanged for existing callers.
+
 ### Breaking Changes
 
 ### Bugs Fixed
diff --git a/sdk/loadtesting/playwright/review/playwright-node.api.md b/sdk/loadtesting/playwright/review/playwright-node.api.md
@@ -16,6 +16,9 @@ export type BrowserConnectOptions = EndpointOptions & {
     options: ConnectOptions;
 };
 
+// @public
+export type BrowserSessionSourceTypeValue = "PlaywrightWorkspacesTestRun" | "Others";
+
 // @public
 export const createAzurePlaywrightConfig: (baseConfig: PlaywrightTestConfig, options?: PlaywrightServiceAdditionalOptions) => PlaywrightTestConfig;
 
@@ -42,6 +45,7 @@ export type PlaywrightServiceAdditionalOptions = {
     credential?: TokenCredential;
     runName?: string;
     apiVersion?: "2025-09-01";
+    sourceType?: BrowserSessionSourceTypeValue;
 };
 
 // @public
diff --git a/sdk/loadtesting/playwright/samples/v1/javascript/customising-service-parameters/playwright.service.config.js b/sdk/loadtesting/playwright/samples/v1/javascript/customising-service-parameters/playwright.service.config.js
@@ -16,6 +16,7 @@ const playwrightServiceAdditionalOptions = {
   useCloudHostedBrowsers: true, // Use cloud hosted browsers
   credential: azureCredential, // Custom token credential for Entra ID authentication
   runName: "JavaScript V1 - Sample Run", // Run name for the test run
+  sourceType: "PlaywrightWorkspacesTestRun", // Identifies the tool that initiated the remote browser sessions
 };
 
 export default defineConfig(
diff --git a/sdk/loadtesting/playwright/samples/v1/typescript/customising-service-parameters/playwright.service.config.ts b/sdk/loadtesting/playwright/samples/v1/typescript/customising-service-parameters/playwright.service.config.ts
@@ -24,6 +24,7 @@ const playwrightServiceAdditionalOptions: PlaywrightServiceAdditionalOptions = {
   useCloudHostedBrowsers: true, // Use cloud hosted browsers
   credential: azureCredential, // Custom token credential for Entra ID authentication
   runName: "Typescript V1 - Sample Run", // Run name for the test run
+  sourceType: "PlaywrightWorkspacesTestRun", // Identifies the tool that initiated the remote browser sessions
 };
 
 export default defineConfig(
diff --git a/sdk/loadtesting/playwright/src/common/constants.ts b/sdk/loadtesting/playwright/src/common/constants.ts
@@ -115,7 +115,8 @@ export const UploadConstants = {
 
 export const BrowserSessionSourceType = {
   PLAYWRIGHT_WORKSPACES_TEST_RUN: "PlaywrightWorkspacesTestRun",
-};
+  OTHERS: "Others",
+} as const;
 
 export const StorageUriValidationConstants = {
   AllowedProtocol: "https:",
diff --git a/sdk/loadtesting/playwright/src/common/playwrightServiceConfig.ts b/sdk/loadtesting/playwright/src/common/playwrightServiceConfig.ts
@@ -2,12 +2,17 @@
 // Licensed under the MIT License.
 
 import {
+  BrowserSessionSourceType,
   Constants,
   DefaultConnectOptionsConstants,
   InternalEnvironmentVariables,
   ServiceAuth,
 } from "./constants.js";
-import type { PlaywrightServiceAdditionalOptions, OsType } from "./types.js";
+import type {
+  BrowserSessionSourceTypeValue,
+  PlaywrightServiceAdditionalOptions,
+  OsType,
+} from "./types.js";
 import type { TokenCredential } from "@azure/identity";
 import { getAndSetRunId, getRunName, ValidateRunID } from "../utils/utils.js";
 import { CIInfoProvider } from "../utils/cIInfoProvider.js";
@@ -22,6 +27,7 @@ class PlaywrightServiceConfig {
   public exposeNetwork: string;
   public runName: string;
   public apiVersion: string;
+  public sourceType: BrowserSessionSourceTypeValue;
   private _serviceAuthType: string = ServiceAuth.ENTRA_ID;
   public credential?: TokenCredential;
 
@@ -35,6 +41,7 @@ class PlaywrightServiceConfig {
     this.exposeNetwork = DefaultConnectOptionsConstants.DEFAULT_EXPOSE_NETWORK;
     this.apiVersion =
       process.env[InternalEnvironmentVariables.MPT_API_VERSION] || Constants.LatestAPIVersion;
+    this.sourceType = BrowserSessionSourceType.PLAYWRIGHT_WORKSPACES_TEST_RUN;
   }
 
   public static get instance(): PlaywrightServiceConfig {
@@ -116,6 +123,9 @@ class PlaywrightServiceConfig {
     if (options?.credential) {
       this.credential = options.credential;
     }
+    if (options?.sourceType) {
+      this.sourceType = options.sourceType;
+    }
   };
 }
 
diff --git a/sdk/loadtesting/playwright/src/common/types.ts b/sdk/loadtesting/playwright/src/common/types.ts
@@ -145,8 +145,25 @@ export type PlaywrightServiceAdditionalOptions = {
    * @defaultValue `2025-09-01`
    */
   apiVersion?: "2025-09-01";
+
+  /**
+   * @public
+   *
+   * Identifies the tool that initiated remote browser sessions, sent to the
+   * service as the `sourceType` query parameter on the WebSocket endpoint.
+   *
+   * @defaultValue `PlaywrightWorkspacesTestRun`
+   */
+  sourceType?: BrowserSessionSourceTypeValue;
 };
 
+/**
+ * @public
+ *
+ * Source identifier values accepted by Azure Playwright for the `sourceType` option.
+ */
+export type BrowserSessionSourceTypeValue = "PlaywrightWorkspacesTestRun" | "Others";
+
 /**
  * @public
  *
diff --git a/sdk/loadtesting/playwright/src/core/playwrightService.ts b/sdk/loadtesting/playwright/src/core/playwrightService.ts
@@ -174,6 +174,7 @@ const createAzurePlaywrightConfig = (
           playwrightServiceConfig.runId,
           playwrightServiceConfig.serviceOs,
           playwrightServiceConfig.apiVersion,
+          playwrightServiceConfig.sourceType,
         ),
         headers: {
           Authorization: `Bearer ${getAccessToken()}`,
@@ -249,6 +250,7 @@ const getConnectOptions = async (
       playwrightServiceConfig.runId,
       playwrightServiceConfig.serviceOs,
       playwrightServiceConfig.apiVersion,
+      playwrightServiceConfig.sourceType,
     ),
     options: {
       headers: {
diff --git a/sdk/loadtesting/playwright/src/index.ts b/sdk/loadtesting/playwright/src/index.ts
@@ -12,6 +12,7 @@ import type {
   OsType,
   AuthenticationType,
   BrowserConnectOptions,
+  BrowserSessionSourceTypeValue,
   EndpointOptions,
   PlaywrightServiceAdditionalOptions,
 } from "./common/types.js";
@@ -26,6 +27,7 @@ export {
   type OsType,
   type AuthenticationType,
   type BrowserConnectOptions,
+  type BrowserSessionSourceTypeValue,
   type EndpointOptions,
   type PlaywrightServiceAdditionalOptions,
 };
diff --git a/sdk/loadtesting/playwright/src/utils/utils.ts b/sdk/loadtesting/playwright/src/utils/utils.ts
@@ -1,7 +1,13 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
-import type { AccessTokenClaims, VersionInfo, JwtPayload, RunConfig } from "../common/types.js";
+import type {
+  AccessTokenClaims,
+  BrowserSessionSourceTypeValue,
+  VersionInfo,
+  JwtPayload,
+  RunConfig,
+} from "../common/types.js";
 import {
   Constants,
   InternalEnvironmentVariables,
@@ -129,8 +135,13 @@ export const getAndSetRunId = (): string => {
   return runId;
 };
 
-export const getServiceWSEndpoint = (runId: string, os: string, apiVersion: string): string => {
-  return `${getServiceBaseURL()}?runId=${encodeURIComponent(runId)}&os=${os}&sourceType=${BrowserSessionSourceType.PLAYWRIGHT_WORKSPACES_TEST_RUN}&api-version=${apiVersion}`;
+export const getServiceWSEndpoint = (
+  runId: string,
+  os: string,
+  apiVersion: string,
+  sourceType: BrowserSessionSourceTypeValue = BrowserSessionSourceType.PLAYWRIGHT_WORKSPACES_TEST_RUN,
+): string => {
+  return `${getServiceBaseURL()}?runId=${encodeURIComponent(runId)}&os=${os}&sourceType=${encodeURIComponent(sourceType)}&api-version=${apiVersion}`;
 };
 
 export const validateServiceUrl = (): void => {
diff --git a/sdk/loadtesting/playwright/test/common/playwrightServiceConfig.spec.ts b/sdk/loadtesting/playwright/test/common/playwrightServiceConfig.spec.ts
@@ -128,6 +128,20 @@ describe("PlaywrightServiceConfig", () => {
     );
     delete process.env[InternalEnvironmentVariables.MPT_SERVICE_RUN_NAME];
   });
+
+  it("should default sourceType to PlaywrightWorkspacesTestRun", () => {
+    const playwrightServiceConfig = new PlaywrightServiceConfig();
+    expect(playwrightServiceConfig.sourceType).to.equal("PlaywrightWorkspacesTestRun");
+  });
+
+  it("should set sourceType from options when provided", () => {
+    const playwrightServiceConfig = new PlaywrightServiceConfig();
+    playwrightServiceConfig.setOptions({
+      sourceType: "Others",
+    });
+    expect(playwrightServiceConfig.sourceType).to.equal("Others");
+  });
+
   it("should use runName from environment variable if already set", () => {
     process.env[InternalEnvironmentVariables.MPT_SERVICE_RUN_NAME] = "existing-run-name";
     const playwrightServiceConfig = new PlaywrightServiceConfig();
diff --git a/sdk/loadtesting/playwright/test/core/playwrightService.spec.ts b/sdk/loadtesting/playwright/test/core/playwrightService.spec.ts
@@ -383,6 +383,22 @@ describe("createAzurePlaywrightConfig", () => {
       credential,
     );
   });
+
+  it("should plumb sourceType from options into the wsEndpoint", async () => {
+    vi.stubEnv(ServiceEnvironmentVariable.PLAYWRIGHT_SERVICE_ACCESS_TOKEN, "token");
+    vi.stubEnv(InternalEnvironmentVariables.MPT_PLAYWRIGHT_VERSION, "1.49.0");
+    const { createAzurePlaywrightConfig: localGetServiceConfig } =
+      await import("../../src/core/playwrightService.js");
+
+    const config = localGetServiceConfig({}, { sourceType: "Others" });
+
+    const wsEndpoint = (config.use?.connectOptions as { wsEndpoint: string }).wsEndpoint;
+    expect(wsEndpoint).toContain("sourceType=Others");
+    expect(wsEndpoint).not.toContain("sourceType=PlaywrightWorkspacesTestRun");
+
+    // Reset singleton sourceType so subsequent tests see the default.
+    PlaywrightServiceConfig.instance.sourceType = "PlaywrightWorkspacesTestRun";
+  });
 });
 
 describe("getConnectOptions", () => {
diff --git a/sdk/loadtesting/playwright/test/utils/utils.spec.ts b/sdk/loadtesting/playwright/test/utils/utils.spec.ts
@@ -186,6 +186,33 @@ describe("Service Utils", () => {
     delete process.env[ServiceEnvironmentVariable.PLAYWRIGHT_SERVICE_URL];
   });
 
+  it("should use the provided sourceType when specified", () => {
+    process.env[ServiceEnvironmentVariable.PLAYWRIGHT_SERVICE_URL] =
+      "wss://eastus.api.playwright.microsoft.com/workspaces/1234/browsers";
+    const runId = "a1b2c3d4-e5f6-47a8-b9c0-d1e2f3a4b5c6";
+    const escapeRunId = encodeURIComponent(runId);
+    const os = "linux";
+    const sourceType = "Others";
+    const expected = `wss://eastus.api.playwright.microsoft.com/workspaces/1234/browsers?runId=${escapeRunId}&os=${os}&sourceType=${sourceType}&api-version=${Constants.LatestAPIVersion}`;
+    expect(getServiceWSEndpoint(runId, os, Constants.LatestAPIVersion, sourceType)).to.equal(
+      expected,
+    );
+
+    delete process.env[ServiceEnvironmentVariable.PLAYWRIGHT_SERVICE_URL];
+  });
+
+  it("should default sourceType to PlaywrightWorkspacesTestRun when omitted", () => {
+    process.env[ServiceEnvironmentVariable.PLAYWRIGHT_SERVICE_URL] =
+      "wss://eastus.api.playwright.microsoft.com/workspaces/1234/browsers";
+    const runId = "a1b2c3d4-e5f6-47a8-b9c0-d1e2f3a4b5c6";
+    const escapeRunId = encodeURIComponent(runId);
+    const os = "linux";
+    const expected = `wss://eastus.api.playwright.microsoft.com/workspaces/1234/browsers?runId=${escapeRunId}&os=${os}&sourceType=PlaywrightWorkspacesTestRun&api-version=${Constants.LatestAPIVersion}`;
+    expect(getServiceWSEndpoint(runId, os, Constants.LatestAPIVersion)).to.equal(expected);
+
+    delete process.env[ServiceEnvironmentVariable.PLAYWRIGHT_SERVICE_URL];
+  });
+
   it("should exit with error message if service url is not set", () => {
     process.env[ServiceEnvironmentVariable.PLAYWRIGHT_SERVICE_URL] = "";
     const exitStub = vi.mocked(process.exit).mockImplementation(() => {
