@applitools/core 4.67.1 → 4.68.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@applitools/core",
-  "version": "4.67.1",
+  "version": "4.68.0",
   "homepage": "https://applitools.com",
   "bugs": {
     "url": "https://github.com/applitools/eyes.sdk.javascript1/issues"
@@ -61,18 +61,19 @@
     "setup:standalone": "sh -c 'yarn chromedriver --port=4444 --verbose &'"
   },
   "dependencies": {
-    "@applitools/core-base": "1.37.0",
+    "@applitools/core-base": "1.38.0",
     "@applitools/dom-capture": "11.8.4",
-    "@applitools/dom-snapshot": "4.17.7",
-    "@applitools/driver": "1.26.6",
-    "@applitools/ec-client": "1.12.39",
+    "@applitools/dom-snapshot": "4.17.8",
+    "@applitools/driver": "1.26.7",
+    "@applitools/ec-client": "1.12.41",
+    "@applitools/image": "1.3.0",
     "@applitools/logger": "2.3.0",
-    "@applitools/nml-client": "1.11.37",
+    "@applitools/nml-client": "1.11.39",
     "@applitools/req": "1.11.2",
-    "@applitools/screenshoter": "3.12.25",
-    "@applitools/snippets": "2.9.4",
+    "@applitools/screenshoter": "3.12.27",
+    "@applitools/snippets": "2.9.5",
     "@applitools/socket": "1.3.15",
-    "@applitools/ufg-client": "1.22.5",
+    "@applitools/ufg-client": "1.23.0",
     "@applitools/utils": "1.15.1",
     "abort-controller": "3.0.0",
     "chalk": "4.1.2",
@@ -83,10 +84,10 @@
   },
   "devDependencies": {
     "@applitools/bongo": "^5.10.0",
-    "@applitools/spec-driver-playwright": "^1.9.6",
-    "@applitools/spec-driver-puppeteer": "^1.8.6",
-    "@applitools/spec-driver-selenium": "^1.8.6",
-    "@applitools/spec-driver-webdriver": "^1.6.6",
+    "@applitools/spec-driver-playwright": "^1.9.7",
+    "@applitools/spec-driver-puppeteer": "^1.8.7",
+    "@applitools/spec-driver-selenium": "^1.8.7",
+    "@applitools/spec-driver-webdriver": "^1.6.7",
     "@applitools/test-server": "^1.4.6",
     "@applitools/test-utils": "^1.5.17",
     "@applitools/tunnel-client": "^1.12.2",
@@ -120,10 +121,10 @@
       "puppeteer": true,
       "ws>bufferutil": false,
       "ws>utf-8-validate": false,
-      "@applitools/core-base>@applitools/image>sharp": false,
       "@swc-node/register>@swc/core": false,
       "selenium-webdriver>ws>bufferutil": false,
-      "selenium-webdriver>ws>utf-8-validate": false
+      "selenium-webdriver>ws>utf-8-validate": false,
+      "@applitools/image>sharp": false
     }
   }
 }

package/types/automation/types.d.ts

@@ -3,6 +3,7 @@ import type * as BaseCore from '@applitools/core-base/types';
 import { type SpecType, type Driver, type ElementReference, type ContextReference } from '@applitools/driver';
 import { type NMLClient, type NMLClientSettings } from '@applitools/nml-client';
 import { type Logger } from '@applitools/logger';
+import type { FigmaOptions } from '../figma/types';
 export type * from '@applitools/core-base/types';
 export type DriverTarget<TSpec extends SpecType> = TSpec['driver'] | Driver<TSpec>;
 export type Target<TSpec extends SpecType> = DriverTarget<TSpec> | BaseCore.Target;
@@ -180,4 +181,12 @@ export type OpenSettings = BaseCore.OpenSettings & {
     disableBrokerUrlCache?: boolean;
     environments?: Environment[];
     bypassCSP?: boolean;
+    /**
+     * @internal Resolved in core's open-eyes (the Figma seam) before session creation and stripped
+     * from the wire config — it is not part of the cross-language wire contract, but is available to
+     * every SDK that routes its opens through core.
+     */
+    figmaBaselines?: string | Record<string, string | string[]>;
+    /** @internal Read and stripped by the Figma seam during open, like `figmaBaselines` — never reaches the wire. */
+    figmaOptions?: FigmaOptions;
 };

