@camperaid/watest 2.5.0 → 2.5.2

package/core/deps.js

@@ -0,0 +1,211 @@
+/**
+ * Dependency and grid metadata extraction for distributed testing.
+ * Parses test folder metadata and generates grid configurations.
+ */
+
+import { pathToFileURL } from 'node:url';
+import { join } from 'node:path';
+import { settings } from './settings.js';
+
+/**
+ * Parse cell syntax: 'e2e+' → { name: 'e2e', split: true }
+ */
+export function parseCellSyntax(cellKey) {
+  if (cellKey.endsWith('+')) {
+    return { name: cellKey.slice(0, -1), split: true };
+  }
+  return { name: cellKey, split: false };
+}
+
+/**
+ * Separate paths (contain '/') from webdrivers (don't contain '/')
+ */
+export function parseGridArgs(args) {
+  const paths = [];
+  const webdrivers = [];
+
+  for (const arg of args) {
+    if (arg.includes('/')) {
+      paths.push(arg);
+    } else {
+      webdrivers.push(arg);
+    }
+  }
+
+  return { paths, webdrivers };
+}
+
+/**
+ * Extract service name from service definition.
+ * Services can be either:
+ * - A string: 'db'
+ * - An array: ['nginx', { env: {...} }] where first element is the name
+ */
+function getServiceName(service) {
+  return Array.isArray(service) ? service[0] : service;
+}
+
+/**
+ * Check if a folder path should be traversed based on target paths.
+ * Similar to series.js matchedPatterns logic:
+ * - folderPath starts with target: we're IN or PAST the target
+ * - target starts with folderPath: we're ON THE WAY to the target
+ */
+function matchesPath(folderPath, targetPaths) {
+  return targetPaths.some(
+    target => folderPath.startsWith(target) || target.startsWith(folderPath),
+  );
+}
+
+/**
+ * Collect metadata from a single directory's meta.js
+ * Helper for collectDeps
+ */
+async function collectMetaFromDir(dirPath, result) {
+  try {
+    const metaPath = join(process.cwd(), dirPath, 'meta.js');
+    const metaUrl = pathToFileURL(metaPath).href;
+    const meta = await import(metaUrl);
+
+    if (meta.servicer && !result.servicers.includes(meta.servicer)) {
+      result.servicers.push(meta.servicer);
+    }
+    if (meta.webdriver) {
+      result.webdriver = true;
+    }
+    if (meta.services) {
+      for (const service of meta.services) {
+        const serviceName = getServiceName(service);
+        if (!result.services.includes(serviceName)) {
+          result.services.push(serviceName);
+        }
+      }
+    }
+
+    return meta;
+  } catch {
+    // No meta.js or error loading it - that's ok
+    return null;
+  }
+}
+
+/**
+ * Recursively collect metadata from nested meta.js files.
+ * Starts from root folder, walks DOWN the tree, only following branches that match target paths.
+ * Similar to how series.js builds tests - uses bidirectional path matching.
+ *
+ * @param {string} folder - Current folder being traversed
+ * @param {string[]} targetPaths - The specific test paths we're collecting deps for
+ * @param {Object} result - Accumulated result object
+ */
+async function collectDepsRecursive(folder, targetPaths, result) {
+  // Collect metadata from current folder
+  const meta = await collectMetaFromDir(folder, result);
+
+  // If this folder has subfolders, filter and recurse
+  if (meta?.folders) {
+    for (const subfolder of meta.folders) {
+      const subfolderPath = join(folder, subfolder);
+
+      // Only follow this branch if it matches any target path
+      if (matchesPath(subfolderPath, targetPaths)) {
+        await collectDepsRecursive(subfolderPath, targetPaths, result);
+      }
+    }
+  }
+}
+
+/**
+ * Collect metadata for given test paths.
+ * Walks the tree from tests root, following only branches that lead to target paths.
+ *
+ * @param {string[]} paths - Test paths to collect metadata for (defaults to entire tree)
+ * @param {Object} result - Initial result object
+ */
+export async function collectDeps(
+  paths = [settings.testsFolder],
+  result = { servicers: [], webdriver: false, services: [] },
+) {
+  const rootFolder = settings.testsFolder;
+
+  // Filter to paths under root folder
+  const targetPaths = paths.filter(
+    p => p === rootFolder || p.startsWith(rootFolder + '/'),
+  );
+
+  if (targetPaths.length > 0) {
+    await collectDepsRecursive(rootFolder, targetPaths, result);
+  }
+
+  return result;
+}
+
+/**
+ * Generate expanded grid from grid config and args.
+ * Returns cell→metadata mapping with + cells expanded per browser.
+ *
+ * Example:
+ *   watest --grid-meta tests/e2e firefox chrome
+ *   → {
+ *       "e2e-firefox": { paths: ["tests/e2e"], webdriver: "firefox", servicers: [...], services: [...] },
+ *       "e2e-chrome": { paths: ["tests/e2e"], webdriver: "chrome", servicers: [...], services: [...] }
+ *     }
+ */
+export async function generateGridTasks(gridConfig, args) {
+  const { paths, webdrivers } = parseGridArgs(args);
+  const browsers =
+    webdrivers.length > 0 ? webdrivers : settings.webdrivers || [];
+
+  // Build cell → paths mapping
+  const cellPathsMap = new Map();
+
+  if (paths.length > 0) {
+    // Map each requested path to its cell
+    for (const [cellKey, cellPaths] of Object.entries(gridConfig)) {
+      const matchingPaths = paths.filter(p =>
+        cellPaths.some(cp => p.startsWith(cp)),
+      );
+      if (matchingPaths.length > 0) {
+        cellPathsMap.set(cellKey, matchingPaths);
+      }
+    }
+  } else {
+    // Use all cells with their configured paths
+    for (const [cellKey, cellPaths] of Object.entries(gridConfig)) {
+      cellPathsMap.set(cellKey, cellPaths);
+    }
+  }
+
+  // Build expanded grid with metadata
+  const expandedGrid = {};
+  for (const [cellKey, cellPaths] of cellPathsMap) {
+    const { name, split } = parseCellSyntax(cellKey);
+    const meta = await collectDeps(cellPaths);
+
+    if (split && meta.webdriver && browsers.length > 1) {
+      // Split: one entry per browser
+      for (const wd of browsers) {
+        expandedGrid[`${name}-${wd}`] = {
+          paths: cellPaths,
+          webdrivers: wd,
+          servicers: meta.servicers,
+          services: meta.services,
+        };
+      }
+    } else {
+      // No split: single entry with all browsers as space-separated string
+      let webdriversValue = '';
+      if (meta.webdriver && browsers.length > 0) {
+        webdriversValue = browsers.join(' ');
+      }
+      expandedGrid[name] = {
+        paths: cellPaths,
+        webdrivers: webdriversValue,
+        servicers: meta.servicers,
+        services: meta.services,
+      };
+    }
+  }
+
+  return expandedGrid;
+}

