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

package/docs/tutorial.md

@@ -0,0 +1,271 @@
+---
+permalink: /tutorial
+title: CodeceptJS Complete Tutorial
+---
+
+# Tutorial: Writing Tests for Checkout Page
+
+**[CodeceptJS](https://codecept.io) is a popular open-source testing framework** for JavaScript. It is designed to simplify writing and maintain end-to-end tests for web applications, using a readable and intuitive syntax. To run tests in browser it uses **[Playwright](https://playwright.dev)** by default but ca execute tests via WebDriver, Puppeteer or Appium.
+
+## Let's get CodeceptJS installed!
+
+To install CodeceptJS, you will need to have Node.js and npm (the Node.js package manager) installed on your system. You can check if you already have these tools installed by running the following commands in a terminal:
+
+```bash
+node --version
+npm --version
+```
+
+If either of these commands return an error, you will need to install Node.js and npm before you can install CodeceptJS. You can download and install the latest version of Node.js from the official website, which includes npm.
+
+To install CodeceptJS create a new folder and run command form terminal:
+
+```
+npx create-codeceptjs .
+```
+
+If you run the npx create-codeceptjs . command, it will install CodeceptJS with Playwright in the current directory. 
+
+> The `npx` command is a tool that comes with npm (the Node.js package manager) and it allows you to run npm packages without having to install them globally on your system.
+
+It may take some time as it downloads browsers: Chrome, Firefox and Safari and creates a demo project.
+
+But we are here to write a checkout test, right?
+
+Let's initialize a new project for that!
+
+Run 
+
+```
+npx codeceptjs init
+```
+Agree on defaults (press Enter for every question asked). When asked for base site URL, provide a URL of a ecommerce website you are testing. For instance, it could be: `https://myshop.com` if you test already published website or `http://localhost` if you run the website locally. 
+
+When asked for a test name and suite name write "Checkout". It will create the following dirctory structure:
+
+```
+.
+├── codecept.conf.js
+├── package.json
+└── Checkout_test.js
+```
+
+The `codecept.conf.js` file in the root of the project directory contains the global configuration settings for CodeceptJS.
+
+Now open a test:
+
+```js
+Feature('Checkout');
+
+Scenario('test something', ({ I }) => {
+});
+```
+Inside the Scenario block you write a test. 
+
+Add `I.amOnPage('/')` into it. It will open the browser on a URL you specified as a base.
+
+```js
+Feature('Checkout');
+
+Scenario('test something', ({ I }) => {
+  I.amOnPage('/')
+});
+```
+But you may want to ask...
+
+## What is I?
+
+Glad you asked! 
+
+In CodeceptJS, the `I` object is used to represent the user performing actions in a test scenario. It provides a number of methods (also known as actions) that can be used to simulate user interactions with the application under test.
+
+Some of the most popular actions of the I object are:
+
+* `I.amOnPage(url)`: This action navigates the user to the specified URL.
+* `I.click(locator)`: This action simulates a click on the element identified by the given locator.
+* `I.fillField(field, value)`: This action fills the specified field with the given value.
+* `I.see(text, context)`: This action checks that the given text is visible on the page (or in the specified context).
+* `I.selectOption(select, option)`: This action selects the specified option from the given select dropdown.
+* `I.waitForElement(locator, timeout)`: This action waits for the specified element to appear on the page, up to the given timeout.
+* `I.waitForText(text, timeout, context)`: This action waits for the given text to appear on the page (or in the specified context), up to the given timeout.
+
+We will need to use them to navigate into Checkout process. How do we navigate web? Sure by clicking on links!
+
+Let's use `I.click()` for that.
+
+But how we can access elements on a webpage? 
+
+CodeceptJS is smart enough to locate clickable elements by their visible text. For instance, if on your ecommerce website you have a product 'Coffee Cup' with that exact name you can use 
+
+```js
+I.click('Coffee Cup');
+```
+
+But sometimes elements are not as easy to locate, so you can use CSS or XPath locators to locate them.
+
+For instance, locating Coffee Cup via CSS can take into accont HTML structure of a page and element attributes. For instance, it can be like this:
+
+```js
+I.click('div.products a.product-name[title="Coffee Cup"]');
+```
+
+In this example, the `div.products` part of the selector specifies a div element with the `products` class, and the `a.product-name[title="Coffee Cup"]` part specifies an a element with `the product-name` class and the `title` attribute set to Coffee Cup. 
+
+You can read more about HTML and CSS locators, and basically that's all what you need to know to start writing a checkout test!
+
+## Get back to Checkout
+
+Let's see how a regular checkout script may look in CodeceptJS:
+
+```js
+Scenario('test the checkout form', async ({ I }) => {
+  // we select one product and switched to checkout project
+  I.amOnPage('/');
+  I.click('Coffee Cup');
+  I.click('Purchase');
+  I.click('Checkout');
+
+  // fill in the shipping address
+  I.fillField('First Name', 'John');
+  I.fillField('Last Name', 'Doe');
+  I.fillField('Address', '123 Main St.');
+  I.fillField('City', 'New York');
+  I.selectOption('State', 'New York');
+  I.fillField('Zip Code', '10001');
+
+  // select a payment method
+  I.click('#credit-card-option');
+  I.fillField('Card Number', '1234-5678-9012-3456');
+  I.fillField('Expiration Date', '12/22');
+  I.fillField('Security Code', '123');
+
+  // click the checkout button
+  I.click('Checkout');
+
+  // verify that the checkout was successful
+  I.see('Your order has been placed successfully!');
+});
+``` 
+Sure, in relaity your script might be more complicated. As you have noticed, we used CSS locator `'#credit-card-option'`  to get select a payment option. However, the test is simple and you can follow user steps through it.
+
+Please note, that you shouldn't use a real credit card number here. Good news, you don't need to. Payment providers like Strip provide dummy card numbers for testing purposes. 
+
+Run the test with next command:
+
+```
+npx codeceptjs run --debug -p pause
+```
+
+What are special options here?
+
+* `--debug` flag is used to output additional information to the console, such as the details of each step in the test, the values of variables, and the results of test assertions. This can help you to identify and fix any issues in your tests.
+* `-p pause` option is also used to keep the browser opened even if a test fails (default `on=fail`). It will help us to identify to which point test was executed and what can be improved.
+
+Add more test steps if needed, update locators, and notify business owners that all that purchases are made by you so your collegues won't call you in the night asking when you want to get a coffee cup 😀 Also the good idea is to run tests on staging website, to not interfere with business process.
+
+What a test is complete you can run it with:
+
+```
+npx codeceptjs run
+```
+
+If you are annoyed to see a browser window you can use `HEADLESS` environment variable:
+
+```
+HEADLESS=true codeceptjs run
+```
+for Windows users HEADLESS should be set in a different manner:
+
+```
+set HEADLESS=true&& codeceptjs run
+```
+The tests will pass but no browser is shown, so you can watch YouTube videos while it goes!
+
+## Refactoring
+
+What if you need to check more purchases? Should you copy paste your code for that?
+
+No! You can use Page Object pattern to put repeating interactions into the reusable functions.
+
+You can create a page object via next command:
+
+```
+npx codeceptjs gpo
+```
+
+Sure, we will call it `Checkout`. It will be created in `./pages/Checkout.js` file. You should enable it in `codecept.conf.js` inside `include` section:
+
+```js
+    include: {
+    ...
+      checkoutPage: './pages/Checkout.js',
+    },
+
+```
+Now open this file:
+
+```js
+const { I } = inject();
+
+export default {
+
+  // insert your locators and methods here
+}
+```
+
+Feels really empty. What should we do about it? Should we write more code? No, we already have it. Let's copy code blocks from a test we have it and place them under a corredponnding function names:
+
+```js
+const { I } = inject();
+
+export default {
+
+  fillShippingAddress(name, address, city, state, zip) {
+    I.fillField('Name', name);
+    I.fillField('Address', address);
+    I.fillField('City', city);
+    I.fillField('State', state);
+    I.fillField('Zip', zip);
+  },
+
+  fillValidCreditCard() {
+    I.click('#credit-card-option');
+    I.fillField('Card Number', '1234-5678-9012-3456');
+    I.fillField('Expiration Date', '12/22');
+    I.fillField('Security Code', '123');
+  },
+
+  checkout() {
+    I.click('Checkout');
+  },
+}
+```
+
+After that we can update our test to use the created page object. Note, that we import Checkout PageObject by its name `checkoutPage` we previously defined in a config.
+
+```js
+Scenario('test the checkout form', async ({I, checkoutPage}) => {
+  I.amOnPage('/');
+  I.click('Coffee Cup');
+  I.click('Purchase');
+  I.click('Checkout');
+
+  // fill in the shipping address using the page object
+  checkoutPage.fillShippingAddress('John', 'Doe', '123 Main St.', 'New York', 'New York', '10001');
+  checkoutPage.fillValidCreditCard();
+  checkoutPage.checkout();
+
+  // verify that the checkout was successful
+  I.see('Your order has been placed successfully!');
+});
+```
+
+As you see the code of a test was reduced. And we can write the similar tests on the same manner.
+
+By applying more and more cases you can test a website to all behaviors.
+
+## Summary
+
+If you think on just starting test automation, CodeceptJS is the best choice for you as it uses native language to pass commands to browser. 
+
+If you already skilled in JavaScript, with CodeceptJS you can focus on business level of your test, instead of writing code for browser. This way you can keep your tests stable and maintainable.

package/docs/typescript.md

@@ -0,0 +1,374 @@
+---
+permalink: /typescript
+title: TypeScript
+---
+
+# TypeScript
+
+CodeceptJS supports [type declaration](https://github.com/codeceptjs/CodeceptJS/tree/master/typings) for [TypeScript](https://www.typescriptlang.org/). It means that you can write your tests in TS. Also, all of your custom steps can be written in TS
+
+# Why TypeScript?
+
+With the TypeScript writing CodeceptJS tests becomes much easier. If you configure TS properly in your project as well as your IDE, you will get the following features:
+- [Autocomplete (with IntelliSense)](https://code.visualstudio.com/docs/editor/intellisense) - a tool that streamlines your work by suggesting when you typing what function or property which exists in a class, what arguments can be passed to that method, what it returns, etc.
+Example:
+
+![Auto Complete](/img/Auto_comlete.gif)
+
+- To show additional information for a step in a test. Example:
+
+![Quick Info](/img/Quick_info.gif)
+
+- Checks types - thanks to TypeScript support in CodeceptJS now allow to tests your tests. TypeScript can prevent some errors:
+  - invalid type of variables passed to function;
+  - calls no-exist method from PageObject or `I` object;
+  - incorrectly used CodeceptJS features;
+
+
+## Getting Started <Badge text="Since 3.3.5" type="warning"/>
+
+CodeceptJS can initialize tests as a TypeScript project.
+When starting a new project with a standard installation via 
+
+```
+npx codeceptjs init
+``` 
+Then select TypeScript as the first question:
+
+```
+? Do you plan to write tests in TypeScript? Yes
+```
+
+Then a config file and new tests will be created in TypeScript format.
+
+If a config file is set in TypeScript format (`codecept.conf.ts`) package `ts-node` will be used to run tests. 
+
+## TypeScript Tests in ESM (CodeceptJS 4.x) <Badge text="Since 4.0.0" type="tip"/>
+
+CodeceptJS 4.x uses ES Modules (ESM) which requires a different approach for TypeScript test files. While TypeScript **config files** (`codecept.conf.ts`) are automatically transpiled, TypeScript **test files** need a loader.
+
+### Using tsx (Recommended)
+
+[tsx](https://tsx.is) is a modern, fast TypeScript loader built on esbuild. It's the recommended way to run TypeScript tests in CodeceptJS 4.x.
+
+**Installation:**
+```bash
+npm install --save-dev tsx
+```
+
+**Configuration:**
+```typescript
+// codecept.conf.ts
+export const config = {
+  tests: './**/*_test.ts',
+  require: ['tsx/cjs'],  // ← Enable TypeScript loader for test files
+  helpers: {
+    Playwright: {
+      url: 'http://localhost',
+      browser: 'chromium'
+    }
+  }
+}
+```
+
+That's it! Now you can write tests in TypeScript with full language support:
+
+```typescript
+// login_test.ts
+Feature('Login')
+
+Scenario('successful login', ({ I }) => {
+  I.amOnPage('/login')
+  I.fillField('email', 'user@example.com')
+  I.fillField('password', 'password123')
+  I.click('Login')
+  I.see('Welcome')
+})
+```
+
+**Why tsx?**
+- ⚡ **Fast:** Built on esbuild, much faster than ts-node
+- 🎯 **Zero config:** Works without tsconfig.json  
+- 🚀 **Works with Mocha:** Uses CommonJS hooks that Mocha understands
+- ✅ **Complete:** Handles all TypeScript features (enums, decorators, etc.)
+
+### Using ts-node/esm (Not Recommended)
+
+> ⚠️ **Note:** `ts-node/esm` has significant limitations with module resolution and doesn't work well with modern ESM TypeScript projects. **We strongly recommend using `tsx` instead.** The information below is provided for reference only.
+
+`ts-node/esm` has several issues:
+- Doesn't support `"type": "module"` in package.json
+- Doesn't resolve extensionless imports or `.js` imports to `.ts` files
+- Requires explicit `.ts` extensions in imports, which isn't standard TypeScript practice
+- Less reliable than `tsx` for ESM scenarios
+
+**If you still want to use ts-node/esm:**
+
+```bash
+npm install --save-dev ts-node
+```
+
+```typescript
+// codecept.conf.ts
+export const config = {
+  tests: './**/*_test.ts',
+  require: ['ts-node/esm'],
+  helpers: { /* ... */ }
+}
+```
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "module": "ESNext",
+    "target": "ES2022",
+    "moduleResolution": "node",
+    "esModuleInterop": true
+  },
+  "ts-node": {
+    "esm": true
+  }
+}
+```
+
+**Critical Limitations:**
+- ❌ Cannot use `"type": "module"` in package.json
+- ❌ Import statements must match the actual file (no automatic resolution)
+- ❌ Module resolution doesn't work like standard TypeScript/Node.js ESM
+
+**Recommendation:** Use `tsx/cjs` instead for a better experience.
+
+### Full TypeScript Features in Tests
+
+With tsx or ts-node/esm, you can use complete TypeScript syntax including imports, enums, interfaces, and types:
+
+```typescript
+// types.ts
+export enum Environment {
+  TEST = 'test',
+  STAGING = 'staging',
+  PRODUCTION = 'production'
+}
+
+export interface User {
+  email: string
+  password: string
+}
+
+// login_test.ts
+import { Environment, User } from './types'
+
+const testUser: User = {
+  email: 'test@example.com',
+  password: 'password123'
+}
+
+Feature('Login')
+
+Scenario(`Login on ${Environment.TEST}`, ({ I }) => {
+  I.amOnPage('/login')
+  I.fillField('email', testUser.email)
+  I.fillField('password', testUser.password)
+  I.click('Login')
+  I.see('Welcome')
+})
+```
+
+### Troubleshooting TypeScript Tests
+
+**Error: "Cannot find module" or "Unexpected token"**
+
+This means the TypeScript loader isn't configured. Make sure:
+1. You have `tsx` or `ts-node` installed: `npm install --save-dev tsx`
+2. Your config includes the loader in `require` array: `require: ['tsx/cjs']`
+3. The loader is specified before test files are loaded
+
+**Error: Module not found when importing from `.ts` files**
+
+When using `ts-node/esm` with ESM, you need to use `.js` extensions in imports:
+
+```typescript
+// This will cause an error in ESM mode:
+import loginPage from "./pages/Login"
+
+// Use .js extension instead:
+import loginPage from "./pages/Login.js"
+```
+
+TypeScript will resolve the `.js` import to your `.ts` file during compilation. This is the standard behavior for ESM + TypeScript.
+
+Alternatively, use `tsx/cjs` which doesn't require explicit extensions.
+
+**TypeScript config files vs test files**
+
+Note the difference:
+- **Config files** (`codecept.conf.ts`, helpers): Automatically transpiled by CodeceptJS
+- **Test files** (`*_test.ts`): Need a loader specified in `config.require`
+
+### Migration from CodeceptJS 3.x
+
+If you're upgrading from CodeceptJS 3.x (CommonJS) to 4.x (ESM):
+
+**Old setup (3.x):**
+```javascript
+// codecept.conf.js
+module.exports = {
+  tests: './*_test.ts',
+  require: ['ts-node/register'],  // CommonJS loader
+  helpers: {}
+}
+```
+
+**New setup (4.x):**
+```typescript
+// codecept.conf.ts
+export const config = {
+  tests: './*_test.ts',
+  require: ['tsx/cjs'],  // TypeScript loader
+  helpers: {}
+}
+```
+
+**Migration steps:**
+1. Install tsx: `npm install --save-dev tsx`
+2. Update package.json: `"type": "module"`
+3. Rename config to `codecept.conf.ts` and use `export const config = {}`
+4. Change `require: ['ts-node/register']` to `require: ['tsx/cjs']`
+5. Run tests: `npx codeceptjs run`
+
+## Promise-Based Typings
+
+By default, CodeceptJS tests are written in synchronous mode. This is a regular CodeceptJS test:
+
+```js
+I.amOnPage('/')
+I.click('Login')
+I.see('Hello!')
+```
+
+Even thought we don't see any `await`, those commands are executed synchronously, one by one.
+All methods of `I` object actually return promise and TypeScript linter requires to use `await` operator for those promises.
+To trick TypeScript and allow writing tests in CodeceptJS manner we create typings where `void` is returned instead of promises. This way linter won't complain on async code without await, as no promise is returned. 
+
+Our philosophy here is: use `await` only when it is actually needed, don't add visual mess to your code prefixing each line with `await`. However, you might want to get a better control of your tests and follow TypeScript conventions.
+This is why you might want to **enable promise-based typings**.
+
+A previous test should be rewritten with `await`s:
+
+```js
+await I.amOnPage('/')
+await I.click('Login')
+await I.see('Hello!')
+```
+
+Using `await` explicitly provides a beter control of execution flow. Some CodeceptJS users report that they increased stability of tests by adopting `await` for all CodeceptJS commands in their codebase.
+
+If you select to use promise-based typings, type definitions will be generated so all actions to return a promise. 
+Otherwise they will still return promises but it won't be relfected in type definitions.
+
+To introduce promise-based typings into a current project edit `codecept.conf.ts`:
+
+```ts
+fullPromiseBased: true;
+```
+
+and rebuild type definitions with
+
+```
+npx codeceptjs def
+```
+
+## Types for custom helper or page object
+
+If you want to get types for your [custom helper](https://codecept.io/helpers/#configuration), you can add their automatically with CodeceptJS command `npx codeceptjs def`.
+
+For example, if you add the new step `printMessage` for your custom helper like this:
+```js
+// customHelper.ts
+export class CustomHelper extends Helper {
+  printMessage(msg: string) {
+    console.log(msg)
+  }
+}
+
+```
+
+Then you need to add this helper to your `codecept.conf.js` like in this [docs](https://codecept.io/helpers/#configuration).
+And then run the command `npx codeceptjs def`.
+
+As result our `steps.d.ts` file will be updated like this:
+```ts
+/// <reference types='codeceptjs' />
+type CustomHelper = import('./CustomHelper');
+
+declare namespace CodeceptJS {
+  interface SupportObject { I: I }
+  interface Methods extends Puppeteer, CustomHelper {}
+  interface I extends WithTranslation<Methods> {}
+  namespace Translation {
+    interface Actions {}
+  }
+}
+```
+
+And now you can use autocomplete on your test.
+
+Generation types for PageObject looks like for a custom helper, but `steps.d.ts` will look like:
+```ts
+/// <reference types='codeceptjs' />
+type loginPage = typeof import('./loginPage');
+type homePage = typeof import('./homePage');
+type CustomHelper = import('./CustomHelper');
+
+declare namespace CodeceptJS {
+  interface SupportObject { I: I, loginPage: loginPage, homePage: homePage }
+  interface Methods extends Puppeteer, CustomHelper {}
+  interface I extends WithTranslation<Methods> {}
+  namespace Translation {
+    interface Actions {}
+  }
+}
+```
+
+## Types for custom strict locators
+
+You can define [custom strict locators](https://codecept.io/locators/#custom-strict-locators) that can be used in all methods taking a locator (parameter type `LocatorOrString`).
+
+Example: A custom strict locator with a `data` property, which can be used like this:
+
+```ts
+I.click({ data: 'user-login' });
+```
+
+In order to use the custom locator in TypeScript code, its type shape needs to be registered in the interface `CustomLocators` in your `steps.d.ts` file:
+
+```ts
+/// <reference types='codeceptjs' />
+...
+
+declare namespace CodeceptJS {
+  ...
+
+  interface CustomLocators {
+    data: { data: string };
+  }
+}
+```
+
+The property keys used in the `CustomLocators` interface do not matter (only the *types* of the interface properties are used). For simplicity it is recommended to use the name that is also used in your custom locator itself.
+
+You can also define more complicated custom locators with multiple (also optional) properties:
+
+```ts
+/// <reference types='codeceptjs' />
+...
+
+declare namespace CodeceptJS {
+  ...
+
+  interface CustomLocators {
+    data: { data: string, value?: number, flag?: boolean };
+  }
+}
+```