codeceptjs 4.0.2-beta.9 → 4.0.2

package/docs/tutorial.md

@@ -0,0 +1,323 @@
+---
+permalink: /tutorial
+title: CodeceptJS Complete Tutorial
+---
+
+# Tutorial: Testing a Checkout Page
+
+**[CodeceptJS](https://codecept.io) is a popular open-source end-to-end testing framework** for JavaScript. It is designed to make web tests readable and easy to maintain by writing them as a linear scenario of user actions. By default it drives the browser with **[Playwright](https://playwright.dev)**, but the same tests can run via WebDriver, Puppeteer, or Appium without changes.
+
+In this tutorial we write a real, runnable test for the **[Bootstrap checkout example](https://getbootstrap.com/docs/4.0/examples/checkout/)** — a public page with a billing and payment form. By the end you will have a clean test and a reusable page object.
+
+## Install CodeceptJS
+
+You need Node.js (and npm) installed. Check with:
+
+```bash
+node --version
+npm --version
+```
+
+Create a new folder, then install CodeceptJS together with Playwright:
+
+```bash
+npm init -y
+npm install codeceptjs playwright --save-dev
+npx playwright install --with-deps
+```
+
+`npx playwright install` downloads the Chromium, Firefox, and WebKit browsers; `--with-deps` also installs the system libraries they need.
+
+Now scaffold the project:
+
+```bash
+npx codeceptjs init
+```
+
+`init` runs a short wizard. Accept the defaults — when asked for the **base URL** enter `https://getbootstrap.com`, and name the first test **Checkout**. This creates:
+
+```
+.
+├── codecept.conf.js
+├── package.json
+└── Checkout_test.js
+```
+
+`codecept.conf.js` holds the project configuration. Because CodeceptJS 4.x uses **ES modules**, the config and tests use `import`/`export` syntax — `init` sets `"type": "module"` in `package.json` for you.
+
+Open `codecept.conf.js`. The two settings that matter here are the helper and the base URL:
+
+```js
+import { setHeadlessWhen } from '@codeceptjs/configure'
+
+// show the browser locally, run headless on CI
+setHeadlessWhen(process.env.CI)
+
+export const config = {
+  tests: './*_test.js',
+  output: './output',
+  helpers: {
+    Playwright: {
+      url: 'https://getbootstrap.com',
+      browser: 'chromium',
+    },
+  },
+}
+```
+
+## Your First Test
+
+Open `Checkout_test.js`:
+
+```js
+Feature('Checkout');
+
+Scenario('test something', ({ I }) => {
+});
+```
+
+A test lives inside a `Scenario` block. Let's open the checkout page:
+
+```js
+Feature('Checkout');
+
+Scenario('test something', ({ I }) => {
+  I.amOnPage('/docs/4.0/examples/checkout/');
+});
+```
+
+`I.amOnPage()` navigates the browser. Because the path is relative, it is appended to the base URL from the config — keep the base URL in config so you can switch between staging and production without touching tests.
+
+But you may be wondering...
+
+### What is `I`?
+
+In CodeceptJS the `I` object is the **actor** — it represents the user performing actions. It exposes methods (called *actions*) that simulate interactions with the app:
+
+- `I.amOnPage(url)` — navigate to a URL
+- `I.click(locator)` — click an element
+- `I.fillField(field, value)` — type into an input
+- `I.selectOption(select, option)` — choose an option in a dropdown
+- `I.checkOption(locator)` — tick a checkbox or radio
+- `I.see(text)` — assert that text is visible
+- `I.seeInField(field, value)` — assert an input holds a value
+
+CodeceptJS **waits automatically** before clicking, filling, and most other actions, so you rarely need explicit waits. Steps also write themselves into a promise chain, so you usually **don't need `await`** for regular actions — only for `grab*` actions and page object methods that return data.
+
+### Locating Elements
+
+Most actions accept a locator. CodeceptJS supports several strategies — prefer the readable ones:
+
+```js
+// by visible text / label
+I.click('Continue to checkout');
+I.fillField('First name', 'John');
+
+// by ARIA role and accessible name (resilient to CSS changes)
+I.click({ role: 'button', name: 'Continue to checkout' });
+
+// by CSS or XPath, when nothing semantic is available
+I.fillField('#email', 'john@example.com');
+```
+
+> **Best practice:** prefer labels and ARIA locators (`{ role, name }`). They survive styling changes and document intent. Fall back to CSS/XPath only when needed.
+
+## Writing the Checkout Test
+
+The Bootstrap checkout form has billing fields, country/state selects, and a payment section. CodeceptJS finds inputs by their visible `<label>`, so the test reads like the form:
+
+```js
+Feature('Checkout');
+
+Scenario('fill in the checkout form', ({ I }) => {
+  I.amOnPage('/docs/4.0/examples/checkout/');
+  I.see('Checkout form');
+
+  // billing address — fields located by their labels
+  I.fillField('First name', 'John');
+  I.fillField('Last name', 'Doe');
+  I.fillField('Username', 'johndoe');
+  I.fillField('#email', 'john@example.com'); // label has "(Optional)", use CSS
+  I.fillField('Address', '123 Main St.');
+  I.selectOption('Country', 'United States');
+  I.selectOption('State', 'California');
+  I.fillField('Zip', '10001');
+
+  // shipping / preferences
+  I.checkOption('Shipping address is the same as my billing address');
+  I.checkOption('Save this information for next time');
+
+  // payment — "Credit card" is selected by default
+  I.click('Credit card');
+  I.fillField('Name on card', 'John Doe');
+  I.fillField('Credit card number', secret('4111 1111 1111 1111'));
+
+  // verify the form holds what we entered
+  I.seeInField('First name', 'John');
+  I.seeInField('Address', '123 Main St.');
+  I.click('Continue to checkout');
+});
+```
+
+A few things worth noting:
+
+- **`secret()`** wraps the card number so it is masked (`****`) in logs and reports. Use it for any sensitive value — see [Secrets](/secrets).
+- Never use a real card number. Payment providers like Stripe publish [test card numbers](https://docs.stripe.com/testing) for exactly this.
+- This is a static demo page with no backend, so we verify by reading field values back with `I.seeInField`. On a real shop you would assert a confirmation, e.g. `I.see('Your order has been placed')`.
+
+### A Negative Scenario
+
+Good test suites cover failures too. The form validates on submit — submitting it empty shows error messages. CodeceptJS doesn't allow multiple scenarios in one file's suite to nest, but you can add as many `Scenario` blocks as you like:
+
+```js
+Scenario('shows validation errors on empty submit', ({ I }) => {
+  I.amOnPage('/docs/4.0/examples/checkout/');
+  I.click('Continue to checkout');
+  I.see('Valid first name is required.');
+});
+```
+
+### Running the Test
+
+```bash
+npx codeceptjs run --steps
+```
+
+`--steps` prints every step as it runs. Useful flags while developing:
+
+- `--steps` — print each step
+- `--debug` — steps plus extra debug output (recommended while writing tests)
+- `--verbose` — everything, including the promise chain
+
+Set a breakpoint to inspect the page interactively by adding `pause()` to the scenario:
+
+```js
+Scenario('fill in the checkout form', ({ I }) => {
+  I.amOnPage('/docs/4.0/examples/checkout/');
+  I.fillField('First name', 'John');
+  pause(); // test stops here; type steps live in the browser
+});
+```
+
+In the pause shell you can type `I.click('...')`, inspect the page, and find better locators. See [Debugging](/debugging).
+
+The browser is shown locally and runs headless on CI thanks to `setHeadlessWhen(process.env.CI)`. To force it either way for one run:
+
+```bash
+npx codeceptjs run --headless
+```
+
+Once the test is stable, run the whole suite:
+
+```bash
+npx codeceptjs run
+```
+
+## Refactoring with a Page Object
+
+What if more tests need to fill this form? Copy-pasting steps doesn't scale. The **Page Object** pattern keeps locators and interactions in one reusable place.
+
+Generate one:
+
+```bash
+npx codeceptjs gpo
+```
+
+Call it `Checkout`. It is created in `./pages/Checkout.js` and registered in `codecept.conf.js` under `include`:
+
+```js
+export const config = {
+  // ...
+  include: {
+    checkoutPage: './pages/Checkout.js',
+  },
+}
+```
+
+Page objects are **classes**. Move the form interactions into named methods:
+
+```js
+const { I } = inject();
+
+class CheckoutPage {
+  url = '/docs/4.0/examples/checkout/'
+
+  open() {
+    I.amOnPage(this.url);
+    I.see('Checkout form');
+  }
+
+  fillBillingAddress({ firstName, lastName, username, address, country, state, zip }) {
+    I.fillField('First name', firstName);
+    I.fillField('Last name', lastName);
+    I.fillField('Username', username);
+    I.fillField('Address', address);
+    I.selectOption('Country', country);
+    I.selectOption('State', state);
+    I.fillField('Zip', zip);
+  }
+
+  payWithCard(name, number) {
+    I.click('Credit card');
+    I.fillField('Name on card', name);
+    I.fillField('Credit card number', secret(number));
+  }
+
+  submit() {
+    I.click('Continue to checkout');
+  }
+}
+
+export default CheckoutPage
+```
+
+> `inject()` returns a lazy proxy, so it's safe to destructure `I` before the class. Export the **class** — CodeceptJS auto-instantiates it. (Plain-object page objects still work but classes support lifecycle hooks and inheritance.)
+
+The test now reads at the business level. Inject `checkoutPage` by the name you set in the config:
+
+```js
+Feature('Checkout');
+
+Scenario('complete a checkout', ({ I, checkoutPage }) => {
+  checkoutPage.open();
+  checkoutPage.fillBillingAddress({
+    firstName: 'John',
+    lastName: 'Doe',
+    username: 'johndoe',
+    address: '123 Main St.',
+    country: 'United States',
+    state: 'California',
+    zip: '10001',
+  });
+  checkoutPage.payWithCard('John Doe', '4111 1111 1111 1111');
+  checkoutPage.submit();
+
+  I.seeInField('First name', 'John');
+});
+```
+
+Shorter, intention-revealing, and every other checkout test can reuse the same methods. As coverage grows, add methods to the page object instead of duplicating steps.
+
+## Going Further
+
+When you have many tests, run them in parallel using Node workers:
+
+```bash
+npx codeceptjs run-workers 3
+```
+
+From here, explore:
+
+- [Locators](/locators) — every locating strategy in depth
+- [Page Objects](/pageobjects) — fragments, step objects, lifecycle hooks
+- [Data-driven tests](/data) — run one scenario over many inputs
+- [Debugging](/debugging) — `pause()`, the interactive shell, and AI-assisted debugging
+- [Continuous Integration](/continuous-integration) — running the suite on CI
+
+## Summary
+
+If you are just starting with test automation, CodeceptJS lets you describe tests in near-natural language and handles waiting and retries for you. If you already know JavaScript, page objects and dependency injection keep your suite focused on business behavior — which is what keeps tests stable and maintainable as the app grows.
+
+> [▶ Next: CodeceptJS Basics](/basics/)
+</content>
+</invoke>

package/docs/typescript.md

@@ -0,0 +1,159 @@
+---
+permalink: /typescript
+title: TypeScript
+---
+
+# TypeScript
+
+CodeceptJS ships [type declarations](https://github.com/codeceptjs/CodeceptJS/tree/master/typings), so you can write tests, page objects, and custom helpers in TypeScript and get autocomplete and type checking in your editor.
+
+## Getting started
+
+`npx codeceptjs init` scaffolds a TypeScript project when you answer **Yes** to:
+
+```
+? Do you plan to write tests in TypeScript? Yes
+```
+
+It writes `codecept.conf.ts` and `*_test.ts` files. The **config file** and helpers are transpiled automatically. **Test files** need a loader — CodeceptJS 4.x is ESM, and Mocha loads test files through CommonJS hooks, so use [`tsx`](https://tsx.is) (fast, esbuild-based, no `tsconfig.json` required):
+
+```sh
+npm i tsx --save-dev
+```
+
+```ts
+// codecept.conf.ts
+export const config = {
+  tests: './**/*_test.ts',
+  require: ['tsx/cjs'],   // loads the *_test.ts files
+  helpers: {
+    Playwright: { url: 'http://localhost', browser: 'chromium' },
+  },
+}
+```
+
+Run the tests with `npx codeceptjs run`.
+
+> Adding TypeScript to an existing project: set `"type": "module"` in `package.json`, rename the config to `codecept.conf.ts` with `export const config = {}`, install `tsx`, and add `require: ['tsx/cjs']`.
+
+## Writing tests
+
+Test files use the full TypeScript syntax — imports, enums, interfaces, types:
+
+```ts
+// fixtures.ts
+export interface User { email: string; password: string }
+export const admin: User = { email: 'admin@example.com', password: 's3cret' }
+
+// login_test.ts
+import { admin } from './fixtures'
+
+Feature('Login')
+
+Scenario('admin signs in', ({ I }) => {
+  I.amOnPage('/login')
+  I.fillField('email', admin.email)
+  I.fillField('password', admin.password)
+  I.click('Login')
+  I.see('Welcome')
+})
+```
+
+> **Cannot find module** or **Unexpected token** while running tests means the loader isn't wired up — check that `tsx` is installed and `require: ['tsx/cjs']` is in the config.
+
+## Promise-based typings
+
+CodeceptJS tests read synchronously even though every `I.*` call returns a promise:
+
+```ts
+I.amOnPage('/')
+I.click('Login')
+I.see('Hello')
+```
+
+The default typings declare these methods as returning `void`, so a linter won't demand `await` on every line. To follow TypeScript conventions and `await` each command instead — some teams find explicit flow control improves stability — enable promise-based typings in `codecept.conf.ts`:
+
+```ts
+export const config = {
+  fullPromiseBased: true,
+  // ...
+}
+```
+
+Rebuild the type definitions:
+
+```sh
+npx codeceptjs def
+```
+
+Now the typings return promises:
+
+```ts
+await I.amOnPage('/')
+await I.click('Login')
+await I.see('Hello')
+```
+
+## Types for page objects and custom helpers
+
+`npx codeceptjs def` regenerates `steps.d.ts` from your config — run it after adding a page object or a custom helper so autocomplete picks them up.
+
+For a custom helper:
+
+```ts
+// CustomHelper.ts
+export class CustomHelper extends Helper {
+  printMessage(msg: string) {
+    console.log(msg)
+  }
+}
+```
+
+Register it in `codecept.conf.ts` ([helper configuration](/helpers#configuration)), run `npx codeceptjs def`, and `steps.d.ts` becomes:
+
+```ts
+/// <reference types='codeceptjs' />
+type CustomHelper = import('./CustomHelper')
+
+declare namespace CodeceptJS {
+  interface SupportObject { I: I }
+  interface Methods extends Playwright, CustomHelper {}
+  interface I extends WithTranslation<Methods> {}
+}
+```
+
+Page objects appear the same way — `def` adds a `type` for each and lists them in `SupportObject`:
+
+```ts
+type loginPage = typeof import('./loginPage')
+type homePage = typeof import('./homePage')
+
+declare namespace CodeceptJS {
+  interface SupportObject { I: I, loginPage: loginPage, homePage: homePage }
+  // ...
+}
+```
+
+## Types for custom locators
+
+If you use [custom locators](/locators#custom-locators) — for example `I.click({ data: 'user-login' })` — declare their shape in the `CustomLocators` interface in `steps.d.ts` so they're accepted wherever a locator is expected:
+
+```ts
+/// <reference types='codeceptjs' />
+
+declare namespace CodeceptJS {
+  interface CustomLocators {
+    data: { data: string }
+  }
+}
+```
+
+Only the property *types* matter, not the keys. Locators with several (optional) properties work too:
+
+```ts
+declare namespace CodeceptJS {
+  interface CustomLocators {
+    data: { data: string; value?: number; flag?: boolean }
+  }
+}
+```