@azure/microsoft-playwright-testing 1.0.0-alpha.20241126.2 → 1.0.0-alpha.20241128.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azure/microsoft-playwright-testing",
-  "version": "1.0.0-alpha.20241126.2",
+  "version": "1.0.0-alpha.20241128.1",
   "description": "Package to integrate your Playwright test suite with Microsoft Playwright Testing service",
   "homepage": "https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/playwrighttesting/microsoft-playwright-testing/README.md",
   "sdk-type": "client",

package/types/microsoft-playwright-testing.d.ts

@@ -1,114 +1,162 @@
 /**
- * Microsoft Playwright Testing's Reporting
- * feature to publish test results and related artifacts and
- * view them in the service portal for faster and easier troubleshooting.
+ * Library for integrating Microsoft Playwright Testing with existing playwright projects.
  *
  * @packageDocumentation
  */
 
-import type { FullConfig } from '@playwright/test/reporter';
-import type { FullResult } from '@playwright/test/reporter';
-import type { Reporter } from '@playwright/test/reporter';
-import type { Suite } from '@playwright/test/reporter';
-import type { TestCase } from '@playwright/test/reporter';
-import type { TestResult } from '@playwright/test/reporter';
+import type { TokenCredential } from '@azure/identity';
 
 /**
  * @public
  *
- * Extends Playwright's Reporter class to enable Microsoft Playwright Testing's Reporting
- * feature to publish test results and related artifacts and
- * view them in the service portal for faster and easier troubleshooting.
+ * Authentication types supported by Microsoft Playwright Testing.
+ */
+export declare type AuthenticationType = (typeof ServiceAuth)[keyof typeof ServiceAuth];
+
+/**
+ * @public
  *
- * @example
+ * Browser connect options for the service. This includes endpoint options and connect options.
  *
+ * @example
  * ```
- * import { defineConfig } from "@playwright/test";
+ * import playwright, { test, expect, BrowserType } from "@playwright/test";
+ * import { getConnectOptions, BrowserConnectOptions } from "@azure/microsoft-playwright-testing";
  *
- * export default defineConfig({
- *  reporter: [["@azure/microsoft-playwright-testing/reporter"]]
+ * test("has title", async ({ browserName }) => {
+ *  const { wsEndpoint, options } : BrowserConnectOptions = await getConnectOptions();
+ *  const browser = await (playwright[browserName] as BrowserType).connect(wsEndpoint, options);
+ *  const context = await browser.newContext();
+ *  const page = await context.newPage();
+ *
+ *  await page.goto("https://playwright.dev/");
+ *  await expect(page).toHaveTitle(/Playwright/);
+ *
+ *  await page.close();
+ *  await context.close();
+ *  await browser.close();
  * });
  * ```
  */
