@applitools/core 2.3.1 → 2.3.3

package/types/ufg/types.d.ts

@@ -0,0 +1,71 @@
+import type { MaybeArray } from '@applitools/utils';
+import type * as BaseCore from '@applitools/core-base/types';
+import type * as AutomationCore from '../automation/types';
+import { type SpecType } from '@applitools/driver';
+import { type Logger } from '@applitools/logger';
+import { type Proxy } from '@applitools/req';
+import { type Renderer, type DomSnapshot, type AndroidSnapshot, type IOSSnapshot } from '@applitools/ufg-client';
+export * from '../automation/types';
+export type SnapshotTarget = MaybeArray<DomSnapshot> | MaybeArray<AndroidSnapshot> | MaybeArray<IOSSnapshot>;
+export type Target<TSpec extends SpecType> = SnapshotTarget | AutomationCore.Target<TSpec>;
+export interface Core<TSpec extends SpecType, TTarget = AutomationCore.Target<TSpec>, TEyes extends Eyes<TSpec, TTarget | SnapshotTarget> = Eyes<TSpec, TTarget | SnapshotTarget>> extends AutomationCore.Core<TSpec, TTarget, TEyes> {
+    readonly type: 'ufg';
+    openEyes(options: {
+        target?: AutomationCore.DriverTarget<TSpec>;
+        settings: OpenSettings;
+        eyes?: BaseCore.Eyes[];
+        logger?: Logger;
+    }): Promise<TEyes>;
+}
+export interface Eyes<TSpec extends SpecType, TTarget = Target<TSpec>> extends AutomationCore.Eyes<TSpec, TTarget> {
+    readonly type: 'ufg';
+    getBaseEyes(options?: {
+        settings?: {
+            type: 'web' | 'native';
+            renderer: Renderer;
+        };
+        logger?: Logger;
+    }): Promise<BaseCore.Eyes[]>;
+    check(options?: {
+        target?: TTarget;
+        settings?: CheckSettings<TSpec>;
+        logger?: Logger;
+    }): Promise<CheckResult[]>;
+    checkAndClose(options?: {
+        target?: TTarget;
+        settings?: CheckSettings<TSpec> & AutomationCore.CloseSettings;
+        logger?: Logger;
+    }): Promise<TestResult[]>;
+    getResults(options?: {
+        settings?: AutomationCore.GetResultsSettings;
+        logger?: Logger;
+    }): Promise<TestResult[]>;
+}
+export type OpenSettings = AutomationCore.OpenSettings & {
+    renderConcurrency?: number;
+};
+export type CheckSettings<TSpec extends SpecType> = AutomationCore.CheckSettings<TSpec> & {
+    renderers?: Renderer[];
+    hooks?: {
+        beforeCaptureScreenshot: string;
+    };
+    disableBrowserFetching?: boolean;
+    layoutBreakpoints?: boolean | number[];
+    ufgOptions?: Record<string, any>;
+    nmgOptions?: Record<string, any>;
+    autProxy?: Proxy & {
+        mode?: 'Allow' | 'Block';
+        domains?: string[];
+    };
+};
+export type CheckResult = AutomationCore.CheckResult & {
+    readonly renderer: Renderer;
+    readonly promise: Promise<Omit<CheckResult, 'promise'> & {
+        eyes: BaseCore.Eyes;
+    }>;
+};
+export type TestResult = AutomationCore.TestResult & {
+    readonly renderer: Renderer;
+} & {
+    eyes: BaseCore.Eyes;
+};

package/types/ufg/utils/extract-broker-url.d.ts

@@ -0,0 +1,6 @@
+import { type SpecType, type Driver } from '@applitools/driver';
+import { type Logger } from '@applitools/logger';
+export declare function extractBrokerUrl<TSpec extends SpecType>({ driver, logger, }: {
+    driver: Driver<TSpec>;
+    logger: Logger;
+}): Promise<string | null>;

package/types/ufg/utils/generate-safe-selectors.d.ts

