@matware/e2e-runner 1.1.1 → 1.3.0

package/src/ai-generate.js

@@ -27,23 +27,110 @@ The test format is:
       { "type": "wait", "text": "Expected text" },
       { "type": "wait", "value": "2000" },
       { "type": "assert_text", "text": "Expected text on page" },
+      { "type": "assert_element_text", "selector": "#title", "text": "Dashboard" },
+      { "type": "assert_element_text", "selector": "#title", "text": "Dashboard", "value": "exact" },
+      { "type": "assert_attribute", "selector": "input#email", "value": "type=email" },
+      { "type": "assert_attribute", "selector": "button", "value": "disabled" },
+      { "type": "assert_class", "selector": ".nav-item", "value": "active" },
+      { "type": "assert_not_visible", "selector": ".error-banner" },
+      { "type": "assert_input_value", "selector": "#email", "value": "user@example.com" },
+      { "type": "assert_matches", "selector": ".phone", "value": "\\\\d{3}-\\\\d{3}-\\\\d{4}" },
       { "type": "assert_url", "value": "/expected-path" },
       { "type": "assert_visible", "selector": ".element" },
       { "type": "assert_count", "selector": ".items", "value": "5" },
+      { "type": "assert_count", "selector": ".rows", "value": ">3" },
+      { "type": "assert_count", "selector": ".errors", "value": "0" },
+      { "type": "get_text", "selector": "#patient-name" },
       { "type": "screenshot", "value": "step-name.png" },
       { "type": "select", "selector": "select#role", "value": "admin" },
       { "type": "clear", "selector": "input" },
       { "type": "press", "value": "Enter" },
       { "type": "scroll", "selector": ".target" },
       { "type": "hover", "selector": ".menu" },
-      { "type": "evaluate", "value": "document.title" }
+      { "type": "evaluate", "value": "document.title" },
+      { "type": "type_react", "selector": "input#search", "value": "search term" },
+      { "type": "click_regex", "text": "submit order", "selector": "button", "value": "last" },
+      { "type": "click_option", "text": "Option Label" },
+      { "type": "focus_autocomplete", "text": "Search by label" },
+      { "type": "click_chip", "text": "Tag Name" },
+      { "type": "set_storage", "value": "token=abc123" },
+      { "type": "set_storage", "value": "theme=dark", "selector": "session" },
+      { "type": "assert_storage", "value": "token" },
+      { "type": "assert_storage", "value": "theme=dark", "selector": "session" },
+      { "type": "click_icon", "value": "edit" },
+      { "type": "click_icon", "value": "delete", "selector": ".user-card" },
+      { "type": "click_menu_item", "text": "Delete" },
+      { "type": "click_menu_item", "text": "Export", "selector": ".actions-menu" },
+      { "type": "click_in_context", "text": "John Doe", "selector": "button.edit" },
+      { "type": "gql", "value": "{ users { id name } }" },
+      { "type": "gql", "value": "query($id: ID) { user(id: $id) { name } }", "text": "{\"id\": \"123\"}" }
     ]
   }
 ]
 
