@camperaid/watest 2.5.9 → 2.6.1

package/README.md

@@ -44,14 +44,28 @@ Each test folder can have a `meta.js` file:
 
 ```javascript
 // tests/e2e/meta.js
-export const folders = ['login', 'checkout'];  // Nested test folders
-export const services = ['db', 'ws'];          // Services to start
-export const servicer = 'docker';              // Service manager: 'docker' | 'kubernetes'
-export const webdriver = true;                 // Enable browser testing
-export const init = async () => { /* setup */ };
-export const uninit = async () => { /* teardown */ };
+export const folders = ['login', 'checkout']; // Nested test folders
+export const services = ['db', 'ws']; // Services to start
+export const servicer = 'docker'; // Service manager: 'docker' | 'kubernetes'
+export const webdriver = true; // Enable browser testing
+export const enabled = process.env.FEATURE_ON; // Optional: true/false, 'true'/'false', or a function returning one
+export const init = async () => {
+  /* setup */
+};
+export const uninit = async () => {
+  /* teardown */
+};
 ```
 
+`enabled` may be:
+
+- a boolean
+- the string `'true'` or `'false'`
+- a synchronous function returning one of those values
+
+Skipped suites are omitted from `--deps` and `--grid` metadata, and their
+services are not started.
+
 ## Configuration
 
 ### Project Configuration File
