feat(actor): chain step options on helper actions

docs/element-selection.md

@@ -11,7 +11,28 @@ 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:
+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. Chain `first()`, `last()` or `at()` to the action:
+
+```js
+I.click('a').first()
+
+// click the last link
+I.click('a').last()
+
+// click the 2nd link
+I.click('a').at(2)
+
+// fill the second-to-last matching input
+I.fillField('.email-input', 'test@example.com').at(-2)
+```
+
+Chain the selection directly to the action, in the same expression. `await I.click('a').last()` works too. Calling it after the step has run throws an error.
+
+These methods exist on helper actions only. They are not available on custom steps and page object methods.
+
+They differ from `locate('a').first()`, which builds a position into the locator. A chained selection picks from whatever the action matched, including fuzzy matches like `I.click('Submit').last()`.
+
+The same selection is available as a step option:
 
 ```js
 import step from 'codeceptjs/steps'
@@ -108,10 +129,12 @@ It works the other way too. If your helper has `strict: true` globally but you n
 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:
+And when you know there are multiple matches and want a specific one, `first()`, `last()`, `at()` and `elementIndex` override 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
+// strict: true in config, but these work without error
+I.click('a').first()
+I.click('a').at(2)
 I.click('a', step.opts({ elementIndex: 2 }))
 ```
 
@@ -120,6 +143,6 @@ I.click('a', step.opts({ elementIndex: 2 }))
 | 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 need a specific element from a known list | Chain `.first()`, `.last()` or `.at(N)` to the action |
 | 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 |

docs/locators.md

@@ -158,17 +158,15 @@ I.tap('~submit')   // mobile
 
 ## Picking a specific element
 
-When a locator matches several elements on the page, CodeceptJS acts on the first one by default. To target a different match, pass `elementIndex` via `step.opts()`:
+When a locator matches several elements on the page, CodeceptJS acts on the first one by default. To target a different match, chain `first()`, `last()` or `at()` to the action:
 
 ```js
-import step from 'codeceptjs/steps'
-
-I.click('a', step.opts({ elementIndex: 2 }))       // the 2nd link
-I.click('a', step.opts({ elementIndex: 'last' }))  // the last link
-I.fillField('.email-input', 'u@t.com', step.opts({ elementIndex: -1 }))
+I.click('a').at(2)   // the 2nd link
+I.click('a').last()  // the last link
+I.fillField('.email-input', 'u@t.com').at(-1)
 ```
 
-`elementIndex` accepts positive numbers (1-based), negative numbers (`-1` is last), or the aliases `'first'` and `'last'`. It works with `click`, `fillField`, `selectOption`, `checkOption`, and other single-element actions.
+`at()` accepts positive numbers (1-based) and negative numbers (`-1` is last). It works with `click`, `fillField`, `selectOption`, `checkOption`, and other single-element actions. The same selection is available as `step.opts({ elementIndex: 2 })`.
 
 To catch ambiguous locators during development rather than silently using the first match, enable `strict: true` in the helper config, or pass `step.opts({ exact: true })` on a single step:
 

docs/migration-4.md

@@ -534,6 +534,8 @@ I.retry(3).click('Submit')  //  I.click('Submit', step.retry(3))
 I.limitTime(10).fillField('Email', 'a@b.c') // I.fillField('Email', 'a@b.c', step.timeout(10))
 ```
 
+You can also chain them to the action: `I.click('Submit').retry(3)`, `I.fillField('Email', 'a@b.c').timeout(10)`. Pass a whole config with `I.click('Submit').stepConfig(step.retry(3).timeout(10))`.
+
 `step.*` configs are also composable with the other step options:
 
 ```js
@@ -648,11 +650,13 @@ The error includes a `fetchDetails()` method that prints XPaths and HTML for eve
 Pick a specific match without writing a more specific locator:
 
 ```js
-I.click('a', step.opts({ elementIndex: 2 }))
-I.click('a', step.opts({ elementIndex: 'last' }))
-I.fillField('input', 'x', step.opts({ elementIndex: -1 }))
+I.click('a').at(2)
+I.click('a').last()
+I.fillField('input', 'x').first()
 ```
 
