@applitools/eyes-storybook 3.55.9 → 3.57.0

package/CHANGELOG.md

@@ -1,5 +1,114 @@
 # Changelog
 
+## [3.57.0](https://github.com/Applitools-Dev/sdk/compare/js/eyes-storybook@3.56.0...js/eyes-storybook@3.57.0) (2025-08-05)
+
+
+### Features
+
+* improve configuration handling ([#3130](https://github.com/Applitools-Dev/sdk/issues/3130)) ([def7be1](https://github.com/Applitools-Dev/sdk/commit/def7be1dd07460f49142cddfe55203baa884e6c3))
+* release java ([7bc39e6](https://github.com/Applitools-Dev/sdk/commit/7bc39e679eab27a19322ca4b121177da7437c106))
+
+
+### Dependencies
+
+* @applitools/utils bumped to 1.11.0
+  #### Features
+
+  * improve configuration handling ([#3130](https://github.com/Applitools-Dev/sdk/issues/3130)) ([def7be1](https://github.com/Applitools-Dev/sdk/commit/def7be1dd07460f49142cddfe55203baa884e6c3))
+  * make utils.general.guid crypto secured ([#3137](https://github.com/Applitools-Dev/sdk/issues/3137)) ([775df08](https://github.com/Applitools-Dev/sdk/commit/775df08307e41402a6603812205bc857bd3f936e))
+* @applitools/eyes bumped to 1.36.0
+  #### Features
+
+  * improve configuration handling ([#3130](https://github.com/Applitools-Dev/sdk/issues/3130)) ([def7be1](https://github.com/Applitools-Dev/sdk/commit/def7be1dd07460f49142cddfe55203baa884e6c3))
+  * release java ([7bc39e6](https://github.com/Applitools-Dev/sdk/commit/7bc39e679eab27a19322ca4b121177da7437c106))
+
+
+
+* @applitools/snaptdout bumped to 1.1.0
+  #### Features
+
+  * release java ([7bc39e6](https://github.com/Applitools-Dev/sdk/commit/7bc39e679eab27a19322ca4b121177da7437c106))
+* @applitools/test-server bumped to 1.3.0
+  #### Features
+
+  * release java ([7bc39e6](https://github.com/Applitools-Dev/sdk/commit/7bc39e679eab27a19322ca4b121177da7437c106))
+
+
+
+* @applitools/logger bumped to 2.2.1
+
+* @applitools/dom-snapshot bumped to 4.13.1
+
+* @applitools/socket bumped to 1.3.1
+
+* @applitools/req bumped to 1.8.1
+
+* @applitools/image bumped to 1.2.1
+
+* @applitools/dom-capture bumped to 11.6.1
+
+* @applitools/driver bumped to 1.23.1
+
+* @applitools/spec-driver-webdriver bumped to 1.4.1
+
+* @applitools/spec-driver-selenium bumped to 1.7.1
+
+* @applitools/spec-driver-puppeteer bumped to 1.6.1
+
+* @applitools/screenshoter bumped to 3.12.1
+
+* @applitools/nml-client bumped to 1.11.1
+
+* @applitools/tunnel-client bumped to 1.10.2
+
+* @applitools/ufg-client bumped to 1.17.1
+
+* @applitools/core-base bumped to 1.27.1
+
+* @applitools/ec-client bumped to 1.12.2
+
+* @applitools/core bumped to 4.44.2
+
+
+## [3.56.0](https://github.com/Applitools-Dev/sdk/compare/js/eyes-storybook@3.55.9...js/eyes-storybook@3.56.0) (2025-07-23)
+
+
+### Features
+
+* eyes-setup script | AD-9543 ([#3075](https://github.com/Applitools-Dev/sdk/issues/3075)) ([27f15f9](https://github.com/Applitools-Dev/sdk/commit/27f15f9b54ba93c8189214a5df424b543d564120))
+
+
+### Bug Fixes
+
+* use strict mode to get config | AD-10156 ([#3092](https://github.com/Applitools-Dev/sdk/issues/3092)) ([6b2d21b](https://github.com/Applitools-Dev/sdk/commit/6b2d21b23219f03b56d27604d0afe768eaae6fc2))
+
+
+### Dependencies
+
+* @applitools/nml-client bumped to 1.10.0
+  #### Features
+
+  * android multi target | AD-9868 ([#2943](https://github.com/Applitools-Dev/sdk/issues/2943)) ([808aa21](https://github.com/Applitools-Dev/sdk/commit/808aa21e489c3562b93006e2e26ff7ffbb743dd6))
+
+
+
+* @applitools/core-base bumped to 1.26.0
+  #### Features
+
+  * batch properties limit | FLD-3174 ([#3080](https://github.com/Applitools-Dev/sdk/issues/3080)) ([feb9e79](https://github.com/Applitools-Dev/sdk/commit/feb9e79d79f5eab3c58eac2b4ef3c15a562f079c))
+* @applitools/ec-client bumped to 1.11.1
+
+* @applitools/core bumped to 4.43.0
+  #### Features
+
+  * android multi target | AD-9868 ([#2943](https://github.com/Applitools-Dev/sdk/issues/2943)) ([808aa21](https://github.com/Applitools-Dev/sdk/commit/808aa21e489c3562b93006e2e26ff7ffbb743dd6))
+  * batch properties limit | FLD-3174 ([#3080](https://github.com/Applitools-Dev/sdk/issues/3080)) ([feb9e79](https://github.com/Applitools-Dev/sdk/commit/feb9e79d79f5eab3c58eac2b4ef3c15a562f079c))
+
+
+
+* @applitools/eyes bumped to 1.35.3
+
+
 ## [3.55.9](https://github.com/Applitools-Dev/sdk/compare/js/eyes-storybook@3.55.8...js/eyes-storybook@3.55.9) (2025-07-15)
 
 

package/bin/eyes-setup.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../src/eyes-setup');

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+import type { Configuration, DesktopBrowserInfo, ChromeEmulationInfo, IOSDeviceInfo, IOSMultiDeviceInfo } from '@applitools/eyes';
+/**
+ * https://applitools.com/tutorials/sdks/storybook/config
+ */
+export type ApplitoolsConfig = Omit<Configuration, '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;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@applitools/eyes-storybook",
-  "version": "3.55.9",
+  "version": "3.57.0",
   "description": "",
   "keywords": [
     "applitools",
@@ -14,7 +14,11 @@
   "homepage": "https://applitools.com/tutorials/sdks/storybook",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Applitools Team <team@applitools.com>",
-  "bin": "./bin/eyes-storybook.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "eyes-setup": "./bin/eyes-setup.js",
+    "eyes-storybook": "./bin/eyes-storybook.js"
+  },
   "files": [
     "src",
     "bin",
@@ -22,7 +26,8 @@
   ],
   "scripts": {
     "lint": "run --top-level eslint '**/*.js'",
-    "build": "rollup -c rollup.config.js",
+    "build:types": "tsc --project tsconfig.types.json",
+    "build": "rollup -c rollup.config.js && yarn build:types",
     "build:heavy": "node scripts/bitmap.js",
     "test": "yarn build && yarn test:mocha",
     "test:mocha": "run --top-level mocha 'test/{unit,it,e2e}/*.test.js'",
@@ -53,15 +58,16 @@
     "up:framework": "cd test/fixtures/storybook-versions/${APPLITOOLS_FRAMEWORK_VERSION} && npm ci"
   },
   "dependencies": {
-    "@applitools/core": "4.42.1",
-    "@applitools/driver": "1.22.1",
-    "@applitools/eyes": "1.35.2",
+    "@applitools/core": "4.44.2",
+    "@applitools/driver": "1.23.1",
+    "@applitools/eyes": "1.36.0",
     "@applitools/functional-commons": "1.6.0",
-    "@applitools/logger": "2.1.5",
+    "@applitools/logger": "2.2.1",
     "@applitools/monitoring-commons": "1.0.19",
-    "@applitools/spec-driver-puppeteer": "1.5.1",
-    "@applitools/ufg-client": "1.16.14",
-    "@applitools/utils": "1.9.0",
+    "@applitools/spec-driver-puppeteer": "1.6.1",
+    "@applitools/ufg-client": "1.17.1",
+    "@applitools/utils": "1.11.0",
+    "@inquirer/prompts": "7.0.1",
     "boxen": "4.2.0",
     "chalk": "3.0.0",
     "detect-port": "1.3.0",
@@ -75,8 +81,8 @@
   },
   "devDependencies": {
     "@applitools/bongo": "^5.10.0",
-    "@applitools/snaptdout": "^1.0.0",
-    "@applitools/test-server": "^1.2.3",
+    "@applitools/snaptdout": "^1.1.0",
+    "@applitools/test-server": "^1.3.0",
     "@applitools/test-utils": "^1.5.17",
     "@storybook/addon-interactions": "^6.4.18",
     "@storybook/react": "^6.5.16",
@@ -92,6 +98,7 @@
     "react-dom": "^16.12.0",
     "rollup": "^1.28.0",
     "rollup-plugin-commonjs": "^10.1.0",
+    "typescript": "^5.3.3",
     "ua-parser-js": "^0.7.21"
   },
   "engines": {

package/src/eyes-setup.js

@@ -0,0 +1,269 @@
+#!/usr/bin/env node
+
+const fs = require('fs').promises;
+const {input, confirm} = require('@inquirer/prompts');
+const yargs = require('yargs/yargs');
+const chalk = require('chalk');
+const {pathToFileURL} = require('url');
+const utils = require('@applitools/utils');
+
+const {hideBin} = require('yargs/helpers');
+yargs(hideBin(process.argv))
+  .command({
+    command: '*',
+    builder: yargs => {
+      const args = yargs.options({
+        apiKey: {
+          describe:
+            "Your Applitools Team's API key (here's how to obtain it: https://applitools.com/docs/topics/overview/obtain-api-key.html)",
+          type: 'string',
+        },
+        serverUrl: {describe: 'Your Eyes dedicated cloud server URL', type: 'string'},
+      });
+      return args;
+    },
+    handler: handleError(init),
+  })
+  .help()
+  .parse();
+
+function handleError(asyncFunc) {
+  return async (...args) =>
+    asyncFunc(...args).catch(err => {
+      if (err.name === 'ExitPromptError') {
+        log('See you next time!');
+      } else {
+        error(`Error while setting up Eyes: ${err.message}`);
+      }
+      process.exit(1);
+    });
+}
+
+async function init(args) {
+  log(chalk.yellow('Setting up Eyes-Storybook for your project:'));
+
+  let {config, fileName, isCorrupted} = await loadExistingConfig();
+
+  if (isCorrupted) {
+    log(chalk.yellow(`\nWarning: Your configuration file '${fileName}' appears to be corrupted.`));
+    const shouldOverwrite = await confirm({
+      message:
+        'Would you like to create a new one? This will replace the corrupted file (Default Yes):',
+      default: true,
+    });
+
+    if (!shouldOverwrite) {
+      log('Aborting setup. Please fix your configuration file manually or remove it.');
+      process.exit(0);
+    }
+    // By letting this block finish, the script proceeds as if no config was found
+  }
+
+  // If no config exists or is corrupted, run the interactive setup
+  let apiKey,
+    serverUrl,
+    warnForApiKey = false;
+
+  let shouldUpdate = !config;
+  if (shouldUpdate) {
+    let shouldUseEnvApiKey = false;
+    if (utils.general.getEnvValue('API_KEY')) {
+      shouldUseEnvApiKey = await confirm({
+        message:
+          'Detected APPLITOOLS_API_KEY environment variable. Would you like it to be used? (default Yes):',
+        default: true,
+      });
+      if (shouldUseEnvApiKey) {
+        apiKey = 'process.env.APPLITOOLS_API_KEY';
+      }
+      warnForApiKey = !shouldUseEnvApiKey; // Warn if the user has an env var but doesn't use it
+    }
+
+    let shouldUseEnvServerUrl = false;
+    for (const url of ['EYES_SERVER_URL', 'SERVER_URL']) {
+      if (utils.general.getEnvValue(url)) {
+        shouldUseEnvServerUrl = await confirm({
+          message: `Detected APPLITOOLS_${url} environment variable. Would you like it to be used? (default Yes):`,
+          default: true,
+        });
+        if (shouldUseEnvServerUrl) {
+          serverUrl = `process.env.APPLITOOLS_${url}`;
+          break; // Use the first one found
+        }
+      }
+    }
+
+    if (!shouldUseEnvApiKey) {
+      apiKey =
+        args.apiKey ??
+        (await input({
+          message:
+            'Enter your API key (https://applitools.com/docs/topics/overview/obtain-api-key.html):',
+        }));
+      warnForApiKey = apiKey !== ''; // Warn if the user provided any API key directly
+    }
+
+    if (!shouldUseEnvServerUrl) {
+      serverUrl =
+        args.serverUrl ??
+        (await input({
+          message: 'Enter your Eyes server URL (default is https://eyes.applitools.com):',
+        }));
+    }
+
+    config = {
+      ...(config || {}),
+      appName: 'My Storybook App',
+      batchName: 'My Storybook',
+      showLogs: false,
+    };
+
+    const fileContent = generateConfigContent();
+    await fs.writeFile(fileName, fileContent, 'utf8');
+  }
+
+  printPostlude();
+
+  // --- Helper Functions ---
+
+  async function loadExistingConfig() {
+    const configFiles = [
+      'applitools.config.js',
+      'applitools.config.mjs',
+      'applitools.config.cjs',
+      'eyes.config.js',
+    ];
+
+    for (const file of configFiles) {
+      try {
+        const fileUrl = pathToFileURL(file).href;
+        const module = await import(`${fileUrl}?t=${Date.now()}`); // Append timestamp to bypass cache
+
+        return {config: module.default || module, fileName: file, isCorrupted: false};
+      } catch (err) {
+        if (err.code === 'ERR_MODULE_NOT_FOUND') {
+          // This file doesn't exist, so we continue searching for the one that does.
+          continue;
+        }
+
+        return {config: null, fileName: file, isCorrupted: true};
+      }
+    }
+
+    // No file was found in any of the possible locations.
+    // We return a default filename for a new file to be created.
+    return {config: null, fileName: 'applitools.config.js', isCorrupted: false};
+  }
+
+  function generateConfigContent() {
+    const envConfigMap = {
+      batchName: 'APPLITOOLS_BATCH_NAME',
+      batchId: 'APPLITOOLS_BATCH_ID',
+      showLogs: 'APPLITOOLS_SHOW_LOGS',
+      batchSequenceName: 'APPLITOOLS_BATCH_SEQUENCE_NAME',
+      proxy: 'APPLITOOLS_PROXY',
+      notifyOnCompletion: 'APPLITOOLS_NOTIFY_ON_COMPLETION',
+      concurrentTabs: 'APPLITOOLS_CONCURRENT_TABS',
+      appName: 'APPLITOOLS_APP_NAME',
+    };
+
+    const configLines = [];
+
+    // Handle apiKey
+    if (apiKey === 'process.env.APPLITOOLS_API_KEY') {
+      configLines.push('apiKey: process.env.APPLITOOLS_API_KEY,');
+    } else if (apiKey) {
+      configLines.push(
+        `apiKey: '${apiKey}', // Warning: 'apiKey' is not obscured, consider setting it via environment variable APPLITOOLS_API_KEY`,
+      );
+    } else {
+      configLines.push(`// apiKey: '',`);
+    }
+
+    // Handle serverUrl
+    if (serverUrl && serverUrl.startsWith('process.env.')) {
+      configLines.push(`serverUrl: ${serverUrl},`);
+    } else if (serverUrl) {
+      configLines.push(`serverUrl: '${serverUrl}',`);
+    }
+
+    // Handle other config lines by prioritizing env vars over defaults
+    const otherKeys = [
+      'appName',
+      'batchName',
+      'batchId',
+      'showLogs',
+      'batchSequenceName',
+      'proxy',
+      'notifyOnCompletion',
+      'concurrentTabs',
+      'navigationWaitUntil',
+      'waitBeforeCapture',
+    ];
+
+    for (const key of otherKeys) {
+      const envVar = envConfigMap[key];
+      // Check if an environment variable for this key is set
+      if (envVar && utils.general.getEnvValue(envVar.replace('APPLITOOLS_', ''))) {
+        configLines.push(`${key}: process.env.${envVar},`);
+      } else if (Object.prototype.hasOwnProperty.call(config, key)) {
+        // Otherwise, use the default value from the config object
+        const value = config[key];
+        if (value !== undefined) {
+          const line = typeof value === 'string' ? `${key}: '${value}',` : `${key}: ${value},`;
+          configLines.push(line);
+        }
+      }
+    }
+
+    return `/**
+ * @type {import('@applitools/eyes-storybook').ApplitoolsConfig}
+ **/
+module.exports = {
+  ${configLines.join('\n  ')}
+  // browsersInfo: [
+  //    {width: 1024, height: 768, name: 'firefox'},
+  //    {width: 1024, height: 768, name: 'chrome'},
+  //    {iosDeviceInfo: {deviceName: 'iPhone 16'}},
+  //    {chromeEmulationInfo: {deviceName: 'Galaxy S20'}},
+  // ]
+};
+`;
+  }
+
+  function printPostlude() {
+    log('');
+    if (shouldUpdate) {
+      log(
+        chalk.green('✔ Success!'),
+        chalk.bold('\n'),
+        chalk.bold('Eyes Storybook is now set up!'),
+        chalk.bold('Please visit our Storybook documentation to learn more.'),
+        chalk.bold('https://applitools.com/tutorials/sdks/storybook/quickstart'),
+      );
+    } else {
+      log(
+        chalk.green('✔ Good news! Eyes Storybook is already properly configured!'),
+        chalk.bold('\n'),
+        chalk.bold('Please visit our Storybook documentation to learn more.'),
+        chalk.bold('https://applitools.com/tutorials/sdks/storybook/quickstart'),
+      );
+    }
+
+    if (warnForApiKey) {
+      log(
+        chalk.yellow(
+          '\nWarning: Consider setting your API key via the APPLITOOLS_API_KEY environment variable.',
+        ),
+      );
+    }
+  }
+}
+
+function log(...args) {
+  console.log(...args);
+}
+
+function error(...args) {
+  console.error(...args);
+}

package/src/eyesStorybook.js

@@ -91,7 +91,11 @@ async function eyesStorybook({
       },
     })
     .catch(async error => {
-      if (error && error.message && error.message.includes('Unauthorized(401)')) {
+      if (
+        error &&
+        error.message &&
+        error.message.includes('Please check your API key and try again.')
+      ) {
         const failMsg = 'Incorrect API Key';
         logger.log(failMsg);
         await browser.close();

package/src/generateConfig.js

@@ -10,7 +10,7 @@ function generateConfig({argv = {}, defaultConfig = {}, externalConfigParams = [
   const defaultConfigParams = Object.keys(defaultConfig);
   const configPaths = argv.conf ? [resolve(process.cwd(), argv.conf)] : undefined;
   const configParams = uniq(defaultConfigParams.concat(externalConfigParams));
-  const config = utils.config.getConfig({paths: configPaths, params: configParams});
+  const config = getAndParseConfig({configPaths, configParams});
   const argvConfig = lodash.pick(argv, configParams);
   const result = Object.assign({}, defaultConfig, config, argvConfig);
 
@@ -81,18 +81,50 @@ function generateConfig({argv = {}, defaultConfig = {}, externalConfigParams = [
   return result;
 }
 
+function getAndParseConfig({configPaths, configParams}) {
+  try {
+    return utils.config.getConfig({
+      paths: configPaths,
+      params: configParams,
+      strict: true,
+      traverse: false,
+    });
+  } catch (error) {
+    if (error.message.includes('Could not find configuration file')) {
+      return utils.config.populateConfigParams({config: {}, params: configParams});
+    }
+    const documentationUrl = 'https://applitools.com/tutorials/sdks/storybook/config#properties';
+    throw new Error(
+      `Your configuration file is invalid. Please review our documentation for valid configuration settings: ${documentationUrl}. 
+      Additionally, you can generate a new configuration by running 'npx eyes-setup'.
+      \n\nError details: ${error.message}`.trim(),
+    );
+  }
+}
+
 function transformConfig(result) {
   transformLayoutBreakpoints(result);
   transformBrowser(result);
 }
 
 function transformBrowser(result) {
+  if (result.browsersInfo) {
+    transformBrowsersInfo(result.browsersInfo);
+    delete result.browsersInfo;
+  }
   if (result.browser) {
+    transformBrowsersInfo(result.browser);
+    delete result.browser;
+  }
+
+  return result;
+
+  function transformBrowsersInfo(info) {
     result.environments = [];
-    if (!Array.isArray(result.browser)) {
-      result.browser = [result.browser];
+    if (!utils.types.isArray(info)) {
+      info = [info];
     }
-    result.environments = result.browser.map(browser => {
+    result.environments = info.map(browser => {
       if (browser.deviceName) {
         return {chromeEmulationInfo: browser};
       } else if (utils.types.has(browser, 'iosDeviceInfo')) {
@@ -104,8 +136,6 @@ function transformBrowser(result) {
       return browser;
     });
   }
-  delete result.browser;
-  return result;
 }
 
 function transformLayoutBreakpoints(result) {

package/src/index.ts

@@ -0,0 +1,35 @@
+import type {Configuration, DesktopBrowserInfo, ChromeEmulationInfo, IOSDeviceInfo, IOSMultiDeviceInfo} from '@applitools/eyes'
+
+/**
+ * https://applitools.com/tutorials/sdks/storybook/config
+ */
+export type ApplitoolsConfig = Omit<Configuration, '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;
+}

package/src/utils/config-validator.js

@@ -0,0 +1,116 @@
+'use strict';
+const chalk = require('chalk');
+const {Configuration} = require('@applitools/eyes');
+
+// Get all keys directly from the base Configuration class
+const dynamicBaseKeys = [
+  ...Object.getOwnPropertyNames(Object.getPrototypeOf(new Configuration())),
+].filter(
+  prop =>
+    !prop.startsWith('get') &&
+    !prop.startsWith('set') &&
+    !prop.startsWith('to') &&
+    !prop.startsWith('_') &&
+    prop !== 'constructor',
+);
+
+// known aliases that are not on the Configuration prototype
+const knownAliases = [
+  'envName',
+  'testConcurrency',
+  'concurrency',
+  'eyesServerUrl',
+  'batchId',
+  'batchName',
+  'batchSequenceName',
+  'keepBatchOpen',
+  'environments',
+];
+
+const applitoolsBaseKeys = [...dynamicBaseKeys, ...knownAliases];
+
+// A list of all keys specific to the eyes-storybook package.
+const storybookSpecificKeys = [
+  'storybookPort',
+  'storybookHost',
+  'storybookConfigDir',
+  'storybookUrl',
+  'storybookStaticDir',
+  'showStorybookOutput',
+  'exitcode',
+  'include',
+  'variations',
+  'runInDocker',
+  'readStoriesTimeout',
+  'reloadPagePerStory',
+  'startStorybookServerTimeout',
+
+  // Browser & Puppeteer Control
+  'browser',
+  'puppeteerOptions',
+  'puppeteerExtraHTTPHeaders',
+  'navigationWaitUntil',
+  'networkBlockPatterns',
+  'browserRequestsTimeout',
+  'browserHeadersOverride',
+  'browserCacheRequests',
+
+  // Region Matching
+  'ignoreRegions',
+  'floatingRegions',
+  'layoutRegions',
+  'strictRegions',
+  'contentRegions',
+  'accessibilityRegions',
+
+  // Reporting
+  'tapFilePath',
+  'xmlFilePath',
+  'jsonFilePath',
+
+  // Legacy & Internal
+  'waitBeforeScreenshot', // backward compatibility
+  'waitBeforeScreenshots', // backward compatibility
+  'waitBeforeCapture',
+  'fakeIE',
+  'storyConfiguration',
+  'storyDataGap',
+  'packagePath',
+];
+
+// Combine all known keys into a single Set for efficient O(1) lookups.
+const knownKeys = new Set([...storybookSpecificKeys, ...applitoolsBaseKeys]);
+
+/**
+ * Checks the user's config object for any keys that are not recognized
+ * and logs a warning to the console if any are found.
+ * @param {object} config - The user's configuration object.
+ * @param {object} logger - The logger instance.
+ */
+function logUnrecognizedKeys(config, logger) {
+  const unrecognizedKeys = Object.keys(config).filter(key => !knownKeys.has(key));
+
+  if (unrecognizedKeys.length > 0) {
+    // uses a warning sign emoji - ⚠️
+    console.log(
+      chalk.yellow(
+        `\n\u26A0 The following configuration keys are unrecognized and will be ignored:`,
+      ),
+    );
+    unrecognizedKeys.forEach(key => {
+      console.log(chalk.yellow(`  - ${key}`));
+    });
+    logger.log('\n');
+
+    const docsUrl = 'https://applitools.com/tutorials/sdks/storybook/config#properties';
+    console.log(
+      chalk.bold(`Please review our documentation for valid configuration settings: ${docsUrl}`),
+    );
+  }
+}
+
+module.exports = {
+  logUnrecognizedKeys,
+  // Exporting the set is optional but can be useful for other utilities
+  knownKeys,
+};

package/src/validateAndPopulateConfig.js

@@ -13,9 +13,11 @@ const startStorybookServer = require('./startStorybookServer');
 const {isIE} = require('./shouldRenderIE');
 const {makeLogger} = require('@applitools/logger');
 const determineStorybookVersion = require('./utils/determineStorybookVersion');
+const {logUnrecognizedKeys} = require('./utils/config-validator');
+const utils = require('@applitools/utils');
 
 async function validateAndPopulateConfig({config, packagePath = '', logger = makeLogger()}) {
-  if (!config.apiKey) {
+  if (!config.apiKey && !utils.general.getEnvValue('API_KEY')) {
     throw new Error(missingApiKeyFailMsg);
   }
 
@@ -77,5 +79,8 @@ async function validateAndPopulateConfig({config, packagePath = '', logger = mak
       ),
     );
   }
+
+  logUnrecognizedKeys(config, logger);
 }
+
 module.exports = validateAndPopulateConfig;