@@ -80,8 +94,8 @@ export default {
   webdriver_window_height: process.env.WATEST_WEBDRIVER_WINDOW_HEIGHT,
 
   // Integration hooks (absolute paths to your project files)
-  servicer: './tests/servicer.js',  // Manages test services
-  logger: './tests/logserver.js',   // Remote test logging
+  servicer: './tests/servicer.js', // Manages test services
+  logger: './tests/logserver.js', // Remote test logging
 
   // Optional: ignore pattern
   ignore_pattern: process.env.WATEST_IGNORE_PATTERN,
@@ -184,9 +198,9 @@ todo('implement logout');
 ```javascript
 import { assert, not_reached, inspect } from '@camperaid/watest';
 
-assert(condition, 'condition must be true');  // Fails with stack trace
-not_reached('should not get here');           // Always fails with stack trace
-inspect(object);                              // Pretty-print object
+assert(condition, 'condition must be true'); // Fails with stack trace
+not_reached('should not get here'); // Always fails with stack trace
+inspect(object); // Pretty-print object
 ```
 
 ### Test Helpers
@@ -195,8 +209,12 @@ inspect(object);                              // Pretty-print object
 import { test_is, test_contains } from '@camperaid/watest';
 
 // Silent checks (no success/fail logging)
-if (test_is(got, expected)) { /* ... */ }
-if (test_contains(array, subset)) { /* ... */ }
+if (test_is(got, expected)) {
+  /* ... */
+}
+if (test_contains(array, subset)) {
+  /* ... */
+}
 ```
 
 ## Integration Testing
@@ -240,7 +258,7 @@ class LoginPage extends AppDriver {
       this.action('Login')
         .sendKeys(this.Email, email)
         .sendKeys(this.Password, password)
-        .click(this.Submit)
+        .click(this.Submit),
     );
   }
 
@@ -266,10 +284,8 @@ Handle known intermittent or permanent failures in `meta.js`:
 ```javascript
 export const expected_failures = [
   [
-    'test_file.js',  // or '*' for all files
-    [
-      [platform, type, group, failures, description],
-    ],
+    'test_file.js', // or '*' for all files
+    [[platform, type, group, failures, description]],
   ],
 ];
 ```
@@ -316,7 +332,7 @@ Watest provides metadata helpers for external orchestrators to distribute tests
 ```javascript
 // tests/meta.js
 export const grid = {
-  'e2e+': ['tests/e2e'],      // '+' = split per browser
+  'e2e+': ['tests/e2e'], // '+' = split per browser
   'www+': ['tests/www'],
   'services': ['tests/services', 'tests/integration'],
   'misc': ['tests/lib', 'tests/ops'],
@@ -340,7 +356,12 @@ watest --deps tests/e2e
 ## System Commands
 
 ```javascript
-import { runCommand, execCommand, spawn, runBashScript } from '@camperaid/watest';
+import {
+  runCommand,
+  execCommand,
+  spawn,
+  runBashScript,
+} from '@camperaid/watest';
 
 // Run command, log output
 await runCommand('npm', ['install']);

package/core/base.js

@@ -67,6 +67,30 @@ function contains(
   msg,
   { ignore_unexpected, fail_ = fail, success_ = success } = {},
 ) {
+  // string contains array of strings: check each substring.
+  if (typeof got == 'string' && expected instanceof Array) {
+    let isok = true;
+    for (let e of expected) {
+      if (typeof e != 'string') {
+        fail_(`${msg}, expected string item, got ${typeof e}: ${stringify(e)}`);
+        isok = false;
+        continue;
+      }
+      if (!got.includes(e)) {
+        fail_(
+          `${msg}, got string doesn't contain expected string, got: ${stringify(
+            got,
+          )}, expected: ${stringify(e)}`,
+        );
+        isok = false;
+      }
+    }
+    if (isok) {
+      success_(`${msg}, got: ${stringify(got)}`);
+    }
+    return isok;
+  }
+
   if (typeof got == 'string' || typeof expected == 'string') {
     if (typeof got != 'string') {
       fail_(`${msg}, expected string, got object: []`);

package/core/deps.js

@@ -3,7 +3,9 @@
  * Parses test folder metadata and generates grid configurations.
  */
 
+import fs from 'node:fs';
 import { pathToFileURL } from 'node:url';
+import { isMetaEnabled } from './meta.js';
 import { join } from 'node:path';
 import { settings } from './settings.js';
 
@@ -58,39 +60,41 @@ function matchesPath(folderPath, targetPaths) {
 }
 
 /**
- * Collect metadata from a single directory's meta.js
- * Helper for collectDeps
+ * Collect metadata from a single directory's meta.js.
  */
-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);
-        }
+async function scanMetaDir(dirPath, result) {
+  const metaPath = join(process.cwd(), dirPath, 'meta.js');
+  if (!fs.existsSync(metaPath)) {
+    return null;
+  }
+
+  const metaUrl = pathToFileURL(metaPath).href;
+  const meta = await import(metaUrl);
+
+  if (!isMetaEnabled(meta)) {
+    return undefined;
+  }
+
+  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;
   }
+
+  return meta;
 }
 
 /**
- * Recursively collect metadata from nested meta.js files.
+ * Walk nested meta.js files from root toward the requested target paths.
  * 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.
  *
@@ -98,9 +102,15 @@ async function collectMetaFromDir(dirPath, result) {
  * @param {string[]} targetPaths - The specific test paths we're collecting deps for
  * @param {Object} result - Accumulated result object
  */
-async function collectDepsRecursive(folder, targetPaths, result) {
+async function walkDepsTree(folder, targetPaths, result) {
   // Collect metadata from current folder
-  const meta = await collectMetaFromDir(folder, result);
+  const meta = await scanMetaDir(folder, result);
+
+  if (meta === undefined) {
+    return false;
+  }
+
+  let hasEnabledTarget = targetPaths.some(target => target === folder);
 
   // If this folder has subfolders, filter and recurse
   if (meta?.folders) {
@@ -109,10 +119,16 @@ async function collectDepsRecursive(folder, targetPaths, result) {
 
       // Only follow this branch if it matches any target path
       if (matchesPath(subfolderPath, targetPaths)) {
-        await collectDepsRecursive(subfolderPath, targetPaths, result);
+        if (await walkDepsTree(subfolderPath, targetPaths, result)) {
+          hasEnabledTarget = true;
+        }
       }
     }
+  } else if (targetPaths.some(target => target.startsWith(`${folder}/`))) {
+    hasEnabledTarget = true;
   }
+
+  return hasEnabledTarget;
 }
 
 /**
@@ -122,7 +138,7 @@ async function collectDepsRecursive(folder, targetPaths, result) {
  * @param {string[]} paths - Test paths to collect metadata for (defaults to entire tree)
  * @param {Object} result - Initial result object
  */
-export async function collectDeps(
+async function buildDepsState(
   paths = [settings.testsFolder],
   result = { servicers: [], webdriver: false, services: [] },
 ) {
@@ -133,11 +149,20 @@ export async function collectDeps(
     p => p === rootFolder || p.startsWith(rootFolder + '/'),
   );
 
+  let hasEnabledTarget = false;
+
   if (targetPaths.length > 0) {
-    await collectDepsRecursive(rootFolder, targetPaths, result);
+    hasEnabledTarget = await walkDepsTree(rootFolder, targetPaths, result);
   }
 
-  return result;
+  return { deps: result, hasEnabledTarget };
+}
+
+export async function collectDeps(
+  paths = [settings.testsFolder],
+  result = { servicers: [], webdriver: false, services: [] },
+) {
+  return (await buildDepsState(paths, result)).deps;
 }
 
 /**
@@ -180,29 +205,33 @@ export async function generateGridTasks(gridConfig, args) {
   const expandedGrid = {};
   for (const [cellKey, cellPaths] of cellPathsMap) {
     const { name, split } = parseCellSyntax(cellKey);
-    const meta = await collectDeps(cellPaths);
+    const { deps, hasEnabledTarget } = await buildDepsState(cellPaths);
+
+    if (!hasEnabledTarget) {
+      continue;
+    }
 
-    if (split && meta.webdriver && browsers.length > 1) {
+    if (split && deps.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,
+          servicers: deps.servicers,
+          services: deps.services,
         };
       }
     } else {
       // No split: single entry with all browsers as space-separated string
       let webdriversValue = '';
-      if (meta.webdriver && browsers.length > 0) {
+      if (deps.webdriver && browsers.length > 0) {
         webdriversValue = browsers.join(' ');
       }
       expandedGrid[name] = {
         paths: cellPaths,
         webdrivers: webdriversValue,
-        servicers: meta.servicers,
-        services: meta.services,
+        servicers: deps.servicers,
+        services: deps.services,
       };
     }
   }

package/core/meta.js

@@ -0,0 +1,30 @@
+function normalizeMetaEnabled(value) {
+  if (value && typeof value.then === 'function') {
+    throw new Error(
+      "Invalid meta.enabled value: async values are not supported; use a boolean, 'true', 'false', or a synchronous function returning one of those values",
+    );
+  }
+
+  if (value === true || value === 'true') {
+    return true;
+  }
+
+  if (value === false || value === 'false') {
+    return false;
+  }
+
+  throw new Error(
+    `Invalid meta.enabled value: expected boolean, 'true', 'false', or a function returning one of those values; got ${JSON.stringify(value)}`,
+  );
+}
+
+export function isMetaEnabled(meta) {
+  if (!meta || meta.enabled === undefined) {
+    return true;
+  }
+
+  const value =
+    typeof meta.enabled === 'function' ? meta.enabled() : meta.enabled;
+
+  return normalizeMetaEnabled(value);
+}

package/core/series.js

@@ -2,12 +2,13 @@ import fs from 'fs';
 import nodepath from 'path';
 import { fileURLToPath } from 'url';
 
-import { assert, fail, testflow } from './core.js';
+import { assert, fail, success, testflow } from './core.js';
 import { parse, parse_failure } from './format.js';
 import { ProcessArgs } from './process-args.js';
 import { settings } from './settings.js';
 import { spawn } from './spawn.js';
 import { stringify } from './util.js';
+import { isMetaEnabled } from './meta.js';
 import { log, log_error } from '../logging/logging.js';
 import { LogPipe } from '../logging/logpipe.js';
 import { DriverBase } from '../webdriver/driver-base.js';
@@ -86,7 +87,7 @@ class Series {
       core,
       LogPipe,
       webdriver,
-      webdrivers = settings.webdrivers,
+      webdrivers = settings.webdrivers || [],
     },
   ) {
     this.debunk = debunk;
@@ -212,12 +213,25 @@ class Series {
     let tests = [];
     try {
       let test_module = await this.loadTestMeta(folder);
+      const enabled = isMetaEnabled(test_module);
       let subfolders = test_module.folders;
       let testfiles = test_module.list || (await this.getTestFileList(folder));
       if (!subfolders && testfiles.length == 0) {
         throw new Error(`No tests found in ${folder}`);
       }
 
+      if (!enabled) {
+        return [
+          {
+            name: virtual_folder,
+            path: `${folder}/meta.js`,
+            func: () => success(`Skipped: meta.enabled=false`),
+            failures_info: [],
+            meta_disabled_folder: true,
+          },
+        ];
+      }
+
       if (test_module.expected_failures) {
         inherited_expected_failures = inherited_expected_failures.concat(
           test_module.expected_failures.filter(v => v[0] == '**'),
@@ -414,6 +428,9 @@ class Series {
 
     return subtests_for_subfolders
       .flatMap(({ subfolder, subtests }) => {
+        if (subtests.some(t => t.meta_disabled_folder)) {
+          return subtests;
+        }
         // Case: no substests for a loader test running in a child process.
         if (subtests.every(t => t.loader)) {
           return subtests;

package/package.json

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

package/tests/base/t-contains.js

@@ -17,12 +17,12 @@ export async function test() {
     `failure`,
   );
 
-  // string: failure: got string, expected array
+  // string, empty array: success (contains all of nothing)
   await is_output(
     () => contains('cat', [], `String contains`),
+    [`Ok: String contains, got: 'cat'`],
     [],
-    [`Failed: String contains, got string, expected object: []`],
-    `failure`,
+    `string empty array`,
   );
 
   // string: failure: doesn't contains
@@ -35,6 +35,34 @@ export async function test() {
     `failure`,
   );
 
+  // string, string[]: success
+  await is_output(
+    () =>
+      contains(
+        'green cat on a mat',
+        ['green', 'cat', 'mat'],
+        `String contains all`,
+      ),
+    [`Ok: String contains all, got: 'green cat on a mat'`],
+    [],
+    `string array success`,
+  );
+
+  // string, string[]: partial failure
+  await is_output(
+    () =>
+      contains(
+        'green cat on a mat',
+        ['green', 'dog', 'mat'],
+        `String contains all`,
+      ),
+    [],
+    [
+      `Failed: String contains all, got string doesn't contain expected string, got: 'green cat on a mat', expected: 'dog'`,
+    ],
+    `string array failure`,
+  );
+
   // array: success
   await is_output(
     () => contains([0, 1], [1], `Array contains`),

package/tests/deps/samples/unified/tests/disabled/meta.js

@@ -0,0 +1,3 @@
+export const enabled = 'false';
+export const servicer = 'docker';
+export const services = ['ws'];

package/tests/deps/samples/unified/tests/disabled-parent/child/meta.js

@@ -0,0 +1,2 @@
+export const servicer = 'docker';
+export const services = ['ws'];

package/tests/deps/samples/unified/tests/disabled-parent/meta.js

@@ -0,0 +1,2 @@
+export const enabled = 'false';
+export const folders = ['child'];

package/tests/deps/samples/unified/tests/meta.js

@@ -1,6 +1,17 @@
-export const folders = ['e2e', 'integration', 'lib', 'services'];
+export const folders = [
+  'disabled',
+  'disabled-parent',
+  'e2e',
+  'integration',
+  'lib',
+  'services',
+];
 
+// Disabled cells stay listed here on purpose so deps/grid tests can verify
+// that watest filters them out from generated metadata.
 export const grid = {
+  'disabled': ['tests/disabled'],
+  'disabled-parent': ['tests/disabled-parent/child'],
   'e2e+': ['tests/e2e'],
   'integration': ['tests/integration'],
   'lib': ['tests/lib'],

package/tests/deps/t-watest-deps.js

@@ -21,6 +21,19 @@ export async function test() {
     services: ['db', 'nginx', 'request', 'inbucket'],
   });
 
+  // Disabled suite should be omitted from deps metadata even when addressed directly
+  await testDeps(['tests/disabled'], unifiedSamplePath, {
+    servicers: [],
+    webdriver: false,
+    services: [],
+  });
+
+  await testDeps(['tests/disabled-parent/child'], unifiedSamplePath, {
+    servicers: [],
+    webdriver: false,
+    services: [],
+  });
+
   // Test with deeply nested test file path
   await testDeps(['tests/services/ws/webservice/t-ws.js'], nestedSamplePath, {
     servicers: ['docker'],

package/tests/deps/t-watest-grid.js

@@ -42,7 +42,7 @@ export async function test() {
         services: ['inbucket', 'request'],
       },
     },
-    'default browsers split + cells',
+    'default browsers split + cells and omit disabled suites',
   );
 
   // Single browser - no split even for + cells
@@ -75,7 +75,7 @@ export async function test() {
         services: ['inbucket', 'request'],
       },
     },
