Debugging CodeceptJS 4 Tests

Failures lie — the error usually points at a step that's a side effect of something earlier (auth expired, frame switch missed, network call pending). Reproduce, capture state, read it, then fix.

Paths

• MCP-first (AI agents): run_test / in-test pause() yield control to the agent on the same I / browser the test uses. Inspect via run_code / snapshot; step through via run_step_by_step + continue.
• CLI fallback (humans / CI / framework internals): --debug → --verbose → DEBUG="codeceptjs:*". The DEBUG escape hatch is only for framework-internal suspicion: recorder hangs, plugin races, event leaks, "step never ran". Namespaces: codeceptjs:recorder, codeceptjs:pause, codeceptjs:ai, codeceptjs:plugin:<name>.

pause() adapts to who's driving: TTY → readline REPL; MCP → yields control to the agent; non-TTY non-MCP subprocess → prints a notice and resolves (no CI deadlock).

Workflow