+Framework-aware action reference (prefer these over evaluate for React/MUI apps):
+- type_react: types into React controlled inputs using native value setter + input/change events (works with both input and textarea)
+- click_regex: click element by regex text match (case-insensitive). Use "value": "last" for last match. Optional "selector" scopes the search
+- click_option: click a [role="option"] element by text — for autocomplete/select dropdowns
+- focus_autocomplete: focus an autocomplete input by its label text (supports MUI .MuiAutocomplete-root and [role="combobox"])
+- click_chip: click a chip/tag element by text (searches [class*="Chip"], [data-chip])
+
+Storage actions:
+- set_storage: set a localStorage key. "value": "key=val". Use "selector": "session" for sessionStorage
+- assert_storage: assert a storage key exists ("value": "key") or has a value ("value": "key=expected"). Use "selector": "session" for sessionStorage
+
+GraphQL action:
+- gql: execute a GraphQL query/mutation via browser fetch. Auth token is read from localStorage automatically (configurable via gqlAuthHeader, gqlAuthKey, gqlAuthPrefix). "value" is the query string. "text" is variables as JSON string. "selector" is an optional JS assertion expression (receives response as "r"). Throws on GraphQL errors automatically. Also installs window.__e2eGql(query, vars) for use in subsequent evaluate actions
+
+Smart interaction actions:
+- click_icon: click an icon by identifier (data-testid fragment, class fragment, aria-label, SVG title). Walks up to nearest clickable parent (button, a, etc.). Optional "selector" scopes the search
+- click_menu_item: click a menu item by text. Searches [role="menuitem"], .dropdown-item, .menu-item, [class*="MenuItem"]. Optional "selector" scopes the search
+- click_in_context: click a child element within a container identified by text. "text" finds the container, "selector" is the child to click. Picks the smallest matching container
+
+Assertion action reference:
+- assert_text: checks if text appears anywhere in the page body
+- assert_element_text: checks textContent of a specific element (use "value": "exact" for strict match)
+- assert_attribute: checks HTML attributes — "attr=value" for value check, "attr" alone for existence
+- assert_class: checks if element has a CSS class via classList.contains
+- assert_visible / assert_not_visible: checks element visibility (display, visibility, opacity)
+- assert_input_value: checks the .value of input/select/textarea elements
+- assert_matches: checks element textContent against a regex pattern
+- assert_count: counts matching elements — exact number or operators (">3", ">=1", "<10", "<=5")
+- assert_url: checks if current URL contains the value
+- get_text: extracts element text (non-assertion, returns { value })
+
+Reusable modules:
+- Tests can reference shared action sequences: { "$use": "module-name", "params": { "key": "value" } }
+- Use modules for repeated flows like login, navigation, or setup
+
+Hooks and DRY patterns:
+- When multiple tests share the same setup (e.g. authentication), use beforeEach instead of repeating it per test
+- Object format with hooks: { "beforeEach": [...], "tests": [{ "name": "...", "actions": [...] }] }
+- Array format (no hooks): [{ "name": "...", "actions": [...] }]
+- If 3+ tests repeat the same action sequence (e.g. goto + wait + screenshot), extract it into a module
+- NEVER repeat the same $use call with identical params across all tests — move it to beforeEach
+
 Rules:
-- Output a JSON array of test objects
-- Use only the action types listed above
+- Output valid JSON: either a plain array of test objects, or an object with "beforeEach"/"tests" keys when hooks are needed
+- NEVER use evaluate with inline JS for assertions that can be done with native action types:
+  * Use assert_element_text instead of evaluate to check element textContent
+  * Use assert_attribute instead of evaluate to check HTML attributes
+  * Use assert_class instead of evaluate to check CSS classes
+  * Use assert_input_value instead of evaluate to check input/select/textarea values
+  * Use assert_matches instead of evaluate for regex text matching
+  * Use assert_not_visible instead of evaluate to verify elements are hidden
+  * Use type_react instead of evaluate with native value setter for React controlled inputs
+  * Use click_regex instead of evaluate with Array.from(querySelectorAll).filter(regex) patterns
+  * Use click_option instead of evaluate with querySelectorAll('[role="option"]') patterns
+  * Use focus_autocomplete instead of evaluate with MuiAutocomplete-root label search patterns
+  * Use click_chip instead of evaluate with querySelectorAll('[class*="Chip"]') patterns
+  * Use set_storage instead of evaluate with localStorage.setItem or sessionStorage.setItem
+  * Use assert_storage instead of evaluate with localStorage.getItem or sessionStorage.getItem checks
+  * Use click_icon instead of evaluate with querySelector('svg[data-testid]').closest('button').click() patterns
+  * Use click_menu_item instead of evaluate with querySelectorAll('[role="menuitem"]') patterns
+  * Use click_in_context instead of evaluate that finds a container by text then clicks a child element
+  * Use gql instead of evaluate with fetch + JSON.stringify + GraphQL queries/mutations
+  * Reserve evaluate ONLY for complex logic that cannot be expressed with existing action types
 - "click" with "text" (no selector) finds buttons/links by visible text
 - "goto" values starting with "/" are relative to the app's base URL
 - Include a screenshot action before key assertions for debugging
