codeceptjs 4.0.0-rc.2 → 4.0.0-rc.20

package/docs/test-structure.md

@@ -0,0 +1,275 @@
+---
+permalink: /test-structure
+title: Test Structure
+---
+
+# Test Structure
+
+A CodeceptJS test file contains one **Feature** (suite) and one or more **Scenarios** (tests).
+
+```js
+Feature('User Authentication')
+
+Scenario('user logs in', ({ I }) => {
+  I.amOnPage('/login')
+  I.fillField('Email', 'user@example.com')
+  I.fillField('Password', secret('123456'))
+  I.click('Sign In')
+  I.see('Welcome')
+})
+```
+
+## Feature
+
+`Feature(title, config?)` declares a suite. Each test file contains exactly one Feature.
+
+```js
+Feature('User Authentication')
+```
+
+An optional config object sets defaults for all scenarios:
+
+```js
+Feature('Payment Processing', {
+  retries: 2,
+  timeout: 30000
+})
+```
+
+Available options:
+
+- `retries` — number of times to retry failed scenarios before marking as failed (see [Retry Mechanisms](/retry))
+- `timeout` — maximum time in milliseconds for each scenario to complete (see [Timeouts](/advanced#timeout))
+- `retryBefore` — number of times to retry the Before hook if it fails
+- `retryAfter` — number of times to retry the After hook if it fails
+- `retryBeforeSuite` — number of times to retry the BeforeSuite hook if it fails
+- `retryAfterSuite` — number of times to retry the AfterSuite hook if it fails
+
+> Unlike Mocha/Jest, nesting suites is not allowed — each file maps to exactly one feature.
+
+## Scenario
+
+`Scenario(title, config?, fn)` declares a test. The function receives an object with `I` (the actor), `test` object, and any page objects declared in `include` config:
+
+```js
+Scenario('guest checkout', ({ I, checkoutPage }) => {
+  checkoutPage.open()
+  I.see('Order Summary')
+})
+```
+
+Access the `test` object to store metadata and artifacts for custom reporting:
+
+```js
+Scenario('payment processing', ({ I, test }) => {
+  test.meta.transactionId = '12345'
+  test.artifacts.receipt = 'receipts/order-12345.pdf'
+  I.amOnPage('/checkout')
+})
+```
+
+Available properties:
+
+- `test.title` — test name
+- `test.tags` — extracted tags from test name (e.g., `@smoke`, `@critical`)
+- `test.steps` — array of executed steps
+- `test.artifacts` — store screenshots, videos, logs, or files
+- `test.meta` — custom metadata for reporters
+- `test.notes` — array for adding notes or annotations
+- `test.file` — path to test file
+- `test.state` — current state (pending, passed, failed)
+- `test.duration` — execution time in milliseconds
+- `test.fullTitle()` — full title including suite name
+
+An optional config object can customize the scenario:
+
+```js
+Scenario('slow test', { 
+  timeout: 60000, 
+  retries: 3 
+}, ({ I }) => {
+  // ...
+})
+```
+
+Available options:
+
+- `timeout` — maximum time in milliseconds for scenario to complete (see [Timeouts](/timeouts))
+- `retries` — number of times to retry the scenario if it fails (see [Retry Mechanisms](/retry))
+- `meta` — metadata object with key-value pairs for reporting or filtering
+- `[helperName]` — helper-specific configuration (e.g., `Playwright: { headless: false }`)
+- `cookies` — pre-loaded cookies for authentication (used by auth plugin)
+- `user` — user identifier for session management (used by auth plugin)
+- `disableRetryFailedStep` — disable automatic step retries for this scenario
+
+### Dynamic Configuration
+
+Override helper config for a single scenario using `.config()`:
+
+```js
+Scenario('run in firefox', ({ I }) => {
+  // ...
+}).config({ browser: 'firefox' })
+```
+
+To target a specific helper, pass its name as the first argument:
+
+```js
+Scenario('use v2 API', ({ I }) => {
+  // ...
+}).config('REST', { endpoint: 'https://api.mysite.com/v2' })
+```
+
+Pass a function to derive config from the test object — useful for cloud providers:
+
+```js
+Scenario('report to BrowserStack', ({ I }) => {
+  // ...
+}).config((test) => ({
+  desiredCapabilities: {
+    project: test.suite.title,
+    name: test.title,
+  }
+}))
+```
+
+Apply config to all scenarios in a suite via `Feature`:
+
+```js
+Feature('Admin Panel').config({ url: 'https://mysite.com/admin' })
+```
+
+Config changes are reverted after the test or suite completes. Some options — such as `browser` when `restart: false` — cannot be changed after the browser has started.
+
+### Data-Driven Scenarios
+
+Use `Data().Scenario` to run the same scenario with multiple datasets:
+
+```js
+const users = new DataTable(['role', 'email'])
+users.add(['admin', 'admin@example.com'])
+users.add(['user', 'user@example.com'])
+
+Data(users).Scenario('user can log in', ({ I, current }) => {
+  I.fillField('Email', current.email)
+  I.click('Login')
+  I.see(`Logged in as ${current.role}`)
+})
+```
+
+> ▶ See [Data Driven Tests](/data) for more details.
+
+### Tags
+
+Append a tag to the scenario title:
+
+```js
+Scenario('update user profile @slow', ...)
+```
+
+Or use the `tag()` method:
+
+```js
+Scenario('update user profile', ({ I }) => {
+  // ...
+}).tag('@slow').tag('important')
+```
+
+Run tagged tests with `--grep`:
+
+```sh
+npx codeceptjs run --grep '@slow'
+```
+
+Use regex for complex filtering:
+
+```sh
+# both @smoke2 and @smoke3
+npx codeceptjs run --grep '(?=.*@smoke2)(?=.*@smoke3)'
+# @smoke2 or @smoke3
+npx codeceptjs run --grep '@smoke2|@smoke3'
+# all except @smoke4
+npx codeceptjs run --grep '(?=.*)^(?!.*@smoke4)'
+```
+
+### Skipping & Focusing
+
+```js
+xScenario('skipped test', ...)       // skip
+Scenario.skip('skipped test', ...)   // skip
+Scenario.only('focused test', ...)   // run only this test
+
+xFeature('Skipped Suite')            // skip entire file
+Feature.skip('Skipped Suite')        // skip entire file
+Feature.only('Run Only This Suite')  // focus entire file
+```
+
+### Todo Scenarios
+
+Mark scenarios as planned but not yet implemented:
+
+```js
+Scenario.todo('user can reset password')
+
+Scenario.todo('user can change avatar', ({ I }) => {
+  /**
+   * 1. Open profile settings
+   * 2. Upload new avatar
+   * Result: avatar is updated
+   */
+})
+```
+
+## Hooks
+
+### Before / After
+
+Run code before or after **each scenario** in the file:
+
+```js
+Before(({ I }) => {
+  I.amOnPage('/')
+})
+
+After(({ I }) => {
+  I.clearCookie()
+})
+```
+
+These are equivalent to `beforeEach` / `afterEach` in Mocha/Jest.
+
+Hooks can be retried on failure:
+
+```js
+Before(({ I }) => {
+  I.amOnPage('/dashboard')
+}).retry(3)
+```
+
+### BeforeSuite / AfterSuite
+
+Run code once before or after **all scenarios** in the file — equivalent to `beforeAll` / `afterAll`:
+
+```js
+BeforeSuite(async ({ I }) => {
+  // seed test data before any scenario runs
+  await I.executeScript(() => window.resetDatabase())
+})
+
+AfterSuite(async ({ I }) => {
+  await I.executeScript(() => window.cleanupDatabase())
+})
+```
+
+> **Note:** The browser is available in `BeforeSuite` when using Playwright or Puppeteer helpers.
+
+Hooks can also be configured at Feature level:
+
+```js
+Feature('My Suite', {
+  retryBefore: 3,
+  retryBeforeSuite: 2,
+  retryAfter: 1,
+  retryAfterSuite: 3,
+})
+```

package/docs/timeouts.md

@@ -0,0 +1,183 @@
+---
+permalink: /timeouts
+title: Timeouts
+---
+
+# Timeouts
+
+CodeceptJS provides multiple timeout configurations to control test execution time at different levels.
+
+## Step Timeout
+
+Set timeout for individual steps using `step.timeout()`:
+
+```js
+import step from 'codeceptjs/steps'
+
+Scenario('test with step timeouts', ({ I }) => {
+  I.amOnPage('/')
+  I.click('Slow Button', step.timeout(30))
+  I.fillField('Email', 'user@example.com', step.timeout(10))
+})
+```
+
+## Scenario Timeout
+
+Override timeout for specific scenarios:
+
+```js
+Scenario('quick test', { timeout: 5 }, ({ I }) => {
+  I.amOnPage('/')
+})
+
+Scenario('slow test', { timeout: 120 }, ({ I }) => {
+  I.amOnPage('/dashboard')
+})
+```
+
+## Feature Timeout
+
+Set timeout for all scenarios in a feature:
+
+```js
+Feature('Slow Operations', { timeout: 60 })
+
+Scenario('first test', ({ I }) => {
+  // has 60 second timeout
+})
+
+Scenario('second test', ({ I }) => {
+  // has 60 second timeout
+})
+```
+
+## Global Timeout
+
+Set default timeout for all tests in `codecept.conf.js`:
+
+```js
+export const config = {
+  timeout: 10  // 10 seconds for all tests
+}
+```
+
+Use advanced configuration with grep patterns for conditional timeouts:
+
+```js
+export const config = {
+  timeout: [
+    10,  // default timeout
+    {
+      grep: '@slow',
+      Feature: 60  // 60 seconds for features tagged @slow
+    },
+    {
+      grep: /critical/,
+      Scenario: 30  // 30 seconds for scenarios matching pattern
+    }
+  ]
+}
+```
+
+## Helper Timeouts
+
+Each helper (Playwright, Puppeteer, WebDriver, Appium, REST) has its own timeout settings for browser actions, API requests, and element interactions. These are configured separately from test timeouts and are measured in milliseconds.
+
+Refer to helper-specific documentation for timeout configuration:
+
+- [Playwright Helper](/helpers/Playwright) — `timeout`, `waitForTimeout`, `getPageTimeout`
+- [Puppeteer Helper](/helpers/Puppeteer) — `waitForTimeout`, `getPageTimeout`
+- [WebDriver Helper](/helpers/WebDriver) — `waitForTimeout`, `smartWait`, `timeouts` object
+- [Appium Helper](/helpers/Appium) — `timeouts` object
+- [REST Helper](/helpers/REST) — `timeout`
+
+## stepTimeout Plugin
+
+Automatically apply timeouts to all steps:
+
+```js
+plugins: {
+  stepTimeout: {
+    enabled: true,
+    timeout: 150,                // default step timeout in seconds
+    overrideStepLimits: false,   // override step.timeout() if true
+    noTimeoutSteps: [
+      'amOnPage',
+      'wait*'                    // wildcard patterns supported
+    ],
+    customTimeoutSteps: [
+      ['slowAction*', 30],       // 30 seconds for matching steps
+      [/critical.*/, 60]         // regex patterns supported
+    ]
+  }
+}
+```
+
+### Timeout Priority
+
+When multiple timeouts are configured, CodeceptJS applies them in priority order:
+
+1. **stepTimeoutHard** — plugin with `overrideStepLimits: true`
+2. **codeLimitTime** — `step.timeout()` or `I.limitTime()`
+3. **stepTimeoutSoft** — plugin with `overrideStepLimits: false`
+4. **testOrSuite** — global test/suite timeout
+
+Higher priority timeouts override lower priority ones.
+
+## Disabling Timeouts
+
+Disable all timeouts for debugging:
+
+```bash
+npx codeceptjs run --no-timeouts
+```
+
+## Complete Example
+
+```js
+// codecept.conf.js
+export const config = {
+  timeout: [
+    10,
+    { grep: '@slow', Feature: 60 },
+    { grep: '@critical', Scenario: 30 }
+  ],
+  
+  helpers: {
+    Playwright: {
+      timeout: 5000,
+      waitForTimeout: 1000,
+      getPageTimeout: 30000
+    }
+  },
+  
+  plugins: {
+    stepTimeout: {
+      enabled: true,
+      timeout: 150,
+      noTimeoutSteps: ['amOnPage', 'wait*'],
+      customTimeoutSteps: [
+        ['slowAction*', 30]
+      ]
+    }
+  }
+}
+```
+
+```js
+// test file
+import step from 'codeceptjs/steps'
+
+Feature('User Management @slow', { timeout: 60 })
+
+Scenario('create user', { timeout: 20 }, ({ I }) => {
+  I.amOnPage('/users')
+  I.click('Create', step.timeout(10))
+  I.fillField('Name', 'John', step.timeout(5).retry(2))
+})
+```
+
+## Timeout Units
+
+- **Global, Feature, Scenario, Step, stepTimeout plugin** — seconds
+- **Helper timeouts** — milliseconds

package/docs/translation.md

@@ -0,0 +1,247 @@
+---
+permalink: /translation
+title: Translation
+---
+
+# Translation 
+
+*Unique feature of CodeceptJS: write tests in your language!*
+
+🇩🇪🇯🇵🇫🇷🇹🇼🇨🇳🇵🇱🇧🇷🇮🇹
+
+Test output and the way tests are written can be localized. This way scenarios can be written in almost native language using UTF support of JavaScript.
+
+If you have non-English team and you work on non-English project consider enabling translation
+by setting translation to [one of available languages](https://github.com/codeceptjs/CodeceptJS/blob/3.x/translations) or writing vocabulary for your language.
+
+## How it works
+
+CodceptJS provides a high-level domain specific language (DSL) for writing end-to-end tests. 
+As CodeceptJS API is designed to provide a minimal set of methods to write test cases of any kind of complexity.
+
+It is possible to add aliases for all CodeceptJS keywords and methods. So if all keywords and methods are translated to a specific language it is possible to write tests in that language. Sure, this is not perfect, as CSS/XPath locators as well as REST API speific words are used as is. However, writing tests in your native language may improve the team's understanding of the test behavior.
+
+You can enable translation if your team is not from English-speaking country developing non-English product.
+
+> ⚠️ It's important to note that default translations are far from being complete. So there are still lots of methods and keywords not translated to your language yet. We recommend to [extend a vocabulary](#extending-vocabulary) to add aliases for non-translated methods and submit a pull request with improvements to a [corresponding language file](https://github.com/codeceptjs/CodeceptJS/blob/3.x/translations).
+
+To enable translition create a new project with 
+
+```
+npx codeceptjs init
+```
+
+And select a language of your choice from a list:
+
+```
+? Do you want localization for tests? (See https://codecept.io/translation/)
+❯ English (no localization) 
+  de-DE 
+  it-IT 
+  fr-FR 
+  ja-JP 
+  pl-PL 
+  pt-BR 
+(Move up and down to reveal more choices)
+```
+> 💡 If you don't see your language in the list but still want to use localized tests, select 'English (no localization)' and create [custom translation](#custom-translation).
+
+
+## Languages
+
+### Portuguese 🇧🇷
+
+To write your tests in portuguese you can enable the portuguese translation in config file like:
+
+```js
+  translation: "pt-BR"
+```
+
+Now you can write test like this:
+
+```js
+Cenário('Efetuar login', ({ Eu }) => {
+    Eu.estouNaPagina('http://minhaAplicacao.com.br');
+    Eu.preenchoOCampo("login", "usuario@minhaAplicacao.com.br");
+    Eu.preenchoOCampo("senha", "123456");
+    Eu.clico("Entrar");
+    Eu.vejo("Seja bem vindo usuário!");
+});
+```
+
+### French 🇫🇷
+
+To write your tests in French you can enable the French translation by adding to config:
+
+```js
+  translation: "fr-FR"
+```
+
+Now you can write tests like this:
+
+```js
+Scenario('Se connecter sur GitHub', (Je) => {
+    Je.suisSurLaPage('https://github.com/login');
+    Je.remplisLeChamp("Username or email address", "jean-dupond");
+    Je.remplisLeChamp("Password", "*********");
+    Je.cliqueSur("Sign in");
+    Je.vois("Learn Git and GitHub without any code!");
+});
+```
+
+### Italian 🇮🇹
+
+Add to `codeceptjs.conf.js` or `codeceptjs.conf.ts` config file:
+
+```js
+  translation: "it-IT"
+```
+
+Now you can write test like this:
+
+```js
+Caratteristica('Effettuare il Login su GitHub', (io) => {
+    io.sono_sulla_pagina('https://github.com/login');
+    io.compilo_il_campo("Username or email address", "giuseppe-santoro");
+    io.compilo_il_campo("Password", "*********");
+    io.faccio_click_su("Sign in");
+    io.vedo("Learn Git and GitHub without any code!");
+});
+```
+
+### Polish 🇵🇱
+
+Add to `codeceptjs.conf.js` or `codeceptjs.conf.ts` config file:
+
+```js
+  translation: "pl-PL"
+```
+
+Now you can write test like this:
+
+```js
+Scenario('Zakładanie konta free trial na stronie głównej GetResponse', ({ Ja }) => {
+    Ja.jestem_na_stronie('https://getresponse.com');
+    Ja.wypełniam_pole("Email address", "sjakubowski@getresponse.com");
+    Ja.wypełniam_pole("Password", "digital-marketing-systems");
+    Ja.klikam('Sign up');
+    Ja.czekam(1);
+    Ja.widzę_w_adresie_url('/account_free_created.html');
+});
+```
+
+### Chinese 🇹🇼🇨🇳
+
+Add to `codeceptjs.conf.js` or `codeceptjs.conf.ts` config: file:
+
+```JS
+  translation: "zh-CN"
+```
+or
+```JS
+  translation: "zh-TW"
+```
+
+This way tests can be written in Chinese language while it is still JavaScript:
+
+```JavaScript
+Feature('CodeceptJS 演示');
+
+Scenario('成功提交表单', ({ 我 }) => {
+    我.在页面('/documentation')
+    我.填写字段('电邮', 'hello@world.com')
+    我.填写字段('密码', '123456')
+    我.勾选选项('激活')
+    我.勾选选项('男');
+    我.单击('创建用户')
+    我.看到('用户名可用')
+    我.在当前网址中看不到('/documentation')
+});
+```
+or
+
+```JavaScript
+Feature('CodeceptJS 演示');
+
+Scenario('成功提交表單', ({ 我 }) => {
+    我.在頁面('/documentation')
+    我.填寫欄位('電郵', 'hello@world.com')
+    我.填寫欄位('密碼', '123456')
+    我.勾選選項('活化')
+    我.勾選選項('男');
+    我.單擊('建立用戶')
+    我.看到('用戶名可用')
+    我.在當前網址中看不到('/documentation')
+});
+```
+
+### Japanese 🇯🇵
+
+Add to `codeceptjs.conf.js` or `codeceptjs.conf.ts` config file:
+
+```js
+  translation: "ja-JP"
+```
+
+Now you can write test like this:
+
+```js
+Scenario('ログインできる', ({ 私は }) => {
+    私は.ページを移動する('/login');
+    私は.フィールドに入力する("Eメール", "foo@example.com");
+    私は.フィールドに入力する("パスワード", "p@ssword");
+    私は.クリックする('ログイン');
+    私は.待つ(1);
+    私は.URLに含まれるか確認する('/home');
+});
+```
+
+## Extending Vocabulary
+
+To add localized aliases to more actions create a new JSON or JavaScript file returning an object with following fields:
+
+```js
+export default {
+  actions: {
+    // add action aliases, translating method name to your language
+    rightClick: 'Rechtsklick'
+  }
+}
+```
+
+Then enable this vocabulary file in codecept conf:
+
+```js
+// inside codecept.conf.js or codecept.conf.ts
+// ...
+  translation: 'de_DE',
+  vocabularies: ['my_translation_file.js'],
+```
+
+### Custom Translation
+
+Create translation file like this:
+
+```js
+export default {
+  I: 'Ya',
+  contexts: {
+    Feature: 'Feature',
+    Scenario: 'Szenario',
+    Before: 'Vor',
+    After: 'Nach',
+    BeforeSuite: 'vor_der_suite',
+    AfterSuite: 'nach_der_suite',
+  },
+  actions: {
+    click: 'Klicken',
+    wait: 'Wartenn',
+  }
+```
+
+And add the file path to your config
+
+```js
+  translation: "MyLang",
+  vocabularies: ["./relative/path/to/your/translation.js"]
+```