Upgrading to CodeceptJS 3

CodeceptJS 3.0 is a new version of CodeceptJS with some breaking changes included. You should update your project following this guide to ensure that everything works correctly.

1️⃣ Syntax Change

CodeceptJS 3.0 introduced a new syntax for declaring tests, instead of:

Scenario('title', (I, loginPage) => {})

we use a new way of passing arguments into a test, via destruction:

Scenario('title', ({ I, loginPage }) => {})

This works similarly to inject() command. This change was done to unify accessing dependency injection container, and to provide better TypeScript support.

If you use BDD-style project with Gherkin, no changes needed for this step.

To upgrade your project, you don't need to change manually all your tests.

💪 Use codecept3-upgrade tool to perform the migration. Use it carefully, as it updates your current code.

To upgrade your codebase, commit all your changes, and switch to a new branch. Run upgrade script (even without installing) for a directory where you have your tests:

npx codecept3-upgrade tests

Review the changes in Git Diff and try to execute tests using CodeceptJS 3.0

2️⃣ Grabbers signature change

There were confusion and inconsistency across grab* methods. What they will return if multiple elements are found? A single element or an array? This was the problem as the format was dependent on a page content.

In 3.0 we decided to make all current grab* methods to return a single value only. While we add new methods grab**FromAll that return an array.

For instance, grabTextFrom will always return a single text value, while grabTextFromAll will return an array of values:

await I.grabTextFrom('.username'); => 'john'
await I.grabTextFromAll('.username'); => ['john', 'claudia', 'bill']

Please update parts in your project where you rely on grab* methods to return an array.

Single Value	Multiple Values
✋grabTextFrom	🙌 grabTextFromAll
✋grabValueFrom	🙌 grabValueFromAll
✋ grabAttributeFrom	🙌grabAttributeFromAll
✋ grabHTMLFrom	🙌 grabHTMLFromAll
✋ grabCssPropertyFrom	🙌 grabCssPropertyFromAll

Single-value grab*From will throw error when no data was matched, while grab*FromAll will return array.

3️⃣ Locator Detection Heuristic Change

In 3.0 we added a new rule to auto-detect CSS locator. If a locator starts with [ parser will use it as a CSS locator, without trying to match value by text.

• Previous behavior: I.click('[user]') - will try to search for a link with [user] text, if no found - take [user] as CSS locator
• Current behavior: I.click('[user]') - will check only for CSS locator [user]

WebDriverIO helper removed

WebDriverIO helper supported webdriverio v4 library, which is not maintained anymore. It should be easy to switch to WebDriver helper which supports webdriverio v6.