codeceptjs 4.0.0-rc.23 → 4.0.0-rc.24

package/docs/hooks.md

@@ -40,7 +40,17 @@ event.dispatcher.on(event.test.before, () => {
 })
 ```
 
-See [Architecture › Events](/architecture#events) for the full event list and the test and step object fields.
+A listener often needs to know *where* in the run it is — which test is active, or whether this is a dry run. Read that from [`store`](/store) instead of tracking it yourself:
+
+```js
+import { event, store } from 'codeceptjs'
+
+event.dispatcher.on(event.step.before, () => {
+  if (store.dryRun) return            // skip side effects on a dry run
+})
+```
+
+See [Architecture › Events](/architecture#events) for the full event list and the test and step object fields, and the [Store reference](/store) for every state field.
 
 ## Plugins
 

package/docs/index.md

@@ -100,7 +100,7 @@ Scenario('Create a new store', async ({ I, login, SettingsPage }) => {
   I.fillField('Email', faker.internet.email());
   I.fillField('Telephone', faker.phone.phoneNumberFormat());
   I.selectInDropdown('Status', 'Active');                     // Use custom methods
-  I.retry(2).click('Create');                                 // Retry flaky step
+  I.click('Create', step.retry(2));                           // Retry flaky step
   I.waitInUrl('/settings/setup/stores');                      // Explicit waiter
   I.see(storeName, '.settings');                              // Assert text present inside an element (located by CSS)
   const storeId = await I.grabTextFrom('#store-id');          // Use await to get information from browser

package/docs/installation.md

@@ -60,26 +60,9 @@ W3C WebDriver — runs Chrome, Firefox, Edge, Safari, and remote or cloud grids.
 npm i webdriverio --save-dev
 ```
 
-WebDriver talks to a Selenium server (or a cloud grid). Pick one:
+WebdriverIO 9 downloads and starts the matching driver automatically — no Selenium server, ChromeDriver, or GeckoDriver to install or run. Just set `browser` (`chrome`, `firefox`, `MicrosoftEdge`, `safari`) in `codecept.conf.js` — see the [WebDriver helper](/webdriver).
 
