codeceptjs 4.0.0-rc.23 → 4.0.0-rc.25

package/README.md

@@ -251,20 +251,22 @@ Add the `testomatio` plugin to your `codecept.conf.js`:
 plugins: {
   testomatio: {
     enabled: true,
-    require: '@testomatio/reporter/lib/adapter/codecept',
+    require: '@testomatio/reporter/codecept',
+    html: true,
+    reportDir: 'output/report',
   },
 }
 ```
 
 ### Usage
 
-Generate HTML reports by setting the `TESTOMATIO_HTML_REPORT_SAVE` environment variable:
+Run tests normally:
 
 ```sh
-TESTOMATIO_HTML_REPORT_SAVE=1 npx codeceptjs run
+npx codeceptjs run
 ```
 
-The report will be saved to `html-report/testomatio-report.html`.
+The report will be saved to `output/report/testomatio-report.html` by default. You can also keep using `TESTOMATIO_HTML_REPORT_SAVE=1` and related environment variables if you prefer env-based setup.
 
 ### Features
 
@@ -278,14 +280,11 @@ The report will be saved to `html-report/testomatio-report.html`.
 ### Customization
 
 ```sh
-# Custom output folder
-TESTOMATIO_HTML_REPORT_SAVE=1 TESTOMATIO_HTML_REPORT_FOLDER=./reports npx codeceptjs run
-
-# Custom filename
-TESTOMATIO_HTML_REPORT_SAVE=1 TESTOMATIO_HTML_FILENAME=my-report.html npx codeceptjs run
+# Custom output folder in codecept.conf.js
+# reportDir: './reports'
 
 # Integrate with Testomat.io cloud