@@ -0,0 +1,16 @@
+import { type SpecType, type Context, type ElementReference, type CommonSelector } from '@applitools/driver';
+export declare function generateSafeSelectors<TSpec extends SpecType>({ context, elementReferences, }: {
+    context: Context<TSpec>;
+    elementReferences: ElementReference<TSpec>[];
+}): Promise<{
+    selectors: ({
+        safeSelector: null;
+        originalSelector: null;
+        elementReference: ElementReference<TSpec>;
+    } | {
+        safeSelector: CommonSelector<never>;
+        originalSelector: import("@applitools/driver").Selector<never> | null;
+        elementReference: ElementReference<TSpec>;
+    })[];
+    cleanupGeneratedSelectors: () => Promise<void>;
+}>;

package/types/ufg/utils/take-dom-snapshot.d.ts

@@ -0,0 +1,49 @@
+import { type Logger } from '@applitools/logger';
+import { type SpecType, type Context } from '@applitools/driver';
+import { type DomSnapshot } from '@applitools/ufg-client';
+type RawDomSnapshot = {
+    url: string;
+    selector: string;
+    cdt: {
+        attributes: {
+            name: string;
+            value: string;
+        }[];
+    }[];
+    crossFrames: {
+        selector: string;
+        index: number;
+    }[];
+    frames: RawDomSnapshot[];
+    resourceUrls: string[];
+    blobs: {
+        url: string;
+        value: string;
+    }[];
+};
+export type DomSnapshotSettings = {
+    disableBrowserFetching?: boolean;
+    skipResources?: string[];
+    chunkByteLength?: number;
+    executionTimeout?: number;
+    pollTimeout?: number;
+    showLogs?: boolean;
+};
+export declare function takeDomSnapshot<TSpec extends SpecType>({ context, settings, logger, }: {
+    context: Context<TSpec>;
+    settings?: DomSnapshotSettings;
+    logger: Logger;
+}): Promise<DomSnapshot>;
+export declare function deserializeDomSnapshot({ snapshot }: {
+    snapshot: RawDomSnapshot;
+}): DomSnapshot;
+export declare function extractCrossFrames({ snapshot, parent, logger, }: {
+    snapshot: RawDomSnapshot;
+    parent?: any;
+    logger: Logger;
+}): {
+    cdtNode: RawDomSnapshot['cdt'][number];
+    reference: any;
+    parentSnapshot: RawDomSnapshot;
+}[];
+export {};

package/types/ufg/utils/take-dom-snapshots.d.ts

@@ -0,0 +1,24 @@
+import type { Size } from '@applitools/utils';
+import { type Logger } from '@applitools/logger';
+import { type SpecType, type Driver } from '@applitools/driver';
+import { type DomSnapshot, type Renderer, type ChromeEmulationDevice, type IOSDevice, type ScreenOrientation } from '@applitools/ufg-client';
+import { type DomSnapshotSettings } from './take-dom-snapshot';
+export * from './take-dom-snapshot';
+export type DomSnapshotsSettings = DomSnapshotSettings & {
+    renderers: Renderer[];
+    waitBeforeCapture?: number | (() => void);
+    layoutBreakpoints?: number[] | boolean;
+};
+export declare function takeDomSnapshots<TSpec extends SpecType>({ driver, settings, hooks, provides, logger, }: {
+    driver: Driver<TSpec>;
+    settings: DomSnapshotsSettings;
+    hooks?: {
+        beforeSnapshots?(): void | Promise<void>;
+        beforeEachSnapshot?(): void | Promise<void>;
+    };
+    provides?: {
+        getChromeEmulationDevices(): Promise<Record<ChromeEmulationDevice, Record<ScreenOrientation, Size>>>;
+        getIOSDevices(): Promise<Record<IOSDevice, Record<ScreenOrientation, Size>>>;
+    };
+    logger: Logger;
+}): Promise<DomSnapshot[]>;

package/types/ufg/utils/take-snapshots.d.ts

