codeceptjs 4.0.2-beta.9 → 4.0.2

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