-TESTOMATIO_HTML_REPORT_SAVE=1 TESTOMATIO=your_api_key npx codeceptjs run
+TESTOMATIO=your_api_key npx codeceptjs run
 ```
 
 ## PageObjects

package/docs/ai.md

@@ -1,15 +1,15 @@
 ---
 permalink: /ai
-title: Testing with AI 🪄
+title: Testing with AI
 ---
 
-# 🪄 Testing with AI
+# Testing with AI
 
 **CodeceptJS is the first open-source test automation framework with AI** features to improve the testing experience. CodeceptJS uses AI provider like OpenAI or Anthropic to auto-heal failing tests, assist in writing tests, and more...
 
 Think of it as your testing co-pilot built into the testing framework
 
-> 🪄 **AI features for testing are experimental**. AI works only for web based testing with Playwright, WebDriver, etc. Those features will be improved based on user's experience.
+> This is guide on using AI features inside CodeceptJS. To control CodeceptJS via AI Agents, see [Agentic Testing Guide](/agents/).
 
 ## How AI Improves Automated Testing
 
@@ -164,50 +164,6 @@ The AI SDK supports 20+ providers including:
 
 See [AI SDK Providers](https://ai-sdk.dev/docs/foundations/providers-and-models) for complete list and configuration details.
 
-## Writing Tests with AI Copilot
-
-If AI features are enabled when using [interactive pause](/basics/#debug) with `pause()` command inside tests:
-
-For instance, let's create a test to try ai features via `gt` command:
-
-```
-npx codeceptjs gt
-```
-
-Name a test and write the code. We will use `Scenario.only` instead of Scenario to execute only this exact test.
-
-```js
-Feature('ai')
-
-Scenario.only('test ai features', ({ I }) => {
-  I.amOnPage('https://getbootstrap.com/docs/5.1/examples/checkout/')
-  pause()
-})
-```
-
-Now run the test in debug mode with AI enabled:
-
-```
-npx codeceptjs run --debug --ai
-```
-
-When pause mode started you can ask GPT to fill in the fields on this page. Use natural language to describe your request, and provide enough details that AI could operate with it. It is important to include at least a space char in your input, otherwise, CodeceptJS will consider the input to be JavaScript code.
-
-```
- I.fill checkout form with valid values without submitting it
-```
-
-![](/img/fill_form_1.png)
-
-GPT will generate code and data and CodeceptJS will try to execute its code. If it succeeds, the code will be saved to history and you will be able to copy it to your test.
-
-![](/img/fill_form2.png)
-
-This AI copilot works best with long static forms. In the case of complex and dynamic single-page applications, it may not perform as well, as the form may not be present on HTML page yet. For instance, interacting with calendars or inputs with real-time validations (like credit cards) can not yet be performed by AI.
-
-Please keep in mind that GPT can't react to page changes and operates with static text only. This is why it is not ready yet to write the test completely. However, if you are new to CodeceptJS and automated testing AI copilot may help you write tests more efficiently.
-
-> 👶 Enable AI copilot for junior test automation engineers. It may help them to get started with CodeceptJS and to write good semantic locators.
 
 ## Self-Healing Tests
 
@@ -409,9 +365,7 @@ ai: {
 
 CodeceptJS uses three main prompts for AI features:
 
-- `writeStep` - generates test code in interactive pause mode
 - `healStep` - suggests fixes for failing tests
-- `generatePageObject` - creates page objects from HTML
 
 To customize a prompt, generate it using:
 
@@ -452,9 +406,7 @@ You can also override prompts programmatically in config:
 ```js
 ai: {
   prompts: {
-    writeStep: (html, input) => [{ role: 'user', content: 'As a test engineer...' }]
     healStep: (html, { step, error, prevSteps }) => [{ role: 'user', content: 'As a test engineer...' }]
-    generatePageObject: (html, extraPrompt = '', rootLocator = null) => [{ role: 'user', content: 'As a test engineer...' }]
   }
 }
 ```

package/docs/architecture.md

@@ -35,6 +35,7 @@ import { recorder, event, output, container, config } from 'codeceptjs'
 | [`recorder`](https://github.com/codeceptjs/CodeceptJS/blob/master/lib/recorder.js) | the global promise chain that orders every step |
 | [`event`](https://github.com/codeceptjs/CodeceptJS/blob/master/lib/event.js) | the event dispatcher and the names of all lifecycle events |
 | [`output`](https://github.com/codeceptjs/CodeceptJS/blob/master/lib/output.js) | the printer used for all console output |
+| [`store`](https://github.com/codeceptjs/CodeceptJS/blob/master/lib/store.js) | global state of the run — current test/step, run modes, directories |
 | [`helper`](https://github.com/codeceptjs/CodeceptJS/blob/master/lib/helper.js) | the base class every helper extends |
 | [`actor`](https://github.com/codeceptjs/CodeceptJS/blob/master/lib/actor.js) | the base class behind the `I` object |
 
@@ -183,6 +184,21 @@ output.log('verbose logging information')
 
 Use these instead of `console.log` so messages respect the chosen verbosity.
 
+## Store
+
+`store` holds the state of the current run — the executing test, suite, and step, the active run modes (`dryRun`, `debugMode`, `workerMode`, …), and the project directories. Listeners, plugins, and helpers read it to know where in the [lifecycle](#events) they are without that information being passed to them:
+
+```js
+import { store } from 'codeceptjs'
+
+event.dispatcher.on(event.step.before, () => {
+  if (store.dryRun) return                    // no side effects on a dry run
+  output.debug(`in ${store.currentTest?.title}`)
+})
+```
+
+CodeceptJS keeps the state fields up to date for you. See the [Store reference](/store) for every field and when to write to it.
+
 ## Helpers and the Actor
 
 The `I` object is an **actor** assembled from the enabled helpers. Each `I.method()` call delegates to the matching helper method and is wrapped as a step. Methods whose names start with `_` are private to the helper and not exposed on `I`. To add your own actions, write a [custom helper](/helpers).

package/docs/bootstrap.md

@@ -6,7 +6,7 @@ title: Bootstrap
 # Bootstrap
 
 In case you need to execute arbitrary code before or after the tests,
-you can use the `bootstrap` and `teardown` config. Use it to start and stop a webserver, Selenium, etc.
+you can use the `bootstrap` and `teardown` config. Use it to start and stop a webserver, seed a database, etc.
 
 When using the [parallel execution](/parallel) mode, there are two additional hooks available; `bootstrapAll` and `teardownAll`. See [bootstrapAll & teardownAll](#bootstrapall-teardownall) for more information.
 

package/docs/continuous-integration.md

@@ -34,11 +34,11 @@ CodeceptJS runs in any CI that can install Node.js. This page covers the setup,
 ## Browsers and drivers
 
 - **Playwright** — `npx playwright install --with-deps`. Docs: [Playwright CI](https://playwright.dev/docs/ci), [Playwright Docker image](https://playwright.dev/docs/docker) (pin the tag to your installed `playwright` version).
-- **WebDriver** — run a Selenium server: `selenium/standalone-chrome` on port `4444`. Docs: [WebDriver helper](/webdriver), [WebdriverIO Selenium Grid](https://webdriver.io/docs/seleniumgrid), [Selenium Docker images](https://github.com/SeleniumHQ/docker-selenium).
+- **WebDriver** — nothing to provision. WebdriverIO 9 downloads and starts both the browser (Chrome, Chromium, or Firefox) and the matching driver automatically. No Selenium server, no browser-install step. Docs: [WebDriver helper](/webdriver), [WebdriverIO driver/browser management](https://webdriver.io/docs/driverbinaries/).
 
 ## Check before running
 
-`npx codeceptjs check` loads the config, opens the browser (or connects to Selenium), and counts tests. Prepend it so a broken environment fails fast with a clear message:
+`npx codeceptjs check` loads the config, opens the browser, and counts tests. Prepend it so a broken environment fails fast with a clear message:
 
 ```bash
 npx codeceptjs check