-- **[`selenium-standalone`](https://www.npmjs.com/package/selenium-standalone)** — one npm package that installs and runs Selenium with ChromeDriver and GeckoDriver:
-
-  ```sh
-  npm i selenium-standalone --save-dev
-  npx selenium-standalone install
-  npx selenium-standalone start
-  ```
-
-- **[Docker](https://github.com/SeleniumHQ/docker-selenium)** — a headless Selenium + browser container:
-
-  ```sh
-  docker run --net=host --shm-size=2g selenium/standalone-chrome
-  # or selenium/standalone-firefox
-  ```
-
-- **A cloud grid** — Sauce Labs, BrowserStack, LambdaTest, and so on. Set the grid's `host`, `port`, `user`, and `key` (or `protocol` / `path`) in the helper config.
-
-Set `browser` (`chrome`, `firefox`, `MicrosoftEdge`, `safari`) and the server `host` / `port` in `codecept.conf.js` — see the [WebDriver helper](/webdriver). For running this on CI, see [Continuous Integration](/continuous-integration).
+To run against a cloud grid (Sauce Labs, BrowserStack, LambdaTest, and so on) instead, set the grid's `host`, `port`, `user`, and `key` (or `protocol` / `path`) in the helper config. For running this on CI, see [Continuous Integration](/continuous-integration).
 
 ## Appium (mobile)
 

package/docs/locators.md

@@ -22,7 +22,7 @@ I.click({ role: 'button', name: 'Submit' }, '#login-form')
 
 The context narrows the search to one region of the page, and the semantic string says what the user actually clicks. This is **more precise than ARIA or CSS alone** because it combines structural scope with human-readable intent.
 
-Supported strategies: `css`, `xpath`, `id`, `name`, `role`, `frame`, `shadow`, `pw`. Shadow DOM and React selectors have their own pages — see [Shadow DOM](/shadow) and [React](/react). Playwright-specific locators use the `pw` strategy: `{ pw: '[data-testid="save"]' }`.
+Supported strategies: `css`, `xpath`, `id`, `name`, `role`, `frame`, `shadow`, `pw`. Shadow DOM has its own page — see [Shadow DOM](/shadow). Playwright-specific locators use the `pw` strategy: `{ pw: '[data-testid="save"]' }`. To test components by their accessible role, use [ARIA locators](#aria-locators).
 
 ## Locator types at a glance
 

package/docs/migrate-from-cypress.md

@@ -0,0 +1,98 @@
+---
+permalink: /migrate-from-cypress
+title: Migrate from Cypress to CodeceptJS
+---
+
+# Migrate from Cypress to CodeceptJS
+
+## Start here: what Cypress boxes you into
+
+A Cypress test runs inside the browser, in the same tab as your app. That keeps a simple test short, but it fixes the test to one tab, one browser, and one origin. A second tab, a second logged-in user, a different domain, or an API call between two clicks each needs a special workaround: `cy.origin`, `cy.session`, request plumbing, tab stubbing. Cross-browser is limited the same way: Chromium first, WebKit partial.
+
+CodeceptJS runs the test in Node and controls the browser from the outside. The test is a normal Node script, so a second tab, a second user, an API call in the middle of a flow, and Firefox or WebKit are ordinary steps instead of workarounds. It drives the browser through Playwright by default, or Puppeteer or WebDriver if you prefer.
+
+Migrating a Cypress suite looks like a lot of work. It is not. We prepared a set of skills, so you can relax and [let an agent do the migration](#let-an-agent-do-the-migration).
+
+## Comparison
+
+The original test in Cypress:
+
+```js
+// Cypress
+it('user can log in', () => {
+  cy.visit('/login');
+  cy.get('#username').type('alice');
+  cy.get('#password').type('secret');
+  cy.contains('Sign in').click();
+  cy.url().should('include', '/dashboard');
+  cy.contains('.welcome', 'Welcome, Alice');
+});
+```
+
+Will look in CodeceptJS:
+
+```js
+// CodeceptJS
+Scenario('user can log in', ({ I }) => {
+  I.amOnPage('/login');
+  I.fillField('Username', 'alice');
+  I.fillField('Password', 'secret');
+  I.click('Sign in');
+  I.seeInCurrentUrl('/dashboard');
+  I.see('Welcome, Alice', '.welcome');
+});
+```
+
+Cypress commands run on a `.then()` queue, so any condition or loop becomes nested callbacks. CodeceptJS is **async/await native**: complex tests stay flat JavaScript, and shared steps move into built-in page objects.
+
+And here is how the test looks while it runs. Every step is printed live, in the same order it was written:
+
+```text
+user can log in
+  I am on page "/login"
+  I fill field "Username", "alice"
+  I fill field "Password", "secret"
+  I click "Sign in"
+  I see in current url "/dashboard"
+  I see "Welcome, Alice", ".welcome"
+```
+
+When a step fails, the output stays on that line, with the locator that missed and a screenshot attached. There is no separate report step before you know what happened.
+
+## Let an agent do the migration
+
+The conversions are mechanical, so you do not have to do them by hand, and the work does not cost you working time. Install the skills bundle, point an agent at the repo, and check back when it reports.
+
+The **`migrate-cypress-to-codeceptjs`** skill in the [CodeceptJS skills bundle](https://github.com/codeceptjs/skills) does the whole port:
+
+1. Inventories the shared logic, custom commands, and page modules.
+2. Sets up CodeceptJS beside the Cypress suite.
+3. Ports the custom commands and page objects.
+4. Converts each spec.
+5. Runs the full suite.
+
+First runs fail, because locators drift and timing changes. The agent then uses the `debugging-codeceptjs-tests` skill to fix each failure against the live browser before moving on. Your Cypress suite keeps running in CI until the port is green, so nothing is at risk while the agent works.
+
+Install the bundle in Claude Code:
+
+```text
+/plugin marketplace add codeceptjs/skills
+/plugin install codeceptjs@codeceptjs-skills
+```
+
+Or any other agent:
+
+```bash
+npx skills add codeceptjs/skills
+```
+
+Then ask: *"Migrate this Cypress suite to CodeceptJS."* The skill triggers on the Cypress signatures in your repo. Start it, do other work, and read the step output when it reports back.
+
+## Pointers
+
+- [/agents](/agents) for how the agent and MCP loop works
+- [/playwright](/playwright) for the default helper in this migration
+- [/locators](/locators) for semantic, ARIA, and `locate()` locators
+- [/auth](/auth) for replacing `cy.session()` and programmatic login
+- [/api](/api) for the REST helper used in `cy.request` ports
+- [/pageobjects](/pageobjects) for ported page objects

package/docs/migrate-from-java.md

@@ -0,0 +1,108 @@
+---
+permalink: /migrate-from-java
+title: Migrate from Java Selenium to CodeceptJS
+---
+
+# Migrate from Java Selenium to CodeceptJS
+
+## Start here: what changes when you leave the JVM
+
+On the JVM, an end-to-end suite is basically its own product. It has its own Maven or Gradle build, its own dependencies, and a JVM that has to warm up before anything runs. In practice it ends up with its own team too — application engineers stay on the app, QA stays on the tests, and the suite drifts whenever nobody is watching it.
+
+In Node there is no compile or build step. Running tests in NodeJS saves time. NodeJS ecosystem is fastest growing opensource ecosystem, with awesome depenency management tools like npm, bun, pnpm. While Java tests still work JS ecosystem is richer and easier to use. Tools like Playwright and Puppeteer originally started on NodeJS.
+
+Even migrating from Java to JavaScript seems like a huge task, it is actually not.
+We prepared a set of skills for, so you can relax and 
+[let an agent do the migration](#let-an-agent-do-the-migration).
+
+## Comparison
+
+The original test in Java Selenium:
+
+```java
+// Java + Selenium + JUnit
+@Test
+public void userCanLogin() {
+    WebDriver driver = new ChromeDriver();
+    WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));
+
+    driver.get("https://example.com/login");
+    wait.until(ExpectedConditions.visibilityOfElementLocated(By.id("username")));
+
+    driver.findElement(By.id("username")).sendKeys("alice");
+    driver.findElement(By.id("password")).sendKeys("secret");
+    driver.findElement(By.cssSelector("button[type=submit]")).click();
+
+    wait.until(ExpectedConditions.urlContains("/dashboard"));
+    WebElement welcome = wait.until(
+        ExpectedConditions.visibilityOfElementLocated(By.cssSelector(".welcome"))
+    );
+    assertEquals("Welcome, Alice", welcome.getText());
+}
+```
+
+Will look in CodeceptJS:
+
+```js
+// CodeceptJS
+Scenario('user can log in', ({ I }) => {
+  I.amOnPage('/login');
+  I.fillField('Username', 'alice');
+  I.fillField('Password', 'secret');
+  I.click('Sign in');
+  I.seeInCurrentUrl('/dashboard');
+  I.see('Welcome, Alice', '.welcome');
+});
+```
+
+And here is how this test looks while running — every step is printed live, in the same order it was written:
+
+```text
+user can log in
+  I am on page "/login"
+  I fill field "Username", "alice"
+  I fill field "Password", "secret"
+  I click "Sign in"
+  I see in current url "/dashboard"
+  I see "Welcome, Alice", ".welcome"
+```
+
+## Let an agent do the migration
+
+The conversions above are mechanical, so you do not have to do them by hand, and the work does not cost you working time. Install the skills bundle, point an agent at the repo, and check back when it reports.
+
+The **`migrate-selenium-java-to-codeceptjs`** skill in the [CodeceptJS skills bundle](https://github.com/codeceptjs/skills) does the whole port:
+
+1. Inventories the page objects, helper classes, hooks, and data providers.
+2. Sets up CodeceptJS beside the Java suite with the WebDriver helper.
+3. Ports the page objects and helpers.
+4. Converts each spec.
+5. Runs the full suite.
+
+First runs fail, because locators drift and timing changes. The agent then uses the `debugging-codeceptjs-tests` skill to fix each failure against the live browser before moving on. Your Java suite keeps running in CI until the port is green, so nothing is at risk while the agent works.
+
+Install the bundle in Claude Code:
+
+```text
+/plugin marketplace add codeceptjs/skills
+/plugin install codeceptjs@codeceptjs-skills
+```
+
+Or any other agent:
+
+```bash
+npx skills add codeceptjs/skills
+```
+
+Then ask: *"Migrate this Java Selenium suite to CodeceptJS."* The skill triggers on the Maven or Gradle and `org.openqa.selenium` signatures in your repo. Start it, do other work, and read the step output when it reports back.
+
+## Pointers
+
+- [/agents](/agents) for how the agent and MCP loop works
+- [/webdriver](/webdriver) for the default helper in this migration, with driver auto-start
+- [/playwright](/playwright) for the optional follow-up swap
+- [/locators](/locators) for semantic, ARIA, and `locate()` locators
+- [/pageobjects](/pageobjects) for ported `@FindBy` page objects
+- [/auth](/auth) for login and session reuse
+- [/api](/api) for the REST helper used in RestAssured ports
+- [/bdd](/bdd) for CodeceptJS BDD in Cucumber-JVM ports

package/docs/migrate-from-protractor.md

@@ -0,0 +1,101 @@
+---
+permalink: /migrate-from-protractor
+title: Migrate from Protractor to CodeceptJS
+---
+
+# Migrate from Protractor to CodeceptJS
+
+## Start here: a dead dependency with an Angular wrapper
+
+Protractor was end-of-lifed in April 2023 and has shipped nothing since. Its design wrapped Selenium with two things: `waitForAngular`, which blocked each action until Angular's digest cycle settled, and the ControlFlow promise manager, which ordered commands so test code could be written as if it were synchronous. That is why a Protractor suite pins an old Selenium version and threads results through `.then()`. The dependency only ages from here.
+
+CodeceptJS drops the Angular coupling. The helper waits on the element you are acting on, not on Angular's digest, so the same test works on an Angular app, a React app, or a static page. It still speaks the WebDriver protocol, so an existing Selenium Grid keeps serving the new suite, or you switch the config to Playwright and run the same test code faster.
+
+Migrating a Protractor suite looks like a lot of work. It is not. We prepared a set of skills, so you can relax and [let an agent do the migration](#let-an-agent-do-the-migration).
+
+## Comparison
+
+The original test in Protractor:
+
+```js
+// Protractor + Jasmine
+describe('login', function () {
+  it('user can log in', function () {
+    browser.get('https://example.com/login');
+    element(by.model('user.email')).sendKeys('alice@example.com');
+    element(by.model('user.password')).sendKeys('secret');
+    element(by.css('button[type=submit]')).click();
+    expect(browser.getCurrentUrl()).toContain('/dashboard');
+    expect(element(by.css('.welcome')).getText()).toContain('Welcome, Alice');
+  });
+});
+```
+
+Will look in CodeceptJS:
+
+```js
+// CodeceptJS
+Scenario('user can log in', ({ I }) => {
+  I.amOnPage('/login');
+  I.fillField('Email', 'alice@example.com');
+  I.fillField('Password', 'secret');
+  I.click('Sign in');
+  I.seeInCurrentUrl('/dashboard');
+  I.see('Welcome, Alice', '.welcome');
+});
+```
+
+The `describe`/`it` nesting, the `by.model` strategy, and the Jasmine assertions are gone. The steps read as a sequence instead of a chain of `.then()` calls.
+
+And here is how the test looks while it runs. Every step is printed live, in the same order it was written:
+
+```text
+user can log in
+  I am on page "/login"
+  I fill field "Email", "alice@example.com"
+  I fill field "Password", "secret"
+  I click "Sign in"
+  I see in current url "/dashboard"
+  I see "Welcome, Alice", ".welcome"
+```
+
+When a step fails, the output stays on that line, with the locator that missed and a screenshot attached. There is no separate report step before you know what happened.
+
+## Let an agent do the migration
+
+The conversions are mechanical, so you do not have to do them by hand, and the work does not cost you working time. Install the skills bundle, point an agent at the repo, and check back when it reports.
+
+The **`migrate-protractor-to-codeceptjs`** skill in the [CodeceptJS skills bundle](https://github.com/codeceptjs/skills) does the whole port:
+
+1. Inventories the page objects, shared helpers, and config hooks.
+2. Sets up CodeceptJS beside the Protractor suite.
+3. Ports the page objects and helpers.
+4. Converts each spec.
+5. Runs the full suite.
+
+First runs fail, because locators drift and timing changes. The agent then uses the `debugging-codeceptjs-tests` skill to fix each failure against the live browser before moving on. Your Protractor suite keeps running in CI until the port is green, so nothing is at risk while the agent works.
+
+Install the bundle in Claude Code:
+
+```text
+/plugin marketplace add codeceptjs/skills
+/plugin install codeceptjs@codeceptjs-skills
+```
+
+Or any other agent:
+
+```bash
+npx skills add codeceptjs/skills
+```
+
+Then ask: *"Migrate this Protractor suite to CodeceptJS."* The skill triggers on the Protractor signatures in your repo. Start it, do other work, and read the step output when it reports back.
+
+## Pointers
+
+- [/agents](/agents) for how the agent and MCP loop works
+- [/playwright](/playwright) for the recommended target helper
+- [/webdriver](/webdriver) for the target if you keep a Selenium Grid
+- [/locators](/locators) for semantic, ARIA, `locate()`, and the `customLocator` plugin
+- [/pageobjects](/pageobjects) for ported Protractor page objects
+- [/auth](/auth) for programmatic login and session reuse
+- [/api](/api) for the REST helper used in HTTP-call ports

package/docs/migrate-from-testcafe.md

@@ -0,0 +1,99 @@
+---
+permalink: /migrate-from-testcafe
+title: Migrate from TestCafe to CodeceptJS
+---
+
+# Migrate from TestCafe to CodeceptJS
+
+## Start here: what the proxy costs you
+
+TestCafe does not drive a browser through a driver. It runs a proxy in front of the browser, rewrites every page and script as they load, and injects its automation into the rewritten page. That worked when it was built, but the web platform now fights it. Content Security Policy blocks the injected script. HSTS, SameSite cookies, and COOP/COEP assume the origin the browser actually requested, not a proxied one. Service workers cache the rewritten responses. The proxy has more to paper over every release, and every action in a test needs its own `await` because each one is a round trip through the injected runtime.
+
+CodeceptJS drives a real browser through a driver: Playwright over CDP, across the same Chromium, Firefox, and WebKit engines TestCafe targeted, with nothing in the request path. The page the test sees is the page the server sent, so there is nothing to rewrite and nothing for the platform to break. Actions queue internally, so they read top to bottom without `await` on every line.
+
+Migrating a TestCafe suite looks like a lot of work. It is not. We prepared a set of skills, so you can relax and [let an agent do the migration](#let-an-agent-do-the-migration).
+
+## Comparison
+
+The original test in TestCafe:
+
+```js
+// TestCafe
+fixture`Login`.page`https://example.com/login`;
+
+test('user can log in', async t => {
+  await t.typeText(Selector('#username'), 'alice');
+  await t.typeText(Selector('#password'), 'secret');
+  await t.click(Selector('button').withText('Sign in'));
+  await t.expect(getLocation()).contains('/dashboard');
+  await t.expect(Selector('.welcome').innerText).contains('Welcome, Alice');
+});
+```
+
+Will look in CodeceptJS:
+
+```js
+// CodeceptJS
+Scenario('user can log in', ({ I }) => {
+  I.amOnPage('/login');
+  I.fillField('Username', 'alice');
+  I.fillField('Password', 'secret');
+  I.click('Sign in');
+  I.seeInCurrentUrl('/dashboard');
+  I.see('Welcome, Alice', '.welcome');
+});
+```
+
+Every `await`, every `t`, and every `Selector` is gone. The steps read as a sequence instead of a chain of awaited calls.
+
+And here is how the test looks while it runs. Every step is printed live, in the same order it was written:
+
+```text
+user can log in
+  I am on page "/login"
+  I fill field "Username", "alice"
+  I fill field "Password", "secret"
+  I click "Sign in"
+  I see in current url "/dashboard"
+  I see "Welcome, Alice", ".welcome"
+```
+
+When a step fails, the output stays on that line, with the locator that missed and a screenshot attached. There is no separate report step before you know what happened.
+
+## Let an agent do the migration
+
+The conversions are mechanical, so you do not have to do them by hand, and the work does not cost you working time. Install the skills bundle, point an agent at the repo, and check back when it reports.
+
+The **`migrate-testcafe-to-codeceptjs`** skill in the [CodeceptJS skills bundle](https://github.com/codeceptjs/skills) does the whole port:
+
+1. Inventories the shared logic: `Role` setup, `ClientFunction` wrappers, page models, and request mocks.
+2. Sets up CodeceptJS beside the TestCafe suite with the Playwright helper.
+3. Ports the abstractions into custom helpers and page objects.
+4. Converts each spec.
+5. Runs the full suite.
+
+First runs fail, because locators drift and timing changes. The agent then uses the `debugging-codeceptjs-tests` skill to fix each failure against the live browser before moving on. Your TestCafe suite keeps running in CI until the port is green, so nothing is at risk while the agent works.
+
+Install the bundle in Claude Code:
+
+```text
+/plugin marketplace add codeceptjs/skills
+/plugin install codeceptjs@codeceptjs-skills
+```
+
+Or any other agent:
+
+```bash
+npx skills add codeceptjs/skills
+```
+
+Then ask: *"Migrate this TestCafe suite to CodeceptJS."* The skill triggers on the TestCafe signatures in your repo. Start it, do other work, and read the step output when it reports back.
+
+## Pointers
+
+- [/agents](/agents) for how the agent and MCP loop works
+- [/playwright](/playwright) for the default helper in this migration
+- [/locators](/locators) for semantic, ARIA, and `locate()` locators in place of `Selector` chains
+- [/auth](/auth) for the plugin that replaces `Role` and `t.useRole`
+- [/api](/api) for the REST helper used in API testing
+- [/pageobjects](/pageobjects) for ported page objects