@@ -53,6 +140,29 @@ Rules:
 - If the issue description is vague, create a reasonable test that covers the described scenario
 - If project context is provided (from CLAUDE.md), use the REAL routes, selectors, and UI patterns described there — never invent routes or selectors`;
 
+const E2E_RULES = `
+CRITICAL — UI-first testing rules:
+- Every test MUST start with a "goto" action to navigate to a real page
+- Tests MUST interact with UI elements: click, type, select, hover, scroll
+- Verify results through visible page state: assert_text, assert_visible, assert_element_text, assert_url
+- NEVER use evaluate to call APIs directly (no fetch, no GraphQL, no XHR, no window.__e2e.gql)
+- NEVER use evaluate to set up or verify data — use the UI workflow instead
+- Test the user journey as a real person would use the application
+- Include screenshot actions before key assertions for debugging
+`;
+
+const API_RULES = `
+API testing rules:
+- Tests verify backend API behavior directly via gql actions (preferred) or evaluate actions
+- Each test should: set up context → call API → assert response shape and values
+- PREFER the gql action for GraphQL queries/mutations — it handles auth and error checking automatically
+- Use gql with "selector" field for inline assertions on the response (JS expression where "r" is the response)
+- Use evaluate with window.__e2eGql() for complex multi-step GraphQL operations (the helper is installed by any gql action)
+- Name tests clearly describing the API operation (e.g. "createUser-returns-new-user")
+- Include error case tests (invalid input, missing fields, auth failures)
+- No need for goto/click/type — this is not UI testing
+`;
+
 /**
  * Reads the project's CLAUDE.md for app context (routes, selectors, UI structure).
  * Returns the content or empty string if not found.
@@ -77,7 +187,7 @@ function loadProjectContext(cwd) {
  * @param {object} config - Loaded config
  * @returns {object}
  */
-export function buildPrompt(issue, config) {
+export function buildPrompt(issue, config, testType = 'e2e') {
   let existingSuites = [];
   try {
     existingSuites = listSuites(config.testsDir).map(s => s.name);
@@ -88,7 +198,9 @@ export function buildPrompt(issue, config) {
     ? `\n## Project Context (from CLAUDE.md)\nUse these REAL routes, selectors, and UI patterns — do NOT invent your own.\n\n${projectContext}\n`
     : '';
 
-  const prompt = `Based on the following issue, generate E2E test actions using the e2e_create_test tool.
+  const categoryRules = testType === 'api' ? API_RULES : E2E_RULES;
+
+  const prompt = `Based on the following issue, generate ${testType === 'api' ? 'API' : 'E2E'} test actions using the e2e_create_test tool.
 
 ## Issue: ${issue.title}
 **Repo:** ${issue.repo}
