@applitools/eyes-storybook 3.57.2 → 3.58.0

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # Changelog
 
+## [3.58.0](https://github.com/Applitools-Dev/sdk/compare/js/eyes-storybook@3.57.2...js/eyes-storybook@3.58.0) (2025-08-21)
+
+
+### Features
+
+* enhance storybook tsdocs and types | AD-10816 ([#3180](https://github.com/Applitools-Dev/sdk/issues/3180)) ([df2c28d](https://github.com/Applitools-Dev/sdk/commit/df2c28d7f3d661596d0f8d6f9389593527bddc71))
+* storybook sharding | AD-10879 ([#3176](https://github.com/Applitools-Dev/sdk/issues/3176)) ([73e5f3f](https://github.com/Applitools-Dev/sdk/commit/73e5f3fce69044696a2457deb82f576542a2589e))
+
+
+### Bug Fixes
+
+* configuration parameters and documentation | AD-10816 ([#3181](https://github.com/Applitools-Dev/sdk/issues/3181)) ([fded470](https://github.com/Applitools-Dev/sdk/commit/fded4705d7fea0c1b523dceec5f1128c68c1d76d))
+
+
+### Code Refactoring
+
+* remove dist folder from eyes-sb ([#3182](https://github.com/Applitools-Dev/sdk/issues/3182)) ([a2696b9](https://github.com/Applitools-Dev/sdk/commit/a2696b969bbc7b686d6ebe03d45b9400e27f65ff))
+
+
+### Dependencies
+
+* @applitools/dom-snapshot bumped to 4.13.3
+
+* @applitools/socket bumped to 1.3.3
+  #### Bug Fixes
+
+  * tunnel uncaught error | FLD-3356 ([#3128](https://github.com/Applitools-Dev/sdk/issues/3128)) ([ed5fb8a](https://github.com/Applitools-Dev/sdk/commit/ed5fb8aad596ec0d8b45a89077a7765c24ae8a8e))
+* @applitools/driver bumped to 1.23.3
+  #### Bug Fixes
+
+  * make orientation more robust | FLD-3470 ([#3166](https://github.com/Applitools-Dev/sdk/issues/3166)) ([3745427](https://github.com/Applitools-Dev/sdk/commit/37454279234b085dc9a159077b3f278cdccc203a))
+* @applitools/spec-driver-webdriver bumped to 1.4.3
+
+* @applitools/spec-driver-selenium bumped to 1.7.3
+
+* @applitools/spec-driver-puppeteer bumped to 1.6.3
+
+* @applitools/screenshoter bumped to 3.12.3
+
+* @applitools/nml-client bumped to 1.11.3
+
+* @applitools/tunnel-client bumped to 1.10.4
+  #### Bug Fixes
+
+  * tunnel uncaught error | FLD-3356 ([#3128](https://github.com/Applitools-Dev/sdk/issues/3128)) ([ed5fb8a](https://github.com/Applitools-Dev/sdk/commit/ed5fb8aad596ec0d8b45a89077a7765c24ae8a8e))
+
+
+
+* @applitools/ec-client bumped to 1.12.4
+
+* @applitools/core bumped to 4.44.4
+
+* @applitools/eyes bumped to 1.36.2
+
+
 ## [3.57.2](https://github.com/Applitools-Dev/sdk/compare/js/eyes-storybook@3.57.1...js/eyes-storybook@3.57.2) (2025-08-12)
 
 

package/dist/index.d.ts

@@ -1,39 +1,246 @@
 import type { ConfigurationPlain, DesktopBrowserInfo, ChromeEmulationInfo, IOSDeviceInfo, IOSMultiDeviceInfo } from '@applitools/eyes';
+type irrelevantToStorybook = 'waitBeforeScreenshots' | 'agentId' | 'captureStatusBar' | 'concurrentSessions' | 'connectionTimeout' | 'debugScreenshots' | 'defaultMatchSettings' | 'disableNMLUrlCache' | 'forceFullPageScreenshot' | 'hideCaret' | 'hideScrollbars' | 'hostApp' | 'hostAppInfo' | 'hostOS' | 'hostOSInfo' | 'ignoreBaseline' | 'ignoreCaret' | 'latestCommitInfo' | 'isDisabled' | 'matchTimeout' | 'mobileOptions' | 'removeSession' | 'rotation' | 'scaleRatio' | 'scrollRootElement' | 'sessionType' | 'stitchMode' | 'stitchOverlap' | 'viewportSize';
 /**
- * https://applitools.com/tutorials/sdks/storybook/config
+ * Configuration options for Applitools Eyes Storybook integration.
+ *
+ * This configuration can be specified in three ways:
+ * - Command line arguments
+ * - Environment variables (uppercase with APPLITOOLS_ prefix)
+ * - applitools.config.js file (CommonJS module export)
+ *
+ * Environment variables override applitools.config.js values.
+ *
+ * @see https://applitools.com/tutorials/sdks/storybook/config
  */
-export type ApplitoolsConfig = Omit<ConfigurationPlain, 'waitBeforeScreenshots'> & {
+export type ApplitoolsConfig = Omit<ConfigurationPlain, irrelevantToStorybook | 'waitBeforeCapture'> & {
+    /**
+     * URL for Storybook instance.
+     * @example 'http://localhost:9001'
+     */
     storybookUrl?: string;
+    /**
+     * Port to run Storybook on.
+     * @default 9000
+     */
     storybookPort?: number;
+    /**
+     * Host to run Storybook on.
+     * @default 'localhost'
+     */
     storybookHost?: string;
+    /**
+     * Path to Storybook's config folder.
+     * @default '.storybook'
+     */
     storybookConfigDir?: string;
+    /**
+     * Path to Storybook's static files folder.
+     */
     storybookStaticDir?: string;
+    /**
+     * Whether to display Storybook output in console.
+     */
     showStorybookOutput?: boolean;
+    /**
+     * Set to true if running the SDK in Docker to resolve potential issues.
+     * @default false
+     */
     runInDocker?: boolean;
+    /**
+     * Predicate function, string, or regex specifying which stories should be visually tested.
+     * Visual baselines will be created only for specified components.
+     * Function receives object with name, kind, storyTitle, and parameters properties.
+     *
+     * @example
+     * // Exclude stories with names starting with [SKIP]
+     * ({name, kind, storyTitle, parameters}) => !/^\\[SKIP\\]/.test(name)
+     *
+     * @default true (includes all stories)
+     */
     include?: ((story: {
         name: string;
         kind: string;
         storyTitle?: string;
         parameters?: any;
     }) => boolean) | string | RegExp;
+    /**
+     * Specifies additional variations for all or some stories (e.g., RTL).
+     */
     variations?: Record<string, any>;
+    /**
+     * Time in milliseconds that Eyes-Storybook waits for Storybook to load.
+     * For Storybook versions 2 and 3, this is also the acknowledgment time.
+     * Recommended to use small values (e.g., 3000) for versions 2-3.
+     *
+     * @default 60000
+     */
     readStoriesTimeout?: number;
+    /**
+     * Low-level options to send to puppeteer.launch().
+     * Use with great care.
+     *
+     * @example
+     * { args: ['--no-sandbox'], headless: false, devtools: true }
+     */
     puppeteerOptions?: Record<string, any>;
+    /**
+     * Options to send to page.setExtraHTTPHeaders().
+     * @see https://pptr.dev/api/puppeteer.page.setextrahttpheaders
+     */
     puppeteerExtraHTTPHeaders?: Record<string, string>;
+    /**
+     * When to consider navigation finished.
+     * @default 'load'
+     */
     navigationWaitUntil?: 'load' | 'domcontentloaded' | 'networkidle0' | 'networkidle2';
+    /**
+     * Cache all requests from browser for faster performance.
+     * @default false
+     */
     browserCacheRequests?: boolean;
+    /**
+     * Array of browser configurations for screenshot generation.
+     * Defines size and browser type for generated screenshots.
+     *
+     * @default [{ width: 1024, height: 768, name: 'chrome' }]
+     */
     browser?: (DesktopBrowserInfo | ChromeEmulationInfo | IOSDeviceInfo | IOSMultiDeviceInfo)[];
+    /**
+     * Name for the environment in which the application under test is running.
+     */
     envName?: string;
+    /**
+     * Maximum number of tests that can run concurrently.
+     * Default value is the allowed amount for free accounts.
+     * For paid accounts, set to your account quota.
+     *
+     * @default 5
+     */
     testConcurrency?: number;
+    /**
+     * Whether to display logs of the Eyes-Storybook plugin.
+     * @default false
+     */
     showLogs?: boolean;
+    /**
+     * If tests failed or have visual differences, close with non-zero exit code.
+     * @default true
+     */
     exitcode?: boolean;
+    /**
+     * Array of regions to ignore when comparing checkpoint with baseline screenshot.
+     */
     ignoreRegions?: any[];
+    /**
+     * Array of regions to consider as floating when comparing checkpoint with baseline.
+     */
     floatingRegions?: any[];
+    /**
+     * Array of regions to consider as match level Layout when comparing screenshots.
+     */
     layoutRegions?: any[];
+    /**
+     * Array of regions to consider as match level Strict when comparing screenshots.
+     */
     strictRegions?: any[];
+    /**
+     * Array of regions to consider as match level Content when comparing screenshots.
+     */
     contentRegions?: any[];
+    /**
+     * Array of regions to validate accessibility according to configured accessibilityValidation.
+     */
     accessibilityRegions?: any[];
+    /**
+     * Directory path for JSON results file.
+     * If set, creates eyes.json file with test results.
+     */
     jsonFilePath?: string;
+    /**
+     * Directory path for TAP results file.
+     * If set, creates eyes.tap file with test results.
+     */
     tapFilePath?: string;
+    /**
+     * Directory path for XUnit XML results file.
+     * If set, creates eyes.xml file with test results.
+     */
     xmlFilePath?: string;
+    /**
+     * Selector, function, or timeout to wait before capturing.
+     *
+     * * number: Milliseconds to wait before capturing.
+     * * string: CSS selector to wait for before capturing.
+     * * function: Predicate or async function to wait for before capturing.
+     *
+     * @example
+     * waitBeforeCapture: '#container.ready',
+     *
+     * @example
+     * waitBeforeCapture: () => document.querySelector('#container.ready') !== null,
+     *
+     * @example
+     * waitBeforeCapture: 3_000
+     *
+     * @see https://applitools.com/tutorials/sdks/storybook/component-config#waitBeforeCapture
+     */
+    waitBeforeCapture?: number | string | (() => boolean | Promise<boolean>);
+    /**
+     * Unique identifier for the batch of tests - set to the same value if you want to group tests together.
+     */
+    batchId?: string;
+    /**
+     * Name for the batch of tests - will appear in the Eyes dashboard.
+     */
+    batchName?: string;
+    /**
+     * Sequence name for the batch of tests - will appear in the Eyes dashboard (in the 'insights' page and in the batch details).
+     */
+    batchSequenceName?: string;
+    /**
+     * Name for the baseline branch - use it if you want to compare with a specific branch that is different from the current branch.
+     *
+     * @see for more information and recommendations regarding baseline branches, see the [documentation](https://applitools.com/tutorials/concepts/best-practices/branching).
+     */
+    baselineBranchName?: string;
+    /**
+     * Dry run - if true, no actual visual testing will be performed.
+     * @default false
+     */
+    isDisabled?: boolean;
+    /**
+     * Whether to ignore the baseline when comparing with the checkpoint (will make all checkpoints `new`)
+     * @default false
+     */
+    ignoreBaseline?: boolean;
+    /**
+     * Settings for accessibility validation.
+     */
+    accessibilitySettings?: {
+        /**
+         * Level of accessibility validation to perform.
+         */
+        level?: 'AA' | 'AAA';
+        /**
+         * Array of specific accessibility guidelines to check.
+         */
+        guidelinesVersion?: "WCAG_2_0" | "WCAG_2_1";
+    };
+    /**
+     * Whether to notify when the test is complete (requires to turn on notifications in the Applitools dashboard).
+     * @see https://applitools.com/tutorials/integrations/chat-&-notifications/email
+     */
+    notifyOnCompletion?: boolean;
+    /**
+     * Whether to show browser logs in the test results.
+     * @default false
+     */
+    showBrowserLogs?: boolean;
+    /**
+     * A string formatted as `<ShardIndex>/<TotalShards>` to enable test sharding (running tests in parallel).
+     * @default undefined
+     */
+    shard?: string;
 };
+export type configKeys = keyof ApplitoolsConfig;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@applitools/eyes-storybook",
-  "version": "3.57.2",
+  "version": "3.58.0",
   "description": "",
   "keywords": [
     "applitools",
@@ -58,13 +58,13 @@
     "up:framework": "cd test/fixtures/storybook-versions/${APPLITOOLS_FRAMEWORK_VERSION} && npm ci"
   },
   "dependencies": {
-    "@applitools/core": "4.44.3",
-    "@applitools/driver": "1.23.2",
-    "@applitools/eyes": "1.36.1",
+    "@applitools/core": "4.44.4",
+    "@applitools/driver": "1.23.3",
+    "@applitools/eyes": "1.36.2",
     "@applitools/functional-commons": "1.6.0",
     "@applitools/logger": "2.2.2",
     "@applitools/monitoring-commons": "1.0.19",
-    "@applitools/spec-driver-puppeteer": "1.6.2",
+    "@applitools/spec-driver-puppeteer": "1.6.3",
     "@applitools/ufg-client": "1.17.2",
     "@applitools/utils": "1.11.1",
     "@inquirer/prompts": "7.0.1",

package/src/cli.js

@@ -32,6 +32,15 @@ const {performance, timeItAsync} = makeTiming();
 
     console.log(`Using @applitools/eyes-storybook version ${VERSION}.\n`);
     const config = generateConfig({argv, defaultConfig, externalConfigParams});
+
+    if (config.shard) {
+      console.log(`Running with shard: ${config.shard.current}/${config.shard.total}`);
+      // Log concurrency and shard configuration to console
+      if (config.testConcurrency && config.testConcurrency !== 5) {
+        console.log(`this shard has concurrency of ${config.testConcurrency} parallel tests`);
+      }
+    }
+
     const logger = makeLogger({level: config.showLogs ? 'info' : 'silent', label: 'eyes'});
     await validateAndPopulateConfig({
       config,

package/src/configParams.js

@@ -1,31 +1,31 @@
+// @ts-check
 'use strict';
 
+/**
+ * @type {Partial<(
+ *  import('./index').configKeys
+ *  | 'concurrency'
+ * )[]>}
+ */
 const configParams = [
   'appName',
   'testName',
   'displayName',
   'browser',
-  'url',
   'apiKey',
   'showLogs',
   'batch',
   'batchId',
   'batchName',
   'batchSequenceName',
-  'batchSequence',
   'properties',
   'baselineBranchName',
-  'baselineBranch',
   'baselineEnvName',
-  'baselineName',
   'envName',
-  'ignoreCaret',
   'isDisabled',
   'matchLevel',
   'parentBranchName',
-  'parentBranch',
   'branchName',
-  'branch',
   'proxy',
   'autProxy',
   'saveDiffs',
@@ -41,9 +41,9 @@ const configParams = [
   'ignoreDisplacements',
   'accessibilitySettings',
   'notifyOnCompletion',
-  'batchNotify',
   'dontCloseBatches',
   'showBrowserLogs',
+  'shard',
 ];
 
 module.exports = {configParams};

package/src/defaultConfig.js

@@ -1,3 +1,4 @@
+// @ts-check
 'use strict';
 
 module.exports = {
@@ -23,4 +24,6 @@ module.exports = {
   browserRequestsTimeout: undefined,
   browserHeadersOverride: undefined,
   browserCacheRequests: undefined,
+  showBrowserLogs: undefined,
+  shard: undefined,
 };

package/src/eyesStorybook.js

@@ -138,6 +138,17 @@ async function eyesStorybook({
     const stories = await getStoriesWithSpinner();
 
     const filteredStories = filterStories({stories, config});
+
+    // Log filtering and sharding results
+    logger.log(`${stories.length} total stories found`);
+    if (config.shard) {
+      logger.log(
+        `${filteredStories.length} stories after filtering and sharding (shard ${config.shard.current}/${config.shard.total})`,
+      );
+    } else {
+      logger.log(`${filteredStories.length} stories after filtering`);
+    }
+
     const storiesIncludingVariations = addVariationStories({
       stories: filteredStories,
       config,

package/src/filterStories.js

@@ -2,7 +2,16 @@
 const getStoryTitle = require('./getStoryTitle');
 
 function filterStories({stories, config}) {
-  return stories.filter(story => filterStory(story, config));
+  // Apply existing filters first
+  let filteredStories = stories.filter(story => filterStory(story, config));
+
+  // Apply sharding after other filters
+  if (config.shard) {
+    const {current, total} = config.shard;
+    filteredStories = filteredStories.filter((_story, index) => index % total === current - 1);
+  }
+
+  return filteredStories;
 }
 
 function filterStory(story, config) {

package/src/generateConfig.js

@@ -55,6 +55,15 @@ function generateConfig({argv = {}, defaultConfig = {}, externalConfigParams = [
   result.viewportSize = result.viewportSize ? result.viewportSize : {width: 1024, height: 600};
 
   result.saveNewTests = result.saveNewTests === undefined ? true : result.saveNewTests;
+
+  // Auto-enable dontCloseBatches when sharding is used (unless explicitly set by user)
+  if (result.shard && result.dontCloseBatches === undefined) {
+    result.dontCloseBatches = true;
+    console.log(
+      'Auto-enabling dontCloseBatches due to sharding configuration - please make sure to close batches manually ( https://applitools.com/tutorials/concepts/best-practices/batching#manually-close-the-shared-batch ).',
+    );
+  }
+
   result.keepBatchOpen = result.dontCloseBatches;
   result.fully = result.fully === undefined ? true : false;
 

package/src/index.ts

@@ -1,35 +1,312 @@
-import type {ConfigurationPlain, DesktopBrowserInfo, ChromeEmulationInfo, IOSDeviceInfo, IOSMultiDeviceInfo} from '@applitools/eyes'
+import type { ConfigurationPlain, DesktopBrowserInfo, ChromeEmulationInfo, IOSDeviceInfo, IOSMultiDeviceInfo } from '@applitools/eyes';
+
+type irrelevantToStorybook = 'waitBeforeScreenshots'
+    | 'agentId'
+    | 'captureStatusBar'
+    | 'concurrentSessions'
+    | 'connectionTimeout'
+    | 'debugScreenshots'
+    | 'defaultMatchSettings'
+    | 'disableNMLUrlCache'
+    | 'forceFullPageScreenshot'
+    | 'hideCaret'
+    | 'hideScrollbars'
+    | 'hostApp'
+    | 'hostAppInfo'
+    | 'hostOS'
+    | 'hostOSInfo'
+    | 'ignoreBaseline'
+    | 'ignoreCaret'
+    | 'latestCommitInfo'
+    | 'isDisabled'
+    | 'matchTimeout'
+    | 'mobileOptions'
+    | 'removeSession'
+    | 'rotation'
+    | 'scaleRatio'
+    | 'scrollRootElement'
+    | 'sessionType'
+    | 'stitchMode'
+    | 'stitchOverlap'
+    | 'viewportSize'
+;
+
 
 /**
- * https://applitools.com/tutorials/sdks/storybook/config
+ * Configuration options for Applitools Eyes Storybook integration.
+ * 
+ * This configuration can be specified in three ways:
+ * - Command line arguments
+ * - Environment variables (uppercase with APPLITOOLS_ prefix)
+ * - applitools.config.js file (CommonJS module export)
+ * 
+ * Environment variables override applitools.config.js values.
+ * 
+ * @see https://applitools.com/tutorials/sdks/storybook/config
  */
-export type ApplitoolsConfig = Omit<ConfigurationPlain, 'waitBeforeScreenshots'> & {
-  storybookUrl?: string;
-  storybookPort?: number;
-  storybookHost?: string;
-  storybookConfigDir?: string;
-  storybookStaticDir?: string;
-  showStorybookOutput?: boolean;
-  runInDocker?: boolean;
-  include?: ((story: { name: string; kind: string; storyTitle?: string; parameters?: any }) => boolean) | string | RegExp;
-  variations?: Record<string, any>;
-  readStoriesTimeout?: number;
-  puppeteerOptions?: Record<string, any>;
-  puppeteerExtraHTTPHeaders?: Record<string, string>;
-  navigationWaitUntil?: 'load' | 'domcontentloaded' | 'networkidle0' | 'networkidle2';
-  browserCacheRequests?: boolean;
-  browser?: (DesktopBrowserInfo | ChromeEmulationInfo | IOSDeviceInfo | IOSMultiDeviceInfo)[];
-  envName?: string;
-  testConcurrency?: number;
-  showLogs?: boolean;
-  exitcode?: boolean;
-  ignoreRegions?: any[];
-  floatingRegions?: any[];
-  layoutRegions?: any[];
-  strictRegions?: any[];
-  contentRegions?: any[];
-  accessibilityRegions?: any[];
-  jsonFilePath?: string;
-  tapFilePath?: string;
-  xmlFilePath?: string;
+export type ApplitoolsConfig = Omit<ConfigurationPlain, irrelevantToStorybook | 'waitBeforeCapture'> & {
+    /** 
+     * URL for Storybook instance.
+     * @example 'http://localhost:9001'
+     */
+    storybookUrl?: string;
+
+    /** 
+     * Port to run Storybook on.
+     * @default 9000
+     */
+    storybookPort?: number;
+
+    /** 
+     * Host to run Storybook on.
+     * @default 'localhost'
+     */
+    storybookHost?: string;
+
+    /** 
+     * Path to Storybook's config folder.
+     * @default '.storybook'
+     */
+    storybookConfigDir?: string;
+
+    /** 
+     * Path to Storybook's static files folder.
+     */
+    storybookStaticDir?: string;
+
+    /** 
+     * Whether to display Storybook output in console.
+     */
+    showStorybookOutput?: boolean;
+
+    /** 
+     * Set to true if running the SDK in Docker to resolve potential issues.
+     * @default false
+     */
+    runInDocker?: boolean;
+
+    /** 
+     * Predicate function, string, or regex specifying which stories should be visually tested.
+     * Visual baselines will be created only for specified components.
+     * Function receives object with name, kind, storyTitle, and parameters properties.
+     * 
+     * @example
+     * // Exclude stories with names starting with [SKIP]
+     * ({name, kind, storyTitle, parameters}) => !/^\\[SKIP\\]/.test(name)
+     * 
+     * @default true (includes all stories)
+     */
+    include?: ((story: { name: string; kind: string; storyTitle?: string; parameters?: any }) => boolean) | string | RegExp;
+
+    /** 
+     * Specifies additional variations for all or some stories (e.g., RTL).
+     */
+    variations?: Record<string, any>;
+
+    /** 
+     * Time in milliseconds that Eyes-Storybook waits for Storybook to load.
+     * For Storybook versions 2 and 3, this is also the acknowledgment time.
+     * Recommended to use small values (e.g., 3000) for versions 2-3.
+     * 
+     * @default 60000
+     */
+    readStoriesTimeout?: number;
+
+    /** 
+     * Low-level options to send to puppeteer.launch().
+     * Use with great care.
+     * 
+     * @example
+     * { args: ['--no-sandbox'], headless: false, devtools: true }
+     */
+    puppeteerOptions?: Record<string, any>;
+
+    /** 
+     * Options to send to page.setExtraHTTPHeaders().
+     * @see https://pptr.dev/api/puppeteer.page.setextrahttpheaders
+     */
+    puppeteerExtraHTTPHeaders?: Record<string, string>;
+
+    /** 
+     * When to consider navigation finished.
+     * @default 'load'
+     */
+    navigationWaitUntil?: 'load' | 'domcontentloaded' | 'networkidle0' | 'networkidle2';
+
+    /** 
+     * Cache all requests from browser for faster performance.
+     * @default false
+     */
+    browserCacheRequests?: boolean;
+
+    /** 
+     * Array of browser configurations for screenshot generation.
+     * Defines size and browser type for generated screenshots.
+     * 
+     * @default [{ width: 1024, height: 768, name: 'chrome' }]
+     */
+    browser?: (DesktopBrowserInfo | ChromeEmulationInfo | IOSDeviceInfo | IOSMultiDeviceInfo)[];
+
+    /** 
+     * Name for the environment in which the application under test is running.
+     */
+    envName?: string;
+
+    /** 
+     * Maximum number of tests that can run concurrently.
+     * Default value is the allowed amount for free accounts.
+     * For paid accounts, set to your account quota.
+     * 
+     * @default 5
+     */
+    testConcurrency?: number;
+
+    /** 
+     * Whether to display logs of the Eyes-Storybook plugin.
+     * @default false
+     */
+    showLogs?: boolean;
+
+    /** 
+     * If tests failed or have visual differences, close with non-zero exit code.
+     * @default true
+     */
+    exitcode?: boolean;
+
+    /** 
+     * Array of regions to ignore when comparing checkpoint with baseline screenshot.
+     */
+    ignoreRegions?: any[];
+
+    /** 
+     * Array of regions to consider as floating when comparing checkpoint with baseline.
+     */
+    floatingRegions?: any[];
+
+    /** 
+     * Array of regions to consider as match level Layout when comparing screenshots.
+     */
+    layoutRegions?: any[];
+
+    /** 
+     * Array of regions to consider as match level Strict when comparing screenshots.
+     */
+    strictRegions?: any[];
+
+    /** 
+     * Array of regions to consider as match level Content when comparing screenshots.
+     */
+    contentRegions?: any[];
+
+    /** 
+     * Array of regions to validate accessibility according to configured accessibilityValidation.
+     */
+    accessibilityRegions?: any[];
+
+    /** 
+     * Directory path for JSON results file.
+     * If set, creates eyes.json file with test results.
+     */
+    jsonFilePath?: string;
+
+    /** 
+     * Directory path for TAP results file.
+     * If set, creates eyes.tap file with test results.
+     */
+    tapFilePath?: string;
+
+    /** 
+     * Directory path for XUnit XML results file.
+     * If set, creates eyes.xml file with test results.
+     */
+    xmlFilePath?: string;
+
+    /**
+     * Selector, function, or timeout to wait before capturing.
+     * 
+     * * number: Milliseconds to wait before capturing.
+     * * string: CSS selector to wait for before capturing.
+     * * function: Predicate or async function to wait for before capturing.
+     * 
+     * @example
+     * waitBeforeCapture: '#container.ready',
+     * 
+     * @example
+     * waitBeforeCapture: () => document.querySelector('#container.ready') !== null,
+     * 
+     * @example
+     * waitBeforeCapture: 3_000
+     * 
+     * @see https://applitools.com/tutorials/sdks/storybook/component-config#waitBeforeCapture
+     */
+    waitBeforeCapture?: number | string | (() => boolean | Promise<boolean>);
+
+    /**
+     * Unique identifier for the batch of tests - set to the same value if you want to group tests together.
+     */
+    batchId?: string;
+
+    /**
+     * Name for the batch of tests - will appear in the Eyes dashboard.
+     */
+    batchName?: string;
+
+    /**
+     * Sequence name for the batch of tests - will appear in the Eyes dashboard (in the 'insights' page and in the batch details).
+     */
+    batchSequenceName?: string;
+
+    /**
+     * Name for the baseline branch - use it if you want to compare with a specific branch that is different from the current branch.
+     *
+     * @see for more information and recommendations regarding baseline branches, see the [documentation](https://applitools.com/tutorials/concepts/best-practices/branching).
+     */
+    baselineBranchName?: string;
+
+    /**
+     * Dry run - if true, no actual visual testing will be performed.
+     * @default false
+     */
+    isDisabled?: boolean;
+
+    /**
+     * Whether to ignore the baseline when comparing with the checkpoint (will make all checkpoints `new`)
+     * @default false
+     */
+    ignoreBaseline?: boolean
+
+    /**
+     * Settings for accessibility validation.
+     */
+    accessibilitySettings?: {
+        /**
+         * Level of accessibility validation to perform.
+         */
+        level?: 'AA' | 'AAA';
+
+        /**
+         * Array of specific accessibility guidelines to check.
+         */
+        guidelinesVersion?: "WCAG_2_0" | "WCAG_2_1";
+    };
+
+    /**
+     * Whether to notify when the test is complete (requires to turn on notifications in the Applitools dashboard).
+     * @see https://applitools.com/tutorials/integrations/chat-&-notifications/email
+     */
+    notifyOnCompletion?: boolean;
+
+    /**
+     * Whether to show browser logs in the test results.
+     * @default false
+     */
+    showBrowserLogs?: boolean;
+
+    /**
+     * A string formatted as `<ShardIndex>/<TotalShards>` to enable test sharding (running tests in parallel).
+     * @default undefined
+     */
+    shard?: string;
 }
+
+export type configKeys = keyof ApplitoolsConfig;

package/src/utils/config-validator.js

@@ -1,6 +1,8 @@
+// @ts-check
 'use strict';
 const chalk = require('chalk');
 const {Configuration} = require('@applitools/eyes');
+const defaultConfig = require('./../defaultConfig');
 
 // Get all keys directly from the base Configuration class
 const dynamicBaseKeys = [
@@ -30,31 +32,30 @@ const knownAliases = [
 const applitoolsBaseKeys = [...dynamicBaseKeys, ...knownAliases];
 
 // A list of all keys specific to the eyes-storybook package.
+/**
+ * @type {Array<keyof (import('../index').ApplitoolsConfig) |
+ *  'reloadPagePerStory' |
+ *  'startStorybookServerTimeout' |
+ *  'networkBlockPatterns' |
+ *  'browserRequestsTimeout' |
+ *  'browserHeadersOverride' |
+ *  'waitBeforeScreenshot' |
+ *  'waitBeforeScreenshots' |
+ *  'fakeIE' |
+ *  'storyConfiguration' |
+ *  'storyDataGap' |
+ *  'packagePath'
+ * >}
+ */
 const storybookSpecificKeys = [
-  'storybookPort',
-  'storybookHost',
-  'storybookConfigDir',
-  'storybookUrl',
-  'storybookStaticDir',
-  'showStorybookOutput',
-  'exitcode',
-  'include',
-  'variations',
+  'variations', // TODO - are we sure it should be supported from the applitools config file? https://applitools.com/tutorials/sdks/storybook/component-config#variations
   'runInDocker',
-  'readStoriesTimeout',
-  'reloadPagePerStory',
-  'startStorybookServerTimeout',
   'showLogs',
 
   // Browser & Puppeteer Control
   'browser',
   'puppeteerOptions',
-  'puppeteerExtraHTTPHeaders',
-  'navigationWaitUntil',
-  'networkBlockPatterns',
-  'browserRequestsTimeout',
-  'browserHeadersOverride',
-  'browserCacheRequests',
+  'puppeteerExtraHTTPHeaders', // created for a specific user, TODO - consider removing
 
   // Region Matching
   'ignoreRegions',
@@ -72,7 +73,6 @@ const storybookSpecificKeys = [
   // Legacy & Internal
   'waitBeforeScreenshot', // backward compatibility
   'waitBeforeScreenshots', // backward compatibility
-  'waitBeforeCapture',
   'fakeIE',
   'storyConfiguration',
   'storyDataGap',
@@ -80,7 +80,11 @@ const storybookSpecificKeys = [
 ];
 
 // Combine all known keys into a single Set for efficient O(1) lookups.
-const knownKeys = new Set([...storybookSpecificKeys, ...applitoolsBaseKeys]);
+const knownKeys = new Set([
+  ...storybookSpecificKeys,
+  ...applitoolsBaseKeys,
+  ...Object.keys(defaultConfig),
+]);
 
 /**
  * Checks the user's config object for any keys that are not recognized
@@ -101,6 +105,7 @@ function logUnrecognizedKeys(config, logger) {
     unrecognizedKeys.forEach(key => {
       console.log(chalk.yellow(`  - ${key}`));
     });
+    // @ts-ignore
     logger.log('\n');
 
     const docsUrl = 'https://applitools.com/tutorials/sdks/storybook/config#properties';

package/src/yargsOptions.js

@@ -83,6 +83,27 @@ module.exports = {
     choices: ['load', 'domcontentloaded', 'networkidle0', 'networkidle2'], // PuppeteerLifeCycleEvent values - https://pptr.dev/api/puppeteer.puppeteerlifecycleevent
   },
 
+  shard: {
+    description: 'Shard tests (format: current/total, e.g., "1/3")',
+    requiresArg: true,
+    string: true,
+    coerce: function (arg) {
+      const match = arg.match(/^(\d+)\/(\d+)$/);
+      if (!match) {
+        throw new Error('shard must be in format "current/total" (e.g., "1/3")');
+      }
+      const current = parseInt(match[1], 10);
+      const total = parseInt(match[2], 10);
+      if (current < 1 || current > total) {
+        throw new Error(`shard current (${current}) must be between 1 and total (${total})`);
+      }
+      if (total < 1) {
+        throw new Error(`shard total (${total}) must be at least 1`);
+      }
+      return {current, total};
+    },
+  },
+
   // general
   exitcode: {
     alias: 'e',

package/dist/getStoryByIndex.js

@@ -1,138 +0,0 @@
-
-function __getStoryByIndex(...args) {
-  var getStoryByIndex = (function () {
-  'use strict';
-
-  const API_VERSIONS = {
-    v4: 'v4',
-    v5: 'v5',
-    v5_2: 'v5_2',
-  };
-
-  function getClientAPI() {
-    const frameWindow = getFrameWindow();
-    const clientAPI = frameWindow.__STORYBOOK_CLIENT_API__;
-    const addons = frameWindow.__STORYBOOK_ADDONS;
-
-    return getAPI(getStorybookVersion());
-
-    function getStorybookVersion() {
-      const addons = frameWindow.__STORYBOOK_ADDONS;
-
-      if (frameWindow.__STORYBOOK_STORY_STORE__) {
-        return API_VERSIONS.v5_2;
-      } else if (frameWindow.__STORYBOOK_CLIENT_API__ && frameWindow.__STORYBOOK_CLIENT_API__.raw) {
-        return API_VERSIONS.v5;
-      } else if (
-        addons &&
-        addons.channel &&
-        addons.channel._listeners &&
-        addons.channel._listeners.setCurrentStory &&
-        addons.channel._listeners.setCurrentStory[0]
-      ) {
-        return API_VERSIONS.v4;
-      } else {
-        throw new Error("Cannot get client API: couldn't detect storybook version");
-      }
-    }
-
-    function getAPI(version) {
-      if (version) {
-        let api;
-        switch (version) {
-          case API_VERSIONS.v4: {
-            api = {
-              getStories: () => {
-                if (!frameWindow.__APPLITOOLS_STORIES) {
-                  frameWindow.__APPLITOOLS_STORIES = Object.values(clientAPI._storyStore._data)
-                    .map(({stories, kind}) => Object.values(stories).map(s => ({...s, kind})))
-                    .flat();
-                }
-                return frameWindow.__APPLITOOLS_STORIES;
-              },
-              selectStory: i => {
-                const {kind, name: story} = api.getStories()[i];
-                addons.channel._listeners.setCurrentStory[0]({kind, story});
-              },
-            };
-            break;
-          }
-
-          case API_VERSIONS.v5: {
-            api = {
-              getStories: () => {
-                return clientAPI.raw();
-              },
-              selectStory: i => {
-                clientAPI._storyStore.setSelection(clientAPI.raw()[i]);
-              },
-            };
-            break;
-          }
-
-          case API_VERSIONS.v5_2: {
-            api = {
-              getStories: () => {
-                return clientAPI.raw();
-              },
-              selectStory: i => {
-                frameWindow.__STORYBOOK_STORY_STORE__.setSelection({storyId: clientAPI.raw()[i].id});
-              },
-            };
-            break;
-          }
-        }
-
-        return {version, ...api};
-      }
-    }
-  }
-
-  function getFrameWindow() {
-    if (/iframe.html/.test(window.location.href)) {
-      return window;
-    }
-
-    const innerFrameWindow = Array.prototype.find.call(window.frames, frame => {
-      try {
-        return /\/iframe.html/.test(frame.location.href);
-      } catch (e) {}
-    });
-
-    if (innerFrameWindow) {
-      return innerFrameWindow;
-    }
-
-    if (window.__STORYBOOK_CLIENT_API__) {
-      return window;
-    }
-
-    throw new Error('Cannot get client API: no frameWindow');
-  }
-
-  var getClientAPI_1 = getClientAPI;
-
-  function getStoryIndex(index) {
-    let api;
-    try {
-      api = getClientAPI_1();
-      const story = api.getStories()[index];
-      if (!story) {
-        console.log('error cannot get story', index);
-        return;
-      }
-      return story;
-    } catch (ex) {
-      return {message: ex.message, version: api ? api.version : undefined};
-    }
-  }
-
-  var getStoryByIndex = getStoryIndex;
-
-  return getStoryByIndex;
-
-}());
-
-  return getStoryByIndex.apply(this, args);
-}
-module.exports = __getStoryByIndex