@sfcicd/browser/dist/index.d.ts

Browser automation library based on Playwright, designed for Salesforce CI/CD use cases.

import { BrowserContextOptions, Response, Browser as PwBrowser, LaunchOptions, BrowserType as PwBrowserType, BrowserContext as PwBrowserContext, BrowserServer, ConnectOverCDPOptions, ConnectOptions, Page as PwPage, FrameLocator } from "playwright";
import { Org } from "@salesforce/core";
/**
 * https://help.salesforce.com/s/articleView?id=xcloud.domain_name_url_formats.htm&type=5
 */
export type SfUrlType = 'Login' | 'ApplicationPageOrTab' | 'CmsPublicChannel' | 'EmailTracking' | 'Lightning' | 'ExperienceCloudSite' | 'LightningContainer' | 'SalesforceSite' | 'SetupPage' | 'ServiceCloudRealtime' | 'OmniChannel' | 'UserContent' | 'UserContentGovCloud' | 'UserImage' | 'ContentFile' | 'ExperienceBuilder' | 'ExperienceBuilderLivePreview' | 'ExperienceBuilderPreview' | 'Visualforce';
export type GotoOptions = Parameters<PwPage['goto']>[1] & {
    sfPageID?: string;
    sfExperienceCloudSitesSubdomainName?: string;
    sfPackageName?: string;
    sfSitesSubdomainName?: string;
    sfLiveAgentPool?: string;
    sfUniqueID?: string;
};
export declare const chromium: {
    connectOverCDP: (arg1: string | (ConnectOverCDPOptions & {
        wsEndpoint: string;
    }), arg2?: ConnectOverCDPOptions) => Promise<Browser>;
    connect: (arg1: string | (ConnectOptions & {
        wsEndpoint: string;
    }), arg2?: ConnectOptions) => Promise<Browser>;
    executablePath: () => string;
    launch: (options?: LaunchOptions) => Promise<Browser>;
    launchPersistentContext: (userDataDir: string, options?: Parameters<PwBrowserType["launchPersistentContext"]>[1]) => Promise<BrowserContext>;
    launchServer: (options?: Parameters<PwBrowserType["launchServer"]>[0]) => Promise<BrowserServer>;
    name: () => string;
};
export declare const firefox: {
    connectOverCDP: (arg1: string | (ConnectOverCDPOptions & {
        wsEndpoint: string;
    }), arg2?: ConnectOverCDPOptions) => Promise<Browser>;
    connect: (arg1: string | (ConnectOptions & {
        wsEndpoint: string;
    }), arg2?: ConnectOptions) => Promise<Browser>;
    executablePath: () => string;
    launch: (options?: LaunchOptions) => Promise<Browser>;
    launchPersistentContext: (userDataDir: string, options?: Parameters<PwBrowserType["launchPersistentContext"]>[1]) => Promise<BrowserContext>;
    launchServer: (options?: Parameters<PwBrowserType["launchServer"]>[0]) => Promise<BrowserServer>;
    name: () => string;
};
export declare const webkit: {
    connectOverCDP: (arg1: string | (ConnectOverCDPOptions & {
        wsEndpoint: string;
    }), arg2?: ConnectOverCDPOptions) => Promise<Browser>;
    connect: (arg1: string | (ConnectOptions & {
        wsEndpoint: string;
    }), arg2?: ConnectOptions) => Promise<Browser>;
    executablePath: () => string;
    launch: (options?: LaunchOptions) => Promise<Browser>;
    launchPersistentContext: (userDataDir: string, options?: Parameters<PwBrowserType["launchPersistentContext"]>[1]) => Promise<BrowserContext>;
    launchServer: (options?: Parameters<PwBrowserType["launchServer"]>[0]) => Promise<BrowserServer>;
    name: () => string;
};
export type Browser = BrowserExtension & Omit<PwBrowser, 'newPage'>;
/**
 * Wrapper around Playwright Browser with proxy forwarding.
 */
declare class BrowserExtension {
    private browser;
    constructor(browser: PwBrowser);
    /**
     * Creates a proxied instance of BrowserExtension.
     * @param browser Playwright Browser instance
     */
    static create(browser: PwBrowser): Browser;
    /**
     * Creates a new page in a fresh context.
     */
    newPage(options?: BrowserContextOptions): Promise<Page>;
    /**
     * Creates a new browser context.
     * @param options Browser context options
     */
    newContext(options?: BrowserContextOptions): Promise<BrowserContext>;
}
export type BrowserContext = ContextExtension & PwBrowserContext;
/**
 * Wrapper around Playwright BrowserContext with proxy forwarding and added Salesforce login support.
 */
declare class ContextExtension {
    private context;
    private Browser;
    private authedOrgs;
    constructor(browser: Browser, context: PwBrowserContext);
    /**
     * Creates a proxied instance of ContextExtension.
     * @param browser Browser instance
     * @param context Playwright BrowserContext instance
     */
    static create(browser: Browser, context: PwBrowserContext): BrowserContext;
    /**
     * Creates a new page in this context.
     */
    newPage(): Promise<Page>;
    /**
     * Perform a login to Salesforce org on the given page or a new page. Usually you do not have to call login()
     * manually. It is called automatically when navigating to a salesforce page.
     * If you are already logged in the method just returns - except you enforce a re-login.
     * @param org Salesforce Org instance
     * @param reLogin Perform a login even if we already did a login to that org within that browser context
     * @param page Optional page to use for login
     */
    login(org: Org, reLogin?: boolean, page?: PwPage | Page): Promise<void>;
}
export type Page = PageExtension & Omit<PwPage, 'context' | 'create'>;
/**
 * Wrapper around Playwright Page with proxy forwarding and Salesforce URL navigation support.
 */
export declare class PageExtension {
    private page;
    private browserContext;
    constructor(context: BrowserContext, page: PwPage);
    /**
     * Creates a proxied instance of PageExtension.
     * @param context BrowserContext instance
     * @param page Playwright Page instance
     */
    static create(context: BrowserContext, page: PwPage): Page;
    /**
     * Returns a Locator for any iframe on the page.
     */
    anyFrameLocator(): FrameLocator;
    context(): BrowserContext;
    private getPartition;
    /**
     * Navigate to a Salesforce URL built from org, urlType and path.
     * @param userName Username that has been autheticated with a Salesforce org already (with SF CLI)
     * @param urlType Type of Salesforce URL to build
     * @param path Absolute path to navigate to
     * @param options Additional navigation options
     */
    goto(userName: string, urlType: SfUrlType, path: string, options?: GotoOptions): Promise<Response | null>;
    /**
     * https://help.salesforce.com/s/articleView?id=xcloud.domain_name_url_formats.htm&type=5
     * @param urlType
     * @param myDomain
     * @param partition
     * @param sandboxName
     * @param options
     * @param trimmedPath
     * @returns
     */
    private buildSalesforceUrl;
}
export {};