synchronized with docs

Author: kobenguyent

docs/WebElement.md

@@ -0,0 +1,251 @@
+# WebElement API
+
+The WebElement class provides a unified interface for interacting with elements across different CodeceptJS helpers (Playwright, WebDriver, Puppeteer). It wraps native element instances and provides consistent methods regardless of the underlying helper.
+
+## Basic Usage
+
+```javascript
+// Get WebElement instances from any helper
+const element = await I.grabWebElement('#button')
+const elements = await I.grabWebElements('.items')
+
+// Use consistent API across all helpers
+const text = await element.getText()
+const isVisible = await element.isVisible()
+await element.click()
+await element.type('Hello World')
+
+// Find child elements
+const childElement = await element.$('.child-selector')
+const childElements = await element.$$('.child-items')
+```
+
+## API Methods
+
+### Element Properties
+
+#### `getText()`
+
+Get the text content of the element.
+
+```javascript
+const text = await element.getText()
+console.log(text) // "Button Text"
+```
+
+#### `getAttribute(name)`
+
+Get the value of a specific attribute.
+
+```javascript
+const id = await element.getAttribute('id')
+const className = await element.getAttribute('class')
+```
+
+#### `getProperty(name)`
+
+Get the value of a JavaScript property.
+
+```javascript
+const value = await element.getProperty('value')
+const checked = await element.getProperty('checked')
+```
+
+#### `getInnerHTML()`
+
+Get the inner HTML content of the element.
+
+```javascript
+const html = await element.getInnerHTML()
+console.log(html) // "<span>Content</span>"
+```
+
+#### `getValue()`
+
+Get the value of input elements.
+
+```javascript
+const inputValue = await element.getValue()
+```
+
+### Element State
+
+#### `isVisible()`
+
+Check if the element is visible.
+
+```javascript
+const visible = await element.isVisible()
+if (visible) {
+  console.log('Element is visible')
+}
+```
+
+#### `isEnabled()`
+
+Check if the element is enabled (not disabled).
+
+```javascript
+const enabled = await element.isEnabled()
+if (enabled) {
+  await element.click()
+}
+```
+
+#### `exists()`
+
+Check if the element exists in the DOM.
+
+```javascript
+const exists = await element.exists()
+if (exists) {
+  console.log('Element exists')
+}
+```
+
+#### `getBoundingBox()`
+
+Get the element's bounding box (position and size).
+
+```javascript
+const box = await element.getBoundingBox()
+console.log(box) // { x: 100, y: 200, width: 150, height: 50 }
+```
+
+### Element Interactions
+
+#### `click(options)`
+
+Click the element.
+
+```javascript
+await element.click()
+// With options (Playwright/Puppeteer)
+await element.click({ button: 'right' })
+```
+
+#### `type(text, options)`
+
+Type text into the element.
+
+```javascript
+await element.type('Hello World')
+// With options (Playwright/Puppeteer)
+await element.type('Hello', { delay: 100 })
+```
+
+### Child Element Search
+
+#### `$(locator)`
+
+Find the first child element matching the locator.
+
+```javascript
+const childElement = await element.$('.child-class')
+if (childElement) {
+  await childElement.click()
+}
+```
+
+#### `$$(locator)`
+
+Find all child elements matching the locator.
+
+```javascript
+const childElements = await element.$$('.child-items')
+for (const child of childElements) {
+  const text = await child.getText()
+  console.log(text)
+}
+```
+
+### Native Access
+
+#### `getNativeElement()`
+
+Get the original native element instance.
+
+```javascript
+const nativeElement = element.getNativeElement()
+// For Playwright: ElementHandle
+// For WebDriver: WebElement
+// For Puppeteer: ElementHandle
+```
+
+#### `getHelper()`
+
+Get the helper instance that created this WebElement.
+
+```javascript
+const helper = element.getHelper()
+console.log(helper.constructor.name) // "Playwright", "WebDriver", or "Puppeteer"
+```
+
+## Locator Support
+
+The `$()` and `$$()` methods support various locator formats:
+
+```javascript
+// CSS selectors
+await element.$('.class-name')
+await element.$('#element-id')
+
+// CodeceptJS locator objects
+await element.$({ css: '.my-class' })
+await element.$({ xpath: '//div[@class="test"]' })
+await element.$({ id: 'element-id' })
+await element.$({ name: 'field-name' })
+await element.$({ className: 'my-class' })
+```
+
+## Cross-Helper Compatibility
+
+The same WebElement code works across all supported helpers:
+
+```javascript
+// This code works identically with Playwright, WebDriver, and Puppeteer
+const loginForm = await I.grabWebElement('#login-form')
+const usernameField = await loginForm.$('[name="username"]')
+const passwordField = await loginForm.$('[name="password"]')
+const submitButton = await loginForm.$('button[type="submit"]')
+
+await usernameField.type('user@example.com')
+await passwordField.type('password123')
+await submitButton.click()
+```
+
+## Migration from Native Elements
+
+If you were previously using native elements, you can gradually migrate:
+
+```javascript
+// Old way - helper-specific
+const nativeElements = await I.grabWebElements('.items')
+// Different API for each helper
+
+// New way - unified
+const webElements = await I.grabWebElements('.items')
+// Same API across all helpers
+
+// Backward compatibility
+const nativeElement = webElements[0].getNativeElement()
+// Use native methods if needed
+```
+
+## Error Handling
+
+WebElement methods will throw appropriate errors when operations fail:
+
+```javascript
+try {
+  const element = await I.grabWebElement('#nonexistent')
+} catch (error) {
+  console.log('Element not found')
+}
+
+try {
+  await element.click()
+} catch (error) {
+  console.log('Click failed:', error.message)
+}
+```

