updated docs

Author: DavertMik

CHANGELOG.md

@@ -134,7 +134,7 @@ Feature('My feature', {key: val});
 Scenario('My scenario', {key: val},({ I }) => {});
 ```
 
-You can use this options for build your own [plugins](https://codecept.io/hooks/#plugins) with [event listners](https://codecept.io/hooks/#api). Example: 
+You can use these options to build your own [plugins](https://codecept.io/hooks#plugins) with [event listeners](https://codecept.io/architecture#events). Example: 
 
 ```js
   // for test

docs/advanced.md

@@ -0,0 +1,219 @@
+---
+permalink: /architecture
+title: Architecture
+---
+
+# CodeceptJS Architecture
+
+How CodeceptJS runs a test, and the internal modules you build [plugins, listeners, and helpers](/hooks) against.
+
+## How a Test Runs
+
+CodeceptJS is built on top of [Mocha](https://mochajs.org). A run goes through these stages:
+
+1. **Load.** CodeceptJS reads the config, builds the [container](#container) (helpers, support objects, plugins), and runs the `bootstrap` hook. `event.all.before` fires.
+2. **Suite.** For each suite, `event.suite.before` fires. Helper `_beforeSuite` hooks run.
+3. **Test.** For each test: `event.test.started` fires; `Before` hooks from helpers (`_before`) and from the suite run, then `event.test.before` fires; the scenario function runs; `event.test.passed` or `event.test.failed` fires; `After` hooks run; `event.test.after` and then `event.test.finished` fire.
+4. **Step.** Each `I.*` call inside a scenario becomes a step. It is *scheduled* onto the [recorder](#the-recorder) — `event.step.before` fires — then executed: `event.step.started`, `event.step.passed` or `event.step.failed`, `event.step.after`, `event.step.finished`.
+5. **Finish.** `event.suite.after` fires after each suite, `event.all.after` after the last one, and `event.all.result` when results are printed. The `teardown` hook runs.
+
+The key idea is step 4: **a scenario doesn't execute its steps as it runs** — it queues them. `I.click()` returns immediately; the [recorder](#the-recorder) runs the queued action later. This is why scenarios rarely need `await`, and why anything that injects async work has to go through the recorder.
+
+## The Internal API
+
+CodeceptJS exposes its internals as named exports of the `codeceptjs` package. Import only what you need:
+
+```js
+import { recorder, event, output, container, config } from 'codeceptjs'
+```
+
+| Export | What it is |
+| --- | --- |
+| [`codecept`](https://github.com/codeceptjs/CodeceptJS/blob/master/lib/codecept.js) | the test runner class |
+| [`config`](https://github.com/codeceptjs/CodeceptJS/blob/master/lib/config.js) | the loaded configuration |
+| [`container`](https://github.com/codeceptjs/CodeceptJS/blob/master/lib/container.js) | dependency-injection container: helpers, support objects, plugins, the Mocha instance |
+| [`recorder`](https://github.com/codeceptjs/CodeceptJS/blob/master/lib/recorder.js) | the global promise chain that orders every step |
+| [`event`](https://github.com/codeceptjs/CodeceptJS/blob/master/lib/event.js) | the event dispatcher and the names of all lifecycle events |
+| [`output`](https://github.com/codeceptjs/CodeceptJS/blob/master/lib/output.js) | the printer used for all console output |
+| [`helper`](https://github.com/codeceptjs/CodeceptJS/blob/master/lib/helper.js) | the base class every helper extends |
+| [`actor`](https://github.com/codeceptjs/CodeceptJS/blob/master/lib/actor.js) | the base class behind the `I` object |
+
+> Older code relied on a global `codeceptjs` object (`const { recorder } = codeceptjs`). That global only exists under `noGlobals: false`, the deprecated 3.x default — prefer named imports.
+
+The [API reference](https://github.com/codeceptjs/CodeceptJS/tree/master/docs/api) on GitHub documents these modules; the source is the final word.
+
+## The Recorder
+
+The recorder is a single global promise chain. Every step a scenario "calls" is appended to it, and the chain runs the steps one after another. To run your own async code at the right point in a test, append it to the recorder too:
+
+```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' })
+  })
+})
+```
+
+- `recorder.add(name, fn)` — append `fn` (async, or returning a promise) to the chain. The name shows up in `--verbose` output.
+- `recorder.startUnlessRunning()` — start a chain if none is running. Call it before `add()` from a listener that may fire outside a running chain, such as `event.all.before`.
+- `recorder.retry({ retries, when })` — retry failing steps that match `when`. See [conditional retries](/helpers#conditional-retries).
+
+Run tests with `--verbose` to watch the recorder schedule and execute each entry.
+
+## Container
+
+The container resolves helpers and support objects by name:
+
+```js
+import { container } from 'codeceptjs'
+
+const helpers = container.helpers()          // every helper, keyed by name
+const { Playwright } = container.helpers()   // one helper
+const support = container.support()          // every support object
+const { UserPage } = container.support()     // one page object
+const plugins = container.plugins()          // enabled plugins
+const mocha = container.mocha()              // the current Mocha instance
+```
+
+Add objects at runtime — useful from a `bootstrap` script:
+
+```js
+import { container } from 'codeceptjs'
+import UserPage from './pages/user.js'
+
+container.append({
+  helpers: { MyHelper: new MyHelper({ host: 'http://example.com' }) },
+  support: { UserPage },
+})
+```
+
+## Events
+
+`event.dispatcher` is a Node `EventEmitter`. Attach listeners to it from a [plugin](/hooks#plugins) or `bootstrap` script.
+
+Events are **sync** or **async**:
+
+- **sync** — fires the moment the action happens. Do synchronous work only.
+- **async** — fires when the action is *scheduled*. To do async work in the right order, queue it with `recorder.add()`.
+
+| Event | Kind | When |
+| --- | --- | --- |
+| `event.all.before` | — | before any test runs |
+| `event.suite.before(suite)` | async | before a suite |
+| `event.test.started(test)` | sync | at the very start of a test |
+| `event.test.before(test)` | async | after `Before` hooks from helpers and the test are run |
+| `event.test.passed(test)` | sync | test passed |
+| `event.test.failed(test, err)` | sync | test failed |
+| `event.test.skipped(test)` | sync | test skipped |
+| `event.test.after(test)` | async | after each test |
+| `event.test.finished(test)` | sync | test finished |
+| `event.suite.after(suite)` | async | after a suite |
+| `event.step.before(step)` | async | step scheduled for execution |
+| `event.step.started(step)` | sync | step starts executing |
+| `event.step.passed(step)` | sync | step passed |
+| `event.step.failed(step, err)` | sync | step failed |
+| `event.step.after(step)` | async | after a step |
+| `event.step.finished(step)` | sync | step finished |
+| `event.step.comment(step)` | sync | a comment such as `I.say(...)` |
+| `event.bddStep.before(step)` / `event.bddStep.after(step)` | async | around a Gherkin step |
+| `event.hook.started(hook)` / `event.hook.passed` / `event.hook.failed` / `event.hook.finished` | sync | around `Before` / `After` / `BeforeSuite` / `AfterSuite` hooks |
+| `event.all.after` | — | after all tests |
+| `event.all.result(result)` | — | when results are printed |
+| `event.all.failures(failures)` | — | when a run reports failures |
+| `event.workers.before` / `event.workers.after` / `event.workers.result(result)` | — | around a [parallel run](/parallel) (parent process only) |
+
+The [built-in listeners](https://github.com/codeceptjs/CodeceptJS/tree/master/lib/listener) are working examples — every reporter and several plugins are listeners.
+
+### Test object
+
+Test events pass a test object with these fields:
+
+- `title` — the test title
+- `body` — the test function as a string
+- `opts` — test options such as `retries` (see [test options](/advanced#test-options))
+- `pending` — `true` while scheduled, `false` once finished
+- `tags` — array of [tags](/test-structure#tags) for this test
+- `artifacts` — files attached to this test (screenshots, videos, …), shared across reporters
+- `file` — path to the test file
+- `steps` — executed steps (only on `test.passed`, `test.failed`, `test.finished`)
+- `skipInfo` — present when the test was skipped: `{ message, description }`
+
+### Step object
+
+Step events pass a step object with these fields:
+
+- `name` — the step name, such as `see` or `click`
+- `actor` — the current actor, usually `I`
+- `helper` — the helper instance that executes this step
+- `helperMethod` — the helper method, usually the same as `name`
+- `status` — `passed` or `failed`
+- `prefix` — for a step inside a `within` block, the within text (e.g. `Within .js-signup-form`)
+- `args` — the arguments passed to the step
+
+## Config
+
+```js
+import { config } from 'codeceptjs'
+
+config.get()                       // the full config object
+config.get('myKey')                // one value
+config.get('myKey', 'fallback')    // one value, with a default
+```
+
+## Output
+
+Output has four verbosity levels, each toggled by a CLI flag:
+
+| Level | Flag | Use |
+| --- | --- | --- |
+| default | — | `output.print` — basic information |
+| steps | `--steps` | step execution |
+| debug | `--debug` | steps plus `output.debug` |
+| verbose | `--verbose` | debug plus `output.log` (internal logs and recorder activity) |
+
+```js
+import { output } from 'codeceptjs'
+
+output.print('basic information')
+output.debug('debug information')
+output.log('verbose logging information')
+```
+
+Use these instead of `console.log` so messages respect the chosen verbosity.
+
+## Helpers and the Actor
+
+The `I` object is an **actor** assembled from the enabled helpers. Each `I.method()` call delegates to the matching helper method and is wrapped as a step. Methods whose names start with `_` are private to the helper and not exposed on `I`. To add your own actions, write a [custom helper](/helpers).
+
+## Running CodeceptJS from Code
+
+CodeceptJS can be driven from your own script. Create the runner with a config and options, initialize it, then bootstrap, load tests, and run:
+
+```js
+import { codecept as Codecept } from 'codeceptjs'
+
+const config = { helpers: { Playwright: { browser: 'chromium', url: 'http://localhost' } } }
+const opts = { steps: true }
+
+const codecept = new Codecept(config, opts)
+codecept.init(import.meta.dirname)   // the test root directory
+
+try {
+  await codecept.bootstrap()
+  codecept.loadTests('**/*_test.js')
+  await codecept.run()               // pass a test file path to run only that file
+} catch (err) {
+  console.error(err)
+  process.exitCode = 1
+} finally {
+  await codecept.teardown()
+}
+```
+
+> To run tests inside workers from a script, see [parallel execution](/parallel).
+
+---
+
+**See also:** [Extending CodeceptJS](/hooks) · [Custom Helpers](/helpers) · [Plugins](/plugins) · [Bootstrap & Teardown](/bootstrap)