@@ -0,0 +1,21 @@
+import type { Size } from '@applitools/utils';
+import { type Logger } from '@applitools/logger';
+import { type SpecType, type Driver } from '@applitools/driver';
+import { type DomSnapshot, type AndroidSnapshot, type IOSSnapshot, type ChromeEmulationDevice, type IOSDevice, type ScreenOrientation } from '@applitools/ufg-client';
+import { type DomSnapshotsSettings } from './take-dom-snapshots';
+import { type VHSesSettings } from './take-vhses';
+export * from './take-dom-snapshots';
+export * from './take-vhses';
+export declare function takeSnapshots<TSpec extends SpecType>({ driver, settings, hooks, provides, logger, }: {
+    driver: Driver<TSpec>;
+    settings: DomSnapshotsSettings & VHSesSettings;
+    hooks: {
+        beforeSnapshots?(): void | Promise<void>;
+        beforeEachSnapshot?(): void | Promise<void>;
+    };
+    provides: {
+        getChromeEmulationDevices(): Promise<Record<ChromeEmulationDevice, Record<ScreenOrientation, Size>>>;
+        getIOSDevices(): Promise<Record<IOSDevice, Record<ScreenOrientation, Size>>>;
+    };
+    logger: Logger;
+}): Promise<DomSnapshot[] | AndroidSnapshot[] | IOSSnapshot[]>;

package/types/ufg/utils/take-vhses.d.ts

@@ -0,0 +1,17 @@
+import type { ServerSettings } from '../types';
+import { type Logger } from '@applitools/logger';
+import { type SpecType, type Driver } from '@applitools/driver';
+import { type Renderer, type AndroidSnapshot, type IOSSnapshot } from '@applitools/ufg-client';
+export type VHSesSettings = ServerSettings & {
+    renderers: Renderer[];
+    waitBeforeCapture?: number;
+};
+export declare function takeVHSes<TSpec extends SpecType>({ driver, settings, hooks, logger, }: {
+    driver: Driver<TSpec>;
+    settings: VHSesSettings;
+    hooks?: {
+        beforeSnapshots?(): void | Promise<void>;
+        beforeEachSnapshot?(): void | Promise<void>;
+    };
+    logger: Logger;
+}): Promise<AndroidSnapshot[] | IOSSnapshot[]>;

package/types/ufg/utils/uniquify-renderers.d.ts

@@ -0,0 +1,2 @@
+import { type Renderer } from '@applitools/ufg-client';
+export declare function uniquifyRenderers(renderers: Renderer[]): Renderer[];

package/types/universal/core-server-process.d.ts

@@ -0,0 +1,9 @@
+/// <reference types="node" />
+import { type Options } from './core-server';
+import { type ForkOptions } from 'child_process';
+export declare function makeCoreServerProcess(options: Options & {
+    forkOptions?: ForkOptions;
+}): Promise<{
+    port: number;
+    close: () => void;
+}>;

package/types/universal/core-server.d.ts

@@ -0,0 +1,12 @@
+import { type ServerOptions } from './ws-server';
+export type Options = ServerOptions & {
+    debug?: boolean;
+    shutdownMode?: 'lazy' | 'stdin';
+    idleTimeout?: number;
+    printStdout?: boolean;
+};
+export declare function makeCoreServer({ debug, shutdownMode, idleTimeout, // 15min
+printStdout, ...handlerOptions }?: Options): Promise<{
+    port: number;
+    close?: () => void;
+}>;

package/types/universal/core.d.ts