docs/basics.md

@@ -961,6 +961,29 @@ Like in Mocha you can use `x` and `only` to skip tests or to run a single test.
 - `Scenario.only` - executes only the current test
 - `xFeature` - skips current suite <Badge text="Since 2.6.6" type="warning"/>
 - `Feature.skip` - skips the current suite <Badge text="Since 2.6.6" type="warning"/>
+- `Feature.only` - executes only the current suite <Badge text="Since 3.7.5" type="warning"/>
+
+When using `Feature.only`, only scenarios within that feature will be executed:
+
+```js
+Feature.only('My Important Feature')
+
+Scenario('test something', ({ I }) => {
+  I.amOnPage('https://github.com')
+  I.see('GitHub')
+})
+
+Scenario('test something else', ({ I }) => {
+  I.amOnPage('https://github.com')
+  I.see('GitHub')
+})
+
+Feature('Another Feature') // This will be skipped
+
+Scenario('will not run', ({ I }) => {
+  // This scenario will be skipped
+})
+```
 
 ## Todo Test
 

docs/build/JSONResponse.js

@@ -72,10 +72,11 @@ class JSONResponse extends Helper {
     if (!this.helpers[this.options.requestHelper]) {
       throw new Error(`Error setting JSONResponse, helper ${this.options.requestHelper} is not enabled in config, helpers: ${Object.keys(this.helpers)}`)
     }
-    // connect to REST helper
+    const origOnResponse = this.helpers[this.options.requestHelper].config.onResponse;
     this.helpers[this.options.requestHelper].config.onResponse = response => {
-      this.response = response
-    }
+      this.response = response;
+      if (typeof origOnResponse === 'function') origOnResponse(response);
+    };
   }
 
   _before() {
@@ -349,7 +350,25 @@ class JSONResponse extends Helper {
     for (const key in expected) {
       assert(key in actual, `Key "${key}" not found in ${JSON.stringify(actual)}`)
       if (typeof expected[key] === 'object' && expected[key] !== null) {
-        this._assertContains(actual[key], expected[key])
+        if (Array.isArray(expected[key])) {
+          // Handle array comparison: each expected element should have a match in actual array
+          assert(Array.isArray(actual[key]), `Expected array for key "${key}", but got ${typeof actual[key]}`)
+          for (const expectedItem of expected[key]) {
+            let found = false
+            for (const actualItem of actual[key]) {
+              try {
+                this._assertContains(actualItem, expectedItem)
+                found = true
+                break
+              } catch (err) {
+                continue
+              }
+            }
+            assert(found, `No matching element found in array for ${JSON.stringify(expectedItem)}`)
+          }
+        } else {
+          this._assertContains(actual[key], expected[key])
+        }
       } else {
         assert.deepStrictEqual(actual[key], expected[key], `Values for key "${key}" don't match`)
       }

docs/build/Mochawesome.js

@@ -37,7 +37,20 @@ class Mochawesome extends Helper {
   }
 
   _test(test) {
-    currentTest = { test }
+    // If this is a retried test, we want to add context to the retried test
+    // but also potentially preserve context from the original test
+    const originalTest = test.retriedTest && test.retriedTest()
+    if (originalTest) {
+      // This is a retried test - use the retried test for context
+      currentTest = { test }
+
+      // Optionally copy context from original test if it exists
+      // Note: mochawesome context is stored in test.ctx, but we need to be careful
+      // not to break the mocha context structure
+    } else {
+      // Normal test (not a retry)
+      currentTest = { test }
+    }
   }
 
   _failed(test) {
@@ -64,7 +77,16 @@ class Mochawesome extends Helper {
 
   addMochawesomeContext(context) {
     if (currentTest === '') currentTest = { test: currentSuite.ctx.test }
-    return this._addContext(currentTest, context)
+
+    // For retried tests, make sure we're adding context to the current (retried) test
+    // not the original test
+    let targetTest = currentTest
+    if (currentTest.test && currentTest.test.retriedTest && currentTest.test.retriedTest()) {
+      // This test has been retried, make sure we're using the current test for context
+      targetTest = { test: currentTest.test }
+    }
+
+    return this._addContext(targetTest, context)
   }
 }