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.)consttr=Reflection.forTest(test)console.log(tr.read())// full Scenario(...) sourceconsole.log(tr.fileName)// path to the source file// Build an edit — nothing is written yetconstedit=tr.replace(`Scenario('login works', async ({ I }) => { I.amOnPage('/') })`)console.log(edit.diff())// unified diff previewconsole.log(edit.preview())// full new sourceedit.apply()// atomic write to diskReflection.forStep(step,{ test })// StepReflectionReflection.forTest(test)// TestReflectionReflection.forSuite(suite)// SuiteReflection — addTest/removeTestReflection.forPageObject(filePath,{ name })// PageObjectReflection — add/replace/remove membersReflection.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:
constbatch=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