@@ -99,8 +211,10 @@ export function buildPrompt(issue, config) {
 ### Description
 ${issue.body || 'No description provided.'}
 ${contextBlock}
+## Test Category: ${testType}
+${categoryRules}
 ## Instructions
-1. Analyze the issue and determine what user flows to test
+1. Analyze the issue and determine what ${testType === 'api' ? 'API operations' : 'user flows'} to test
 2. Create one or more tests that verify the expected behavior
 3. For bug reports: assert the CORRECT behavior (test failure = bug confirmed)
 4. Use the \`e2e_create_test\` tool with suite name \`issue-${issue.number}\`
@@ -141,7 +255,7 @@ export function hasApiKey(config = {}) {
  * @param {object} config - Loaded config
  * @returns {Promise<{ tests: object[], suiteName: string }>}
  */
-export async function generateTests(issue, config) {
+export async function generateTests(issue, config, testType = 'e2e') {
   const apiKey = config.anthropicApiKey || process.env.ANTHROPIC_API_KEY;
   if (!apiKey) {
     throw new Error('ANTHROPIC_API_KEY is required for test generation. Set it as an environment variable or in config.');
@@ -155,7 +269,9 @@ export async function generateTests(issue, config) {
     ? `\n## Project Context (from CLAUDE.md)\nIMPORTANT: Use these REAL routes, selectors, and UI patterns — do NOT invent your own.\n\n${projectContext}\n`
     : '';
 
-  const userMessage = `Generate E2E tests for this issue:
+  const categoryRules = testType === 'api' ? API_RULES : E2E_RULES;
+
+  const userMessage = `Generate ${testType === 'api' ? 'API' : 'E2E'} tests for this issue:
 
 Title: ${issue.title}
 Repo: ${issue.repo}
@@ -165,9 +281,11 @@ State: ${issue.state}
 Description:
 ${issue.body || 'No description provided.'}
 ${contextBlock}
+Test Category: ${testType}
+${categoryRules}
 Base URL: ${config.baseUrl}
 
-Output a JSON array of test objects. Nothing else.`;
+Output ONLY valid JSON. Either a plain array of test objects, or an object with "beforeEach" and "tests" keys if hooks are needed. Nothing else.`;
 
   const response = await fetch('https://api.anthropic.com/v1/messages', {
     method: 'POST',
@@ -208,9 +326,21 @@ Output a JSON array of test objects. Nothing else.`;
     throw new Error(`Failed to parse generated tests as JSON: ${err.message}\n\nRaw output:\n${text}`);
   }
 
-  if (!Array.isArray(tests)) {
-    throw new Error('Generated tests must be a JSON array');
+  // Accept both array format and object format with hooks
+  let hooks;
+  if (Array.isArray(tests)) {
+    // Plain array: [{ name, actions }]
+  } else if (tests && Array.isArray(tests.tests)) {
+    // Object with hooks: { beforeEach: [...], tests: [...] }
+    hooks = {};
+    for (const key of ['beforeAll', 'afterAll', 'beforeEach', 'afterEach']) {
+      if (Array.isArray(tests[key])) hooks[key] = tests[key];
+    }
+    if (Object.keys(hooks).length === 0) hooks = undefined;
+    tests = tests.tests;
+  } else {
+    throw new Error('Generated tests must be a JSON array or an object with a "tests" array');
   }
 
-  return { tests, suiteName };
+  return { tests, hooks, suiteName };
 }

package/src/config.js

@@ -12,10 +12,27 @@ import fs from 'fs';
 import path from 'path';
 import { pathToFileURL } from 'url';
 
+/** Deep merge utility for nested config objects */
+function deepMerge(...objects) {
+  const result = {};
+  for (const obj of objects) {
+    if (!obj || typeof obj !== 'object') continue;
+    for (const key of Object.keys(obj)) {
+      if (obj[key] && typeof obj[key] === 'object' && !Array.isArray(obj[key])) {
+        result[key] = deepMerge(result[key] || {}, obj[key]);
+      } else if (obj[key] !== undefined) {
+        result[key] = obj[key];
+      }
+    }
+  }
+  return result;
+}
+
 const DEFAULTS = {
   baseUrl: 'http://host.docker.internal:3000',
   poolUrl: 'ws://localhost:3333',
   testsDir: 'e2e/tests',
+  modulesDir: 'e2e/modules',
   screenshotsDir: 'e2e/screenshots',
   concurrency: 3,
   viewport: { width: 1280, height: 720 },
@@ -33,18 +50,84 @@ const DEFAULTS = {
   dashboardPort: 8484,
   maxHistoryRuns: 100,
   projectName: null,
+  exclude: [],
   failOnNetworkError: false,
+  actionRetries: 0,
+  actionRetryDelay: 500,
   anthropicApiKey: null,
   anthropicModel: 'claude-sonnet-4-5-20250929',
   authToken: null,
   authStorageKey: 'accessToken',
+  learningsEnabled: true,
+  learningsMarkdown: true,
+  learningsNeo4j: false,
+  learningsDays: 30,
+  neo4jBoltUrl: 'bolt://localhost:7687',
+  neo4jUser: 'neo4j',
+  neo4jPassword: 'e2erunner',
+  neo4jBoltPort: 7687,
+  neo4jHttpPort: 7474,
+  verificationStrictness: 'moderate',
+  networkIgnoreDomains: [],
+  authLoginEndpoint: null,
+  authCredentials: null,
+  authTokenPath: 'token',
+  gqlEndpoint: '/api/graphql',
+  gqlAuthHeader: 'Authorization',
+  gqlAuthKey: 'accessToken',
+  gqlAuthPrefix: 'Bearer ',
+  poolUrls: null,
+  watchInterval: null,
+  watchRunOnStart: true,
+  watchGitPoll: false,
+  watchGitBranch: null,
+  watchGitInterval: '30s',
+  watchWebhookUrl: null,
+  watchWebhookEvents: 'failure',
+  watchProjects: null,
+  
+  // Sync configuration
+  sync: {
+    mode: 'standalone',  // 'standalone' | 'hub' | 'agent'
+    hub: {
+      port: null,        // null = use dashboardPort
+      tls: {
+        enabled: false,
+        certPath: null,
+        keyPath: null,
+        mtls: false,
+        caPath: null,
+      },
+      allowRegistration: true,
+      requireApproval: false,
+      masterKeyEnv: 'E2E_SYNC_MASTER_KEY',
+    },
+    agent: {
+      hubUrl: null,
+      instanceId: null,
+      displayName: null,
+      apiKeyEnv: 'E2E_SYNC_API_KEY',
+      totpSecretEnv: 'E2E_SYNC_TOTP',
+      tls: {
+        certPath: null,
+        keyPath: null,
+        caPath: null,
+      },
+      autoSync: true,
+      pullOnDashboard: true,
+      offlineQueue: true,
+      queueRetryInterval: 60,
+    },
+  },
 };
 
 function loadEnvVars() {
   const env = {};
   if (process.env.BASE_URL) env.baseUrl = process.env.BASE_URL;
   if (process.env.CHROME_POOL_URL) env.poolUrl = process.env.CHROME_POOL_URL;
+  if (process.env.CHROME_POOL_URLS) env.poolUrls = process.env.CHROME_POOL_URLS.split(',').map(u => u.trim()).filter(Boolean);
   if (process.env.TESTS_DIR) env.testsDir = process.env.TESTS_DIR;
+  if (process.env.MODULES_DIR) env.modulesDir = process.env.MODULES_DIR;
   if (process.env.SCREENSHOTS_DIR) env.screenshotsDir = process.env.SCREENSHOTS_DIR;
   if (process.env.CONCURRENCY) env.concurrency = parseInt(process.env.CONCURRENCY);
   if (process.env.DEFAULT_TIMEOUT) env.defaultTimeout = parseInt(process.env.DEFAULT_TIMEOUT);
@@ -57,10 +140,76 @@ function loadEnvVars() {
   if (process.env.E2E_ENV) env.env = process.env.E2E_ENV;
   if (process.env.PROJECT_NAME) env.projectName = process.env.PROJECT_NAME;
   if (process.env.FAIL_ON_NETWORK_ERROR) env.failOnNetworkError = process.env.FAIL_ON_NETWORK_ERROR === 'true' || process.env.FAIL_ON_NETWORK_ERROR === '1';
+  if (process.env.ACTION_RETRIES) env.actionRetries = parseInt(process.env.ACTION_RETRIES);
+  if (process.env.ACTION_RETRY_DELAY) env.actionRetryDelay = parseInt(process.env.ACTION_RETRY_DELAY);
   if (process.env.ANTHROPIC_API_KEY) env.anthropicApiKey = process.env.ANTHROPIC_API_KEY;
   if (process.env.ANTHROPIC_MODEL) env.anthropicModel = process.env.ANTHROPIC_MODEL;
   if (process.env.AUTH_TOKEN) env.authToken = process.env.AUTH_TOKEN;
   if (process.env.AUTH_STORAGE_KEY) env.authStorageKey = process.env.AUTH_STORAGE_KEY;
+  if (process.env.LEARNINGS_ENABLED) env.learningsEnabled = process.env.LEARNINGS_ENABLED !== 'false' && process.env.LEARNINGS_ENABLED !== '0';
+  if (process.env.LEARNINGS_MARKDOWN) env.learningsMarkdown = process.env.LEARNINGS_MARKDOWN !== 'false' && process.env.LEARNINGS_MARKDOWN !== '0';
+  if (process.env.LEARNINGS_NEO4J) env.learningsNeo4j = process.env.LEARNINGS_NEO4J === 'true' || process.env.LEARNINGS_NEO4J === '1';
+  if (process.env.LEARNINGS_DAYS) env.learningsDays = parseInt(process.env.LEARNINGS_DAYS);
+  if (process.env.NEO4J_BOLT_URL) env.neo4jBoltUrl = process.env.NEO4J_BOLT_URL;
+  if (process.env.NEO4J_USER) env.neo4jUser = process.env.NEO4J_USER;
+  if (process.env.NEO4J_PASSWORD) env.neo4jPassword = process.env.NEO4J_PASSWORD;
+  if (process.env.NEO4J_BOLT_PORT) env.neo4jBoltPort = parseInt(process.env.NEO4J_BOLT_PORT);
+  if (process.env.NEO4J_HTTP_PORT) env.neo4jHttpPort = parseInt(process.env.NEO4J_HTTP_PORT);
+  if (process.env.NETWORK_IGNORE_DOMAINS) env.networkIgnoreDomains = process.env.NETWORK_IGNORE_DOMAINS.split(',').map(d => d.trim()).filter(Boolean);
+  if (process.env.AUTH_LOGIN_ENDPOINT) env.authLoginEndpoint = process.env.AUTH_LOGIN_ENDPOINT;
+  if (process.env.AUTH_TOKEN_PATH) env.authTokenPath = process.env.AUTH_TOKEN_PATH;
+  if (process.env.GQL_ENDPOINT) env.gqlEndpoint = process.env.GQL_ENDPOINT;
+  if (process.env.GQL_AUTH_HEADER) env.gqlAuthHeader = process.env.GQL_AUTH_HEADER;
+  if (process.env.GQL_AUTH_KEY) env.gqlAuthKey = process.env.GQL_AUTH_KEY;
+  if (process.env.GQL_AUTH_PREFIX) env.gqlAuthPrefix = process.env.GQL_AUTH_PREFIX;
+  if (process.env.WATCH_INTERVAL) env.watchInterval = process.env.WATCH_INTERVAL;
+  if (process.env.WATCH_WEBHOOK_URL) env.watchWebhookUrl = process.env.WATCH_WEBHOOK_URL;
+  if (process.env.WATCH_WEBHOOK_EVENTS) env.watchWebhookEvents = process.env.WATCH_WEBHOOK_EVENTS;
+  if (process.env.WATCH_GIT_POLL) env.watchGitPoll = process.env.WATCH_GIT_POLL === 'true' || process.env.WATCH_GIT_POLL === '1';
+  if (process.env.WATCH_GIT_BRANCH) env.watchGitBranch = process.env.WATCH_GIT_BRANCH;
+  if (process.env.WATCH_GIT_INTERVAL) env.watchGitInterval = process.env.WATCH_GIT_INTERVAL;
+  if (process.env.VERIFICATION_STRICTNESS) {
+    const val = process.env.VERIFICATION_STRICTNESS.toLowerCase();
+    if (['strict', 'moderate', 'lenient'].includes(val)) {
+      env.verificationStrictness = val;
+    }
+  }
+  
+  // Sync configuration from env vars
+  if (process.env.E2E_SYNC_MODE) {
+    const mode = process.env.E2E_SYNC_MODE.toLowerCase();
+    if (['standalone', 'hub', 'agent'].includes(mode)) {
+      env.sync = env.sync || {};
+      env.sync.mode = mode;
+    }
+  }
+  if (process.env.E2E_SYNC_HUB_URL) {
+    env.sync = env.sync || {};
+    env.sync.agent = env.sync.agent || {};
+    env.sync.agent.hubUrl = process.env.E2E_SYNC_HUB_URL;
+  }
+  if (process.env.E2E_SYNC_INSTANCE_ID) {
+    env.sync = env.sync || {};
+    env.sync.agent = env.sync.agent || {};
+    env.sync.agent.instanceId = process.env.E2E_SYNC_INSTANCE_ID;
+  }
+  if (process.env.E2E_SYNC_DISPLAY_NAME) {
+    env.sync = env.sync || {};
+    env.sync.agent = env.sync.agent || {};
+    env.sync.agent.displayName = process.env.E2E_SYNC_DISPLAY_NAME;
+  }
+  if (process.env.E2E_SYNC_HUB_PORT) {
+    env.sync = env.sync || {};
+    env.sync.hub = env.sync.hub || {};
+    env.sync.hub.port = parseInt(process.env.E2E_SYNC_HUB_PORT);
+  }
+  if (process.env.E2E_SYNC_TLS_ENABLED) {
+    env.sync = env.sync || {};
+    env.sync.hub = env.sync.hub || {};
+    env.sync.hub.tls = env.sync.hub.tls || {};
+    env.sync.hub.tls.enabled = process.env.E2E_SYNC_TLS_ENABLED === 'true' || process.env.E2E_SYNC_TLS_ENABLED === '1';
+  }
+  
   return env;
 }
 
@@ -117,6 +266,16 @@ export async function loadConfig(cliArgs = {}, cwd = null) {
     ...envConfig,
     ...cliArgs,
   };
+  
+  // Deep merge sync config (nested objects need special handling)
+  if (fileConfig.sync || envConfig.sync || cliArgs.sync) {
+    config.sync = deepMerge(
+      DEFAULTS.sync,
+      fileConfig.sync || {},
+      envConfig.sync || {},
+      cliArgs.sync || {}
+    );
+  }
 
   // Apply environment profile overrides
   if (config.env && config.env !== 'default' && config.environments?.[config.env]) {
@@ -129,6 +288,9 @@ export async function loadConfig(cliArgs = {}, cwd = null) {
   if (!path.isAbsolute(config.testsDir)) {
     config.testsDir = path.join(cwd, config.testsDir);
   }
+  if (config.modulesDir && !path.isAbsolute(config.modulesDir)) {
+    config.modulesDir = path.join(cwd, config.modulesDir);
+  }
   if (!path.isAbsolute(config.screenshotsDir)) {
     config.screenshotsDir = path.join(cwd, config.screenshotsDir);
   }
@@ -144,5 +306,14 @@ export async function loadConfig(cliArgs = {}, cwd = null) {
     config.projectName = path.basename(cwd);
   }
 
+  // Normalize pool URLs: poolUrls array → _poolUrls, keep poolUrl as primary
+  if (config.poolUrls && Array.isArray(config.poolUrls) && config.poolUrls.length > 0) {
+    config._poolUrls = config.poolUrls;
+    config.poolUrl = config.poolUrls[0];
+  } else {
+    config._poolUrls = [config.poolUrl];
+  }
+  delete config.poolUrls;
+
   return config;
 }