codeceptjs 4.0.0-rc.18 → 4.0.0-rc.19

package/docs/effects.md

@@ -0,0 +1,179 @@
+---
+permalink: /effects
+title: Effects
+---
+
+# Effects
+
+Effects are functions that can modify scenario flow. They provide ways to handle conditional steps, retries, scoped contexts, and test flow control.
+
+## Installation
+
+Effects can be imported directly from CodeceptJS:
+
+```js
+import { tryTo, retryTo, hopeThat, within } from 'codeceptjs/effects'
+```
+
+> 📝 Note: Prior to v4, `tryTo` and `retryTo` were enabled via plugins (`tryTo`, `retryTo`) that registered them as globals. Those plugins are removed in v4 — import effects from `codeceptjs/effects` instead.
+
+## tryTo
+
+The `tryTo` effect allows you to attempt steps that may fail without stopping test execution. It's useful for handling optional steps or conditions that aren't critical for the test flow.
+
+```js
+import { tryTo } from 'codeceptjs/effects'
+
+// inside a test
+const success = await tryTo(() => {
+  // These steps may fail but won't stop the test
+  I.see('Cookie banner')
+  I.click('Accept cookies')
+})
+
+if (!success) {
+  I.say('Cookie banner was not found')
+}
+```
+
+If the steps inside `tryTo` fail:
+
+- The test will continue execution
+- The failure will be logged in debug output
+- `tryTo` returns `false`
+- Auto-retries are disabled inside `tryTo` blocks
+
+## hopeThat
+
+`hopeThat` is the soft-assertion effect. It wraps a block of steps; if any step inside fails, the failure is recorded as a note on the test and `hopeThat` returns `false`, but the scenario keeps running. Call `hopeThat.noErrors()` once at the end to fail the scenario if any soft assertion failed.
+
+```js
+import { hopeThat } from 'codeceptjs/effects'
+
+Scenario('form shows every validation error', ({ I }) => {
+  I.amOnPage('/signup')
+  I.click('Submit')
+
+  await hopeThat(() => I.see('Email is required', '#email-error'))
+  await hopeThat(() => I.see('Password is required', '#password-error'))
+  await hopeThat(() => I.see('You must accept the terms', '#terms-error'))
+
+  hopeThat.noErrors()  // throws once, listing every recorded failure
+})
+```
+
+`hopeThat` returns `Promise<boolean>` — `true` on success, `false` on caught failure — which is handy for branching:
+
+```js
+const cookieAccepted = await hopeThat(() => I.click('Accept cookies'))
+if (!cookieAccepted) I.say('No cookie banner')
+```
+
+> 💡 In 3.x, soft assertions were provided by `SoftExpectHelper` (`I.softAssert`, `I.softExpectEqual`, `I.flushSoftAssertions`). That helper is gone in 4.x — use `hopeThat()` and `hopeThat.noErrors()` instead. `hopeThat` works with **any** assertion you can write inside a step: built-in `I.see*`, custom-helper assertions, `expect()` from your own assertion library, plain `assert` from Node — anything that throws on failure.
+
+The same `hopeThat` is also re-exported from `codeceptjs/assertions` if you prefer that subpath:
+
+```js
+import { hopeThat } from 'codeceptjs/assertions'
+```
+
+## retryTo
+
+The `retryTo` effect allows you to retry a set of steps multiple times until they succeed. This is useful for handling flaky elements or conditions that may need multiple attempts.
+
+```js
+import { retryTo } from 'codeceptjs/effects'
+
+// Retry up to 5 times with 200ms between attempts
+await retryTo(() => {
+  I.switchTo('#editor-frame')
+  I.fillField('textarea', 'Hello world')
+}, 5)
+```
+
+Parameters:
+
+- `callback` - Function containing steps to retry
+- `maxTries` - Maximum number of retry attempts
+- `pollInterval` - (optional) Delay between retries in milliseconds (default: 200ms)
+
+The callback receives the current retry count as an argument:
+
+```js
+import { retryTo } from 'codeceptjs/effects'
+
+// inside a test...
+await retryTo(tries => {
+  I.say(`Attempt ${tries}`)
+  I.click('Submit')
+  I.see('Success')
+}, 3)
+```
+
+## within
+
+The `within` effect scopes all actions inside it to a specific element on the page — useful when working with repeated UI components or narrowing interaction to a specific section.
+
+```js
+import { within } from 'codeceptjs/effects'
+
+// inside a test...
+await within('.js-signup-form', () => {
+  I.fillField('user[login]', 'User')
+  I.fillField('user[email]', 'user@user.com')
+  I.fillField('user[password]', 'user@user.com')
+  I.click('button')
+})
+I.see('There were problems creating your account.')
+```
+
+> ⚠ `within` can cause problems when used incorrectly. If you see unexpected behavior, refactor to use the context parameter on individual actions instead (e.g. `I.click('Login', '.nav')`). Keep `within` for the simplest cases.
+
+> ⚠ Since `within` returns a Promise, always `await` it when you need its return value.
+
+### IFrames
+
+Use a `frame` locator to scope actions inside an iframe:
+
+```js
+await within({ frame: '#editor' }, () => {
+  I.see('Page')
+  I.fillField('Body', 'Hello world')
+})
+```
+
+Nested iframes _(WebDriver & Puppeteer only)_:
+
+```js
+await within({ frame: ['.content', '#editor'] }, () => {
+  I.see('Page')
+})
+```
+
+> ℹ IFrames can also be accessed via `I.switchTo` command.
+
+### Returning Values
+
+`within` can return a value for use in the scenario:
+
+```js
+const val = await within('#sidebar', () => {
+  return I.grabTextFrom({ css: 'h1' })
+})
+I.fillField('Description', val)
+```
+
+When running steps inside a `within` block, they will be shown indented in the output.
+
+## Usage with TypeScript
+
+Effects are fully typed and work well with TypeScript:
+
+```ts
+import { tryTo, retryTo, within } from 'codeceptjs/effects'
+
+const success = await tryTo(async () => {
+  await I.see('Element')
+})
+```
+

