codeceptjs 3.7.5-beta.1 → 3.7.5-beta.3

package/bin/codecept.js

@@ -296,6 +296,29 @@ program
 
   .action(require('../lib/command/run-rerun'))
 
+program
+  .command('run-failed-tests')
+  .description('Re-run tests that failed in the previous test run')
+  .option(commandFlags.config.flag, commandFlags.config.description)
+  .option(commandFlags.profile.flag, commandFlags.profile.description)
+  .option(commandFlags.verbose.flag, commandFlags.verbose.description)
+  .option(commandFlags.debug.flag, commandFlags.debug.description)
+  .option(commandFlags.steps.flag, commandFlags.steps.description)
+  .option('-o, --override [value]', 'override current config options')
+  .option('-f, --file [path]', 'path to failed tests file (default: ./failed-tests.json)')
+  .option('-g, --grep <pattern>', 'only run failed tests matching <pattern>')
+  .option('-p, --plugins <k=v,k2=v2,...>', 'enable plugins, comma-separated')
+  .option('--features', 'run only *.feature files and skip tests')
+  .option('--tests', 'run only JS test files and skip features')
+  .option('--colors', 'force enabling of colors')
+  .option('--no-colors', 'force disabling of colors')
+  .option('-R, --reporter <name>', 'specify the reporter to use')
+  .option('-O, --reporter-options <k=v,k2=v2,...>', 'reporter-specific options')
+  .option('--workers <number>', 'run failed tests in parallel using specified number of workers')
+  .option('--suites', 'parallel execution of suites not single tests (when using --workers)')
+  .option('--by <strategy>', 'test distribution strategy when using --workers: "test", "suite", or "pool"')
+  .action(errorHandler(require('../lib/command/run-failed-tests')))
+
 program.on('command:*', cmd => {
   console.log(`\nUnknown command ${cmd}\n`)
   program.outputHelp()

package/lib/command/run-failed-tests.js

@@ -0,0 +1,218 @@
+const fs = require('fs')
+const path = require('path')
+const { getConfig, printError, getTestRoot, createOutputDir } = require('./utils')
+const Config = require('../config')
+const store = require('../store')
+const Codecept = require('../codecept')
+const output = require('../output')
+const Workers = require('../workers')
+const { tryOrDefault } = require('../utils')
+
+module.exports = async function (options) {
+  // registering options globally to use in config
+  if (options.profile) {
+    process.env.profile = options.profile
+  }
+  if (options.verbose || options.debug) store.debugMode = true
+
+  const configFile = options.config
+  let config = getConfig(configFile)
+  
+  if (options.override) {
+    config = Config.append(JSON.parse(options.override))
+  }
+  
+  const testRoot = getTestRoot(configFile)
+  createOutputDir(config, testRoot)
+
+  // Determine failed tests file path - respect CodeceptJS output directory
+  const failedTestsFile = options.file || 'failed-tests.json'
+  const failedTestsPath = path.isAbsolute(failedTestsFile)
+    ? failedTestsFile
+    : path.resolve(global.output_dir || './output', failedTestsFile)
+
+  // Check if failed tests file exists
+  if (!fs.existsSync(failedTestsPath)) {
+    output.error(`Failed tests file not found: ${failedTestsPath}`)
+    output.print('Run tests first to generate a failed tests file, or specify a different file with --file option')
+    process.exitCode = 1
+    return
+  }
+
+  let failedTestsData
+  try {
+    const fileContent = fs.readFileSync(failedTestsPath, 'utf8')
+    failedTestsData = JSON.parse(fileContent)
+  } catch (error) {
+    output.error(`Failed to read or parse failed tests file: ${error.message}`)
+    process.exitCode = 1
+    return
+  }
+
+  if (!failedTestsData.tests || failedTestsData.tests.length === 0) {
+    output.print('No failed tests found in the file')
+    return
+  }
+
+  output.print(`Found ${failedTestsData.tests.length} failed tests from ${failedTestsData.timestamp}`)
+
+  // Build test patterns from failed tests
+  const testPatterns = []
+  const testsByFile = new Map()
+
+  // Group tests by file for more efficient execution
+  failedTestsData.tests.forEach(test => {
+    if (test.file) {
+      if (!testsByFile.has(test.file)) {
+        testsByFile.set(test.file, [])
+      }
+      testsByFile.get(test.file).push(test)
+    }
+  })
+
+  // If we have specific test files, use them
+  if (testsByFile.size > 0) {
+    for (const [file, tests] of testsByFile) {
+      if (options.grep) {
+        // If grep is specified, combine with file pattern
+        testPatterns.push(file)
+      } else {
+        // Try to be more specific with test titles if possible
+        testPatterns.push(file)
+      }
+    }
+  } else {
+    // Fallback: use test titles with grep
+    const testTitles = failedTestsData.tests.map(test => test.title).filter(Boolean)
+    if (testTitles.length > 0) {
+      // Create a regex pattern to match any of the failed test titles
+      const grepPattern = testTitles.map(title => title.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|')
+      options.grep = grepPattern
+    }
+  }
+
+  // Check if user wants to run with workers
+  if (options.workers) {
+    await runWithWorkers(config, options, testPatterns, failedTestsData)
+  } else {
+    await runWithoutWorkers(config, options, testPatterns, failedTestsData, testRoot)
+  }
+}
+
+async function runWithWorkers(config, options, testPatterns, failedTestsData) {
+  const numberOfWorkers = parseInt(options.workers, 10)
+  const overrideConfigs = tryOrDefault(() => JSON.parse(options.override || '{}'), {})
+  
+  // Determine test split strategy
+  let by = 'test' // default for failed tests
+  if (options.by) {
+    by = options.by
+  } else if (options.suites) {
+    by = 'suite'
+  }
+
+  // Validate the by option
+  const validStrategies = ['test', 'suite', 'pool']
+  if (!validStrategies.includes(by)) {
+    throw new Error(`Invalid --by strategy: ${by}. Valid options are: ${validStrategies.join(', ')}`)
+  }
+
+  const workerConfig = {
+    by,
+    testConfig: options.config,
+    options,
+    selectedRuns: undefined,
+  }
+
+  output.print(`CodeceptJS v${require('../codecept').version()}`)
+  output.print(`Re-running ${failedTestsData.tests.length} failed tests in ${output.styles.bold(numberOfWorkers)} workers...`)
+  output.print()
+  store.hasWorkers = true
+
+  const workers = new Workers(numberOfWorkers, workerConfig)
+  workers.overrideConfig(overrideConfigs)
+
+  // Set up event listeners for worker output
+  workers.on('test.failed', test => {
+    output.test.failed(test)
+  })
+
+  workers.on('test.passed', test => {
+    output.test.passed(test)
+  })
+
+  workers.on('test.skipped', test => {
+    output.test.skipped(test)
+  })
+
+  workers.on('all.result', result => {
+    workers.printResults()
+  })
+
+  try {
+    if (options.verbose || options.debug) store.debugMode = true
+
+    if (options.verbose) {
+      output.print('\nFailed tests to re-run with workers:')
+      failedTestsData.tests.forEach((test, index) => {
+        output.print(`  ${index + 1}. ${test.fullTitle || test.title} (${test.file || 'unknown file'})`)
+        if (test.error && test.error.message) {
+          output.print(`     Error: ${test.error.message}`)
+        }
+      })
+      output.print('')
+      
+      const { getMachineInfo } = require('./info')
+      await getMachineInfo()
+    }
+
+    await workers.bootstrapAll()
+    await workers.run()
+  } catch (err) {
+    printError(err)
+    process.exitCode = 1
+  } finally {
+    await workers.teardownAll()
+  }
+}
+
+async function runWithoutWorkers(config, options, testPatterns, failedTestsData, testRoot) {
+  const codecept = new Codecept(config, options)
+
+  try {
+    codecept.init(testRoot)
+    await codecept.bootstrap()
+
+    // Load tests - if we have specific patterns, use them, otherwise load all and filter with grep
+    if (testPatterns.length > 0) {
+      codecept.loadTests(testPatterns.join(' '))
+    } else {
+      codecept.loadTests()
+    }
+
+    if (options.verbose) {
+      global.debugMode = true
+      const { getMachineInfo } = require('./info')
+      await getMachineInfo()
+    }
+
+    // Display information about what we're running
+    if (options.verbose) {
+      output.print('\nFailed tests to re-run:')
+      failedTestsData.tests.forEach((test, index) => {
+        output.print(`  ${index + 1}. ${test.fullTitle || test.title} (${test.file || 'unknown file'})`)
+        if (test.error && test.error.message) {
+          output.print(`     Error: ${test.error.message}`)
+        }
+      })
+      output.print('')
+    }
+
+    await codecept.run()
+  } catch (err) {
+    printError(err)
+    process.exitCode = 1
+  } finally {
+    await codecept.teardown()
+  }
+}

package/lib/helper/Playwright.js

@@ -38,6 +38,8 @@ const WebElement = require('../element/WebElement')
 let playwright
 let perfTiming
 let defaultSelectorEnginesInitialized = false
+let registeredCustomLocatorStrategies = new Set()
+let globalCustomLocatorStrategies = new Map()
 
 const popupStore = new Popup()
 const consoleLogStore = new Console()
@@ -96,6 +98,7 @@ const pathSeparator = path.sep
  * @prop {boolean} [highlightElement] - highlight the interacting elements. Default: false. Note: only activate under verbose mode (--verbose).
  * @prop {object} [recordHar] - record HAR and will be saved to `output/har`. See more of [HAR options](https://playwright.dev/docs/api/class-browser#browser-new-context-option-record-har).
  * @prop {string} [testIdAttribute=data-testid] - locate elements based on the testIdAttribute. See more of [locate by test id](https://playwright.dev/docs/locators#locate-by-test-id).
+ * @prop {object} [customLocatorStrategies] - custom locator strategies. An object with keys as strategy names and values as JavaScript functions. Example: `{ byRole: (selector, root) => { return root.querySelector(\`[role="\${selector}\"]\`) } }`
  */
 const config = {}
 
@@ -344,9 +347,23 @@ class Playwright extends Helper {
     this.recordingWebSocketMessages = false
     this.recordedWebSocketMessagesAtLeastOnce = false
     this.cdpSession = null
+    this.customLocatorStrategies = typeof config.customLocatorStrategies === 'object' && config.customLocatorStrategies !== null ? config.customLocatorStrategies : null
+    this._customLocatorsRegistered = false
+
+    // Add custom locator strategies to global registry for early registration
+    if (this.customLocatorStrategies) {
+      for (const [strategyName, strategyFunction] of Object.entries(this.customLocatorStrategies)) {
+        globalCustomLocatorStrategies.set(strategyName, strategyFunction)
+      }
+    }
 
     // override defaults with config
     this._setConfig(config)
+
+    // Call _init() to register selector engines - use setTimeout to avoid blocking constructor
+    setTimeout(() => {
+      this._init().catch(console.error)
+    }, 0)
   }
 
   _validateConfig(config) {
@@ -463,12 +480,61 @@ class Playwright extends Helper {
 
   async _init() {
     // register an internal selector engine for reading value property of elements in a selector
-    if (defaultSelectorEnginesInitialized) return
-    defaultSelectorEnginesInitialized = true
     try {
-      await playwright.selectors.register('__value', createValueEngine)
-      await playwright.selectors.register('__disabled', createDisabledEngine)
-      if (process.env.testIdAttribute) await playwright.selectors.setTestIdAttribute(process.env.testIdAttribute)
+      if (!defaultSelectorEnginesInitialized) {
+        await playwright.selectors.register('__value', createValueEngine)
+        await playwright.selectors.register('__disabled', createDisabledEngine)
+        if (process.env.testIdAttribute) await playwright.selectors.setTestIdAttribute(process.env.testIdAttribute)
+        defaultSelectorEnginesInitialized = true
+      }
+
+      // Register all custom locator strategies from the global registry
+      for (const [strategyName, strategyFunction] of globalCustomLocatorStrategies.entries()) {
+        if (!registeredCustomLocatorStrategies.has(strategyName)) {
+          try {
+            // Create a selector engine factory function exactly like createValueEngine pattern
+            // Capture variables in closure to avoid reference issues
+            const createCustomEngine = ((name, func) => {
+              return () => {
+                return {
+                  create() {
+                    return null
+                  },
+                  query(root, selector) {
+                    try {
+                      if (!root) return null
+                      const result = func(selector, root)
+                      return Array.isArray(result) ? result[0] : result
+                    } catch (error) {
+                      console.warn(`Error in custom locator "${name}":`, error)
+                      return null
+                    }
+                  },
+                  queryAll(root, selector) {
+                    try {
+                      if (!root) return []
+                      const result = func(selector, root)
+                      return Array.isArray(result) ? result : result ? [result] : []
+                    } catch (error) {
+                      console.warn(`Error in custom locator "${name}":`, error)
+                      return []
+                    }
+                  },
+                }
+              }
+            })(strategyName, strategyFunction)
+
+            await playwright.selectors.register(strategyName, createCustomEngine)
+            registeredCustomLocatorStrategies.add(strategyName)
+          } catch (error) {
+            if (!error.message.includes('already registered')) {
+              console.warn(`Failed to register custom locator strategy '${strategyName}':`, error)
+            } else {
+              console.log(`Custom locator strategy '${strategyName}' already registered`)
+            }
+          }
+        }
+      }
     } catch (e) {
       console.warn(e)
     }
@@ -827,6 +893,9 @@ class Playwright extends Helper {
   }
 
   async _startBrowser() {
+    // Ensure custom locator strategies are registered before browser launch
+    await this._init()
+
     if (this.isElectron) {
       this.browser = await playwright._electron.launch(this.playwrightOptions)
     } else if (this.isRemoteBrowser && this.isCDPConnection) {
@@ -862,6 +931,30 @@ class Playwright extends Helper {
     return this.browser
   }
 
+  _lookupCustomLocator(customStrategy) {
+    if (typeof this.customLocatorStrategies !== 'object' || this.customLocatorStrategies === null) {
+      return null
+    }
+    const strategy = this.customLocatorStrategies[customStrategy]
+    return typeof strategy === 'function' ? strategy : null
+  }
+
+  _isCustomLocator(locator) {
+    const locatorObj = new Locator(locator)
+    if (locatorObj.isCustom()) {
+      const customLocator = this._lookupCustomLocator(locatorObj.type)
+      if (customLocator) {
+        return true
+      }
+      throw new Error('Please define "customLocatorStrategies" as an Object and the Locator Strategy as a "function".')
+    }
+    return false
+  }
+
+  _isCustomLocatorStrategyDefined() {
+    return !!(this.customLocatorStrategies && Object.keys(this.customLocatorStrategies).length > 0)
+  }
+
   /**
    * Create a new browser context with a page. \
    * Usually it should be run from a custom helper after call of `_startBrowser()`
@@ -869,11 +962,64 @@ class Playwright extends Helper {
    */
   async _createContextPage(contextOptions) {
     this.browserContext = await this.browser.newContext(contextOptions)
+
+    // Register custom locator strategies for this context
+    await this._registerCustomLocatorStrategies()
+
     const page = await this.browserContext.newPage()
     targetCreatedHandler.call(this, page)
     await this._setPage(page)
   }
 
+  async _registerCustomLocatorStrategies() {
+    if (!this.customLocatorStrategies) return
+
+    for (const [strategyName, strategyFunction] of Object.entries(this.customLocatorStrategies)) {
+      if (!registeredCustomLocatorStrategies.has(strategyName)) {
+        try {
+          const createCustomEngine = ((name, func) => {
+            return () => {
+              return {
+                create(root, target) {
+                  return null
+                },
+                query(root, selector) {
+                  try {
+                    if (!root) return null
+                    const result = func(selector, root)
+                    return Array.isArray(result) ? result[0] : result
+                  } catch (error) {
+                    console.warn(`Error in custom locator "${name}":`, error)
+                    return null
+                  }
+                },
+                queryAll(root, selector) {
+                  try {
+                    if (!root) return []
+                    const result = func(selector, root)
+                    return Array.isArray(result) ? result : result ? [result] : []
+                  } catch (error) {
+                    console.warn(`Error in custom locator "${name}":`, error)
+                    return []
+                  }
+                },
+              }
+            }
+          })(strategyName, strategyFunction)
+
+          await playwright.selectors.register(strategyName, createCustomEngine)
+          registeredCustomLocatorStrategies.add(strategyName)
+        } catch (error) {
+          if (!error.message.includes('already registered')) {
+            console.warn(`Failed to register custom locator strategy '${strategyName}':`, error)
+          } else {
+            console.log(`Custom locator strategy '${strategyName}' already registered`)
+          }
+        }
+      }
+    }
+  }
+
   _getType() {
     return this.browser._type
   }
@@ -885,7 +1031,10 @@ class Playwright extends Helper {
     this.frame = null
     popupStore.clear()
     if (this.options.recordHar) await this.browserContext.close()
+    this.browserContext = null
     await this.browser.close()
+    this.browser = null
+    this.isRunning = false
   }
 
   async _evaluateHandeInContext(...args) {
@@ -1266,9 +1415,9 @@ class Playwright extends Helper {
   async _locate(locator) {
     const context = await this._getContext()
 
-    if (this.frame) return findElements(this.frame, locator)
+    if (this.frame) return findElements.call(this, this.frame, locator)
 
-    const els = await findElements(context, locator)
+    const els = await findElements.call(this, context, locator)
 
     if (store.debugMode) {
       const previewElements = els.slice(0, 3)
@@ -2063,11 +2212,25 @@ class Playwright extends Helper {
    * @param {*} locator
    */
   _contextLocator(locator) {
-    locator = buildLocatorString(new Locator(locator, 'css'))
+    const locatorObj = new Locator(locator, 'css')
+
+    // Handle custom locators differently
+    if (locatorObj.isCustom()) {
+      return buildCustomLocatorString(locatorObj)
+    }
+
+    locator = buildLocatorString(locatorObj)
 
     if (this.contextLocator) {
-      const contextLocator = buildLocatorString(new Locator(this.contextLocator, 'css'))
-      locator = `${contextLocator} >> ${locator}`
+      const contextLocatorObj = new Locator(this.contextLocator, 'css')
+      if (contextLocatorObj.isCustom()) {
+        // For custom context locators, we can't use the >> syntax
+        // Instead, we'll need to handle this differently in the calling methods
+        return locator
+      } else {
+        const contextLocator = buildLocatorString(contextLocatorObj)
+        locator = `${contextLocator} >> ${locator}`
+      }
     }
 
     return locator
@@ -2078,11 +2241,25 @@ class Playwright extends Helper {
    *
    */
   async grabTextFrom(locator) {
-    locator = this._contextLocator(locator)
-    const text = await this.page.textContent(locator)
-    assertElementExists(text, locator)
-    this.debugSection('Text', text)
-    return text
+    const locatorObj = new Locator(locator, 'css')
+
+    if (locatorObj.isCustom()) {
+      // For custom locators, find the element first
+      const elements = await findCustomElements.call(this, this.page, locatorObj)
+      if (elements.length === 0) {
+        throw new Error(`Element not found: ${locatorObj.toString()}`)
+      }
+      const text = await elements[0].textContent()
+      assertElementExists(text, locatorObj.toString())
+      this.debugSection('Text', text)
+      return text
+    } else {
+      locator = this._contextLocator(locator)
+      const text = await this.page.textContent(locator)
+      assertElementExists(text, locator)
+      this.debugSection('Text', text)
+      return text
+    }
   }
 
   /**
@@ -2095,7 +2272,6 @@ class Playwright extends Helper {
     for (const el of els) {
       texts.push(await el.innerText())
     }
-    this.debug(`Matched ${els.length} elements`)
     return texts
   }
 
@@ -2114,7 +2290,6 @@ class Playwright extends Helper {
    */
   async grabValueFromAll(locator) {
     const els = await findFields.call(this, locator)
-    this.debug(`Matched ${els.length} elements`)
     return Promise.all(els.map(el => el.inputValue()))
   }
 
@@ -2133,7 +2308,6 @@ class Playwright extends Helper {
    */
   async grabHTMLFromAll(locator) {
     const els = await this._locate(locator)
-    this.debug(`Matched ${els.length} elements`)
     return Promise.all(els.map(el => el.innerHTML()))
   }
 
@@ -2154,7 +2328,6 @@ class Playwright extends Helper {
    */
   async grabCssPropertyFromAll(locator, cssProperty) {
     const els = await this._locate(locator)
-    this.debug(`Matched ${els.length} elements`)
     const cssValues = await Promise.all(els.map(el => el.evaluate((el, cssProperty) => getComputedStyle(el).getPropertyValue(cssProperty), cssProperty)))
 
     return cssValues
@@ -2265,7 +2438,6 @@ class Playwright extends Helper {
    */
   async grabAttributeFromAll(locator, attr) {
     const els = await this._locate(locator)
-    this.debug(`Matched ${els.length} elements`)
     const array = []
 
     for (let index = 0; index < els.length; index++) {
@@ -2285,7 +2457,6 @@ class Playwright extends Helper {
     const res = await this._locateElement(locator)
     assertElementExists(res, locator)
     const elem = res
-    this.debug(`Screenshot of ${new Locator(locator)} element has been saved to ${outputFile}`)
     return elem.screenshot({ path: outputFile, type: 'png' })
   }
 
@@ -2580,7 +2751,16 @@ class Playwright extends Helper {
 
     const context = await this._getContext()
     try {
-      await context.locator(buildLocatorString(locator)).first().waitFor({ timeout: waitTimeout, state: 'attached' })
+      if (locator.isCustom()) {
+        // For custom locators, we need to use our custom element finding logic
+        const elements = await findCustomElements.call(this, context, locator)
+        if (elements.length === 0) {
+          throw new Error(`Custom locator ${locator.type}=${locator.value} not found`)
+        }
+        await elements[0].waitFor({ timeout: waitTimeout, state: 'attached' })
+      } else {
+        await context.locator(buildLocatorString(locator)).first().waitFor({ timeout: waitTimeout, state: 'attached' })
+      }
     } catch (e) {
       throw new Error(`element (${locator.toString()}) still not present on page after ${waitTimeout / 1000} sec\n${e.message}`)
     }
@@ -2594,9 +2774,30 @@ class Playwright extends Helper {
   async waitForVisible(locator, sec) {
     const waitTimeout = sec ? sec * 1000 : this.options.waitForTimeout
     locator = new Locator(locator, 'css')
+
     const context = await this._getContext()
     let count = 0
 
+    // Handle custom locators
+    if (locator.isCustom()) {
+      let waiter
+      do {
+        const elements = await findCustomElements.call(this, context, locator)
+        if (elements.length > 0) {
+          waiter = await elements[0].isVisible()
+        } else {
+          waiter = false
+        }
+        if (!waiter) {
+          await this.wait(1)
+          count += 1000
+        }
+      } while (!waiter && count <= waitTimeout)
+
+      if (!waiter) throw new Error(`element (${locator.toString()}) still not visible after ${waitTimeout / 1000} sec.`)
+      return
+    }
+
     // we have this as https://github.com/microsoft/playwright/issues/26829 is not yet implemented
     let waiter
     if (this.frame) {
@@ -2623,6 +2824,7 @@ class Playwright extends Helper {
   async waitForInvisible(locator, sec) {
     const waitTimeout = sec ? sec * 1000 : this.options.waitForTimeout
     locator = new Locator(locator, 'css')
+
     const context = await this._getContext()
     let waiter
     let count = 0
@@ -2653,6 +2855,7 @@ class Playwright extends Helper {
   async waitToHide(locator, sec) {
     const waitTimeout = sec ? sec * 1000 : this.options.waitForTimeout
     locator = new Locator(locator, 'css')
+
     const context = await this._getContext()
     let waiter
     let count = 0
@@ -2774,9 +2977,18 @@ class Playwright extends Helper {
     if (context) {
       const locator = new Locator(context, 'css')
       try {
+        if (locator.isCustom()) {
+          // For custom locators, find the elements first then check for text within them
+          const elements = await findCustomElements.call(this, contextObject, locator)
+          if (elements.length === 0) {
+            throw new Error(`Context element not found: ${locator.toString()}`)
+          }
+          return elements[0].locator(`text=${text}`).first().waitFor({ timeout: waitTimeout, state: 'visible' })
+        }
+
         if (!locator.isXPath()) {
           return contextObject
-            .locator(`${locator.isCustom() ? `${locator.type}=${locator.value}` : locator.simplify()} >> text=${text}`)
+            .locator(`${locator.simplify()} >> text=${text}`)
             .first()
             .waitFor({ timeout: waitTimeout, state: 'visible' })
             .catch(e => {
@@ -3421,9 +3633,15 @@ class Playwright extends Helper {
 
 module.exports = Playwright
 
+function buildCustomLocatorString(locator) {
+  // Note: this.debug not available in standalone function, using console.log
+  console.log(`Building custom locator string: ${locator.type}=${locator.value}`)
+  return `${locator.type}=${locator.value}`
+}
+
 function buildLocatorString(locator) {
   if (locator.isCustom()) {
-    return `${locator.type}=${locator.value}`
+    return buildCustomLocatorString(locator)
   }
   if (locator.isXPath()) {
     return `xpath=${locator.value}`
@@ -3435,15 +3653,119 @@ async function findElements(matcher, locator) {
   if (locator.react) return findReact(matcher, locator)
   if (locator.vue) return findVue(matcher, locator)
   if (locator.pw) return findByPlaywrightLocator.call(this, matcher, locator)
+
   locator = new Locator(locator, 'css')
 
-  return matcher.locator(buildLocatorString(locator)).all()
+  // Handle custom locators directly instead of relying on Playwright selector engines
+  if (locator.isCustom()) {
+    return findCustomElements.call(this, matcher, locator)
+  }
+
+  // Check if we have a custom context locator and need to search within it
+  if (this.contextLocator) {
+    const contextLocatorObj = new Locator(this.contextLocator, 'css')
+    if (contextLocatorObj.isCustom()) {
+      // Find the context elements first
+      const contextElements = await findCustomElements.call(this, matcher, contextLocatorObj)
+      if (contextElements.length === 0) {
+        return []
+      }
+
+      // Search within the first context element
+      const locatorString = buildLocatorString(locator)
+      return contextElements[0].locator(locatorString).all()
+    }
+  }
+
+  const locatorString = buildLocatorString(locator)
+
+  return matcher.locator(locatorString).all()
+}
+
+async function findCustomElements(matcher, locator) {
+  const customLocatorStrategies = this.customLocatorStrategies || globalCustomLocatorStrategies
+  const strategyFunction = customLocatorStrategies.get ? customLocatorStrategies.get(locator.type) : customLocatorStrategies[locator.type]
+
+  if (!strategyFunction) {
+    throw new Error(`Custom locator strategy "${locator.type}" is not defined. Please define "customLocatorStrategies" in your configuration.`)
+  }
+
+  // Execute the custom locator function in the browser context using page.evaluate
+  const page = matcher.constructor.name === 'Page' ? matcher : await matcher.page()
+
+  const elements = await page.evaluate(
+    ({ strategyCode, selector }) => {
+      const strategy = new Function('return ' + strategyCode)()
+      const result = strategy(selector, document)
+
+      // Convert NodeList or single element to array
+      if (result && result.nodeType) {
+        return [result]
+      } else if (result && result.length !== undefined) {
+        return Array.from(result)
+      } else if (Array.isArray(result)) {
+        return result
+      }
+
+      return []
+    },
+    {
+      strategyCode: strategyFunction.toString(),
+      selector: locator.value,
+    },
+  )
+
+  // Convert the found elements back to Playwright locators
+  if (elements.length === 0) {
+    return []
+  }
+
+  // Create CSS selectors for the found elements and return as locators
+  const locators = []
+  const timestamp = Date.now()
+
+  for (let i = 0; i < elements.length; i++) {
+    // Use a unique attribute approach to target specific elements
+    const uniqueAttr = `data-codecept-custom-${timestamp}-${i}`
+
+    await page.evaluate(
+      ({ index, uniqueAttr, strategyCode, selector }) => {
+        // Re-execute the strategy to find elements and mark the specific one
+        const strategy = new Function('return ' + strategyCode)()
+        const result = strategy(selector, document)
+
+        let elementsArray = []
+        if (result && result.nodeType) {
+          elementsArray = [result]
+        } else if (result && result.length !== undefined) {
+          elementsArray = Array.from(result)
+        } else if (Array.isArray(result)) {
+          elementsArray = result
+        }
+
+        if (elementsArray[index]) {
+          elementsArray[index].setAttribute(uniqueAttr, 'true')
+        }
+      },
+      {
+        index: i,
+        uniqueAttr,
+        strategyCode: strategyFunction.toString(),
+        selector: locator.value,
+      },
+    )
+
+    locators.push(page.locator(`[${uniqueAttr}="true"]`))
+  }
+
+  return locators
 }
 
 async function findElement(matcher, locator) {
   if (locator.react) return findReact(matcher, locator)
   if (locator.vue) return findVue(matcher, locator)
   if (locator.pw) return findByPlaywrightLocator.call(this, matcher, locator)
+
   locator = new Locator(locator, 'css')
 
   return matcher.locator(buildLocatorString(locator)).first()
@@ -3764,9 +4086,7 @@ async function targetCreatedHandler(page) {
   if (this.options.windowSize && this.options.windowSize.indexOf('x') > 0 && this._getType() === 'Browser') {
     try {
       await page.setViewportSize(parseWindowSize(this.options.windowSize))
-    } catch (err) {
-      this.debug('Target can be already closed, ignoring...')
-    }
+    } catch (err) {}
   }
 }
 

package/lib/plugin/failedTestsTracker.js

@@ -0,0 +1,213 @@
+const fs = require('fs')
+const path = require('path')
+const event = require('../event')
+const output = require('../output')
+const store = require('../store')
+
+const defaultConfig = {
+  enabled: true,
+  outputFile: 'failed-tests.json',
+  clearOnSuccess: true,
+  includeStackTrace: true,
+  includeMetadata: true,
+}
+
+/**
+ * Failed Tests Tracker Plugin for CodeceptJS
+ *
+ * Tracks failed tests and saves them to a file for later re-execution.
+ * 
+ * ## Configuration
+ *
+ * ```js
+ * "plugins": {
+ *    "failedTestsTracker": {
+ *      "enabled": true,
+ *      "outputFile": "./failed-tests.json",
+ *      "clearOnSuccess": true,
+ *      "includeStackTrace": true,
+ *      "includeMetadata": true
+ *    }
+ * }
+ * ```
+ *
+ * @param {object} config plugin configuration
+ */
+module.exports = function (config) {
+  const options = { ...defaultConfig, ...config }
+  let failedTests = []
+  let allTestsPassed = true
+  let workerFailedTests = new Map() // Track failed tests from workers
+
+  // Track test failures
+  event.dispatcher.on(event.test.failed, test => {
+    allTestsPassed = false
+    
+    const failedTest = {
+      title: test.title,
+      fullTitle: test.fullTitle(),
+      file: test.file || (test.parent && test.parent.file),
+      uid: test.uid,
+      timestamp: new Date().toISOString(),
+    }
+
+    // Add parent suite information
+    if (test.parent) {
+      failedTest.suite = test.parent.title
+      failedTest.suiteFile = test.parent.file
+    }
+
+    // Add error information if available
+    if (test.err && options.includeStackTrace) {
+      failedTest.error = {
+        message: test.err.message || 'Test failed',
+        stack: test.err.stack || '',
+        name: test.err.name || 'Error',
+      }
+    }
+
+    // Add metadata if available
+    if (options.includeMetadata) {
+      failedTest.metadata = {
+        tags: test.tags || [],
+        meta: test.meta || {},
+        opts: test.opts || {},
+        duration: test.duration || 0,
+        retries: test.retries || 0,
+      }
+    }
+
+    // Add BDD/Gherkin information if available
+    if (test.parent && test.parent.feature) {
+      failedTest.bdd = {
+        feature: test.parent.feature.name || test.parent.title,
+        scenario: test.title,
+        featureFile: test.parent.file,
+      }
+    }
+
+    failedTests.push(failedTest)
+    output.print(`Failed Tests Tracker: Recorded failed test - ${test.title}`)
+  })
+
+  // Save failed tests to file after all tests complete
+  event.dispatcher.on(event.all.result, (result) => {
+    // Respect CodeceptJS output directory like other plugins
+    const outputDir = global.output_dir || './output'
+    const outputPath = path.isAbsolute(options.outputFile) 
+      ? options.outputFile 
+      : path.resolve(outputDir, options.outputFile)
+    let allFailedTests = [...failedTests]
+
+    // In worker mode, collect failed tests from consolidated result
+    if (store.hasWorkers && result && result.tests) {
+      const workerFailedTests = result.tests.filter(test => test.state === 'failed' || test.err)
+      
+      // Use a Set to track unique test identifiers to prevent duplicates
+      const existingTestIds = new Set(allFailedTests.map(test => test.uid || `${test.file}:${test.title}`))
+      
+      workerFailedTests.forEach(test => {
+        // Create unique identifier for deduplication
+        const testId = test.uid || `${test.file || 'unknown'}:${test.title}`
+        
+        // Skip if we already have this test
+        if (existingTestIds.has(testId)) {
+          return
+        }
+        
+        const failedTest = {
+          title: test.title,
+          fullTitle: test.fullTitle || test.title,
+          file: test.file || (test.parent && test.parent.file),
+          uid: test.uid,
+          timestamp: new Date().toISOString(),
+        }
+
+        // Add parent suite information
+        if (test.parent) {
+          failedTest.suite = test.parent.title
+          failedTest.suiteFile = test.parent.file
+        }
+
+        // Add error information if available
+        if (test.err && options.includeStackTrace) {
+          failedTest.error = {
+            message: test.err.message || 'Test failed',
+            stack: test.err.stack || '',
+            name: test.err.name || 'Error',
+          }
+        }
+
+        // Add metadata if available
+        if (options.includeMetadata) {
+          failedTest.metadata = {
+            tags: test.tags || [],
+            meta: test.meta || {},
+            opts: test.opts || {},
+            duration: test.duration || 0,
+            retries: test.retries || 0,
+          }
+        }
+
+        // Add BDD/Gherkin information if available
+        if (test.parent && test.parent.feature) {
+          failedTest.bdd = {
+            feature: test.parent.feature.name || test.parent.title,
+            scenario: test.title,
+            featureFile: test.parent.file,
+          }
+        }
+
+        allFailedTests.push(failedTest)
+        existingTestIds.add(testId)
+      })
+    }
+
+    if (allFailedTests.length === 0) {
+      if (options.clearOnSuccess && fs.existsSync(outputPath)) {
+        try {
+          fs.unlinkSync(outputPath)
+          output.print(`Failed Tests Tracker: Cleared previous failed tests file (all tests passed)`)
+        } catch (error) {
+          output.print(`Failed Tests Tracker: Could not clear failed tests file: ${error.message}`)
+        }
+      } else {
+        output.print(`Failed Tests Tracker: No failed tests to save`)
+      }
+      return
+    }
+
+    const failedTestsData = {
+      timestamp: new Date().toISOString(),
+      totalFailedTests: allFailedTests.length,
+      codeceptVersion: require('../codecept').version(),
+      tests: allFailedTests,
+    }
+
+    try {
+      // Ensure directory exists
+      const dir = path.dirname(outputPath)
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true })
+      }
+
+      fs.writeFileSync(outputPath, JSON.stringify(failedTestsData, null, 2))
+      output.print(`Failed Tests Tracker: Saved ${allFailedTests.length} failed tests to ${outputPath}`)
+    } catch (error) {
+      output.print(`Failed Tests Tracker: Failed to save failed tests: ${error.message}`)
+    }
+  })
+
+  // Reset state for new test runs
+  event.dispatcher.on(event.all.before, () => {
+    failedTests = []
+    allTestsPassed = true
+    workerFailedTests.clear()
+  })
+
+  // Handle worker mode - listen to workers.result event for consolidated results
+  event.dispatcher.on(event.workers.result, (result) => {
+    // This event is fired in worker mode with consolidated results
+    // The event.all.result handler above will process the consolidated data
+  })
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeceptjs",
-  "version": "3.7.5-beta.1",
+  "version": "3.7.5-beta.3",
   "description": "Supercharged End 2 End Testing Framework for NodeJS",
   "keywords": [
     "acceptance",

package/typings/promiseBasedTypes.d.ts

@@ -2733,8 +2733,11 @@ declare namespace CodeceptJS {
      * @property [highlightElement] - highlight the interacting elements. Default: false. Note: only activate under verbose mode (--verbose).
      * @property [recordHar] - record HAR and will be saved to `output/har`. See more of [HAR options](https://playwright.dev/docs/api/class-browser#browser-new-context-option-record-har).
      * @property [testIdAttribute = data-testid] - locate elements based on the testIdAttribute. See more of [locate by test id](https://playwright.dev/docs/locators#locate-by-test-id).
+     * @property [customLocatorStrategies] - custom locator strategies. An object with keys as strategy names and values as JavaScript functions. Example: `{ byRole: (selector, root) => { return root.querySelector(\`[role="\${selector}\"]\`) } }`
      */
     // @ts-ignore
+    // @ts-ignore
+    // @ts-ignore
     type PlaywrightConfig = {
         url?: string;
         browser?: 'chromium' | 'firefox' | 'webkit' | 'electron';
@@ -2772,6 +2775,7 @@ declare namespace CodeceptJS {
         highlightElement?: boolean;
         recordHar?: any;
         testIdAttribute?: string;
+        customLocatorStrategies?: any;
     };
     /**
      * Uses [Playwright](https://github.com/microsoft/playwright) library to run tests inside:
@@ -6112,6 +6116,8 @@ declare namespace CodeceptJS {
      * @property [highlightElement] - highlight the interacting elements. Default: false. Note: only activate under verbose mode (--verbose).
      */
     // @ts-ignore
+    // @ts-ignore
+    // @ts-ignore
     type PuppeteerConfig = {
         url: string;
         basicAuth?: any;
@@ -6535,17 +6541,6 @@ declare namespace CodeceptJS {
          * {{ react }}
          */
         _locate(): Promise<any>;
-        /**
-         * Get single element by different locator types, including strict locator
-         * Should be used in custom helpers:
-         *
-         * ```js
-         * const element = await this.helpers['Puppeteer']._locateElement({name: 'password'});
-         * ```
-         *
-         * {{ react }}
-         */
-        _locateElement(): Promise<any>;
         /**
          * Find a checkbox by providing human-readable text:
          * NOTE: Assumes the checkable element exists
@@ -6582,17 +6577,6 @@ declare namespace CodeceptJS {
          * @returns WebElement of being used Web helper
          */
         grabWebElements(locator: CodeceptJS.LocatorOrString): Promise<any>;
-        /**
-         * Grab WebElement for given locator
-         * Resumes test execution, so **should be used inside an async function with `await`** operator.
-         *
-         * ```js
-         * const webElement = await I.grabWebElement('#button');
-         * ```
-         * @param locator - element located by CSS|XPath|strict locator.
-         * @returns WebElement of being used Web helper
-         */
-        grabWebElement(locator: CodeceptJS.LocatorOrString): Promise<any>;
         /**
          * Switch focus to a particular tab by its number. It waits tabs loading and then switch tab
          *
@@ -7928,22 +7912,6 @@ declare namespace CodeceptJS {
          */
         flushWebSocketMessages(): Promise<any>;
     }
-    /**
-     * Find elements using Puppeteer's native element discovery methods
-     * Note: Unlike Playwright, Puppeteer's Locator API doesn't have .all() method for multiple elements
-     * @param matcher - Puppeteer context to search within
-     * @param locator - Locator specification
-     * @returns Array of ElementHandle objects
-     */
-    function findElements(matcher: any, locator: any | string): Promise<any[]>;
-    /**
-     * Find a single element using Puppeteer's native element discovery methods
-     * Note: Puppeteer Locator API doesn't have .first() method like Playwright
-     * @param matcher - Puppeteer context to search within
-     * @param locator - Locator specification
-     * @returns Single ElementHandle object
-     */
-    function findElement(matcher: any, locator: any | string): Promise<object>;
     /**
      * ## Configuration
      * @property [endpoint] - API base URL
@@ -7957,6 +7925,8 @@ declare namespace CodeceptJS {
      * @property [maxUploadFileSize] - set the max content file size in MB when performing api calls.
      */
     // @ts-ignore
+    // @ts-ignore
+    // @ts-ignore
     type RESTConfig = {
         endpoint?: string;
         prettyPrintJson?: boolean;
@@ -9103,6 +9073,8 @@ declare namespace CodeceptJS {
      * @property [logLevel = silent] - level of logging verbosity. Default: silent. Options: trace | debug | info | warn | error | silent. More info: https://webdriver.io/docs/configuration/#loglevel
      */
     // @ts-ignore
+    // @ts-ignore
+    // @ts-ignore
     type WebDriverConfig = {
         url: string;
         browser: string;
@@ -9573,17 +9545,6 @@ declare namespace CodeceptJS {
          * @returns WebElement of being used Web helper
          */
         grabWebElements(locator: CodeceptJS.LocatorOrString): Promise<any>;
-        /**
-         * Grab WebElement for given locator
-         * Resumes test execution, so **should be used inside an async function with `await`** operator.
-         *
-         * ```js
-         * const webElement = await I.grabWebElement('#button');
-         * ```
-         * @param locator - element located by CSS|XPath|strict locator.
-         * @returns WebElement of being used Web helper
-         */
-        grabWebElement(locator: CodeceptJS.LocatorOrString): Promise<any>;
         /**
          * Set [WebDriver timeouts](https://webdriver.io/docs/timeouts.html) in realtime.
          *

package/typings/types.d.ts

@@ -2823,8 +2823,11 @@ declare namespace CodeceptJS {
      * @property [highlightElement] - highlight the interacting elements. Default: false. Note: only activate under verbose mode (--verbose).
      * @property [recordHar] - record HAR and will be saved to `output/har`. See more of [HAR options](https://playwright.dev/docs/api/class-browser#browser-new-context-option-record-har).
      * @property [testIdAttribute = data-testid] - locate elements based on the testIdAttribute. See more of [locate by test id](https://playwright.dev/docs/locators#locate-by-test-id).
+     * @property [customLocatorStrategies] - custom locator strategies. An object with keys as strategy names and values as JavaScript functions. Example: `{ byRole: (selector, root) => { return root.querySelector(\`[role="\${selector}\"]\`) } }`
      */
     // @ts-ignore
+    // @ts-ignore
+    // @ts-ignore
     type PlaywrightConfig = {
         url?: string;
         browser?: 'chromium' | 'firefox' | 'webkit' | 'electron';
@@ -2862,6 +2865,7 @@ declare namespace CodeceptJS {
         highlightElement?: boolean;
         recordHar?: any;
         testIdAttribute?: string;
+        customLocatorStrategies?: any;
     };
     /**
      * Uses [Playwright](https://github.com/microsoft/playwright) library to run tests inside:
@@ -6353,6 +6357,8 @@ declare namespace CodeceptJS {
      * @property [highlightElement] - highlight the interacting elements. Default: false. Note: only activate under verbose mode (--verbose).
      */
     // @ts-ignore
+    // @ts-ignore
+    // @ts-ignore
     type PuppeteerConfig = {
         url: string;
         basicAuth?: any;
@@ -6792,17 +6798,6 @@ declare namespace CodeceptJS {
          * {{ react }}
          */
         _locate(): void;
-        /**
-         * Get single element by different locator types, including strict locator
-         * Should be used in custom helpers:
-         *
-         * ```js
-         * const element = await this.helpers['Puppeteer']._locateElement({name: 'password'});
-         * ```
-         *
-         * {{ react }}
-         */
-        _locateElement(): void;
         /**
          * Find a checkbox by providing human-readable text:
          * NOTE: Assumes the checkable element exists
@@ -6839,17 +6834,6 @@ declare namespace CodeceptJS {
          * @returns WebElement of being used Web helper
          */
         grabWebElements(locator: CodeceptJS.LocatorOrString): Promise<any>;
-        /**
-         * Grab WebElement for given locator
-         * Resumes test execution, so **should be used inside an async function with `await`** operator.
-         *
-         * ```js
-         * const webElement = await I.grabWebElement('#button');
-         * ```
-         * @param locator - element located by CSS|XPath|strict locator.
-         * @returns WebElement of being used Web helper
-         */
-        grabWebElement(locator: CodeceptJS.LocatorOrString): Promise<any>;
         /**
          * Switch focus to a particular tab by its number. It waits tabs loading and then switch tab
          *
@@ -8305,22 +8289,6 @@ declare namespace CodeceptJS {
          */
         flushWebSocketMessages(): void;
     }
-    /**
-     * Find elements using Puppeteer's native element discovery methods
-     * Note: Unlike Playwright, Puppeteer's Locator API doesn't have .all() method for multiple elements
-     * @param matcher - Puppeteer context to search within
-     * @param locator - Locator specification
-     * @returns Array of ElementHandle objects
-     */
-    function findElements(matcher: any, locator: any | string): Promise<any[]>;
-    /**
-     * Find a single element using Puppeteer's native element discovery methods
-     * Note: Puppeteer Locator API doesn't have .first() method like Playwright
-     * @param matcher - Puppeteer context to search within
-     * @param locator - Locator specification
-     * @returns Single ElementHandle object
-     */
-    function findElement(matcher: any, locator: any | string): Promise<object>;
     /**
      * ## Configuration
      * @property [endpoint] - API base URL
@@ -8334,6 +8302,8 @@ declare namespace CodeceptJS {
      * @property [maxUploadFileSize] - set the max content file size in MB when performing api calls.
      */
     // @ts-ignore
+    // @ts-ignore
+    // @ts-ignore
     type RESTConfig = {
         endpoint?: string;
         prettyPrintJson?: boolean;
@@ -9540,6 +9510,8 @@ declare namespace CodeceptJS {
      * @property [logLevel = silent] - level of logging verbosity. Default: silent. Options: trace | debug | info | warn | error | silent. More info: https://webdriver.io/docs/configuration/#loglevel
      */
     // @ts-ignore
+    // @ts-ignore
+    // @ts-ignore
     type WebDriverConfig = {
         url: string;
         browser: string;
@@ -10010,17 +9982,6 @@ declare namespace CodeceptJS {
          * @returns WebElement of being used Web helper
          */
         grabWebElements(locator: CodeceptJS.LocatorOrString): Promise<any>;
-        /**
-         * Grab WebElement for given locator
-         * Resumes test execution, so **should be used inside an async function with `await`** operator.
-         *
-         * ```js
-         * const webElement = await I.grabWebElement('#button');
-         * ```
-         * @param locator - element located by CSS|XPath|strict locator.
-         * @returns WebElement of being used Web helper
-         */
-        grabWebElement(locator: CodeceptJS.LocatorOrString): Promise<any>;
         /**
          * Set [WebDriver timeouts](https://webdriver.io/docs/timeouts.html) in realtime.
          *
@@ -11565,13 +11526,6 @@ declare namespace CodeceptJS {
          * Loads tests by pattern or by config.tests
          */
         loadTests(pattern?: string): void;
-        /**
-         * Apply sharding to test files based on shard configuration
-         * @param testFiles - Array of test file paths
-         * @param shardConfig - Shard configuration in format "index/total" (e.g., "1/4")
-         * @returns - Filtered array of test files for this shard
-         */
-        _applySharding(testFiles: string[], shardConfig: string): string[];
         /**
          * Run a specific test or all loaded tests.
          */
@@ -12065,10 +12019,6 @@ declare namespace CodeceptJS {
          * Get a state of current queue and tasks
          */
         toString(): string;
-        /**
-         * Get current session ID
-         */
-        getCurrentSessionId(): string | null;
     }
     interface RecorderSession {
         running: boolean;