@@ -61,7 +61,7 @@ Use [`@testomatio/reporter`](https://github.com/testomatio/reporter). It ships p
 
 ## CI examples
 
-Each example uses Playwright by default; a WebDriver-with-Selenium variant follows where it differs. A `node:20` base image plus `npx playwright install --with-deps` keeps these configs free of version pins.
+Each example uses Playwright by default; a WebDriver variant follows where it differs. WebdriverIO 9 downloads its own browser and driver, so the WebDriver variants run on a plain `node:20` image with no Selenium service and no browser-install step. For Playwright, a `node:20` base image plus `npx playwright install --with-deps` keeps these configs free of version pins.
 
 ### GitHub Actions — Playwright
 
@@ -98,7 +98,9 @@ jobs:
           path: output/
 ```
 
-### GitHub Actions — WebDriver + Selenium
+### GitHub Actions — WebDriver
+
+WebdriverIO 9 downloads its own browser and driver, so the job is just `npm ci` + run — no Selenium service, no browser-install step. This mirrors [WebdriverIO's own boilerplate CI](https://github.com/webdriverio/jasmine-boilerplate/blob/master/.github/workflows/ci.yaml).
 
 ```yaml
 name: WebDriver Tests
@@ -107,15 +109,7 @@ on: [push, pull_request]
 jobs:
   test:
     runs-on: ubuntu-latest
-    services:
-      selenium:
-        image: selenium/standalone-chrome
-        ports:
-          - 4444:4444
-        options: --shm-size=2g
     env:
-      SELENIUM_HOST: localhost
-      SELENIUM_PORT: 4444
       FORCE_COLOR: 1
     steps:
       - uses: actions/checkout@v4
@@ -217,13 +211,7 @@ playwright:
 
 webdriver:
   stage: test
-  image: node:20
-  services:
-    - name: selenium/standalone-chrome
-      alias: selenium
-  variables:
-    SELENIUM_HOST: selenium
-    SELENIUM_PORT: "4444"
+  image: node:20  # WebdriverIO 9 downloads its own browser and driver
   script:
     - npm ci
     - npx codeceptjs check
@@ -245,10 +233,6 @@ image: node:20
 definitions:
   caches:
     playwright: ~/.cache/ms-playwright
-  services:
-    selenium:
-      image: selenium/standalone-chrome
-      memory: 2048
 
 pipelines:
   default:
@@ -273,16 +257,16 @@ pipelines:
             artifacts: [output/**]
 ```
 
-For WebDriver, attach the Selenium service to the step:
+For WebDriver, no Selenium service or browser image is needed — WebdriverIO 9 downloads its own browser and driver:
 
 ```yaml
+image: node:20
+
 pipelines:
   default:
     - step:
-        services: [selenium]
         script:
           - npm ci
-          - export SELENIUM_HOST=localhost SELENIUM_PORT=4444
           - npx codeceptjs check
           - npx codeceptjs run-workers 2 --by pool
         artifacts: [output/**]
@@ -327,19 +311,13 @@ pipeline {
 }
 ```
 
-For WebDriver, run Selenium alongside the test container:
+For WebDriver, keep the same `node:20` agent — WebdriverIO 9 downloads its own browser and driver, so no Selenium container is needed:
 
 ```groovy
 stage('Test') {
   steps {
-    script {
-      docker.image('selenium/standalone-chrome').withRun('--shm-size=2g -p 4444:4444') { c ->
-        withEnv(['SELENIUM_HOST=localhost', 'SELENIUM_PORT=4444']) {
-          sh 'npx codeceptjs check'
-          sh 'npx codeceptjs run-workers 2 --by pool'
-        }
-      }
-    }
+    sh 'npx codeceptjs check'
+    sh 'npx codeceptjs run-workers 2 --by pool'
   }
 }
 ```
@@ -371,11 +349,8 @@ jobs:
 
   webdriver:
     docker:
+      # WebdriverIO 9 downloads its own browser and driver
       - image: cimg/node:20.18
-      - image: selenium/standalone-chrome
-    environment:
-      SELENIUM_HOST: localhost
-      SELENIUM_PORT: 4444
     steps:
       - checkout
       - run: npm ci
@@ -427,13 +402,10 @@ steps:
       artifactName: codeceptjs-output-$(System.JobPositionInPhase)
 ```
 
-For WebDriver, run Selenium as a sidecar before the tests:
+For WebDriver, no extra setup is needed — WebdriverIO 9 downloads its own browser and driver:
 
 ```yaml
-  - script: docker run -d --net=host --shm-size=2g selenium/standalone-chrome
-    displayName: Start Selenium
   - script: |
-      export SELENIUM_HOST=localhost SELENIUM_PORT=4444
       npx codeceptjs check
       npx codeceptjs run-workers 2 --by pool
     displayName: Run tests
@@ -446,7 +418,7 @@ The official `codeceptjs/codeceptjs` image runs Playwright, Puppeteer, and WebDr
 ## See also
 
 - [Playwright CI guide](https://playwright.dev/docs/ci) · [Playwright Docker image](https://playwright.dev/docs/docker)
-- [WebdriverIO Selenium Grid](https://webdriver.io/docs/seleniumgrid) · [Selenium Docker images](https://github.com/SeleniumHQ/docker-selenium)
+- [WebdriverIO driver management](https://webdriver.io/blog/2023/07/31/driver-management/)
 - [Parallel Execution](/parallel) · [Reports](/reports) · [Plugins](/plugins) · [Docker](/docker)
 
 ## Community recipes

package/docs/custom-helpers.md

@@ -212,7 +212,7 @@ _before() {
 }
 ```
 
-`recorder.retry` acts similarly to `I.retry()` and accepts the same parameters. It expects the `when` parameter to be set so it would handle only specific errors and not to retry for every failed step.
+`recorder.retry` registers a retry rule at the recorder level and accepts the same options as `step.retry()` (`retries`, `minTimeout`, `when`, ...). It expects the `when` parameter to be set so it would handle only specific errors and not to retry for every failed step.
 
 Retry rules are available in array `recorder.retries`. The last retry rule can be disabled by running `recorder.retries.pop()`;
 

package/docs/detox.md

@@ -31,7 +31,7 @@ CodeceptJS provides next features over standard Detox:
 
 * **Unified API**. The same test can be executed in Appium or Detox. Unified API helps different teams to use the same syntax and easy port tests from one engine to another.
 * [Interactive pause](/basics#pause). When starting/stopping an application takes a long time, debugging and writing tests can be hard. CodeceptJS solves this by pausing an execution and letting you try different commands and locators. With this feature a test can be writtern during one running session.
-* [Auto-retries](/basics#retries) using `retryFailedStepPlugin` and `I.retry()`
+* [Auto-retries](/basics#retries) using the `retryFailedStep` plugin and `step.retry()`
 * **Cross-Platform testing** - one test can be executed on different engines. When needed, platform-specific actions and locators can be easily applied.
 
 ## A Test

package/docs/docker.md

@@ -38,7 +38,6 @@ services:
   codeceptjs:
     image: codeceptjs/codeceptjs
     depends_on:
-      - firefox
       - web
     volumes:
       - .:/tests
@@ -47,38 +46,10 @@ services:
     command: node app/server.js
     volumes:
       - .:/app
-  firefox:
-    image: selenium/standalone-firefox-debug:2.53.0
-    ports:
-      - '4444'
-      - '5900'
 ```
 
-### Linking Containers
+The official image bundles browsers, and WebdriverIO 9 starts the matching driver automatically — no separate Selenium container or container linking is required for the WebDriver engine.
 
-If using the WebDriver driver, link the container with a Selenium Standalone docker container with an alias of `selenium`. Additionally, make sure your `codeceptjs.conf.js` contains the following to allow CodeceptJS to identify where Selenium is running.
-
-```javascript
-  ...
-  helpers: {
-    WebDriver: {
-      ...
-      host: process.env.HOST
-      ...
-    }
-  }
-  ...
-```
-
-```sh
-$ docker run -d -P --name selenium-chrome selenium/standalone-chrome
-
-# Alternatively, selenium/standalone-firefox can be used
-
-$ docker run -it --rm -v /<path_to_codeceptjs_test_dir>/:/tests/ --link selenium-chrome:selenium codeceptjs/codeceptjs
-```
-
-You may run use `-v $(pwd)/:tests/` if running this from the root of your CodeceptJS tests directory.
 _Note: The output of your test run will appear in your local directory if your output path is `./output` in the CodeceptJS config_
 
 ### Build

package/docs/examples.md

@@ -107,7 +107,6 @@ This repository demonstrates usage of
 
 - Puppeteer helper
 - Working with Angular CLI
-- Reports with Mochawesome helper
 
 ## [REST Example Tests](https://github.com/PeterNgTr/codeceptjs-rest-demo)
 

package/docs/helpers/Appium.md

@@ -936,8 +936,12 @@ I.click('//form/*[@type=submit]');
 I.click('Logout', '#nav');
 // using strict locator
 I.click({css: 'nav a.login'});
+// using ARIA role locator
+I.click({role: 'button', name: 'Submit'});
 ```
 
+> ℹ️ ARIA role locators (`{role, name}`) match elements the way assistive technology does and survive markup refactors. See [Locators][17].
+
 #### Parameters
 
 *   `locator` **([string][5] | [object][11])** (optional, `'//body'` by default) clickable link or button located by text, or any element located by CSS|XPath|strict locator. (optional, default `'//body'`)
@@ -1034,10 +1038,14 @@ I.fillField('password', secret('123456'));
 I.fillField('form#login input[name=username]', 'John');
 // or by strict locator
 I.fillField({css: 'form#login input[name=username]'}, 'John');
+// by ARIA role locator
+I.fillField({role: 'textbox', name: 'Email'}, 'hello@world.com');
 // within a context
 I.fillField('Name', 'John', '#section2');
 ```
 
+> ℹ️ ARIA role locators (`{role, name}`) match fields by their accessible name and survive markup refactors. See [Locators][17].
+
 #### Parameters
 
 *   `field` **([string][5] | [object][11])** located by label|name|CSS|XPath|strict locator.
@@ -1188,7 +1196,7 @@ I.scrollIntoView('#submit', { behavior: "smooth", block: "center", inline: "cent
 #### Parameters
 
 *   `locator` **([string][5] | [object][11])** located by CSS|XPath|strict locator.
-*   `scrollIntoViewOptions` **(ScrollIntoViewOptions | [boolean][7])** either alignToTop=true|false or scrollIntoViewOptions. See [https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView][17].
+*   `scrollIntoViewOptions` **(ScrollIntoViewOptions | [boolean][7])** either alignToTop=true|false or scrollIntoViewOptions. See [https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView][18].
 
 Returns **void** automatically synchronized promise through #recorderSupported only for web testing
 
@@ -1218,8 +1226,12 @@ The second parameter is a context (CSS or XPath locator) to narrow the search.
 ```js
 I.seeElement('#modal');
 I.seeElement('#modal', '#container');
+// using ARIA role locator
+I.seeElement({role: 'dialog'});
 ```
 
+> ℹ️ ARIA role locators (`{role, name}`) match elements the way assistive technology does and survive markup refactors. See [Locators][17].
+
 #### Parameters
 
 *   `locator` **([string][5] | [object][11])** located by CSS|XPath|strict locator.
@@ -1402,4 +1414,6 @@ Returns **void** automatically synchronized promise through #recorder
 
 [16]: http://webdriver.io/api/mobile/setImmediateValue.html
 
-[17]: https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView
+[17]: /locators#aria-locators
+
+[18]: https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView