AST-based reflection for CodeceptJS tests, suites, and steps. Safely read and edit scenario source without regex.
npm install @codeceptjs/reflectionCodeceptJS test runners, healers, AI agents, and MCP servers need to read and rewrite scenario source code. Doing that with regex is fragile and unsafe. This package gives you a principled, AST-driven API to locate a step, test, or suite in its source file, read the exact range, and replace it while preserving formatting, comments, and metadata.
import { Reflection } from '@codeceptjs/reflection'
// You have a live CodeceptJS test object (from event.test.before, event.test.after, etc.)
const tr = Reflection.forTest(test)
console.log(tr.read()) // full Scenario(...) source
console.log(tr.fileName) // path to the source file
// Build an edit — nothing is written yet
const edit = tr.replace(`Scenario('login works', async ({ I }) => { I.amOnPage('/') })`)
console.log(edit.diff()) // unified diff preview
console.log(edit.preview()) // full new source
edit.apply() // atomic write to diskReflection.forStep(step, { test }) // StepReflection
Reflection.forTest(test) // TestReflection
Reflection.forSuite(suite) // SuiteReflection — addTest/removeTest
Reflection.forPageObject(filePath, { name }) // PageObjectReflection — add/replace/remove members
Reflection.project('./codecept.conf.js') // ProjectReflection — enumerate suites, tests, steps, page objectsEach forX reflector exposes the same shape: fileName, read(), replace(), plus type-specific accessors. SuiteReflection and PageObjectReflection also support programmatic add/remove of children.
Reflection.project(...) reads a CodeceptJS config and gives you the map of the whole project — then hands off individual targets to the specialized reflectors.
Replace multiple things in one file, one write:
const batch = Reflection.batch(filePath)
batch.add(sr1.replace('I.click("a")'))
batch.add(sr2.replace('I.click("b")'))
batch.apply()- Node.js 18+
- CodeceptJS 3.x or 4.x (optional peer — only needed at runtime by consumers)
typescriptpackage (optional peer — only needed if you reflect.ts/.tsxfiles)
MIT