package/core/{process_args.js → process-args.js}

@@ -28,6 +28,14 @@ class ProcessArgs {
           obj.showHelp = true;
           break;
 
+        case '--grid':
+          obj.grid = true;
+          break;
+
+        case '--deps':
+          obj.deps = true;
+          break;
+
         case '--child-process':
           obj.childProcess = true;
           break;

package/core/series.js

@@ -4,13 +4,13 @@ import { fileURLToPath } from 'url';
 
 import { assert, fail, testflow } from './core.js';
 import { parse, parse_failure } from './format.js';
-import { ProcessArgs } from './process_args.js';
-import settings from './settings.js';
+import { ProcessArgs } from './process-args.js';
+import { settings } from './settings.js';
 import { spawn } from './spawn.js';
 import { stringify } from './util.js';
 import { log, log_error } from '../logging/logging.js';
 import { LogPipe } from '../logging/logpipe.js';
-import { DriverBase } from '../webdriver/driver_base.js';
+import { DriverBase } from '../webdriver/driver-base.js';
 
 import {
   format_started,
@@ -27,7 +27,7 @@ import {
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = nodepath.dirname(__filename);
 
-const root_folder = 'tests';
+const rootFolder = () => settings.testsFolder;
 const root_dir = nodepath.resolve('.');
 
 const kKungFuDeathGripTimeout = {};
@@ -107,7 +107,7 @@ class Series {
     this.ocnt = 0;
 
     this.core = core || testflow.core;
-    testflow.lock({ core: this.core });
+    testflow.lock({ core: this.core, series: this });
 
     this.core.setTimeout(timeout);
     this.core.clearStats();
@@ -145,9 +145,6 @@ class Series {
         await this.runFor(this.failures, '2');
       }
     }
-
-    await settings.servicer.shutdown();
-
     log(`Elapsed: ${Date.now() - start_time}ms`);
   }
 
@@ -157,7 +154,7 @@ class Series {
   async runFor(patterns, name_postfix = '') {
     let tests = await this.build({
       patterns,
-      folder: root_folder,
+      folder: rootFolder(),
       virtual_folder: this.invocation,
     });
 
@@ -181,7 +178,10 @@ class Series {
   }
 
   shutdown() {
+    this.shutdownServicer();
     testflow.unlock();
+
+    console.log(`Testsuite: shutdown`);
     return this.failures.length > 0 ? this.failures : null;
   }
 
@@ -367,8 +367,24 @@ class Series {
       return [];
     }
 
+    // Filter subfolders to only process those that match the patterns
+    let filteredSubfolders = subfolders;
+    if (patterns.length > 0) {
+      filteredSubfolders = subfolders.filter(subfolder => {
+        const subfolderPath = `${folder}/${subfolder}`;
+        return (
+          this.matchedPatterns({
+            path: subfolderPath,
+            webdriver,
+            patterns,
+            path_is_not_final: true,
+          }).length > 0
+        );
+      });
+    }
+
     let subtests_for_subfolders = await Promise.all(
-      subfolders.map(subfolder =>
+      filteredSubfolders.map(subfolder =>
         this.build({
           patterns,
           folder: `${folder}/${subfolder}`,
@@ -428,15 +444,16 @@ class Series {
       test_module.expected_failures || [],
     );
 
-    // Initialize
-    if (test_module.services || test_module.init) {
+    // Initialize.
+    // Servicer is only created when explicitly requested via 'servicer' property.
+    // Tests with just 'services' but no 'servicer' won't trigger servicer creation.
+    const has_servicer = test_module.servicer !== undefined;
+    const has_init = test_module.init;
+    if (has_servicer || has_init) {
       let init = async () => {
-        // Start services if any.
-        let chain = Promise.resolve();
-        for (let service of test_module.services || []) {
-          chain = chain.then(() => settings.servicer.start(service));
-        }
-        await chain;
+        // Initialize servicer with services (if any).
+        const servicer = this.getServicer(test_module.servicer);
+        await servicer.init(test_module.services);
 
         // Do initialization if any.
         if (test_module.init) {
@@ -460,7 +477,7 @@ class Series {
       // A function to notify the servicer the test is about to start and then
       // to invoke the test.
       const test_wrap = () =>
-        Promise.resolve(settings.servicer.ontest(name)).then(test);
+        Promise.resolve(this.#servicer?.ontest(name)).then(test);
 
       let failures_info = Series.failuresInfo({
         failures: expected_failures,
@@ -484,18 +501,14 @@ class Series {
     }
 
     // Uninitialize.
-    if (test_module.services || test_module.init) {
+    if (has_servicer || has_init) {
       let uninit = async () => {
         // Deinitalize test env.
         if (test_module.uninit) {
           await test_module.uninit();
         }
-        // Stop services in reverse order.
-        await Promise.all(
-          [...(test_module.services || [])]
-            .reverse()
-            .map(s => settings.servicer.stop(s)),
-        );
+        // Deinitialize servicer with services.
+        await this.#servicer?.deinit(test_module.services);
       };
       tests.push({
         name: `${virtual_folder}/uninit`,
@@ -910,7 +923,7 @@ class Series {
       .readdirSync(nodepath.join(root_dir, folder))
       .filter(
         n =>
-          n.startsWith('t_') &&
+          settings.testFilePattern.test(n) &&
           (!settings.ignorePattern || !settings.ignorePattern.test(n)),
       );
   }
@@ -938,7 +951,10 @@ class Series {
       args.push('--webdriver', webdriver);
     }
 
-    return spawn('node', args, {}, buffer =>
+    // Pass run ID to child process to ensure consistent test artifact IDs
+    const env = { ...process.env, WATEST_RUN: settings.run };
+
+    return spawn('node', args, { env }, buffer =>
       this.processChildProcessOutput(name, buffer),
     ).catch(e => {
       log_error(e);
@@ -1032,6 +1048,32 @@ class Series {
       }
     }
   }
+
+  getServicer(requestedType) {
+    // Create servicer if none exists or if switching to a different type.
+    // Note: we don't shutdown the old servicer here - the servicer factory
+    // handles stopping conflicting services for better performance.
+    if (
+      !this.#servicer ||
+      (requestedType !== undefined && this.#servicer.type !== requestedType)
+    ) {
+      this.#servicer = this.createServicer(requestedType);
+    }
+    return this.#servicer;
+  }
+
+  createServicer(servicerType) {
+    return settings.getServicer(servicerType);
+  }
+
+  shutdownServicer() {
+    if (this.#servicer) {
+      this.#servicer.shutdown();
+      this.#servicer = null;
+    }
+  }
+
+  #servicer;
 }
 
 export { Series };

package/core/settings.js

@@ -7,16 +7,18 @@ class Settings {
     this.tmp_storage_dir = '';
     this.logger = null;
     this.servicer = null;
+    this.silent = false;
   }
 
-  async initialize() {
+  async initialize(options = {}) {
+    this.silent = options.silent || false;
     this.rc = (await import(path.resolve('.', './.watestrc.js'))).default;
 
     this.logger = (
       await import(this.rc.logger || '../interfaces/logger.js')
     ).default;
 
-    this.servicer = (
+    this.getServicer = (
       await import(this.rc.servicer || '../interfaces/servicer.js')
     ).default;
 
@@ -47,33 +49,49 @@ class Settings {
     return parseInt(this.rc.debunk_limit) || 5;
   }
 
+  get testsFolder() {
+    return this.rc?.tests_folder ?? 'tests';
+  }
+
+  get testFilePattern() {
+    return this.rc.test_file_pattern || /^t[-_]/;
+  }
+
   get timeout() {
     return parseInt(this.rc.timeout) || 0;
   }
 
   setupTmpStorageDir() {
     if (!this.rc.tmp_dir) {
-      console.log(`Settings: no temporary storage dir`);
+      if (!this.silent) {
+        console.log(`Settings: no temporary storage dir`);
+      }
       return;
     }
 
     this.tmp_storage_dir = path.join(this.rc.tmp_dir, 'watest-tmpstorage');
-    console.log(
-      `Settings: temporary storage dir is at ${this.tmp_storage_dir}`,
-    );
+    if (!this.silent) {
+      console.log(
+        `Settings: temporary storage dir is at ${this.tmp_storage_dir}`,
+      );
+    }
   }
 
   setupLogDir() {
     const log_dir = this.rc.log_dir;
     if (!log_dir) {
-      console.log('Settings: no file logging');
+      if (!this.silent) {
+        console.log('Settings: no file logging');
+      }
       return;
     }
 
     this.run = this.rc.run || `${parseInt(Date.now() / 1000)}`;
 
     this.log_dir = path.join(log_dir, this.run);
-    console.log(`Settings: logging into ${log_dir}`);
+    if (!this.silent) {
+      console.log(`Settings: logging into ${log_dir}`);
+    }
   }
 
   setupWebdrivers() {
@@ -100,10 +118,10 @@ class Settings {
     this.webdriver_window_height =
       parseInt(this.rc.webdriver_window_height) || 768;
 
-    if (this.webdrivers) {
+    if (this.webdrivers && !this.silent) {
       console.log(`Settings: ${this.webdrivers.join(', ')} webdrivers`);
     }
   }
 }
 
-export default new Settings();
+export const settings = new Settings();

package/core/system.js

@@ -0,0 +1,68 @@
+import { spawn } from './spawn.js';
+
+/**
+ * Run a shell command and capture its output
+ * @param {string} cmd - Command to run
+ * @param {string[]} args - Command arguments
+ * @param {object} options - Spawn options
+ * @returns {Promise<{stdout: string, stderr: string, exitCode: number, stdoutLines: string[], stderrLines: string[]}>}
+ */
+export async function runCommand(cmd, args = [], options = {}) {
+  let stdout = [];
+  let stderr = [];
+  let exitCode = 0;
+
+  try {
+    exitCode = await spawn(cmd, args, options, buffer => {
+      for (let { str_data, is_stdout } of buffer) {
+        const lines = str_data.split('\n').filter(line => line);
+        if (is_stdout) {
+          stdout.push(...lines);
+        } else {
+          stderr.push(...lines);
+        }
+      }
+    });
+  } catch (code) {
+    exitCode = code;
+  }
+
+  return {
+    stdout: stdout.join('\n'),
+    stderr: stderr.join('\n'),
+    exitCode,
+    stdoutLines: stdout,
+    stderrLines: stderr,
+  };
+}
+
+/**
+ * Run a bash script with proper error handling
+ * @param {string} script - Bash script content
+ * @param {string[]} args - Script arguments
+ * @param {object} options - Spawn options
+ * @returns {Promise<{stdout: string, stderr: string, exitCode: number, stdoutLines: string[], stderrLines: string[]}>}
+ */
+export async function runBashScript(script, args = [], options = {}) {
+  return runCommand('bash', ['-c', script, '--', ...args], options);
+}
+
+/**
+ * Run a shell command and return only stdout (for simple cases)
+ * @param {string} cmd - Command to run
+ * @param {string[]} args - Command arguments
+ * @param {object} options - Spawn options
+ * @returns {Promise<string>} stdout content
+ */
+export async function execCommand(cmd, args = [], options = {}) {
+  const result = await runCommand(cmd, args, options);
+  if (result.exitCode !== 0) {
+    throw new Error(
+      `Command failed with exit code ${result.exitCode}: ${result.stderr}`,
+    );
+  }
+  return result.stdout;
+}
+
+// Export the raw spawn function for advanced use cases
+export { spawn };

package/core/util.js

@@ -3,7 +3,7 @@ import querystring from 'querystring';
 import util from 'util';
 
 import { log } from '../logging/logging.js';
-import settings from './settings.js';
+import { settings } from './settings.js';
 
 /**
  * Logs object in console colored.

package/eslint.config.js

@@ -6,7 +6,7 @@ export default [
   nodePlugin.configs['flat/recommended-script'],
   {
     languageOptions: {
-      ecmaVersion: 2021,
+      ecmaVersion: 2022,
       sourceType: 'module',
     },
   },

package/index.js

@@ -8,6 +8,7 @@ import {
   success,
   todo,
   warn,
+  getServicer,
 } from './core/core.js';
 
 import {
@@ -21,19 +22,27 @@ import {
   test_contains,
 } from './core/base.js';
 
-import settings from './core/settings.js';
+import { settings } from './core/settings.js';
 import { inspect } from './core/util.js';
-import { AppDriver } from './webdriver/app_driver.js';
-import { ControlDriver } from './webdriver/control_driver.js';
+import { AppDriver } from './webdriver/app-driver.js';
+import { ControlDriver } from './webdriver/control-driver.js';
 import { start_session, scope } from './webdriver/session.js';
+import {
+  runCommand,
+  runBashScript,
+  execCommand,
+  spawn,
+} from './core/system.js';
 
 export {
   AppDriver,
   ControlDriver,
   assert,
   contains,
+  execCommand,
   failed,
   fail,
+  getServicer,
   group,
   is,
   is_output,
@@ -42,7 +51,10 @@ export {
   not_reached,
   no_throws,
   ok,
+  runBashScript,
+  runCommand,
   scope,
+  spawn,
   start_session,
   success,
   todo,

package/interfaces/servicer.js

@@ -2,6 +2,18 @@
  * Manages services requested by a testsuite.
  */
 class Servicer {
+  /**
+   * Initialize servicer and optionally start services.
+   * Called at the beginning of a test folder.
+   */
+  async init(/* services */) {}
+
+  /**
+   * Deinitialize servicer and stop services.
+   * Called at the end of a test folder.
+   */
+  async deinit(/* services */) {}
+
   /**
    * Starts a service.
    */
@@ -15,9 +27,7 @@ class Servicer {
   /**
    * Called when the testsuite gets shutdown.
    */
-  shutdown() {
-    console.log(`Testsuite: shutdown`);
-  }
+  shutdown() {}
 
   /**
    * Called when test is started.

package/logging/logging.js

@@ -1,4 +1,4 @@
-import { ProcessArgs } from '../core/process_args.js';
+import { ProcessArgs } from '../core/process-args.js';
 
 function log(...args) {
   console.log(...args);