improved docs about store

Author: DavertMik

docs/architecture.md

@@ -35,6 +35,7 @@ import { recorder, event, output, container, config } from 'codeceptjs'
 | [`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 |
+| [`store`](https://github.com/codeceptjs/CodeceptJS/blob/master/lib/store.js) | global state of the run — current test/step, run modes, directories |
 | [`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 |
 
@@ -183,6 +184,21 @@ output.log('verbose logging information')
 
 Use these instead of `console.log` so messages respect the chosen verbosity.
 
+## Store
+
+`store` holds the state of the current run — the executing test, suite, and step, the active run modes (`dryRun`, `debugMode`, `workerMode`, …), and the project directories. Listeners, plugins, and helpers read it to know where in the [lifecycle](#events) they are without that information being passed to them:
+
+```js
+import { store } from 'codeceptjs'
+
+event.dispatcher.on(event.step.before, () => {
+  if (store.dryRun) return                    // no side effects on a dry run
+  output.debug(`in ${store.currentTest?.title}`)
+})
+```
+
+CodeceptJS keeps the state fields up to date for you. See the [Store reference](/store) for every field and when to write to it.
+
 ## 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).

docs/hooks.md

@@ -40,7 +40,17 @@ event.dispatcher.on(event.test.before, () => {
 })
 ```
 
-See [Architecture › Events](/architecture#events) for the full event list and the test and step object fields.
+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
 

docs/store.md

@@ -0,0 +1,94 @@
+---
+permalink: /store
+title: Store
+---
+
+# Store
+
+`store` is a global object that holds the state of the current run — which test and step are executing, which modes are enabled, and where the project lives on disk. Listeners, plugins, and helpers read it to find out *where in the lifecycle* they are without threading that information through every call.
+
+```js
+import { store } from 'codeceptjs'
+
+event.dispatcher.on(event.step.before, () => {
+  if (store.dryRun) return            // skip side effects on a dry run
+  console.log(`running ${store.currentTest?.title}`)
+})
+```
+
+It is a single shared object for the whole process. Read from it freely; write to it only if you are deliberately driving execution state (see [Writing to the store](#writing-to-the-store)).
+
+## Fields
+
+### Required
+
+Set once when the runner starts and immutable afterwards. Resolved from the test root, falling back to the legacy `global.codecept_dir` / `global.output_dir`.
+
+| Field | Type | What it is |
+| --- | --- | --- |
+| `store.codeceptDir` | `string` | root directory of the tests |
+| `store.outputDir` | `string` | resolved output directory for artifacts |
+| `store.workerMode` | `boolean` | `true` when running inside a [parallel](/parallel) worker |
+
+### Session config
+
+Set at session start and stable for that session. They reflect how the run was invoked.
+
+| Field | Type | What it is |
+| --- | --- | --- |
+| `store.debugMode` | `boolean` | run started with `--debug` |
+| `store.timeouts` | `boolean` | [timeouts](/timeouts) are enabled |
+| `store.autoRetries` | `boolean` | step auto-retries are active (the `tryTo` [effect](/effects) turns this off while it runs) |
+| `store.dryRun` | `boolean` | run is a `--dry-run`; steps must not cause side effects |
+| `store.featureOnly` | `boolean` | a `Feature.only()` was used |
+| `store.scenarioOnly` | `boolean` | a `Scenario.only()` was used |
+| `store.maskSensitiveData` | `boolean \| object` | mask [secret](/secrets) values in output |
+| `store.noGlobals` | `boolean` | `noGlobals` mode — the user imports everything instead of relying on globals |
+
+### State
+
+Changes constantly as the run progresses. The most useful fields for plugins and listeners:
+
+| Field | Type | What it is |
+| --- | --- | --- |
+| `store.onPause` | `boolean` | execution is paused inside [`pause()`](/basics#pause) |
+| `store.currentTest` | `Test \| null` | the running test, or `null` between tests |
+| `store.currentStep` | `Step \| null` | the running step, or `null` |
+| `store.currentSuite` | `Suite \| null` | the running suite, or `null` between suites |
+| `store.tsFileMapping` | `Map \| null` | TypeScript source-map lookup, when running `.ts` tests |
+
+`currentTest`, `currentStep`, and `currentSuite` carry the same objects passed to lifecycle events — see the [test and step object](/architecture#test-object) fields.
+
+## Reading the store
+
+A typical use is gating expensive or unsafe work by run mode:
+
+```js
+import { store, recorder } from 'codeceptjs'
+
+event.dispatcher.on(event.test.before, () => {
+  if (store.dryRun || store.workerMode) return
+
+  recorder.add('seed fixture data', async () => {
+    await api.post('/users', { name: 'john' })
+  })
+})
+```
+
+`store.currentTest` is the simplest way to attach context to the current test from anywhere — for example tagging an artifact:
+
+```js
+import { store } from 'codeceptjs'
+
+store.currentTest?.artifacts.push({ name: 'log', path: '/tmp/run.log' })
+```
+
+## Writing to the store
+
+CodeceptJS keeps the state fields current for you — the built-in [`store` listener](https://github.com/codeceptjs/CodeceptJS/blob/master/lib/listener/store.js) sets `currentSuite` and `currentTest` around each suite and test. You rarely need to write to it.
+
+Write only when you are deliberately driving execution — for example, a tool that opens `pause()` sets `store.onPause`. The required fields (`codeceptDir`, `outputDir`) are locked after `store.initialize()` and cannot be reassigned.
+
+---
+
+**See also:** [Architecture](/architecture) · [Extending CodeceptJS](/hooks) · [Events](/architecture#events)