@@ -0,0 +1,21 @@
+import type { Core, EyesManager, Eyes } from '../types';
+import type { ClientSocket, Ref } from './types';
+import type { SpecType, SpecDriver } from '@applitools/driver';
+import { type Socket } from '@applitools/socket';
+import { WebSocket } from 'ws';
+export declare function makeCore<TSpec extends SpecType, TType extends 'classic' | 'ufg'>(options: {
+    agentId: string;
+    spec: 'webdriver' | SpecDriver<TSpec>;
+}): Core<TSpec, TType>;
+export declare function makeManager<TSpec extends SpecType, TType extends 'classic' | 'ufg'>({ socket, manager, }: {
+    socket: ClientSocket<TSpec, TType>;
+    manager: Ref<EyesManager<TSpec, TType>>;
+}): EyesManager<TSpec, TType>;
+export declare function makeEyes<TSpec extends SpecType, TType extends 'classic' | 'ufg'>({ socket, eyes, }: {
+    socket: ClientSocket<TSpec, TType>;
+    eyes: Ref<Eyes<TSpec, TType>>;
+}): Eyes<TSpec, TType>;
+export declare function makeClientSocket<TSpec extends SpecType>({ agentId, spec, }: {
+    agentId: string;
+    spec: 'webdriver' | SpecDriver<TSpec>;
+}): Promise<ClientSocket<TSpec, 'classic' | 'ufg'> & Socket<WebSocket>>;

package/types/universal/history.d.ts

@@ -0,0 +1,2 @@
+import { type Socket } from '@applitools/socket';
+export declare function withHistory<TSocket extends Socket>(socket: TSocket): () => Record<string, any>;

package/types/universal/refer.d.ts

@@ -0,0 +1,8 @@
+import type { Ref } from './types';
+export interface Refer {
+    isRef<TValue = any>(ref: any): ref is Ref<TValue>;
+    ref<TValue>(value: TValue, parentRef?: Ref<unknown>): Ref<TValue>;
+    deref<TValue>(ref: Ref<TValue>): TValue;
+    destroy(ref: Ref<any>): void;
+}
+export declare function makeRefer(): Refer;

package/types/universal/spec-driver.d.ts

@@ -0,0 +1,11 @@
+import type { Ref, ServerSocket, UniversalSpecDriver } from './types';
+import type { SpecType as BaseSpecType, SpecDriver, CommonSelector } from '@applitools/driver';
+export type Driver = Ref;
+export type Context = Ref;
+export type Element = Ref;
+export type Selector = string | CommonSelector | Ref;
+export type SpecType = BaseSpecType<Driver, Context, Element, Selector>;
+export declare function makeSpec({ socket, spec, }: {
+    socket: ServerSocket<SpecType, any>;
+    spec: (keyof UniversalSpecDriver<SpecType>)[];
+}): SpecDriver<SpecType>;

package/types/universal/types.d.ts