+`step.opts({ elementIndex: 2 })` does the same.
+
 ### Unfocused Element Detection
 
 `I.type()` and `I.pressKey()` throw `NonFocusedType` if no element has focus. Click or focus the field first.

docs/retry.md

@@ -119,7 +119,7 @@ import step from 'codeceptjs/steps'
 Scenario('checkout', ({ I }) => {
   I.amOnPage('/cart')
   I.click('Proceed to Checkout', step.retry(5))  // retry up to 5 times
-  I.see('Payment')
+  I.see('Payment').retry(3)                      // same, chained to the action
 })
 ```
 

docs/timeouts.md

@@ -9,14 +9,14 @@ CodeceptJS provides multiple timeout configurations to control test execution ti
 
 ## Step Timeout
 
-Set timeout for individual steps using `step.timeout()`:
+Set timeout for individual steps by chaining `timeout()` to the action, or by passing `step.timeout()`:
 
 ```js
 import step from 'codeceptjs/steps'
 
 Scenario('test with step timeouts', ({ I }) => {
   I.amOnPage('/')
-  I.click('Slow Button', step.timeout(30))
+  I.click('Slow Button').timeout(30)
   I.fillField('Email', 'user@example.com', step.timeout(10))
 })
 ```

docs/webapi/amOnPage.mustache

@@ -8,4 +8,4 @@ I.amOnPage('/login'); // opens a login page
 ```
 
 @param {string} url url path or global url.
-@returns {void} automatically synchronized promise through #recorder
+@returns {CodeceptJS.StepPromise} automatically synchronized promise through #recorder

docs/webapi/appendField.mustache

@@ -13,4 +13,4 @@ I.appendField('name', 'John', '.form-container');
 @param {CodeceptJS.LocatorOrString} field located by label|name|CSS|XPath|strict locator
 @param {string} value text value to append.
 @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element located by CSS | XPath | strict locator.
-@returns {void} automatically synchronized promise through #recorder
+@returns {CodeceptJS.ElementStepPromise} automatically synchronized promise through #recorder

docs/webapi/attachFile.mustache

@@ -21,4 +21,4 @@ I.attachFile('#dropzone', 'data/avatar.jpg');
 @param {CodeceptJS.LocatorOrString} locator field located by label|name|CSS|XPath|strict locator.
 @param {string} pathToFile local file path relative to codecept.conf.ts or codecept.conf.js config file.
 @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element located by CSS | XPath | strict locator.
-@returns {void} automatically synchronized promise through #recorder
+@returns {CodeceptJS.ElementStepPromise} automatically synchronized promise through #recorder

docs/webapi/blur.mustache