package/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](web-element.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()
+  })
+})
+```

package/docs/element-selection.md

@@ -0,0 +1,125 @@
+---
+permalink: /element-selection
+title: Element Selection
+---
+
+# Element Selection
+
+When you write `I.click('a')` and there are multiple links on a page, CodeceptJS clicks the **first** one it finds. Most of the time this is exactly what you need — your locators are specific enough that there's only one match, or the first match happens to be the right one.
+
+But what happens when it's not?
+
+## Picking a Specific Element
+
+Say you have a list of items and you want to click the second one. You could write a more specific CSS selector, but sometimes the simplest approach is to tell CodeceptJS which element you want by position:
+
+```js
+import step from 'codeceptjs/steps'
+
+// click the 2nd link
+I.click('a', step.opts({ elementIndex: 2 }))
+
+// click the last link
+I.click('a', step.opts({ elementIndex: 'last' }))
+
+// fill the last matching input
+I.fillField('.email-input', 'test@example.com', step.opts({ elementIndex: -1 }))
+```
+
+The `elementIndex` option accepts:
+
+* **Positive numbers** (1-based) — `1` is first, `2` is second, `3` is third
+* **Negative numbers** — `-1` is last, `-2` is second-to-last
+* **`'first'`** and **`'last'`** as readable aliases
+
+This works with any action that targets a single element: `click`, `doubleClick`, `rightClick`, `fillField`, `appendField`, `clearField`, `checkOption`, `selectOption`, `attachFile`, and others.
+
+If only one element matches the locator, `elementIndex` is silently ignored — you always get that single element regardless of the index value. This is convenient when the number of matches depends on page state: you won't get an error if the list happens to have just one item.
+
+When multiple elements exist but the index is out of range, CodeceptJS throws a clear error:
+
+```
+elementIndex 100 exceeds the number of elements found (3) for "a"
+```
+
+You can combine `elementIndex` with other step options:
+
+```js
+I.click('a', step.opts({ elementIndex: 2 }).timeout(5).retry(3))
+```
+
+## Strict Mode
+
+If you'd rather not silently click the first of many matches, enable `strict: true` in your helper configuration. This makes CodeceptJS throw an error whenever a locator matches more than one element, forcing you to write precise locators:
+
+```js
+// codecept.conf.js
+helpers: {
+  Playwright: {
+    url: 'http://localhost',
+    browser: 'chromium',
+    strict: true,
+  }
+}
+```
+
+Now any ambiguous locator will fail immediately:
+
+```js
+I.click('a') // MultipleElementsFound: Multiple elements (3) found for "a" in strict mode
+```
+
+This is useful on projects where you want to catch accidental matches early — clicking the wrong button because of a vague locator is a common source of flaky tests.
+
+When a test fails in strict mode, the error includes a `fetchDetails()` method that lists the matched elements with their XPath and simplified HTML, so you can see exactly what was found and write a better locator:
+
+```js
+// Multiple elements (3) found for "a" in strict mode. Call fetchDetails() for full information.
+// After fetchDetails():
+// /html/body/div/a[1] <a id="first-link">First</a>
+// /html/body/div/a[2] <a id="second-link">Second</a>
+// /html/body/div/a[3] <a id="third-link">Third</a>
+// Use a more specific locator or grabWebElements() to work with multiple elements
+```
+
+Strict mode is supported in **Playwright**, **Puppeteer**, and **WebDriver** helpers.
+
+### Per-Step Strict Mode with `exact`
+
+You don't have to enable strict mode globally. Use `exact: true` to enforce it on a single step — handy when most of your tests are fine with default behavior but a particular action needs to be precise:
+
+```js
+import step from 'codeceptjs/steps'
+
+I.click('a', step.opts({ exact: true }))
+// throws MultipleElementsFound if more than one link matches
+```
+
+`strictMode: true` is an alias if you prefer a more descriptive name:
+
+```js
+I.click('a', step.opts({ strictMode: true }))
+```
+
+It works the other way too. If your helper has `strict: true` globally but you need to relax it for one step, use `exact: false`:
+
+```js
+// strict: true in config, but this step allows multiple matches
+I.click('a', step.opts({ exact: false }))
+```
+
+And when you know there are multiple matches and want a specific one, `elementIndex` also overrides the strict check — no error is thrown because you've explicitly chosen which element to use:
+
+```js
+// strict: true in config, but this works without error
+I.click('a', step.opts({ elementIndex: 2 }))
+```
+
+## Summary
+
+| Situation | Approach |
+|-----------|----------|
+| You want to catch ambiguous locators early | Enable `strict: true` in helper config |
+| You need a specific element from a known list | Use `step.opts({ elementIndex: N })` |
+| You want to iterate over all matching elements | Use [`eachElement`](/els) from the `els` module |
+| You need full control over element inspection | Use [`grabWebElements`](/WebElement) to get all matches |