@@ -0,0 +1,191 @@
+import type { Size, Region } from '@applitools/utils';
+import type { Emitter, Listener, Client, Server } from '@applitools/socket';
+import type { SpecType, DriverInfo, Cookie, WaitOptions } from '@applitools/driver';
+import type * as MainCore from '../types';
+/**
+ * Wraps the type with a ref if it vas to be refed
+ */
+type Refify<TValue> = TValue extends string | number | boolean | null | undefined ? TValue : TValue extends Array<infer TItem> ? Refify<TItem>[] : Extract<TValue[keyof TValue], (...args: any) => any> extends never ? TValue : Ref<TValue>;
+/**
+ * Creates universalized object out of an ordinary interface:
+ * - Filters out properties that are not of async function type
+ * - Adds domain to the method names (`Domain.methodName`)
+ * - Keep only first (`options`) argument of the methods
+ * - Introduces additional option to the methods with a ref of the current instance
+ * - Refifies return values of the methods
+ */
+type Universalize<TTarget extends Record<string, any>, TDomain extends string, TRefKey extends string = never> = {
+    [TKey in keyof TTarget as NonNullable<TTarget[TKey]> extends (...args: any[]) => Promise<any> ? `${TDomain}.${TKey & string}` : never]: NonNullable<TTarget[TKey]> extends (options: infer TOptions) => Promise<infer TResult> ? (options: TOptions & {
+        [TKey in TRefKey]: Ref<TTarget>;
+    }) => Promise<Refify<TResult>> : never;
+};
+export type Ref<TValue = never> = {
+    'applitools-ref-id': string;
+    type?: string;
+};
+export type ClientSocket<TSpec extends SpecType, TType extends 'classic' | 'ufg'> = unknown & Emitter<Universalize<UniversalCore<TSpec, TType>, 'Core'>> & Client<Universalize<MainCore.Core<TSpec, TType>, 'Core'>> & Client<Universalize<MainCore.EyesManager<TSpec, TType>, 'EyesManager', 'manager'>> & Client<Universalize<MainCore.Eyes<TSpec, TType>, 'Eyes', 'eyes'>> & Client<Universalize<UniversalDebug<TSpec>, 'Debug'>> & Server<Universalize<UniversalSpecDriver<TSpec>, 'Driver'>>;
+export type ServerSocket<TSpec extends SpecType, TType extends 'classic' | 'ufg'> = unknown & Listener<Universalize<UniversalCore<TSpec, TType>, 'Core'>> & Emitter<Universalize<UniversalLogger, 'Logger'>> & Server<Universalize<MainCore.Core<TSpec, TType>, 'Core'>> & Server<Universalize<MainCore.EyesManager<TSpec, TType>, 'EyesManager', 'manager'>> & Server<Universalize<MainCore.Eyes<TSpec, TType>, 'Eyes', 'eyes'>> & Server<Universalize<UniversalDebug<TSpec>, 'Debug'>> & Client<Universalize<UniversalSpecDriver<TSpec>, 'Driver'>>;
+export interface UniversalCore<TSpec extends SpecType, TType extends 'classic' | 'ufg'> {
+    makeCore(options: {
+        agentId: string;
+        cwd: string;
+        spec: 'webdriver' | (keyof UniversalSpecDriver<TSpec>)[];
+    }): Promise<MainCore.Core<TSpec, TType>>;
+}
+export interface UniversalLogger {
+    log(options: {
+        level: string;
+        message: string;
+    }): Promise<void>;
+}
+export interface UniversalDebug<TSpec extends SpecType> {
+    getHistory(): Promise<any>;
+    checkSpecDriver(options: {
+        driver: TSpec['driver'];
+        commands: (keyof UniversalSpecDriver<TSpec>)[];
+    }): Promise<any>;
+}
+/**
+ * Ideally would be transform SpecDriver type to the type with single object argument
+ * but typescript doesn't have a possibility to convert named tuples to object types at the moment
+ */
+export interface UniversalSpecDriver<T extends SpecType> {
+    isEqualElements(options: {
+        context: T['context'];
+        element1: T['element'];
+        element2: T['element'];
+    }): Promise<boolean>;
+    mainContext(options: {
+        context: T['context'];
+    }): Promise<T['context']>;
+    parentContext(options: {
+        context: T['context'];
+    }): Promise<T['context']>;
+    childContext(options: {
+        context: T['context'];
+        element: T['element'];
+    }): Promise<T['context']>;
+    executeScript(options: {
+        context: T['context'];
+        script: string;
+        arg?: any;
+    }): Promise<any>;
+    findElement(options: {
+        context: T['context'];
+        selector: T['selector'];
+        parent?: T['element'];
+    }): Promise<T['element'] | null>;
+    findElements(options: {
+        context: T['context'];
+        selector: T['selector'];
+        parent?: T['element'];
+    }): Promise<T['element'][]>;
+    waitForSelector(options: {
+        context: T['context'];
+        selector: T['selector'];
+        parent?: T['element'];
+        options?: WaitOptions;
+    }): Promise<T['element'] | null>;
+    setElementText(options: {
+        context: T['context'];
+        element: T['element'];
+        text: string;
+    }): Promise<void>;
+    getElementText(options: {
+        context: T['context'];
+        element: T['element'];
+    }): Promise<string>;
+    setWindowSize(options: {
+        driver: T['driver'];
+        size: Size;
+    }): Promise<void>;
+    getWindowSize(options: {
+        driver: T['driver'];
+    }): Promise<Size>;
+    setViewportSize(options: {
+        driver: T['driver'];
+        size: Size;
+    }): Promise<void>;
+    getViewportSize(options: {
+        driver: T['driver'];
+    }): Promise<Size>;
+    getCookies(options: {
+        driver: T['driver'] | T['context'];
+        context?: boolean;
+    }): Promise<Cookie[]>;
+    getDriverInfo(options: {
+        driver: T['driver'];
+    }): Promise<DriverInfo>;
+    getCapabilities(options: {
+        driver: T['driver'];
+    }): Promise<Record<string, any>>;
+    getSessionMetadata(options: {
+        driver: T['driver'];
+    }): Promise<any[] | null>;
+    getTitle(options: {
+        driver: T['driver'];
+    }): Promise<string>;
+    getUrl(options: {
+        driver: T['driver'];
+    }): Promise<string>;
+    takeScreenshot(options: {
+        driver: T['driver'];
+    }): Promise<string>;
+    click(options: {
+        context: T['context'];
+        element: T['element'] | T['selector'];
+    }): Promise<void>;
+    visit(options: {
+        driver: T['driver'];
+        url: string;
+    }): Promise<void>;
+    getOrientation(options: {
+        driver: T['driver'];
+    }): Promise<'portrait' | 'landscape' | 'portrait-secondary' | 'landscape-secondary'>;
+    setOrientation(options: {
+        driver: T['driver'];
+        orientation: 'portrait' | 'landscape' | 'portrait-secondary' | 'landscape-secondary';
+    }): Promise<void>;
+    getSystemBars(options: {
+        driver: T['driver'];
+    }): Promise<{
+        statusBar: {
+            visible: boolean;
+            x: number;
+            y: number;
+            height: number;
+            width: number;
+        };
+        navigationBar: {
+            visible: boolean;
+            x: number;
+            y: number;
+            height: number;
+            width: number;
+        };
+    }>;
+    getElementRegion(options: {
+        driver: T['driver'];
+        element: T['element'];
+    }): Promise<Region>;
+    getElementAttribute(options: {
+        driver: T['driver'];
+        element: T['element'];
+        attr: string;
+    }): Promise<string>;
+    performAction(options: {
+        driver: T['driver'];
+        steps: any[];
+    }): Promise<void>;
+    getCurrentWorld(options: {
+        driver: T['driver'];
+    }): Promise<string>;
+    getWorlds(options: {
+        driver: T['driver'];
+    }): Promise<string[]>;
+    switchWorld(options: {
+        driver: T['driver'];
+        name: string;
+    }): Promise<void>;
+}
+export {};

