codeceptjs 4.0.2-beta.8 → 4.0.2

package/docs/hooks.md

@@ -0,0 +1,148 @@
+---
+permalink: /hooks
+title: Extending CodeceptJS
+---
+
+# Extending CodeceptJS
+
+CodeceptJS has four extension points. Pick the lightest one that does the job:
+
+| Use | To |
+| --- | --- |
+| [`bootstrap` / `teardown`](/bootstrap) | run setup or teardown code once, around the whole suite |
+| [Event listeners](#event-listeners) | react to test, suite, or step events without packaging anything |
+| [Plugins](#plugins) | bundle reusable behavior — listeners, recorder hooks, config — into a module |
+| [Custom helpers](/helpers) | add new `I.*` actions backed by a browser or an HTTP library |
+
+Listeners and plugins use CodeceptJS internals — the `event` dispatcher, the `recorder` promise chain, the `container`, `output`. See [Architecture](/architecture) for what those are and how a test runs.
+
+## Event Listeners
+
+Attach a listener to `event.dispatcher` to run code at any point in the [test lifecycle](/architecture#events). A listener can live in a [plugin](#plugins) or in your [`bootstrap`](/bootstrap) script.
+
+```js
+import { event } from 'codeceptjs'
+
+event.dispatcher.on(event.test.before, test => {
+  console.log(`starting ${test.title}`)
+})
+```
+
+[Sync events](/architecture#events) run inline. For async work, queue it on the recorder so it runs in order with the test's steps:
+
+```js
+import { event, recorder } from 'codeceptjs'
+
+event.dispatcher.on(event.test.before, () => {
+  recorder.add('seed fixture data', async () => {
+    await api.post('/users', { name: 'john', email: 'john@example.com' })
+  })
+})
+```
+
+A listener often needs to know *where* in the run it is — which test is active, or whether this is a dry run. Read that from [`store`](/store) instead of tracking it yourself:
+
+```js
+import { event, store } from 'codeceptjs'
+
+event.dispatcher.on(event.step.before, () => {
+  if (store.dryRun) return            // skip side effects on a dry run
+})
+```
+
+See [Architecture › Events](/architecture#events) for the full event list and the test and step object fields, and the [Store reference](/store) for every state field.
+
+## Plugins
+
+A plugin packages listeners, recorder hooks, container changes, and config into one module. CodeceptJS ships [built-in plugins](/plugins) — [their source](https://github.com/codeceptjs/CodeceptJS/tree/master/lib/plugin) doubles as example code.
+
+A plugin is a module that exports a function. CodeceptJS calls it once at startup with the plugin's config:
+
+```js
+import { event } from 'codeceptjs'
+
+const defaultConfig = {
+  someOption: true,
+}
+
+export default function (config) {
+  config = { ...defaultConfig, ...config }
+
+  event.dispatcher.on(event.test.before, test => {
+    // use config, register listeners, hook into the recorder
+  })
+}
+```
+
+### Enabling a plugin
+
+Add it to the `plugins` section of the config and point `require` at the module:
+
+```js
+plugins: {
+  myPlugin: {
+    require: './path/to/plugin',   // relative to the config file
+    enabled: true,
+  }
+}
+```
+
+- `require` — path to the plugin file, relative to the config file.
+- `enabled` — set `true` to load it.
+- any other key is passed straight to the plugin function as config.
+
+A disabled or unlisted plugin can be turned on for a single run from the command line:
+
+```
+npx codeceptjs run --plugin myPlugin
+npx codeceptjs run --plugin myPlugin,allure
+```
+
+### Example: run code for a tagged group of tests
+
+[Tag](/test-structure#tags) the tests you want to target, then check the tag on `event.test.before`:
+
+```js
+import { event, recorder } from 'codeceptjs'
+
+export default function () {
+  event.dispatcher.on(event.test.before, test => {
+    if (!test.tags.includes('@populate')) return
+
+    recorder.add('populate database', async () => {
+      // seed data for this test
+    })
+  })
+}
+```
+
+### Example: run async setup before all tests
+
+`event.all.before` can fire before the recorder chain is running, so start it first:
+
+```js
+import { event, recorder } from 'codeceptjs'
+
+export default function () {
+  event.dispatcher.on(event.all.before, () => {
+    recorder.startUnlessRunning()
+    recorder.add('warm up cache', async () => {
+      // your async setup
+    })
+  })
+}
+```
+
+Wrapping bootstrap logic in a plugin like this lets you share it across projects and combine several setup scripts.
+
+## Custom Helpers
+
+To add new `I.*` actions — a higher-level step, a wrapper around a browser SDK, an assertion against your backend — write a helper class. Helpers can also be published as npm packages. See [Custom Helpers](/helpers).
+
+## Bootstrap & Teardown
+
+For setup and teardown that needs no packaging — start a server, create a database — use the `bootstrap` and `teardown` config hooks. In [parallel runs](/parallel), `bootstrapAll` / `teardownAll` run once in the parent process. See [Bootstrap & Teardown](/bootstrap).
+
+---
+
+**See also:** [Architecture](/architecture) · [Plugins reference](/plugins) · [Custom Helpers](/helpers) · [Bootstrap & Teardown](/bootstrap)

package/docs/index.md

@@ -0,0 +1,111 @@
+---
+layout: Landing
+sidebar: false
+actionText: Quickstart
+actionLink: /quickstart
+---
+
+::: slot pause
+## Write a Test with Interactive Pause
+
+Open a browser on an empty page and pause execution.
+Type in commands to complete the test scenario.
+
+Successful commands will be saved into a file.
+
+```js
+Scenario('Checkout test', ({ I }) => {
+  I.amOnPage('/checkout');
+  pause();
+})
+```
+Copy commands from a file into a test. A test is ready!
+:::
+
+::: slot write
+## Write Tests from UI
+
+With CodeceptUI you can write your tests without closing a browser at all.
+
+Write initial commands and execute a test. An interactive pause will be started when test finishes.
+
+Share one browser accross test runs to save time on opening a browser.
+:::
+
+
+::: slot autocomplete
+## Powered with IntelliSense
+
+Use auto-completion writing a test fast.
+
+We use TypeScript type definitions that are automatically updated for custom steps and page objects.
+
+Writing a test in Visual Studio Code is as easy as picking a correct action and putting a parameter. It's really that nice!
+
+:::
+
+
+::: slot ui
+
+## Watch & Run Tests from UI
+
+We have a flexible interactive web runner which allows you to watch, debug, and write your tests in a web mode.
+
+Features:
+
+* Toggle headless/window mode with one click
+* See HTML snapshot of each step
+* Works with WebDriver, Puppeteer, Playwright
+* Shows step-by-step execution
+* Integrated with your local IDE
+
+:::
+
+
+::: slot run
+
+## Print a Test
+
+Each executed step will be printed on screen when running with `--steps`
+```js
+Scenario('Checkout test', ({ I }) => {
+  I.amOnPage('/checkout');
+  I.fillField('First name', 'davert');
+  I.fillField('#lastName', 'mik');
+  I.fillField('Promo code', '123345')
+  //...
+})
+```
+
+:::
+
+::: slot code
+
+## Realworld Example
+
+Can we use it for long scenarios? Sure!
+
+```js
+import { faker } from '@faker-js/faker'                                     // Use 3rd-party JS code
+
+Feature('Store');
+
+Scenario('Create a new store', async ({ I, login, SettingsPage }) => {
+  const storeName = faker.lorem.slug();
+  login('customer');                                          // Login customer from saved cookies
+  SettingsPage.open();                                        // Use Page objects
+  I.dontSee(storeName, '.settings');                          // Assert text not present inside an element (located by CSS)
+  I.click('Add', '.settings');                                // Click link by text inside element (located by CSS)
+  I.fillField('Store Name', storeName);                       // Fill fields by labels or placeholders
+  I.fillField('Email', faker.internet.email());
+  I.fillField('Telephone', faker.phone.phoneNumberFormat());
+  I.selectInDropdown('Status', 'Active');                     // Use custom methods
+  I.click('Create', step.retry(2));                           // Retry flaky step
+  I.waitInUrl('/settings/setup/stores');                      // Explicit waiter
+  I.see(storeName, '.settings');                              // Assert text present inside an element (located by CSS)
+  const storeId = await I.grabTextFrom('#store-id');          // Use await to get information from browser
+  I.say(`Created a store with ${storeId}`);                   // Print custom comments
+}).tag('stores');`;
+
+```
+:::

package/docs/installation.md

@@ -0,0 +1,121 @@
+---
+permalink: /installation
+title: Installation
+---
+
+# Installation
+
+For the quickest start (CodeceptJS + Playwright) follow the [Quickstart](/quickstart). This page covers every browser, mobile, and API helper and what each one needs installed.
+
+## Set up a project
+
+```sh
+npm init -y                  # if you don't have a package.json yet
+npm i codeceptjs --save-dev
+```
+
+Install one of the helpers below, then scaffold the config and a sample test:
+
+```sh
+npx codeceptjs init
+```
+
+`init` runs a short wizard, writes `codecept.conf.js` and a sample test, and installs the helper's driver package if it's missing. The [Quickstart](/quickstart) walks through the questions.
+
+## Playwright
+
+Fast, modern browser automation — the recommended helper for web testing.
+
+```sh
+npm i playwright --save-dev
+npx playwright install --with-deps
+```
+
+`playwright install` downloads the browser binaries; `--with-deps` also installs the Linux system libraries they need (run it with `sudo` if your user can't install packages).
+
+Set `browser` in the helper config to one of:
+
+- `chromium` — default
+- `firefox`
+- `webkit` — the open-source Safari engine
+- `electron` — test an Electron app (set `electron.executablePath`)
+
+To drive branded Chrome or Edge instead of bundled Chromium, install that channel — `npx playwright install chrome` (or `msedge`) — and set `channel` in the config. See the [Playwright helper](/playwright).
+
+## Puppeteer
+
+Chrome/Chromium automation over the DevTools protocol.
+
+```sh
+npm i puppeteer --save-dev
+```
+
+Puppeteer downloads a matching Chromium when it installs — nothing else to set up. To drive an existing Chrome instead, set `chrome.executablePath` in the helper config (or install `puppeteer-core` and point it at your browser). See the [Puppeteer helper](/puppeteer).
+
+## WebDriver
+
+W3C WebDriver — runs Chrome, Firefox, Edge, Safari, and remote or cloud grids.
+
+```sh
+npm i webdriverio --save-dev
+```
+
+WebdriverIO 9 downloads and starts the matching driver automatically — no Selenium server, ChromeDriver, or GeckoDriver to install or run. Just set `browser` (`chrome`, `firefox`, `MicrosoftEdge`, `safari`) in `codecept.conf.js` — see the [WebDriver helper](/webdriver).
+
+To run against a cloud grid (Sauce Labs, BrowserStack, LambdaTest, and so on) instead, set the grid's `host`, `port`, `user`, and `key` (or `protocol` / `path`) in the helper config. For running this on CI, see [Continuous Integration](/continuous-integration).
+
+## Appium (mobile)
+
+Native iOS and Android testing. Appium speaks the WebDriver protocol, so CodeceptJS drives it through `webdriverio`:
+
+```sh
+npm i webdriverio --save-dev
+npm i -g appium
+```
+
+Install the platform driver(s) and start the server:
+
+```sh
+appium driver install uiautomator2   # Android
+appium driver install xcuitest       # iOS
+appium
+```
+
+You'll also need the Android SDK and an emulator or device, or Xcode and a simulator or device (or a device-cloud account). Set `platformName`, `deviceName`, and `app` in the helper config — see [Mobile Testing](/mobile).
+
+## API testing
+
+REST and GraphQL tests need no browser — the helpers are built in (they use `axios`, already a dependency):
+
+```sh
+npm i codeceptjs --save-dev
+```
+
+Choose `REST` or `GraphQL` when `init` asks, set `endpoint` in the config, and add the `JSONResponse` helper if you want response assertions. See [Testing APIs](/api).
+
+## ESM
+
+CodeceptJS 4.x uses ECMAScript Modules. A project created by `init` is set up for it; an existing project needs `"type": "module"` in `package.json` and `import` syntax in the config and tests. Coming from 3.x — see the [Migration Guide](/migration-4).
+
+## TypeScript
+
+`npx codeceptjs init` scaffolds a TypeScript project when you answer **Yes** to "Do you plan to write tests in TypeScript?" — it writes `codecept.conf.ts` and `*_test.ts` files.
+
+The config file (`codecept.conf.ts`) and helpers are transpiled automatically. Test files need a loader; install [`tsx`](https://tsx.is) and add it to `require`:
+
+```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 tests as usual with `npx codeceptjs run`. For promise-based typings, types for page objects and custom helpers, and custom locator types, see the [TypeScript guide](/typescript).

package/docs/internal-test-server.md

@@ -0,0 +1,89 @@
+# Internal API Test Server
+
+This directory contains the internal API test server implementation that replaces the third-party `json-server` dependency.
+
+## Files
+
+- `lib/test-server.js` - Main TestServer class implementation
+- `bin/test-server.js` - CLI script to run the server standalone
+
+## Usage
+
+### As npm script:
+
+```bash
+npm run test-server
+```
+
+### Directly:
+
+```bash
+node bin/test-server.js [options] [db-file]
+```
+
+### Options:
+
+- `-p, --port <port>` - Port to listen on (default: 8010)
+- `--host <host>` - Host to bind to (default: 0.0.0.0)
+- `db-file` - Path to JSON database file (default: test/data/rest/db.json)
+
+## Features
+
+- **Full REST API compatibility** with json-server
+- **Automatic file watching** - Reloads data when db.json file changes
+- **CORS support** - Allows cross-origin requests for testing
+- **Custom headers support** - Handles special headers like X-Test
+- **File upload endpoints** - Basic file upload simulation
+- **Express.js based** - Uses familiar Express.js framework
+
+## API Endpoints
+
+The server provides the same API endpoints as json-server:
+
+### Users
+
+- `GET /user` - Get user data
+- `POST /user` - Create/update user
+- `PATCH /user` - Partially update user
+- `PUT /user` - Replace user
+
+### Posts
+
+- `GET /posts` - Get all posts
+- `GET /posts/:id` - Get specific post
+- `POST /posts` - Create new post
+- `PUT /posts/:id` - Replace specific post
+- `PATCH /posts/:id` - Partially update specific post
+- `DELETE /posts/:id` - Delete specific post
+
+### Comments
+
+- `GET /comments` - Get all comments
+- `POST /comments` - Create new comment
+- `DELETE /comments/:id` - Delete specific comment
+
+### Utility
+
+- `GET /headers` - Return request headers (for testing)
+- `POST /headers` - Return request headers (for testing)
+- `POST /upload` - File upload simulation
+- `POST /_reload` - Manually reload database file
+
+## Migration from json-server
+
+This server is designed as a drop-in replacement for json-server. The key differences:
+
+1. **No CLI options** - Configuration is done through constructor options or CLI args
+2. **Automatic file watching** - No need for `--watch` flag
+3. **Built-in middleware** - Headers and CORS are handled automatically
+4. **Simpler file upload** - Basic implementation without full multipart support
+
+## Testing
+
+The server is used by the following test suites:
+
+- `test/rest/REST_test.js` - REST helper tests
+- `test/rest/ApiDataFactory_test.js` - API data factory tests
+- `test/helper/JSONResponse_test.js` - JSON response helper tests
+
+All tests pass with the internal server, proving full compatibility.