-    'single browser no split',
+    'single browser no split and omit disabled suites',
   );
 
   // Multiple browsers without split (no + cells, explicit browsers)
@@ -119,4 +119,13 @@ export async function test() {
     },
     'filtered paths with split',
   );
+
+  const result5 = await testGrid(['tests/disabled', 'chrome'], samplesPath);
+  is(result5, {}, 'disabled grid cell should be omitted');
+
+  const result6 = await testGrid(
+    ['tests/disabled-parent/child', 'chrome'],
+    samplesPath,
+  );
+  is(result6, {}, 'grid cell should be omitted when a parent meta disables it');
 }

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

@@ -16,7 +16,7 @@
     },
     "../../../..": {
       "name": "@camperaid/watest",
-      "version": "2.5.1",
+      "version": "2.6.0",
       "dev": true,
       "license": "MPL",
       "dependencies": {
@@ -187,7 +187,6 @@
       "version": "8.12.1",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "bin": {
         "acorn": "bin/acorn"
       },
@@ -451,7 +450,6 @@
       "version": "9.8.0",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@eslint-community/eslint-utils": "^4.2.0",
         "@eslint-community/regexpp": "^4.11.0",

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

@@ -16,7 +16,7 @@
     },
     "../../../..": {
       "name": "@camperaid/watest",
-      "version": "2.5.1",
+      "version": "2.6.0",
       "dev": true,
       "license": "MPL",
       "dependencies": {
@@ -187,7 +187,6 @@
       "version": "8.12.1",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "bin": {
         "acorn": "bin/acorn"
       },
@@ -451,7 +450,6 @@
       "version": "9.8.0",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@eslint-community/eslint-utils": "^4.2.0",
         "@eslint-community/regexpp": "^4.11.0",

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

@@ -16,7 +16,7 @@
     },
     "../../../..": {
       "name": "@camperaid/watest",
-      "version": "2.5.1",
+      "version": "2.6.0",
       "dev": true,
       "license": "MPL",
       "dependencies": {
@@ -187,7 +187,6 @@
       "version": "8.12.1",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "bin": {
         "acorn": "bin/acorn"
       },
@@ -451,7 +450,6 @@
       "version": "9.8.0",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@eslint-community/eslint-utils": "^4.2.0",
         "@eslint-community/regexpp": "^4.11.0",

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

@@ -16,7 +16,7 @@
     },
     "../../../..": {
       "name": "@camperaid/watest",
-      "version": "2.5.1",
+      "version": "2.6.0",
       "dev": true,
       "license": "MPL",
       "dependencies": {
@@ -187,7 +187,6 @@
       "version": "8.12.1",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "bin": {
         "acorn": "bin/acorn"
       },
@@ -451,7 +450,6 @@
       "version": "9.8.0",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@eslint-community/eslint-utils": "^4.2.0",
         "@eslint-community/regexpp": "^4.11.0",