@codeceptjs/reflection

AST-based reflection for CodeceptJS tests, suites, and steps. Safely read and edit scenario source without regex.

Install

npm install @codeceptjs/reflection

Why

CodeceptJS 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.

Quick start

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 disk

Reflection classes

Reflection.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 objects

Each 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.

Batching

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()

Documentation

• Getting started
• API reference
• Heal plugin integration
• AI-assisted editing
• Limitations

Requirements

• Node.js 18+
• CodeceptJS 3.x or 4.x (optional peer — only needed at runtime by consumers)
• typescript package (optional peer — only needed if you reflect .ts / .tsx files)

License

MIT