package/types/universal/ws-server.d.ts

@@ -0,0 +1,14 @@
+/// <reference types="node" />
+import { Server as WsServer } from 'ws';
+export type ServerOptions = {
+    port?: number;
+    singleton?: boolean;
+    portResolutionMode?: 'next' | 'random' | 'lazy';
+    debug?: boolean;
+    key?: string | Buffer;
+    cert?: string | Buffer;
+};
+export declare function makeServer(options?: ServerOptions): Promise<{
+    server?: WsServer;
+    port: number;
+}>;

package/types/utils/extract-ci-provider.d.ts

@@ -0,0 +1 @@
+export declare function extractCIProvider(): string | null;

package/types/utils/format-results.d.ts

@@ -0,0 +1,16 @@
+import type { TestResult } from '@applitools/core-base';
+export declare function toFormatterString(results: TestResult[], { includeSubTests, markNewAsPassed }?: {
+    includeSubTests?: boolean;
+    markNewAsPassed?: boolean;
+}): string;
+export declare function toHierarchicTAPString(results: TestResult[], { includeSubTests, markNewAsPassed }?: {
+    includeSubTests?: boolean;
+    markNewAsPassed?: boolean;
+}): string;
+export declare function toFlattenedTAPString(results: TestResult[], { markNewAsPassed }?: {
+    markNewAsPassed?: boolean;
+}): string;
+export declare function toXmlOutput(results: TestResult[], { totalTime }?: {
+    totalTime?: number;
+}): string;
+export declare function toJsonOutput(results: TestResult[], space?: number | string): string;