-declare class MPTReporter implements Reporter {
-    private isTokenValid;
-    private enableGitHubSummary;
-    private isRegionValid;
-    private shard;
-    private isTestRunStartSuccess;
-    private ciInfo;
-    private serviceClient;
-    private storageClient;
-    private reporterUtils;
-    private envVariables;
-    private testRawResults;
-    private promiseOnBegin;
-    private _testEndPromises;
-    private testResultBatch;
-    private errorMessages;
-    private informationalMessages;
-    private processedErrorMessageKeys;
-    private sasUri;
-    private uploadMetadata;
-    private numWorkers;
-    private testRunUrl;
-    private enableResultPublish;
-    constructor(config: Partial<MPTReporterConfig>);
-    private _addError;
-    private _addInformationalMessage;
-    private _addKeyToInformationMessage;
-    private _isInformationMessagePresent;
-    private _reporterFailureHandler;
+export declare type BrowserConnectOptions = EndpointOptions & {
+    options: ConnectOptions;
+};
+
+/**
+ * @public
+ *
+ * Connect options for the service.
+ */
+export declare type ConnectOptions = {
+    /**
+     * @public
+     *
+     * Additional HTTP headers to be sent with web socket connect request.
+     */
+    headers?: {
+        [key: string]: string;
+    };
     /**
      * @public
      *
-     * Called once before running tests.
+     * Exposes network available on the connecting client to the browser being connected to.
      *
-     * @param config - Resolved configuration.
-     * @param suite - The root suite that contains all projects, files and test cases.
+     * @defaultValue `<loopback>`
      */
-    onBegin(config: FullConfig, suite: Suite): void;
+    exposeNetwork?: string;
     /**
      * @public
      *
-     * Called after a test has been finished in the worker process.
+     * Maximum time in milliseconds to wait for the connection to be established.
      *
-     * @param test - Test that has been finished.
-     * @param result - Result of the test run.
+     * @defaultValue `30000`
      */
-    onTestEnd(test: TestCase, result: TestResult): void;
+    timeout?: number;
     /**
      * @public
      *
-     * Called after all tests have been run, or testing has been interrupted. Note that this method may return a [Promise]
-     * and Playwright Test will await it. Reporter is allowed to override the status and hence affect the exit code of the
-     * test runner.
+     * Slows down Playwright operations by the specified amount of milliseconds.
      *
-     * @param result - Result of the full test run, `status` can be one of:
-     * - `'passed'` - Everything went as expected.
-     * - `'failed'` - Any test has failed.
-     * - `'timedout'` - The
-     * {@link https://playwright.dev/docs/api/class-testconfig#test-config-global-timeout | testConfig.globalTimeout} has
-     * been reached.
-     * - `'interrupted'` - Interrupted by the user.
+     * @defaultValue `0`
      */
-    onEnd(result: FullResult): Promise<void>;
-    private _onBegin;
-    private _onTestEnd;
-    private _onEnd;
-    private _uploadTestResultAttachments;
-    private initializeMPTReporter;
-    private displayAdditionalInformation;
-    private processTestResult;
+    slowMo?: number;
+};
+
+/**
+ * @public
+ *
+ * Endpoint options for the service.
+ */
+export declare type EndpointOptions = {
     /**
      * @public
      *
-     * Whether this reporter uses stdio for reporting. When it does not, Playwright Test could add some output to enhance
-     * user experience. If your reporter does not print to the terminal, it is strongly recommended to return `false`.
+     * A browser websocket endpoint to connect to.
      */
-    printsToStdio(): boolean;
-}
-export default MPTReporter;
+    wsEndpoint: string;
+};
+
+/**
+ * @public
+ *
+ * Get connect options required to connect to Microsoft Playwright Testing's cloud hosted browsers.
+ *
+ * @param options - additional options for the service
+ * @returns BrowserConnectOptions
+ *
+ * @example
+ * ```
+ * import playwright, { test, expect, BrowserType } from "@playwright/test";
+ * import { getConnectOptions } from "@azure/microsoft-playwright-testing";
+ *
+ * test('has title', async ({ browserName }) => {
+ *  const { wsEndpoint, options } = await getConnectOptions();
+ *  const browser = await (playwright[browserName] as BrowserType).connect(wsEndpoint, options);
+ *  const context = await browser.newContext();
+ *  const page = await context.newPage();
+ *
+ *  await page.goto('https://playwright.dev/');
+ *  await expect(page).toHaveTitle(/Playwright/);
+ *
+ *  await page.close();
+ *  await context.close();
+ *  await browser.close();
+ * });
+ * ```
+ */
+export declare const getConnectOptions: (options?: Omit<PlaywrightServiceAdditionalOptions, "serviceAuthType">) => Promise<BrowserConnectOptions>;
+
+/**
+ * @public
+ *
+ * Generate playwright configuration integrated with Microsoft Playwright Testing.
+ *
+ * @param config - base playwright configuration
+ * @param options - additional options for the service
+ * @returns PlaywrightConfig
+ *
+ * @example
+ * ```
+ * import { defineConfig } from "playwright/test";
+ * import { getServiceConfig } from "@azure/microsoft-playwright-testing";
+ * import playwrightConfig from "./playwright.config";
+ *
+ * export default defineConfig(playwrightConfig, getServiceConfig(playwrightConfig));
+ * ```
+ *
+ * @example
+ * ```
+ * import { defineConfig } from "playwright/test";
+ * import { getServiceConfig, ServiceOS } from "@azure/microsoft-playwright-testing";
+ * import playwrightConfig from "./playwright.config";
+ *
+ * export default defineConfig(playwrightConfig, getServiceConfig(playwrightConfig, {
+ *  runId: "custom run id",
+ *  os: ServiceOS.WINDOWS
+ * }));
+ * ```
+ */
+export declare const getServiceConfig: (config: PlaywrightConfigInput, options?: PlaywrightServiceAdditionalOptions) => PlaywrightConfig;
 
 /**
  * @public
@@ -127,7 +175,7 @@ export default MPTReporter;
  * });
  * ```
  */
