Debugging CodeceptJS 4 Tests

Failures lie. The error usually points at a step that's a side effect of something earlier — auth expired, a frame switch missed, a network call still pending. Reproduce, capture state, and read it before fixing.

Two paths, picked by who's driving:

• MCP-first (for AI agents) — drive the test through the MCP server. In-test pause() and the pauseAt: N option on run_test both yield control back to the agent in-process — same I / browser the test is using. Inspect via run_code / snapshot, advance one step at a time via run_step_by_step + continue, release a pause via continue. aiTrace artifacts cover the prior steps.
• CLI fallback (for humans / CI / framework internals) — npx codeceptjs run --debug for verbose framework output. Escalate to DEBUG="codeceptjs:*" when the framework itself looks at fault: recorder hangs, plugin races, event leaks, "step never ran". Use this path for CI repros, headless servers, and framework-internal bugs.

In-test pause() adapts to who's driving: at a TTY it opens the readline REPL; under MCP it yields control to the agent (same in-process I / browser); in a non-TTY non-MCP subprocess it prints a notice and resolves immediately so leftover pause() calls don't deadlock CI. Adding pause() is now the primary MCP breakpoint — drop it where you want to look, run via run_test, drive the live page through run_code, release with continue.

Workflow

1. Read the project (fundamentals)

Run the codeceptjs-fundamentals skill. You need: helper, plugins on (especially aiTrace, screenshot, pageInfo, retryFailedStep, pause, auth), env vars, whether MCP is wired up. If aiTrace is not declared, add it once with plugins: { aiTrace: { enabled: true } } — most of this skill leans on its output.

Declare aiTrace once; never edit config to change its trigger. The capture mode is controlled per-run from the CLI, exactly like the pause plugin: