Merge branch '4.x' into 4.x-docs-update

Author: DavertMik

bin/mcp-server.js

@@ -12,7 +12,8 @@ import path from 'path'
 import crypto from 'crypto'
 import { spawn } from 'child_process'
 import { createRequire } from 'module'
-import { existsSync, readdirSync } from 'fs'
+import { existsSync, readdirSync, writeFileSync } from 'fs'
+import { mkdirp } from 'mkdirp'
 
 const require = createRequire(import.meta.url)
 
@@ -439,12 +440,38 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const helper = Object.values(helpers)[0]
             if (helper) {
               try {
-                if (helper.grabAriaSnapshot) result.artifacts.aria = await helper.grabAriaSnapshot()
-                if (helper.grabCurrentUrl) result.artifacts.url = await helper.grabCurrentUrl()
-                if (helper.grabBrowserLogs) result.artifacts.consoleLogs = (await helper.grabBrowserLogs()) || []
+                const traceDir = getTraceDir('mcp', 'run_code')
+                mkdirp.sync(traceDir)
+
+                if (helper.grabAriaSnapshot) {
+                  const aria = await helper.grabAriaSnapshot()
+                  const ariaFile = path.join(traceDir, 'aria.txt')
+                  writeFileSync(ariaFile, aria)
+                  result.artifacts.aria = `file://${ariaFile}`
+                }
+
+                if (helper.grabCurrentUrl) {
+                  result.artifacts.url = await helper.grabCurrentUrl()
+                }
+
+                if (helper.grabBrowserLogs) {
+                  const logs = (await helper.grabBrowserLogs()) || []
+                  const logsFile = path.join(traceDir, 'console.json')
+                  writeFileSync(logsFile, JSON.stringify(logs, null, 2))
+                  result.artifacts.consoleLogs = `file://${logsFile}`
+                }
+
                 if (helper.grabSource) {
                   const html = await helper.grabSource()
-                  result.artifacts.html = html.substring(0, 10000) + '...'
+                  const htmlFile = path.join(traceDir, 'page.html')
+                  writeFileSync(htmlFile, html)
+                  result.artifacts.html = `file://${htmlFile}`
+                }
+
+                if (helper.saveScreenshot) {
+                  const screenshotFile = path.join(traceDir, 'screenshot.png')
+                  await helper.saveScreenshot(screenshotFile)
+                  result.artifacts.screenshot = `file://${screenshotFile}`
                 }
               } catch (e) {
                 result.output += ` (Warning: ${e.message})`

docs/data.md

@@ -18,7 +18,11 @@ The most efficient way would be to allow test to control its data, i.e. the 3rd
 However, accessing database directly is not a good idea as database vendor, schema and data are used by application internally and are out of scope of acceptance test.
 
 Today all modern web applications have REST or GraphQL API . So it is a good idea to use it to create data for a test and delete it after.
-API is supposed to be a stable interface and it can be used by acceptance tests. CodeceptJS provides 4 helpers for Data Management via REST and GraphQL API.
+API is supposed to be a stable interface and it can be used by acceptance tests. CodeceptJS provides helpers for Data Management via REST and GraphQL API, as well as **[Data Objects](/pageobjects#data-objects)** — class-based page objects with automatic cleanup via lifecycle hooks.
+
+## Data Objects
+
+For a lightweight, class-based approach to managing test data, see **[Data Objects](/pageobjects#data-objects)** in the Page Objects documentation. Data Objects let you create page object classes that manage API data with automatic cleanup via the `_after()` hook — no factory configuration needed.
 
 ## REST
 

docs/element-based-testing.md

@@ -0,0 +1,295 @@
+# Element-Based Testing
+
+CodeceptJS offers multiple ways to write tests. While the traditional `I.*` actions provide a clean, readable syntax, element-based testing gives you more control and flexibility when working with complex DOM structures.
+
+## Why Element-Based Testing?
+
+Element-based testing is useful when:
+
+- **You need direct access to DOM properties** - Inspect attributes, computed styles, or form values
+- **Working with lists and collections** - Iterate over multiple elements with custom logic
+- **Complex assertions** - Validate conditions that built-in methods don't cover
+- **Performance optimization** - Reduce redundant lookups by reusing element references
+- **Custom interactions** - Perform actions not available in standard helper methods
+
+## The CodeceptJS Hybrid Approach
+
+CodeceptJS uniquely combines both styles. You can freely mix `I.*` actions with element-based operations in the same test:
+
+```js
+// Import element functions
+import { element, eachElement, expectElement } from 'codeceptjs/els'
+
+Scenario('checkout flow', async ({ I }) => {
+  // Use I.* for navigation and high-level actions
+  I.amOnPage('/products')
+  I.click('Add to Cart')
+
+  // Use element-based for detailed validation
+  await element('.cart-summary', async cart => {
+    const total = await cart.getAttribute('data-total')
+    console.log('Cart total:', total)
+  })
+
+  // Continue with I.* actions
+  I.click('Checkout')
+})
+```
+
+This hybrid approach gives you the best of both worlds - readable high-level actions mixed with low-level control when needed.
+
+## Quick Comparison
+
+### Traditional I.* Approach
+
+```js
+Scenario('form validation', async ({ I }) => {
+  I.amOnPage('/register')
+  I.fillField('Email', 'test@example.com')
+  I.fillField('Password', 'secret123')
+  I.click('Register')
+  I.see('Welcome')
+})
+```
+
+### Element-Based Approach
+
+```js
+import { element, expectElement } from 'codeceptjs/els'
+
+Scenario('form validation', async ({ I }) => {
+  I.amOnPage('/register')
+
+  // Direct form manipulation
+  await element('#email', async input => {
+    await input.type('test@example.com')
+  })
+
+  await element('#password', async input => {
+    await input.type('secret123')
+  })
+
+  await element('button[type="submit"]', async btn => {
+    await btn.click()
+  })
+
+  // Custom assertion
+  await expectElement('.welcome-message', async msg => {
+    const text = await msg.getText()
+    return text.includes('Welcome')
+  })
+})
+```
+
+### When to Use Each
+
+| Use `I.*` actions when... | Use element-based when... |
+|---------------------------|---------------------------|
+| Simple navigation and clicks | Complex DOM traversal |
+| Standard form interactions | Custom validation logic |
+| Built-in assertions suffice | Need specific element properties |
+| Readability is priority | Working with element collections |
+| Single-step operations | Chaining multiple operations on same element |
+
+## Element Chaining
+
+Element-based testing allows you to chain queries to find child elements, reducing redundant lookups:
+
+```js
+import { element } from 'codeceptjs/els'
+
+Scenario('product list', async ({ I }) => {
+  I.amOnPage('/products')
+
+  // Chain into child elements
+  await element('.product-list', async list => {
+    const firstProduct = await list.$('.product-item')
+    const title = await firstProduct.$('.title')
+    const price = await firstProduct.$('.price')
+
+    const titleText = await title.getText()
+    const priceValue = await price.getText()
+
+    console.log(`${titleText}: ${priceValue}`)
+  })
+})
+```
+
+## Real-World Examples
+
+### Example 1: Form Validation
+
+Validate complex form requirements that built-in methods don't cover:
+
+```js
+import { element, eachElement } from 'codeceptjs/els'
+import { expect } from 'chai'
+
+Scenario('validate form fields', async ({ I }) => {
+  I.amOnPage('/register')
+
+  // Check all required fields are properly marked
+  await eachElement('[required]', async field => {
+    const ariaRequired = await field.getAttribute('aria-required')
+    const required = await field.getAttribute('required')
+    if (!ariaRequired && !required) {
+      throw new Error('Required field missing indicators')
+    }
+  })
+
+  // Fill form with custom validation
+  await element('#email', async input => {
+    await input.type('test@example.com')
+    const value = await input.getValue()
+    expect(value).to.include('@')
+  })
+
+  I.click('Submit')
+})
+```
+
+### Example 2: Data Table Processing
+
+Work with tabular data using iteration and child element queries:
+
+```js
+import { eachElement, element } from 'codeceptjs/els'
+
+Scenario('verify table data', async ({ I }) => {
+  I.amOnPage('/dashboard')
+
+  // Get table row count
+  await element('table tbody', async tbody => {
+    const rows = await tbody.$$('tr')
+    console.log(`Table has ${rows.length} rows`)
+  })
+
+  // Verify each row has expected structure
+  await eachElement('table tbody tr', async (row, index) => {
+    const cells = await row.$$('td')
+    if (cells.length < 3) {
+      throw new Error(`Row ${index} should have at least 3 columns`)
+    }
+  })
+})
+```
+
+### Example 3: Dynamic Content Waiting
+
+Wait for and validate dynamic content with custom conditions:
+
+```js
+import { element, expectElement } from 'codeceptjs/els'
+
+Scenario('wait for dynamic content', async ({ I }) => {
+  I.amOnPage('/search')
+  I.fillField('query', 'test')
+  I.click('Search')
+
+  // Wait for results with custom validation
+  await expectElement('.search-results', async results => {
+    const items = await results.$$('.result-item')
+    return items.length > 0
+  })
+})
+```
+
+### Example 4: Shopping Cart Operations
+
+Calculate and verify cart totals by iterating through items:
+
+```js
+import { element, eachElement } from 'codeceptjs/els'
+import { expect } from 'chai'
+
+Scenario('calculate cart total', async ({ I }) => {
+  I.amOnPage('/cart')
+
+  let total = 0
+
+  // Sum up all item prices
+  await eachElement('.cart-item .price', async priceEl => {
+    const priceText = await priceEl.getText()
+    const price = parseFloat(priceText.replace('$', ''))
+    total += price
+  })
+
+  // Verify displayed total matches calculated sum
+  await element('.cart-total', async totalEl => {
+    const displayedTotal = await totalEl.getText()
+    const displayedValue = parseFloat(displayedTotal.replace('$', ''))
+    expect(displayedValue).to.equal(total)
+  })
+})
+```
+
+### Example 5: List Filtering and Validation
+
+Validate filtered results meet specific criteria:
+
+```js
+import { element, eachElement, expectAnyElement } from 'codeceptjs/els'
+import { expect } from 'chai'
+
+Scenario('filter products by price', async ({ I }) => {
+  I.amOnPage('/products')
+  I.click('Under $100')
+
+  // Verify all displayed products are under $100
+  await eachElement('.product-item', async product => {
+    const priceEl = await product.$('.price')
+    const priceText = await priceEl.getText()
+    const price = parseFloat(priceText.replace('$', ''))
+    expect(price).to.be.below(100)
+  })
+
+  // Check at least one product exists
+  await expectAnyElement('.product-item', async () => true)
+})
+```
+
+## Best Practices
+
+1. **Mix styles appropriately** - Use `I.*` for navigation and high-level actions, element-based for complex validation
+
+2. **Use descriptive purposes** - Add purpose strings for better debugging logs:
+   ```js
+   await element(
+     'verify discount applied',
+     '.price',
+     async el => { /* ... */ }
+   )
+   ```
+
+3. **Reuse element references** - Chain `$(locator)` to avoid redundant lookups
+
+4. **Handle empty results** - Always check if elements exist before accessing properties
+
+5. **Prefer standard assertions** - Use `I.see()`, `I.dontSee()` when possible for readability
+
+6. **Consider page objects** - Combine with Page Objects for reusable element logic
+
+## API Reference
+
+- **[Element Access](els.md)** - Complete reference for `element()`, `eachElement()`, `expectElement()`, `expectAnyElement()`, `expectAllElements()` functions
+- **[WebElement API](WebElement.md)** - Complete reference for WebElement class methods (`getText()`, `getAttribute()`, `click()`, `$$()`, etc.)
+
+## Portability
+
+Elements are wrapped in a `WebElement` class that provides a consistent API across all helpers (Playwright, WebDriver, Puppeteer). Your element-based tests will work the same way regardless of which helper you're using:
+
+```js
+// This test works identically with Playwright, WebDriver, or Puppeteer
+import { element } from 'codeceptjs/els'
+
+Scenario('portable test', async ({ I }) => {
+  I.amOnPage('/')
+
+  await element('.main-title', async title => {
+    const text = await title.getText()        // Works on all helpers
+    const className = await title.getAttribute('class')
+    const visible = await title.isVisible()
+    const enabled = await title.isEnabled()
+  })
+})
+```