-declare interface MPTReporterConfig {
+export declare interface MPTReporterConfig {
     /**
      * @public
      *
@@ -146,4 +194,166 @@ declare interface MPTReporterConfig {
     enableResultPublish?: boolean;
 }
 
+/**
+ * @public
+ *
+ * OS Types supported by Microsoft Playwright Testing.
+ */
+export declare type OsType = (typeof ServiceOS)[keyof typeof ServiceOS];
+
+/**
+ * @public
+ *
+ * Playwright configuration integrated with Microsoft Playwright Testing.
+ *
+ * @remarks
+ *
+ * GlobalSetup and globalTeardown wraps around any existing global setup
+ * and teardown present in the base playwright configuration and runs it.
+ */
+export declare type PlaywrightConfig = {
+    use?: {
+        connectOptions: BrowserConnectOptions;
+    };
+    globalSetup?: string | string[];
+    globalTeardown?: string | string[];
+};
+
+/**
+ * @public
+ *
+ * Base playwright configuration inputs required for generating the service config.
+ */
+export declare type PlaywrightConfigInput = {
+    /**
+     * @public
+     *
+     * Path to the global setup file. This file will be required and run before all the tests. It must export a single
+     * function that takes a [`TestConfig`] argument.
+     *
+     * Learn more about {@link https://playwright.dev/docs/test-global-setup-teardown | global setup and teardown}.
+     */
+    globalSetup?: string | string[];
+    /**
+     * @public
+     *
+     * Path to the global teardown file. This file will be required and run after all the tests. It must export a single
+     * function. See also
+     * {@link https://playwright.dev/docs/api/class-testconfig#test-config-global-teardown | testConfig.globalTeardown}.
+     *
+     * Learn more about {@link https://playwright.dev/docs/test-global-setup-teardown | global setup and teardown}.
+     */
+    globalTeardown?: string | string[];
+};
+
+/**
+ * @public
+ *
+ * Additional options for the service.
+ */
+export declare type PlaywrightServiceAdditionalOptions = {
+    /**
+     * @public
+     *
+     * Authentication types supported by Microsoft Playwright Testing.
+     *
+     * @defaultValue  `ENTRA_ID`
+     */
+    serviceAuthType?: AuthenticationType;
+    /**
+     * @public
+     *
+     * Operating system types supported by Microsoft Playwright Testing.
+     *
+     * @defaultValue  `linux`
+     */
+    os?: OsType;
+    /**
+     * @public
+     *
+     * Run id for the test run.
+     *
+     * @defaultValue `current datetime as ISO string`
+     */
+    runId?: string;
+    /**
+     * @public
+     *
+     * Maximum time in milliseconds to wait for the connection to be established.
+     *
+     * @defaultValue `30000`
+     */
+    timeout?: number;
+    /**
+     * @public
+     *
+     * Slows down Playwright operations by the specified amount of milliseconds.
+     *
+     * @defaultValue `0`
+     */
+    slowMo?: number;
+    /**
+     * @public
+     *
+     * Exposes network available on the connecting client to the browser being connected to.
+     *
+     * @defaultValue `<loopback>`
+     */
+    exposeNetwork?: string;
+    /**
+     * @public
+     *
+     * Use cloud hosted browsers.
+     *
+     * @defaultValue `false`
+     */
+    useCloudHostedBrowsers?: boolean;
+    /**
+     * @public
+     *
+     * Custom token credential for Entra ID authentication. Learn more at {@link https://github.com/Azure/azure-sdk-for-js/blob/main/documentation/using-azure-identity.md | Using Azure Identity}.
+     *
+     * @defaultValue `DefaultAzureCredential`
+     */
+    credential?: TokenCredential;
+    /**
+     * @public
+     *
+     * Run name for the test run.
+     *
+     * @defaultValue `guid`
+     */
+    runName?: string;
+};
+
+/** @public
+ *
+ * Authentication types supported on Microsoft Playwright Testing
+ */
+export declare const ServiceAuth: {
+    readonly ENTRA_ID: "ENTRA_ID";
+    readonly ACCESS_TOKEN: "ACCESS_TOKEN";
+};
+
+/** @public
+ *
+ * Environment variables used by Microsoft Playwright Testing
+ */
+export declare const ServiceEnvironmentVariable: {
+    PLAYWRIGHT_SERVICE_OS: string;
+    PLAYWRIGHT_SERVICE_EXPOSE_NETWORK_ENVIRONMENT_VARIABLE: string;
+    PLAYWRIGHT_SERVICE_ACCESS_TOKEN: string;
+    PLAYWRIGHT_SERVICE_URL: string;
+    PLAYWRIGHT_SERVICE_REPORTING_URL: string;
+};
+
+/** @public
+ *
+ * OS types supported on Microsoft Playwright Testing cloud hosted browsers
+ */
+export declare const ServiceOS: {
+    readonly LINUX: "linux";
+    readonly WINDOWS: "windows";
+};
+
 export { }

package/types/reporter/microsoft-playwright-testing.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Microsoft Playwright Testing's Reporting
+ * feature to publish test results and related artifacts and
+ * view them in the service portal for faster and easier troubleshooting.
+ *
+ * @packageDocumentation
+ */
+
+import type { FullConfig } from '@playwright/test/reporter';
+import type { FullResult } from '@playwright/test/reporter';
+import type { Reporter } from '@playwright/test/reporter';
+import type { Suite } from '@playwright/test/reporter';
+import type { TestCase } from '@playwright/test/reporter';
+import type { TestResult } from '@playwright/test/reporter';
+
+/**
+ * @public
+ *
+ * Extends Playwright's Reporter class to enable Microsoft Playwright Testing's Reporting
+ * feature to publish test results and related artifacts and
+ * view them in the service portal for faster and easier troubleshooting.
+ *
+ * @example
+ *
+ * ```
+ * import { defineConfig } from "@playwright/test";
+ *
+ * export default defineConfig({
+ *  reporter: [["@azure/microsoft-playwright-testing/reporter"]]
+ * });
+ * ```
+ */
+declare class MPTReporter implements Reporter {
+    private isTokenValid;
+    private enableGitHubSummary;
+    private isRegionValid;
+    private shard;
+    private isTestRunStartSuccess;
+    private ciInfo;
+    private serviceClient;
+    private storageClient;
+    private reporterUtils;
+    private envVariables;
+    private testRawResults;
+    private promiseOnBegin;
+    private _testEndPromises;
+    private testResultBatch;
+    private errorMessages;
+    private informationalMessages;
+    private processedErrorMessageKeys;
+    private sasUri;
+    private uploadMetadata;
+    private numWorkers;
+    private testRunUrl;
+    private enableResultPublish;
+    constructor(config: Partial<MPTReporterConfig>);
+    private _addError;
+    private _addInformationalMessage;
+    private _addKeyToInformationMessage;
+    private _isInformationMessagePresent;
+    private _reporterFailureHandler;
+    /**
+     * @public
+     *
+     * Called once before running tests.
+     *
+     * @param config - Resolved configuration.
+     * @param suite - The root suite that contains all projects, files and test cases.
+     */
+    onBegin(config: FullConfig, suite: Suite): void;
+    /**
+     * @public
+     *
+     * Called after a test has been finished in the worker process.
+     *
+     * @param test - Test that has been finished.
+     * @param result - Result of the test run.
+     */
+    onTestEnd(test: TestCase, result: TestResult): void;
+    /**
+     * @public
+     *
+     * Called after all tests have been run, or testing has been interrupted. Note that this method may return a [Promise]
+     * and Playwright Test will await it. Reporter is allowed to override the status and hence affect the exit code of the
+     * test runner.
+     *
+     * @param result - Result of the full test run, `status` can be one of:
+     * - `'passed'` - Everything went as expected.
+     * - `'failed'` - Any test has failed.
+     * - `'timedout'` - The
+     * {@link https://playwright.dev/docs/api/class-testconfig#test-config-global-timeout | testConfig.globalTimeout} has
+     * been reached.
+     * - `'interrupted'` - Interrupted by the user.
+     */
+    onEnd(result: FullResult): Promise<void>;
+    private _onBegin;
+    private _onTestEnd;
+    private _onEnd;
+    private _uploadTestResultAttachments;
+    private initializeMPTReporter;
+    private displayAdditionalInformation;
+    private processTestResult;
+    /**
+     * @public
+     *
+     * Whether this reporter uses stdio for reporting. When it does not, Playwright Test could add some output to enhance
+     * user experience. If your reporter does not print to the terminal, it is strongly recommended to return `false`.
+     */
+    printsToStdio(): boolean;
+}
+export default MPTReporter;
+
+/**
+ * @public
+ *
+ * Optional configuration for MPT Reporter.
+ *
+ * @example
+ *
+ * ```
+ * import { defineConfig } from "@playwright/test";
+ *
+ * export default defineConfig({
+ *  reporter: [["@azure/microsoft-playwright-testing/reporter", {
+ *   enableGitHubSummary: true
+ *  }]],
+ * });
+ * ```
+ */
+declare interface MPTReporterConfig {
+    /**
+     * @public
+     *
+     * Enable GitHub Actions annotations to diagnose test failures and deep link to MPT Portal.
+     *
+     * @defaultValue `true`
+     */
+    enableGitHubSummary?: boolean;
+    /**
+     * @public
+     *
+     * Enable result publishing for the test run. This will upload the test result and artifacts to the MPT Portal.
+     *
+     * @defaultValue `true`
+     */
+    enableResultPublish?: boolean;
+}
+
+export { }