@@ -15,4 +15,4 @@ I.dontSee('#add-to-cart-btn');
 
 @param {CodeceptJS.LocatorOrString} locator field located by label|name|CSS|XPath|strict locator.
 @param {any} [options] Playwright only: [Additional options](https://playwright.dev/docs/api/class-locator#locator-blur) for available options object as 2nd argument.
-@returns {void} automatically synchronized promise through #recorder
+@returns {CodeceptJS.ElementStepPromise} automatically synchronized promise through #recorder

docs/webapi/checkOption.mustache

@@ -10,4 +10,4 @@ I.checkOption('agree', '//form');
 ```
 @param {CodeceptJS.LocatorOrString} field checkbox located by label | name | CSS | XPath | strict locator.
 @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element located by CSS | XPath | strict locator.
-@returns {void} automatically synchronized promise through #recorder
+@returns {CodeceptJS.ElementStepPromise} automatically synchronized promise through #recorder

docs/webapi/clearClipboard.mustache

@@ -5,4 +5,4 @@ I.clearClipboard();
 I.seeClipboardEquals('');
 ```
 
-@returns {void} automatically synchronized promise through #recorder
+@returns {CodeceptJS.StepPromise} automatically synchronized promise through #recorder

docs/webapi/clearField.mustache

@@ -11,4 +11,4 @@ I.clearField('Email', '.form-container');
 ```
 @param {LocatorOrString} editable field located by label|name|CSS|XPath|strict locator.
 @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element located by CSS | XPath | strict locator.
-@returns {void} automatically synchronized promise through #recorder.
+@returns {CodeceptJS.ElementStepPromise} automatically synchronized promise through #recorder.

docs/webapi/click.mustache

@@ -30,4 +30,4 @@ I.click({role: 'button', name: 'Submit'});
 
 @param {CodeceptJS.LocatorOrString} [locator='//body'] (optional, `'//body'` by default) clickable link or button located by text, or any element located by CSS|XPath|strict locator.
 @param {?CodeceptJS.LocatorOrString | null} [context=null] (optional, `null` by default) element to search in CSS|XPath|Strict locator.
-@returns {void} automatically synchronized promise through #recorder
+@returns {CodeceptJS.ElementStepPromise} automatically synchronized promise through #recorder

docs/webapi/clickLink.mustache

@@ -5,4 +5,4 @@ I.clickLink('Logout', '#nav');
 ```
 @param {CodeceptJS.LocatorOrString} locator clickable link or button located by text, or any element located by CSS|XPath|strict locator
 @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element to search in CSS|XPath|Strict locator
-@returns {void} automatically synchronized promise through #recorder
+@returns {CodeceptJS.ElementStepPromise} automatically synchronized promise through #recorder

docs/webapi/closeCurrentTab.mustache

@@ -4,4 +4,4 @@ Close current tab.
 I.closeCurrentTab();
 ```
 
-@returns {void} automatically synchronized promise through #recorder
+@returns {CodeceptJS.StepPromise} automatically synchronized promise through #recorder

docs/webapi/closeOtherTabs.mustache

@@ -5,4 +5,4 @@ Close all tabs except for the current one.
 I.closeOtherTabs();
 ```
 
-@returns {void} automatically synchronized promise through #recorder
+@returns {CodeceptJS.StepPromise} automatically synchronized promise through #recorder

docs/webapi/dontSee.mustache

@@ -8,4 +8,4 @@ I.dontSee('Login', '.nav'); // no login inside .nav element
 
 @param {string} text which is not present.
 @param {CodeceptJS.LocatorOrString} [context] (optional) element located by CSS|XPath|strict locator in which to perfrom search.
-@returns {void} automatically synchronized promise through #recorder
+@returns {CodeceptJS.StepPromise} automatically synchronized promise through #recorder

docs/webapi/dontSeeCheckboxIsChecked.mustache

@@ -7,4 +7,4 @@ I.dontSeeCheckboxIsChecked('agree'); // located by name
 ```
 
 @param {CodeceptJS.LocatorOrString} field located by label|name|CSS|XPath|strict locator.
-@returns {void} automatically synchronized promise through #recorder
+@returns {CodeceptJS.StepPromise} automatically synchronized promise through #recorder

docs/webapi/dontSeeCookie.mustache

@@ -5,4 +5,4 @@ I.dontSeeCookie('auth'); // no auth cookie
 ```
 
 @param {string} name cookie name.
-@returns {void} automatically synchronized promise through #recorder
+@returns {CodeceptJS.StepPromise} automatically synchronized promise through #recorder

docs/webapi/dontSeeCurrentPathEquals.mustache

@@ -7,4 +7,4 @@ I.dontSeeCurrentPathEquals('/'); // fails for '/', '/?user=ok', '/#top'
 ```
 
 @param {string} path value to check.
-@returns {void} automatically synchronized promise through #recorder
+@returns {CodeceptJS.StepPromise} automatically synchronized promise through #recorder

docs/webapi/dontSeeCurrentUrlEquals.mustache

@@ -7,4 +7,4 @@ I.dontSeeCurrentUrlEquals('http://mysite.com/login'); // absolute urls are also
 ```
 
 @param {string} url value to check.
-@returns {void} automatically synchronized promise through #recorder
+@returns {CodeceptJS.StepPromise} automatically synchronized promise through #recorder

docs/webapi/dontSeeElement.mustache

@@ -9,4 +9,4 @@ I.dontSeeElement('.modal', '#container');
 
 @param {CodeceptJS.LocatorOrString} locator located by CSS|XPath|Strict locator.
 @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element located by CSS | XPath | strict locator.
-@returns {void} automatically synchronized promise through #recorder
+@returns {CodeceptJS.StepPromise} automatically synchronized promise through #recorder

docs/webapi/dontSeeElementInDOM.mustache

@@ -5,4 +5,4 @@ I.dontSeeElementInDOM('.nav'); // checks that element is not on page visible or
 ```
 
 @param {CodeceptJS.LocatorOrString} locator located by CSS|XPath|Strict locator.
-@returns {void} automatically synchronized promise through #recorder
+@returns {CodeceptJS.StepPromise} automatically synchronized promise through #recorder

docs/webapi/dontSeeInCurrentUrl.mustache

@@ -1,4 +1,4 @@
 Checks that current url does not contain a provided fragment.
 
 @param {string} url value to check.
-@returns {void} automatically synchronized promise through #recorder
+@returns {CodeceptJS.StepPromise} automatically synchronized promise through #recorder

docs/webapi/dontSeeInField.mustache

@@ -13,4 +13,4 @@ I.dontSeeInField('Name', 'old_value', '.form-container');
 @param {CodeceptJS.LocatorOrString} field located by label|name|CSS|XPath|strict locator.
 @param {CodeceptJS.StringOrSecret} value value to check.
 @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element located by CSS | XPath | strict locator.
-@returns {void} automatically synchronized promise through #recorder
+@returns {CodeceptJS.StepPromise} automatically synchronized promise through #recorder

docs/webapi/dontSeeInSource.mustache

@@ -5,4 +5,4 @@ I.dontSeeInSource('<!--'); // no comments in source
 ```
 
 @param {string} value to check.
-@returns {void} automatically synchronized promise through #recorder
+@returns {CodeceptJS.StepPromise} automatically synchronized promise through #recorder

docs/webapi/dontSeeInTitle.mustache

@@ -5,4 +5,4 @@ I.dontSeeInTitle('Error');
 ```
 
 @param {string} text value to check.
-@returns {void} automatically synchronized promise through #recorder
+@returns {CodeceptJS.StepPromise} automatically synchronized promise through #recorder

docs/webapi/doubleClick.mustache

@@ -10,4 +10,4 @@ I.doubleClick('.btn.edit');
 
 @param {CodeceptJS.LocatorOrString} locator clickable link or button located by text, or any element located by CSS|XPath|strict locator.
 @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element to search in CSS|XPath|Strict locator.
-@returns {void} automatically synchronized promise through #recorder
+@returns {CodeceptJS.ElementStepPromise} automatically synchronized promise through #recorder

docs/webapi/dragAndDrop.mustache

@@ -6,4 +6,4 @@ I.dragAndDrop('#dragHandle', '#container');
 
 @param {LocatorOrString} srcElement located by CSS|XPath|strict locator.
 @param {LocatorOrString} destElement located by CSS|XPath|strict locator.
-@returns {void} automatically synchronized promise through #recorder
+@returns {CodeceptJS.ElementStepPromise} automatically synchronized promise through #recorder

docs/webapi/dragSlider.mustache

@@ -8,4 +8,4 @@ I.dragSlider('#slider', -70);
 
 @param {CodeceptJS.LocatorOrString} locator located by label|name|CSS|XPath|strict locator.
 @param {number} offsetX position to drag.
-@returns {void} automatically synchronized promise through #recorder
+@returns {CodeceptJS.ElementStepPromise} automatically synchronized promise through #recorder

docs/webapi/fillField.mustache

@@ -22,4 +22,4 @@ I.fillField('Name', 'John', '#section2');
 @param {CodeceptJS.LocatorOrString} field located by label|name|CSS|XPath|strict locator.
 @param {CodeceptJS.StringOrSecret} value text value to fill.
 @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element located by CSS | XPath | strict locator.
-@returns {void} automatically synchronized promise through #recorder
+@returns {CodeceptJS.ElementStepPromise} automatically synchronized promise through #recorder

docs/webapi/focus.mustache

@@ -10,4 +10,4 @@ I.see('#add-to-cart-bnt');
 
 @param {CodeceptJS.LocatorOrString} locator field located by label|name|CSS|XPath|strict locator.
 @param {any} [options] Playwright only: [Additional options](https://playwright.dev/docs/api/class-locator#locator-focus) for available options object as 2nd argument.
-@returns {void} automatically synchronized promise through #recorder
+@returns {CodeceptJS.ElementStepPromise} automatically synchronized promise through #recorder

docs/webapi/forceClick.mustache

@@ -25,4 +25,4 @@ I.forceClick({css: 'nav a.login'});
 
 @param {CodeceptJS.LocatorOrString} locator clickable link or button located by text, or any element located by CSS|XPath|strict locator.
 @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element to search in CSS|XPath|Strict locator.
-@returns {void} automatically synchronized promise through #recorder
+@returns {CodeceptJS.ElementStepPromise} automatically synchronized promise through #recorder

docs/webapi/forceRightClick.mustache

@@ -15,4 +15,4 @@ I.forceRightClick('Menu');
 
 @param {CodeceptJS.LocatorOrString} locator clickable link or button located by text, or any element located by CSS|XPath|strict locator.
 @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element to search in CSS|XPath|Strict locator.
-@returns {void} automatically synchronized promise through #recorder
+@returns {CodeceptJS.StepPromise} automatically synchronized promise through #recorder

docs/webapi/grabDataFromPerformanceTiming.mustache

@@ -17,4 +17,4 @@ let data = await I.grabDataFromPerformanceTiming();
   loadEventEnd: 241
 }
 ```
-@returns {void} automatically synchronized promise through #recorder
+@returns {CodeceptJS.StepPromise} automatically synchronized promise through #recorder

docs/webapi/moveCursorTo.mustache

@@ -13,4 +13,4 @@ I.moveCursorTo('#submit', '.container');
 @param {CodeceptJS.LocatorOrString} locator located by CSS|XPath|strict locator.
 @param {number|CodeceptJS.LocatorOrString} [offsetX=0] (optional, `0` by default) X-axis offset or context locator.
 @param {number} [offsetY=0] (optional, `0` by default) Y-axis offset.
-@returns {void} automatically synchronized promise through #recorder
+@returns {CodeceptJS.ElementStepPromise} automatically synchronized promise through #recorder

docs/webapi/openNewTab.mustache

@@ -4,4 +4,4 @@ Open new tab and switch to it.
 I.openNewTab();
 ```
 
-@returns {void} automatically synchronized promise through #recorder
+@returns {CodeceptJS.StepPromise} automatically synchronized promise through #recorder

docs/webapi/pressKeyDown.mustache

@@ -9,4 +9,4 @@ I.pressKeyUp('Control');
 ```
 
 @param {string} key name of key to press down.
-@returns {void} automatically synchronized promise through #recorder
+@returns {CodeceptJS.StepPromise} automatically synchronized promise through #recorder

docs/webapi/pressKeyUp.mustache

@@ -9,4 +9,4 @@ I.pressKeyUp('Control');
 ```
 
 @param {string} key name of key to release.
-@returns {void} automatically synchronized promise through #recorder
+@returns {CodeceptJS.StepPromise} automatically synchronized promise through #recorder

docs/webapi/pressKeyWithKeyNormalization.mustache

@@ -57,4 +57,4 @@ Some of the supported key names are:
 - `'Tab'`
 
 @param {string|string[]} key key or array of keys to press.
-@returns {void} automatically synchronized promise through #recorder
+@returns {CodeceptJS.StepPromise} automatically synchronized promise through #recorder

docs/webapi/refreshPage.mustache

@@ -3,4 +3,4 @@ Reload the current page.
 ```js
 I.refreshPage();
 ```
-@returns {void} automatically synchronized promise through #recorder
+@returns {CodeceptJS.StepPromise} automatically synchronized promise through #recorder

docs/webapi/resizeWindow.mustache

@@ -3,4 +3,4 @@ First parameter can be set to `maximize`.
 
 @param {number} width width in pixels or `maximize`.
 @param {number} height height in pixels.
-@returns {void} automatically synchronized promise through #recorder
+@returns {CodeceptJS.StepPromise} automatically synchronized promise through #recorder

docs/webapi/rightClick.mustache

@@ -11,4 +11,4 @@ I.rightClick('Click me', '.context');
 
 @param {CodeceptJS.LocatorOrString} locator clickable element located by CSS|XPath|strict locator.
 @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element located by CSS|XPath|strict locator.
-@returns {void} automatically synchronized promise through #recorder
+@returns {CodeceptJS.ElementStepPromise} automatically synchronized promise through #recorder