package/types/autonomous/types.d.ts

@@ -71,6 +71,7 @@ export type StartedRender = {
     settings: UFGCore.SafeCheckSettings;
     environment: UFGCore.ExactEnvironment;
     account: UFGCore.Account;
+    accessibilityReportLocation?: string;
 };
 export type RenderResult = {
     status: 'rendering' | 'rendered' | 'error';

package/types/figma/client/figma-req.d.ts

@@ -0,0 +1,9 @@
+import { type Req, type Proxy } from '@applitools/req';
+import { type Logger } from '@applitools/logger';
+export declare const FIGMA_API = "https://api.figma.com/v1";
+export type FigmaReqOptions = {
+    proxy?: Proxy;
+    logger?: Logger;
+    maxRateLimitWaitSeconds?: number;
+};
+export declare function makeFigmaReq({ proxy, logger, maxRateLimitWaitSeconds }?: FigmaReqOptions): Req;

package/types/figma/client/figma-rest.d.ts

@@ -0,0 +1,24 @@
+import { type Logger } from '@applitools/logger';
+import type { Proxy, Req } from '@applitools/req';
+import type { FigmaImageResult, FigmaNodeMetadata } from '../types';
+export type FigmaRestOptions = {
+    tempPath?: string;
+    nodesCacheTtlSeconds?: number;
+    maxRateLimitWaitSeconds?: number;
+    /** Serve from the on-disk caches only; throw on any miss. */
+    skipApi?: boolean;
+    proxy?: Proxy;
+    /** Defaults to `makeFigmaReq(…)`; tests inject a stub. */
+    req?: Req;
+    logger?: Logger;
+};
+/**
+ * Cache names are hashed because Figma node ids are not filename-safe — an instance node id looks like
+ * `I1:2;3:4`, and `:` / `;` are illegal on Windows.
+ *
+ * `test/fixtures/figma-cache/seed.mjs` mirrors both functions — keep them in sync.
+ */
+export declare function figmaNodesCacheFileName(fileId: string, uniqueNodeIds: string[]): string;
+export declare function figmaImageCacheFileName(fileId: string, nodeId: string, lastModifiedUnix: number): string;
+export declare function fetchFigmaMetadata(urls: string[], accessToken: string, opts?: FigmaRestOptions): Promise<FigmaNodeMetadata[]>;
+export declare function fetchFigmaImages(urls: string[], accessToken: string, opts?: FigmaRestOptions): Promise<FigmaImageResult[]>;

package/types/figma/client/index.d.ts

@@ -0,0 +1,2 @@
+export * from './figma-req';
+export * from './figma-rest';

package/types/figma/figma-images.d.ts

@@ -0,0 +1,6 @@
+export declare function createPlaceholderPng(width: number, height: number, tempPath: string): Promise<string>;
+export declare function createPaddedDesignImage(imagePath: string, width: number, height: number, minSize: number, tempPath: string): Promise<{
+    imagePath: string;
+    width: number;
+    height: number;
+}>;

package/types/figma/figma.d.ts

@@ -0,0 +1,21 @@
+import { type Logger } from '@applitools/logger';
+import type { Proxy, Req } from '@applitools/req';
+import type { OpenSettings } from '../automation/types';
+import { type FigmaMode } from './utils';
+import type { FigmaViewportOptions, FigmaBaselineDeps } from './types';
+export declare function setFigmaBaselineFlow(figmaUrls: string[], originalConfig: Partial<OpenSettings>, deps: FigmaBaselineDeps, mode?: Exclude<FigmaMode, 'disabled'>, viewportOpts?: FigmaViewportOptions, logger?: Logger): Promise<Partial<OpenSettings>>;
+export declare function setFigmaBaseline(configuration: Partial<OpenSettings>, figmaBaselines: string | Record<string, string | string[]>, opts?: {
+    accessToken?: string;
+    maxRateLimitWaitSeconds?: number;
+    nodesCacheTtlSeconds?: number;
+    tempPath?: string;
+    mode?: FigmaMode;
+    maxViewportHeight?: number;
+    minViewportSize?: number | null;
+    /** Serve from the disk caches only; throw on any miss. */
+    skipApi?: boolean;
+    proxy?: Proxy;
+    /** Defaults to the client's own req; tests inject a stub. */
+    req?: Req;
+    logger?: Logger;
+}): Promise<void>;

package/types/figma/index.d.ts

@@ -0,0 +1,8 @@
+export * from './types';
+export * from './utils';
+export * from './target-config';
+export * from './client';
+export * from './figma-images';
+export * from './figma';
+export { runFigmaCheck } from './run-figma-check';
+export { applyFigmaBaselines } from './seam';

package/types/figma/run-figma-check.d.ts

@@ -0,0 +1,13 @@
+import type { FigmaReferenceConfig } from './types';
+/**
+ * Establishes/updates the Figma-reference baseline via a throwaway headless classic image test (checks
+ * each PNG, closes, deletes the result — the saved baseline persists). Uses core's own API, not the
+ * eyes layer (core cannot depend on `@applitools/eyes`).
+ */
+export declare function runFigmaCheck(config: FigmaReferenceConfig, checks: Array<{
+    imagePath: string;
+    tag: string;
+}>): Promise<{
+    isNew: boolean;
+    diffs: boolean;
+}>;

package/types/figma/seam.d.ts

@@ -0,0 +1,12 @@
+import type { OpenSettings } from '../automation/types';
+import { type Logger } from '@applitools/logger';
+import { setFigmaBaseline } from './figma';
+/**
+ * @internal
+ * Resolves the `figmaBaselines` / `figmaOptions` open config once per open, then always strips both — they
+ * are off-the-wire and must never be logged or sent. The resolver mutates `settings` in place.
+ *
+ * The only place the Figma feature reads the environment; everything below it takes parameters. Each
+ * `figmaOptions` field wins over its env fallback.
+ */
+export declare function applyFigmaBaselines(settings: Partial<OpenSettings>, logger: Logger, resolve?: typeof setFigmaBaseline): Promise<void>;

package/types/figma/target-config.d.ts

@@ -0,0 +1,7 @@
+import type { OpenSettings, Environment } from '../automation/types';
+import { type FigmaMode } from './utils';
+import type { FigmaNodeMetadata, FigmaViewport, FigmaBaselineLink } from './types';
+export declare const DEFAULT_MAX_VIEWPORT_HEIGHT = 800;
+export declare const PLACEHOLDER_TAG = "(no design)";
+export declare function deduplicateBrowsers(environments: Environment[], targetWidth: number, targetHeight: number): Environment[];
+export declare function buildTargetTestConfig(originalConfig: Partial<OpenSettings>, metadata: FigmaNodeMetadata, figmaViewport: FigmaViewport, baselineLink: FigmaBaselineLink | null, mode: FigmaMode): Partial<OpenSettings>;

package/types/figma/types.d.ts

@@ -0,0 +1,69 @@
+import type { OpenSettings } from '../automation/types';
+import type { FigmaMode } from './utils';
+/**
+ * The user-facing `figmaOptions` open config. Precedence is per field, not per object: a field set here
+ * wins, one left unset falls back to that field's environment variable where it has one; `README.md`
+ * holds the per-field mapping.
+ *
+ * `APPLITOOLS_FIGMA_SKIP_API` has no field by design — it is a CI/debug switch, not a user option.
+ */
+export type FigmaOptions = FigmaViewportOptions & {
+    mode?: FigmaMode;
+    accessToken?: string;
+    maxRateLimitWaitSeconds?: number;
+    nodesCacheTtlSeconds?: number;
+    tempPath?: string;
+};
+export type FigmaNodeRef = {
+    fileId: string;
+    nodeId: string;
+};
+export type FigmaNodeMetadata = {
+    name: string;
+    type: string;
+    width: number;
+    height: number;
+    revision: string;
+    lastModifiedAt: string;
+};
+export type FigmaImageResult = {
+    imagePath: string;
+    metadata: FigmaNodeMetadata;
+};
+export type FigmaViewport = {
+    width: number;
+    height: number;
+};
+export type FigmaViewportOptions = {
+    maxViewportHeight?: number;
+    /**
+     * One dimension, not a width/height pair: the same floor applies to both axes independently, so 320
+     * means "at least 320 wide AND at least 320 tall". `null` disables the floor.
+     */
+    minViewportSize?: number | null;
+};
+export type FigmaBaselineLink = {
+    figmaEnvName: string;
+    useLatestEnvBaseline: boolean;
+};
+/** The throwaway Figma-reference test's config: a subset of core `OpenSettings` plus `saveNewTests` (maps to close's `updateBaselineIfNew`). */
+export type FigmaReferenceConfig = Partial<OpenSettings> & {
+    saveNewTests?: boolean;
+};
+export type FigmaBaselineDeps = {
+    fetchFigmaImages: (figmaUrls: string[]) => Promise<FigmaImageResult[]>;
+    fetchFigmaMetadata: (figmaUrls: string[]) => Promise<FigmaNodeMetadata[]>;
+    createPlaceholderImage: (width: number, height: number) => Promise<string>;
+    padDesignImage: (imagePath: string, width: number, height: number, minViewportSize: number) => Promise<{
+        imagePath: string;
+        width: number;
+        height: number;
+    }>;
+    runFigmaCheck: (config: FigmaReferenceConfig, checks: Array<{
+        imagePath: string;
+        tag: string;
+    }>) => Promise<{
+        isNew: boolean;
+        diffs: boolean;
+    }>;
+};

package/types/figma/utils.d.ts

@@ -0,0 +1,26 @@
+import type { FigmaNodeRef, FigmaNodeMetadata, FigmaViewport } from './types';
+export declare function isFigmaUrl(url: string): boolean;
+export declare function parseFigmaNodeUrl(url: string): FigmaNodeRef;
+/**
+ * The tag becomes the Eyes baseline step name, and Eyes matches steps by name, so it must derive only from
+ * stable identity. Figma's "Copy link to selection" appends a `t=` param that differs on every copy —
+ * keeping it means re-copying the link renames the step and orphans its accepted baseline.
+ *
+ * Drop only `t`: `node-id` is what distinguishes two frames of the same file, so stripping the whole query
+ * would give every frame in a file the same step name.
+ */
+export declare function figmaStepTag(figmaUrl: string): string;
+export declare function resolveFigmaUrls(figmaBaselines: string | Record<string, string | string[]>, testName: string | undefined): string[] | null;
+export declare const FIGMA_MODES: readonly ["figma-baseline", "test-baseline", "auto-baseline", "disabled"];
+export type FigmaMode = (typeof FIGMA_MODES)[number];
+export declare function resolveFigmaMode(value: string | undefined): FigmaMode;
+export declare function figmaMetadataToProperties(metadata: FigmaNodeMetadata, mode: FigmaMode): Array<{
+    name: string;
+    value: string;
+}>;
+export declare function boundingViewport(viewports: FigmaViewport[]): FigmaViewport;
+export declare function computeFigmaViewport(stepViewports: FigmaViewport[], maxViewportHeight: number): FigmaViewport;
+export declare function paddedDesignSize(width: number, height: number, minSize: number): {
+    width: number;
+    height: number;
+};

package/types/types.d.ts

@@ -8,6 +8,7 @@ import { type Logger } from '@applitools/logger';
 import { type ECClient, type ECClientSettings } from '@applitools/ec-client';
 export { ECClient };
 export * from './automation/types';
+export type { FigmaOptions } from './figma/types';
 export { DEFAULT_CONCURRENCY } from '@applitools/core-base';
 export type TypedCore<TSpec extends SpecType, TType extends 'classic' | 'ufg'> = TType extends 'ufg' ? UFGCore.Core<TSpec> : ClassicCore.Core<TSpec>;
 export type TypedEyes<TSpec extends SpecType, TType extends 'classic' | 'ufg'> = TType extends 'ufg' ? UFGCore.Eyes<TSpec> : ClassicCore.Eyes<TSpec>;

package/types/ufg/build-accessibility-report-options.d.ts

@@ -0,0 +1,13 @@
+import { type Account } from '@applitools/core-base';
+/**
+ * Builds the `accessibilityReportOptions` render option: forwards `runOptions` verbatim and fills the
+ * `uploadUrl` template's `__report_id__` with a fresh random id. Returns `undefined` when the account
+ * has no accessibility options.
+ */
+export declare function buildAccessibilityReportOptions({ accessibilityOptions, reportId, }: {
+    accessibilityOptions?: Account['accessibilityOptions'];
+    reportId?: string;
+}): {
+    axeCoreOptions: unknown;
+    uploadUrl: string;
+} | undefined;