@camperaid/watest 2.6.2 → 2.6.3

package/.watestrc.js

@@ -54,6 +54,12 @@ const cfg = {
    */
   webdrivers: process.env.WATEST_WEBDRIVERS,
 
+  /**
+   * Project-defined webdriver aliases. JSON object mapping alias names to
+   * { browser, isMobile?, chrome?, windowWidth?, windowHeight? }.
+   */
+  webdriver_aliases: process.env.WATEST_WEBDRIVER_ALIASES,
+
   /**
    * Logger module.
    */

package/README.md

@@ -121,6 +121,7 @@ WATEST_TMP_DIR=/tmp                          # Temporary files directory
 
 # WebDriver
 WATEST_WEBDRIVERS='["chrome","firefox"]'     # Browser list (JSON array)
+WATEST_WEBDRIVER_ALIASES='{"chrome-mobile":{"browser":"chrome","isMobile":true,"chrome":{"mobileEmulation":{"deviceName":"iPhone 7"}}}}'
 WATEST_WEBDRIVER_HEADLESS=true               # Run browsers headless
 WATEST_WEBDRIVER_LOGLEVEL=info               # WebDriver log level
 WATEST_WEBDRIVER_WINDOW_WIDTH=1280           # Browser window width
@@ -134,12 +135,38 @@ WATEST_IGNORE_PATTERN=_browser\.js$          # Regex for files to skip
 
 ### Webdrivers
 
-Built-in webdriver configurations:
+Built-in browsers:
 
 - `chrome` - Chrome browser
-- `chrome-mobile` - Chrome with iPhone emulation
 - `firefox` - Firefox browser
 - `safari` - Safari browser
+- `edge` - Edge browser
+
+Project-defined aliases go in `.watestrc.js` as `webdriver_aliases` (or
+`WATEST_WEBDRIVER_ALIASES` JSON env var). Each alias maps a name to a base
+browser plus overrides:
+
+```js
+webdriver_aliases: {
+  'chrome-mobile': {
+    browser: 'chrome',
+    isMobile: true,
+    chrome: {
+      mobileEmulation: { deviceName: 'iPhone 7' },
+    },
+  },
+  'chrome-iphone10': {
+    browser: 'chrome',
+    isMobile: true,
+    chrome: {
+      mobileEmulation: { deviceName: 'iPhone X' },
+    },
+  },
+},
+```
+
+Supported alias fields: `browser` (required), `isMobile`, `browserLoggingOn`,
+`chrome.mobileEmulation`, `windowWidth`, `windowHeight`.
 
 ## CLI Options
 

package/core/series.js

@@ -692,6 +692,9 @@ class Series {
       // Set a webdiver on stack if not empty.
       if (webdriver) {
         settings.webdriver = webdriver;
+        process.env.WATEST_WEBDRIVER = webdriver;
+      } else {
+        delete process.env.WATEST_WEBDRIVER;
       }
 
       // Subtests.

package/core/settings.js

@@ -1,5 +1,14 @@
 import path from 'path';
 
+const baseBrowsers = ['chrome', 'firefox', 'safari', 'edge'];
+
+const baseBrowserDefaults = {
+  chrome: { chrome: true, browserLoggingOn: true },
+  firefox: { firefox: true },
+  safari: { safari: true },
+  edge: { edge: true },
+};
+
 class Settings {
   constructor() {
     this.log_dir = '';
@@ -8,6 +17,11 @@ class Settings {
     this.logger = null;
     this.servicer = null;
     this.silent = false;
+    this.webdriver_aliases = {};
+  }
+
+  get baseBrowsers() {
+    return baseBrowsers;
   }
 
   async initialize(options = {}) {
@@ -94,7 +108,128 @@ class Settings {
     }
   }
 
+  parseJsonObject(value, label) {
+    if (value == null || value === '') {
+      return null;
+    }
+    if (typeof value == 'object') {
+      return value;
+    }
+    if (typeof value == 'string') {
+      try {
+        return JSON.parse(value);
+      } catch (e) {
+        console.error(`Settings: failed to parse ${label} '${value}'`, e);
+      }
+    }
+    return null;
+  }
+
+  setupWebdriverAliases() {
+    this.webdriver_aliases = {};
+
+    const aliases = this.parseJsonObject(
+      this.rc.webdriver_aliases,
+      'webdriver_aliases',
+    );
+    if (!aliases) {
+      return;
+    }
+
+    for (const [name, alias] of Object.entries(aliases)) {
+      if (baseBrowsers.includes(name)) {
+        throw new Error(
+          `Settings: webdriver alias '${name}' conflicts with built-in browser`,
+        );
+      }
+      if (!alias || typeof alias != 'object') {
+        throw new Error(
+          `Settings: webdriver alias '${name}' must be an object`,
+        );
+      }
+      if (!alias.browser) {
+        throw new Error(
+          `Settings: webdriver alias '${name}' is missing required 'browser' field`,
+        );
+      }
+      if (!baseBrowsers.includes(alias.browser)) {
+        throw new Error(
+          `Settings: webdriver alias '${name}' has unexpected browser '${alias.browser}'`,
+        );
+      }
+      this.webdriver_aliases[name] = alias;
+    }
+  }
+
+  isKnownWebdriver(name) {
+    return baseBrowsers.includes(name) || name in this.webdriver_aliases;
+  }
+
+  resolveWebdriver(name) {
+    if (!name) {
+      throw new Error(`Settings: no webdriver name provided`);
+    }
+
+    const alias = this.webdriver_aliases[name];
+    if (alias) {
+      const flags = {
+        ...baseBrowserDefaults[alias.browser],
+      };
+      if (alias.isMobile) {
+        flags.isMobile = true;
+      }
+      if (alias.browserLoggingOn != null) {
+        flags.browserLoggingOn = alias.browserLoggingOn;
+      }
+
+      return {
+        name,
+        browser: alias.browser,
+        flags,
+        chrome: alias.chrome || null,
+        windowWidth: alias.windowWidth,
+        windowHeight: alias.windowHeight,
+      };
+    }
+
+    if (baseBrowsers.includes(name)) {
+      return {
+        name,
+        browser: name,
+        flags: { ...baseBrowserDefaults[name] },
+        chrome: null,
+        windowWidth: undefined,
+        windowHeight: undefined,
+      };
+    }
+
+    throw new Error(
+      `Settings: unexpected webdriver '${name}', define it in webdriver_aliases`,
+    );
+  }
+
+  validateWebdrivers() {
+    if (!this.webdrivers) {
+      return;
+    }
+    if (!(this.webdrivers instanceof Array)) {
+      throw new Error(
+        `Settings: webdrivers must be an array, got: ${JSON.stringify(this.webdrivers)}`,
+      );
+    }
+
+    for (const webdriver of this.webdrivers) {
+      if (!this.isKnownWebdriver(webdriver)) {
+        throw new Error(
+          `Settings: unexpected webdriver '${webdriver}', define it in webdriver_aliases`,
+        );
+      }
+    }
+  }
+
   setupWebdrivers() {
+    this.setupWebdriverAliases();
+
     this.webdrivers = this.rc.webdrivers;
     if (typeof this.rc.webdrivers == 'string') {
       try {
@@ -107,6 +242,8 @@ class Settings {
       }
     }
 
+    this.validateWebdrivers();
+
     this.webdriver = null;
     this.webdriver_headless =
       this.rc.webdriver_headless == true ||
@@ -142,6 +279,13 @@ class Settings {
     if (this.webdrivers && !this.silent) {
       console.log(`Settings: ${this.webdrivers.join(', ')} webdrivers`);
     }
+
+    const aliasCount = Object.keys(this.webdriver_aliases).length;
+    if (aliasCount > 0 && !this.silent) {
+      console.log(
+        `Settings: ${aliasCount} webdriver alias(es): ${Object.keys(this.webdriver_aliases).join(', ')}`,
+      );
+    }
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camperaid/watest",
-  "version": "2.6.2",
+  "version": "2.6.3",
   "description": "Web Application Testsuite",
   "type": "module",
   "engines": {

package/tests/core/t-webdriver-aliases.js

@@ -0,0 +1,179 @@
+import { is, throws } from '../base/test.js';
+import { settings } from '../../core/settings.js';
+import { DriverBase } from '../../webdriver/driver-base.js';
+
+function withSettings(rcPatch, fn) {
+  const saved = {
+    rc: { ...settings.rc },
+    webdriver_aliases: { ...settings.webdriver_aliases },
+    webdrivers: settings.webdrivers,
+  };
+  settings.rc = { ...settings.rc, ...rcPatch };
+  settings.silent = true;
+  try {
+    settings.setupWebdrivers();
+    return fn();
+  } finally {
+    settings.rc = saved.rc;
+    settings.webdriver_aliases = saved.webdriver_aliases;
+    settings.webdrivers = saved.webdrivers;
+    settings.silent = false;
+  }
+}
+
+export function test() {
+  const chromeMobileAlias = {
+    browser: 'chrome',
+    isMobile: true,
+    chrome: {
+      mobileEmulation: { deviceName: 'iPhone 7' },
+    },
+  };
+
+  withSettings(
+    {
+      webdriver_aliases: {
+        'chrome-mobile': chromeMobileAlias,
+      },
+    },
+    () => {
+      is(
+        settings.resolveWebdriver('chrome-mobile'),
+        {
+          name: 'chrome-mobile',
+          browser: 'chrome',
+          flags: {
+            chrome: true,
+            browserLoggingOn: true,
+            isMobile: true,
+          },
+          chrome: {
+            mobileEmulation: { deviceName: 'iPhone 7' },
+          },
+          windowWidth: undefined,
+          windowHeight: undefined,
+        },
+        'resolve chrome-mobile alias',
+      );
+
+      is(
+        settings.resolveWebdriver('chrome'),
+        {
+          name: 'chrome',
+          browser: 'chrome',
+          flags: {
+            chrome: true,
+            browserLoggingOn: true,
+          },
+          chrome: null,
+          windowWidth: undefined,
+          windowHeight: undefined,
+        },
+        'resolve chrome base browser',
+      );
+
+      is(settings.isKnownWebdriver('chrome-mobile'), true, 'known alias');
+      is(settings.isKnownWebdriver('firefox'), true, 'known base browser');
+      is(settings.isKnownWebdriver('unknown'), false, 'unknown webdriver');
+    },
+  );
+
+  withSettings(
+    {
+      webdriver_aliases: JSON.stringify({
+        'firefox-mobile': {
+          browser: 'firefox',
+          isMobile: true,
+        },
+      }),
+    },
+    () => {
+      is(
+        settings.resolveWebdriver('firefox-mobile').browser,
+        'firefox',
+        'parse alias JSON string',
+      );
+      is(
+        DriverBase.isStdOutLogging('firefox-mobile'),
+        true,
+        'firefox alias uses stdout logging',
+      );
+    },
+  );
+
+  withSettings(
+    {
+      webdriver_aliases: {
+        'safari-mobile': {
+          browser: 'safari',
+          isMobile: true,
+          windowWidth: 375,
+          windowHeight: 667,
+        },
+      },
+    },
+    () => {
+      is(
+        settings.resolveWebdriver('safari-mobile'),
+        {
+          name: 'safari-mobile',
+          browser: 'safari',
+          flags: {
+            safari: true,
+            isMobile: true,
+          },
+          chrome: null,
+          windowWidth: 375,
+          windowHeight: 667,
+        },
+        'resolve safari-mobile alias',
+      );
+    },
+  );
+
+  withSettings(
+    {
+      webdrivers: ['chrome-mobile'],
+      webdriver_aliases: {
+        'chrome-mobile': chromeMobileAlias,
+      },
+    },
+    () => {
+      is(settings.webdrivers, ['chrome-mobile'], 'validate known alias');
+    },
+  );
+
+  throws(
+    () =>
+      withSettings(
+        {
+          webdrivers: ['chrome-mobile'],
+        },
+        () => {},
+      ),
+    /unexpected webdriver 'chrome-mobile'/,
+    'reject undefined alias in webdrivers',
+  );
+
+  throws(
+    () =>
+      withSettings(
+        {
+          webdriver_aliases: {
+            chrome: {
+              browser: 'chrome',
+            },
+          },
+        },
+        () => {},
+      ),
+    /conflicts with built-in browser/,
+    'reject alias colliding with base browser',
+  );
+
+  throws(
+    () => settings.resolveWebdriver('unknown-alias'),
+    /unexpected webdriver 'unknown-alias'/,
+    'reject unknown webdriver resolution',
+  );
+}

package/tests/e2e/samples/folder/package-lock.json

@@ -16,7 +16,7 @@
     },
     "../../../..": {
       "name": "@camperaid/watest",
-      "version": "2.6.2",
+      "version": "2.6.3",
       "dev": true,
       "license": "MPL",
       "dependencies": {

package/tests/e2e/samples/loader/package-lock.json

@@ -16,7 +16,7 @@
     },
     "../../../..": {
       "name": "@camperaid/watest",
-      "version": "2.6.2",
+      "version": "2.6.3",
       "dev": true,
       "license": "MPL",
       "dependencies": {

package/tests/e2e/samples/loader-mixed/package-lock.json

@@ -16,7 +16,7 @@
     },
     "../../../..": {
       "name": "@camperaid/watest",
-      "version": "2.6.2",
+      "version": "2.6.3",
       "dev": true,
       "license": "MPL",
       "dependencies": {

package/tests/e2e/samples/loader-multiple/package-lock.json

@@ -16,7 +16,7 @@
     },
     "../../../..": {
       "name": "@camperaid/watest",
-      "version": "2.6.2",
+      "version": "2.6.3",
       "dev": true,
       "license": "MPL",
       "dependencies": {

package/tests/e2e/samples/single/package-lock.json

@@ -16,7 +16,7 @@
     },
     "../../../..": {
       "name": "@camperaid/watest",
-      "version": "2.6.2",
+      "version": "2.6.3",
       "dev": true,
       "license": "MPL",
       "dependencies": {

package/tests/meta.js

@@ -1 +1 @@
-export var folders = ['base', 'series', 'webdriver', 'e2e', 'deps'];
+export var folders = ['base', 'core', 'series', 'webdriver', 'e2e', 'deps'];

package/webdriver/driver-base.js

@@ -24,18 +24,21 @@ import {
 import firefox from 'selenium-webdriver/firefox.js';
 import chrome from 'selenium-webdriver/chrome.js';
 
-function getChromeOptions() {
+function getChromeOptions(resolved) {
+  const windowWidth =
+    resolved.windowWidth ?? settings.webdriver_window_width;
+  const windowHeight =
+    resolved.windowHeight ?? settings.webdriver_window_height;
+
   const chromeOptions = new chrome.Options().windowSize({
-    width: settings.webdriver_window_width,
-    height: settings.webdriver_window_height,
+    width: windowWidth,
+    height: windowHeight,
   });
   if (settings.webdriver_headless) {
     chromeOptions.addArguments('headless=new');
   }
-  if (settings.webdriver == 'chrome-mobile') {
-    chromeOptions.setMobileEmulation({
-      deviceName: 'iPhone 7',
-    });
+  if (resolved.chrome?.mobileEmulation) {
+    chromeOptions.setMobileEmulation(resolved.chrome.mobileEmulation);
   }
   // Accept self-signed certificates (for k3s testing)
   chromeOptions.addArguments('ignore-certificate-errors');
@@ -63,6 +66,15 @@ function getFirefoxArgs() {
   return settings.webdriver_headless ? ['-headless'] : [];
 }
 
+async function applyResolvedWindowSize(driver, resolved) {
+  if (resolved.windowWidth == null && resolved.windowHeight == null) {
+    return;
+  }
+  const width = resolved.windowWidth ?? settings.webdriver_window_width;
+  const height = resolved.windowHeight ?? settings.webdriver_window_height;
+  await driver.manage().window().setRect({ width, height, x: 0, y: 0 });
+}
+
 const defaultTimeout = 10;
 const getTimeout = () => (testflow.core.getTimeout() || defaultTimeout) * 1000;
 const getTimeoutOnFailure = () => (testflow.core.getTimeout() || 0) * 1000; // use non zero values for failure debugging
@@ -107,9 +119,10 @@ class DriverBase {
    * Creates an instance of web driver.
    */
   static async build() {
-    log(`Build WebDriver for '${settings.webdriver}'`);
+    const resolved = settings.resolveWebdriver(settings.webdriver);
+    log(`Build WebDriver for '${resolved.name}'`);
 
-    switch (settings.webdriver) {
+    switch (resolved.browser) {
       case 'chrome': {
         const driver = await new Builder()
           .withCapabilities({
@@ -118,14 +131,13 @@ class DriverBase {
               browser: browserLogLevel,
             },
           })
-          .setChromeOptions(getChromeOptions())
+          .setChromeOptions(getChromeOptions(resolved))
           .build();
 
         return [
           driver,
           {
-            browserLoggingOn: true,
-            chrome: true,
+            ...resolved.flags,
           },
         ];
       }
@@ -154,38 +166,18 @@ class DriverBase {
         return [
           driver,
           {
-            firefox: true,
-          },
-        ];
-      }
-
-      case 'chrome-mobile': {
-        const driver = await new Builder()
-          .withCapabilities({
-            'browserName': Browser.CHROME,
-            'goog:loggingPrefs': {
-              browser: browserLogLevel,
-            },
-          })
-          .setChromeOptions(getChromeOptions())
-          .build();
-
-        return [
-          driver,
-          {
-            isMobile: true,
-            chrome: true,
-            browserLoggingOn: true,
+            ...resolved.flags,
           },
         ];
       }
 
       case 'safari': {
         const driver = await new Builder().forBrowser(Browser.SAFARI).build();
+        await applyResolvedWindowSize(driver, resolved);
         return [
           driver,
           {
-            safari: true,
+            ...resolved.flags,
           },
         ];
       }
@@ -195,18 +187,18 @@ class DriverBase {
         return [
           driver,
           {
-            edge: true,
+            ...resolved.flags,
           },
         ];
       }
 
       default:
-        throw new Error(`Unexpected '${settings.webdriver}' webdriver`);
+        throw new Error(`Unexpected '${resolved.browser}' webdriver browser`);
     }
   }
 
   static isStdOutLogging(webdriver) {
-    return webdriver == 'firefox';
+    return settings.resolveWebdriver(webdriver).browser == 'firefox';
   }
 
   static get Errors() {