@azure/microsoft-playwright-testing/types/microsoft-playwright-testing.d.ts

Package to integrate your Playwright test suite with Microsoft Playwright Testing service

/**
 * Library for integrating Microsoft Playwright Testing with existing playwright projects.
 *
 * @packageDocumentation
 */

import type { PlaywrightTestConfig } from '@playwright/test';
import type { TokenCredential } from '@azure/identity';

/**
 * @public
 *
 * Authentication types supported by Microsoft Playwright Testing.
 */
export declare type AuthenticationType = (typeof ServiceAuth)[keyof typeof ServiceAuth];

/**
 * @public
 *
 * Browser connect options for the service. This includes endpoint options and connect options.
 *
 * @example
 * ```
 * import playwright, { test, expect, BrowserType } from "@playwright/test";
 * import { getConnectOptions, BrowserConnectOptions } from "@azure/microsoft-playwright-testing";
 *
 * 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();
 * });
 * ```
 */
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
     *
     * Exposes network available on the connecting client to the browser being connected to.
     *
     * @defaultValue `<loopback>`
     */
    exposeNetwork?: 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
 *
 * Endpoint options for the service.
 */
export declare type EndpointOptions = {
    /**
     * @public
     *
     * A browser websocket endpoint to connect to.
     */
    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: PlaywrightTestConfig, options?: PlaywrightServiceAdditionalOptions) => PlaywrightTestConfig;

/**
 * @public
 *
 * Optional configuration for MPT Reporter.
 *
 * @example
 *
 * ```
 * import { defineConfig } from "@playwright/test";
 *
 * export default defineConfig({
 *  reporter: [["@azure/microsoft-playwright-testing/reporter", {
 *   enableGitHubSummary: true
 *  }]],
 * });
 * ```
 */
export 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;
}

/**
 * @public
 *
 * OS Types supported by Microsoft Playwright Testing.
 */
export declare type OsType = (typeof ServiceOS)[keyof typeof ServiceOS];

/**
 * @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 { }