@testspectra/cli 1.1.6 → 1.1.8-rc.1

package/dist/refactor/__tests__/refactor-engine.test.js

@@ -45,6 +45,63 @@ describe('CLI Workspace-Wide Symbol Refactoring Engine (docs/v2/cli/synchronized
         expect(updatedSpec).toContain('AuthPage.username');
         expect(updatedSpec).not.toContain('LoginPage.username');
     });
+    it('renames page-object with export default new ClassName() pattern across web.ts and mobile.ts', async () => {
+        // 1. Setup MatchersPage directory with both mobile.ts and web.ts matching the default template
+        const poDir = path.join(tmpDir, 'page-objects', 'MatchersPage');
+        fs.mkdirSync(poDir, { recursive: true });
+        fs.writeFileSync(path.join(poDir, 'mobile.ts'), 'export class MatchersPage {\n  get visibleElement() { return Spectra.get("~visible"); }\n}\n\nexport default new MatchersPage();\n');
+        fs.writeFileSync(path.join(poDir, 'web.ts'), 'export class MatchersPage {\n  get visibleElement() { return Spectra.get("#visible"); }\n}\n\nexport default new MatchersPage();\n');
+        // 2. Setup spec referencing MatchersPage
+        const specDir = path.join(tmpDir, 'specs', 'Matchers');
+        fs.mkdirSync(specDir, { recursive: true });
+        const specFile = path.join(specDir, 'mobile.test.ts');
+        fs.writeFileSync(specFile, 'await MatchersPage.visibleElement.shouldBeVisible();\nconst instance = new MatchersPage();');
+        const result = await RefactorEngine.renameSymbol({
+            workspaceRoot: tmpDir,
+            type: 'page-object',
+            oldName: 'MatchersPage',
+            newName: 'AssertionsPage',
+        });
+        expect(result.status).toBe('success');
+        expect(result.oldSymbol).toBe('MatchersPage');
+        expect(result.newSymbol).toBe('AssertionsPage');
+        // Verify folder was renamed
+        expect(fs.existsSync(path.join(tmpDir, 'page-objects', 'MatchersPage'))).toBe(false);
+        const targetDir = path.join(tmpDir, 'page-objects', 'AssertionsPage');
+        expect(fs.existsSync(targetDir)).toBe(true);
+        // Verify mobile.ts updated both `class AssertionsPage` and `export default new AssertionsPage();`
+        const updatedMobile = fs.readFileSync(path.join(targetDir, 'mobile.ts'), 'utf-8');
+        expect(updatedMobile).toContain('export class AssertionsPage');
+        expect(updatedMobile).toContain('export default new AssertionsPage();');
+        expect(updatedMobile).not.toContain('MatchersPage');
+        // Verify web.ts updated both `class AssertionsPage` and `export default new AssertionsPage();`
+        const updatedWeb = fs.readFileSync(path.join(targetDir, 'web.ts'), 'utf-8');
+        expect(updatedWeb).toContain('export class AssertionsPage');
+        expect(updatedWeb).toContain('export default new AssertionsPage();');
+        expect(updatedWeb).not.toContain('MatchersPage');
+        // Verify spec updated both static access and new instantiation
+        const updatedSpec = fs.readFileSync(specFile, 'utf-8');
+        expect(updatedSpec).toContain('AssertionsPage.visibleElement.shouldBeVisible()');
+        expect(updatedSpec).toContain('const instance = new AssertionsPage();');
+        expect(updatedSpec).not.toContain('MatchersPage');
+    });
+    it('renames page-object with export default ClassName (without new)', async () => {
+        const poDir = path.join(tmpDir, 'page-objects', 'CustomPage');
+        fs.mkdirSync(poDir, { recursive: true });
+        fs.writeFileSync(path.join(poDir, 'web.ts'), 'class CustomPage {}\n\nexport default CustomPage;\n');
+        const result = await RefactorEngine.renameSymbol({
+            workspaceRoot: tmpDir,
+            type: 'page-object',
+            oldName: 'CustomPage',
+            newName: 'BrandNewPage',
+        });
+        expect(result.status).toBe('success');
+        const targetDir = path.join(tmpDir, 'page-objects', 'BrandNewPage');
+        const updatedWeb = fs.readFileSync(path.join(targetDir, 'web.ts'), 'utf-8');
+        expect(updatedWeb).toContain('class BrandNewPage');
+        expect(updatedWeb).toContain('export default BrandNewPage;');
+        expect(updatedWeb).not.toContain('CustomPage');
+    });
     it('renames shared step folder, spec directives, and Step call sites', async () => {
         const stepDir = path.join(tmpDir, 'support', 'steps', 'loginUser');
         fs.mkdirSync(stepDir, { recursive: true });
@@ -172,4 +229,645 @@ describe('CLI Workspace-Wide Symbol Refactoring Engine (docs/v2/cli/synchronized
             writeSpy.mockRestore();
         }
     });
+    it('enforces entity-specific naming conventions (PascalCase, camelCase, snake_case)', async () => {
+        // 1. Page Object must be PascalCase
+        const poRes1 = await RefactorEngine.renameSymbol({
+            workspaceRoot: tmpDir,
+            type: 'page-object',
+            oldName: 'LoginPage',
+            newName: 'authPage', // rejected: starts with lowercase
+        });
+        expect(poRes1.status).toBe('failed');
+        expect(poRes1.error).toContain('PascalCase');
+        // oldName is not restricted by convention so legacy badly-named symbols can be fixed
+        fs.mkdirSync(path.join(tmpDir, 'page-objects', 'loginPage'), { recursive: true });
+        const poRes2 = await RefactorEngine.renameSymbol({
+            workspaceRoot: tmpDir,
+            type: 'page-object',
+            oldName: 'loginPage', // legacy lowercase symbol
+            newName: 'AuthPage', // valid PascalCase
+            dryRun: true,
+        });
+        expect(poRes2.status).toBe('success');
+        // 2. Step must be camelCase
+        const stepRes1 = await RefactorEngine.renameSymbol({
+            workspaceRoot: tmpDir,
+            type: 'step',
+            oldName: 'loginUser',
+            newName: 'LoginAsAdmin', // rejected: PascalCase
+        });
+        expect(stepRes1.status).toBe('failed');
+        expect(stepRes1.error).toContain('camelCase');
+        // 3. Action must be camelCase
+        const actionRes1 = await RefactorEngine.renameSymbol({
+            workspaceRoot: tmpDir,
+            type: 'action',
+            oldName: 'customSwipe',
+            newName: 'SwipeTop', // rejected: PascalCase
+        });
+        expect(actionRes1.status).toBe('failed');
+        expect(actionRes1.error).toContain('camelCase');
+        // 4. Fixture allows camelCase and snake_case starting with lowercase
+        fs.mkdirSync(path.join(tmpDir, 'fixtures'), { recursive: true });
+        fs.writeFileSync(path.join(tmpDir, 'fixtures', 'users.json'), '{}');
+        const fixCamelRes = await RefactorEngine.renameSymbol({
+            workspaceRoot: tmpDir,
+            type: 'fixture',
+            oldName: 'users',
+            newName: 'userAccounts',
+            dryRun: true,
+        });
+        expect(fixCamelRes.status).toBe('success');
+        const fixSnakeRes = await RefactorEngine.renameSymbol({
+            workspaceRoot: tmpDir,
+            type: 'fixture',
+            oldName: 'users',
+            newName: 'user_accounts',
+            dryRun: true,
+        });
+        expect(fixSnakeRes.status).toBe('success');
+        const fixInvalidRes = await RefactorEngine.renameSymbol({
+            workspaceRoot: tmpDir,
+            type: 'fixture',
+            oldName: 'users',
+            newName: 'UserAccounts', // rejected: PascalCase
+        });
+        expect(fixInvalidRes.status).toBe('failed');
+        expect(fixInvalidRes.error).toContain('camelCase or snake_case');
+    });
+    it('rejects refactoring if source symbol does not exist in the workspace', async () => {
+        // 1. Nonexistent page-object
+        const poRes = await RefactorEngine.renameSymbol({
+            workspaceRoot: tmpDir,
+            type: 'page-object',
+            oldName: 'NonExistentPage',
+            newName: 'ValidNewPage',
+            dryRun: true,
+        });
+        expect(poRes.status).toBe('failed');
+        expect(poRes.error).toContain('Source page-object "NonExistentPage" was not found in the workspace');
+        // 2. Nonexistent step
+        const stepRes = await RefactorEngine.renameSymbol({
+            workspaceRoot: tmpDir,
+            type: 'step',
+            oldName: 'nonExistentStep',
+            newName: 'validNewStep',
+            dryRun: true,
+        });
+        expect(stepRes.status).toBe('failed');
+        expect(stepRes.error).toContain('Source step "nonExistentStep" was not found in the workspace');
+        // 3. Nonexistent action
+        const actionRes = await RefactorEngine.renameSymbol({
+            workspaceRoot: tmpDir,
+            type: 'action',
+            oldName: 'nonExistentAction',
+            newName: 'validNewAction',
+            dryRun: true,
+        });
+        expect(actionRes.status).toBe('failed');
+        expect(actionRes.error).toContain('Source action "nonExistentAction" was not found in the workspace');
+        // 4. Nonexistent fixture
+        const fixRes = await RefactorEngine.renameSymbol({
+            workspaceRoot: tmpDir,
+            type: 'fixture',
+            oldName: 'nonExistentFixture',
+            newName: 'validNewFixture',
+            dryRun: true,
+        });
+        expect(fixRes.status).toBe('failed');
+        expect(fixRes.error).toContain('Source fixture "nonExistentFixture" was not found in the workspace');
+    });
+    it('prioritizes source non-existence error over target collision', async () => {
+        const poDir = path.join(tmpDir, 'page-objects', 'ExistingTargetPage');
+        fs.mkdirSync(poDir, { recursive: true });
+        // Target exists, but source does NOT exist
+        const result = await RefactorEngine.renameSymbol({
+            workspaceRoot: tmpDir,
+            type: 'page-object',
+            oldName: 'NonExistentSource',
+            newName: 'ExistingTargetPage',
+            dryRun: true,
+        });
+        expect(result.status).toBe('failed');
+        expect(result.error).toContain('Source page-object "NonExistentSource" was not found in the workspace');
+        expect(result.error).not.toContain('already exists');
+    });
+    it('rejects refactoring if target page-object directory already exists on disk', async () => {
+        const poDir1 = path.join(tmpDir, 'page-objects', 'LoginPage');
+        const poDir2 = path.join(tmpDir, 'page-objects', 'AuthPage');
+        fs.mkdirSync(poDir1, { recursive: true });
+        fs.mkdirSync(poDir2, { recursive: true });
+        const result = await RefactorEngine.renameSymbol({
+            workspaceRoot: tmpDir,
+            type: 'page-object',
+            oldName: 'LoginPage',
+            newName: 'AuthPage',
+        });
+        expect(result.status).toBe('failed');
+        expect(result.error).toContain('already exists');
+    });
+    it('rejects refactoring if target fixture file already exists on disk', async () => {
+        const fixturesDir = path.join(tmpDir, 'fixtures');
+        fs.mkdirSync(fixturesDir, { recursive: true });
+        fs.writeFileSync(path.join(fixturesDir, 'users.json'), '{}');
+        fs.writeFileSync(path.join(fixturesDir, 'accounts.json'), '{}');
+        const result = await RefactorEngine.renameSymbol({
+            workspaceRoot: tmpDir,
+            type: 'fixture',
+            oldName: 'users',
+            newName: 'accounts',
+        });
+        expect(result.status).toBe('failed');
+        expect(result.error).toContain('already exists');
+    });
+    it('refactors fixtures across multi-format extensions (.csv, .yaml, .yml, .ts, .js) and string references', async () => {
+        const fixturesDir = path.join(tmpDir, 'fixtures');
+        fs.mkdirSync(fixturesDir, { recursive: true });
+        fs.writeFileSync(path.join(fixturesDir, 'dataset.csv'), 'id,name\n1,Alpha');
+        fs.writeFileSync(path.join(fixturesDir, 'config.yaml'), 'env: production');
+        fs.writeFileSync(path.join(fixturesDir, 'rules.yml'), 'enabled: true');
+        fs.writeFileSync(path.join(fixturesDir, 'mockData.ts'), 'export default {}');
+        fs.writeFileSync(path.join(fixturesDir, 'helpers.js'), 'module.exports = {}');
+        const specDir = path.join(tmpDir, 'specs', 'Data');
+        fs.mkdirSync(specDir, { recursive: true });
+        const specFile = path.join(specDir, 'web.test.ts');
+        fs.writeFileSync(specFile, "const d = Fixture.dataset;\nconst path = 'fixtures/dataset.csv';\nconst c = Fixture.config;\nconst m = Fixture.mockData;");
+        // 1. Refactor dataset.csv -> data_records.csv
+        const res1 = await RefactorEngine.renameSymbol({
+            workspaceRoot: tmpDir,
+            type: 'fixture',
+            oldName: 'dataset',
+            newName: 'data_records',
+        });
+        expect(res1.status).toBe('success');
+        expect(fs.existsSync(path.join(fixturesDir, 'dataset.csv'))).toBe(false);
+        expect(fs.existsSync(path.join(fixturesDir, 'data_records.csv'))).toBe(true);
+        // 2. Refactor mockData.ts -> appMocks.ts
+        const res2 = await RefactorEngine.renameSymbol({
+            workspaceRoot: tmpDir,
+            type: 'fixture',
+            oldName: 'mockData',
+            newName: 'appMocks',
+        });
+        expect(res2.status).toBe('success');
+        expect(fs.existsSync(path.join(fixturesDir, 'mockData.ts'))).toBe(false);
+        expect(fs.existsSync(path.join(fixturesDir, 'appMocks.ts'))).toBe(true);
+        // Verify spec updates for both Fixture.<name> and 'filename.ext'
+        const updatedSpec = fs.readFileSync(specFile, 'utf-8');
+        expect(updatedSpec).toContain('Fixture.data_records');
+        expect(updatedSpec).toContain("'fixtures/data_records.csv'");
+        expect(updatedSpec).toContain('Fixture.appMocks');
+        expect(updatedSpec).not.toContain('Fixture.dataset');
+        expect(updatedSpec).not.toContain("'fixtures/dataset.csv'");
+        expect(updatedSpec).not.toContain('Fixture.mockData');
+    });
+    it('supports passing fixture name with extension and nested subdirectories', async () => {
+        const nestedDir = path.join(tmpDir, 'fixtures', 'auth');
+        fs.mkdirSync(nestedDir, { recursive: true });
+        fs.writeFileSync(path.join(nestedDir, 'tokens.yaml'), 'jwt: secret');
+        const result = await RefactorEngine.renameSymbol({
+            workspaceRoot: tmpDir,
+            type: 'fixture',
+            oldName: 'tokens.yaml',
+            newName: 'auth_tokens.yaml',
+        });
+        expect(result.status).toBe('success');
+        expect(fs.existsSync(path.join(nestedDir, 'tokens.yaml'))).toBe(false);
+        expect(fs.existsSync(path.join(nestedDir, 'auth_tokens.yaml'))).toBe(true);
+    });
+    describe('parseEntityFromPath deterministic detection', () => {
+        it('parses page-object paths across directory, file, and trailing slash variants', () => {
+            expect(RefactorEngine.parseEntityFromPath('page-objects/LoginPage')).toEqual({
+                type: 'page-object',
+                symbol: 'LoginPage',
+            });
+            expect(RefactorEngine.parseEntityFromPath('page-objects/LoginPage/')).toEqual({
+                type: 'page-object',
+                symbol: 'LoginPage',
+            });
+            expect(RefactorEngine.parseEntityFromPath('page-objects/LoginPage/web.ts')).toEqual({
+                type: 'page-object',
+                symbol: 'LoginPage',
+            });
+            expect(RefactorEngine.parseEntityFromPath('page-objects/LoginPage.ts')).toEqual({
+                type: 'page-object',
+                symbol: 'LoginPage',
+            });
+            expect(RefactorEngine.parseEntityFromPath('C:\\repo\\page-objects\\LoginPage')).toEqual({
+                type: 'page-object',
+                symbol: 'LoginPage',
+            });
+        });
+        it('parses step paths across support/steps, steps, and nested step files', () => {
+            expect(RefactorEngine.parseEntityFromPath('support/steps/loginUser')).toEqual({
+                type: 'step',
+                symbol: 'loginUser',
+            });
+            expect(RefactorEngine.parseEntityFromPath('support/steps/loginUser/')).toEqual({
+                type: 'step',
+                symbol: 'loginUser',
+            });
+            expect(RefactorEngine.parseEntityFromPath('steps/loginUser')).toEqual({
+                type: 'step',
+                symbol: 'loginUser',
+            });
+            expect(RefactorEngine.parseEntityFromPath('support/steps/loginUser/step.md')).toEqual({
+                type: 'step',
+                symbol: 'loginUser',
+            });
+            expect(RefactorEngine.parseEntityFromPath('support/steps/loginUser/web.ts')).toEqual({
+                type: 'step',
+                symbol: 'loginUser',
+            });
+        });
+        it('parses action paths across support/actions and actions', () => {
+            expect(RefactorEngine.parseEntityFromPath('support/actions/customSwipe')).toEqual({
+                type: 'action',
+                symbol: 'customSwipe',
+            });
+            expect(RefactorEngine.parseEntityFromPath('actions/customSwipe')).toEqual({
+                type: 'action',
+                symbol: 'customSwipe',
+            });
+            expect(RefactorEngine.parseEntityFromPath('support/actions/customSwipe/action.ts')).toEqual({
+                type: 'action',
+                symbol: 'customSwipe',
+            });
+        });
+        it('parses fixture paths across extensions and nested subdirectories', () => {
+            expect(RefactorEngine.parseEntityFromPath('fixtures/users.json')).toEqual({
+                type: 'fixture',
+                symbol: 'users',
+            });
+            expect(RefactorEngine.parseEntityFromPath('fixtures/users.csv')).toEqual({
+                type: 'fixture',
+                symbol: 'users',
+            });
+            expect(RefactorEngine.parseEntityFromPath('fixtures/auth/tokens.yaml')).toEqual({
+                type: 'fixture',
+                symbol: 'tokens',
+            });
+            expect(RefactorEngine.parseEntityFromPath('fixtures/users')).toEqual({
+                type: 'fixture',
+                symbol: 'users',
+            });
+        });
+        it('returns null for non-entity paths or root directory paths without entity symbol', () => {
+            expect(RefactorEngine.parseEntityFromPath('')).toBeNull();
+            expect(RefactorEngine.parseEntityFromPath('src/utils/helpers.ts')).toBeNull();
+            expect(RefactorEngine.parseEntityFromPath('page-objects')).toBeNull();
+            expect(RefactorEngine.parseEntityFromPath('page-objects/')).toBeNull();
+            expect(RefactorEngine.parseEntityFromPath('fixtures/')).toBeNull();
+            expect(RefactorEngine.parseEntityFromPath('support/steps')).toBeNull();
+        });
+    });
+    describe('renameFromPaths path-based refactoring', () => {
+        it('successfully refactors page-object using paths', async () => {
+            const poDir = path.join(tmpDir, 'page-objects', 'LoginPage');
+            fs.mkdirSync(poDir, { recursive: true });
+            fs.writeFileSync(path.join(poDir, 'web.ts'), 'export default class LoginPage {}');
+            const specDir = path.join(tmpDir, 'specs', 'Auth');
+            fs.mkdirSync(specDir, { recursive: true });
+            const specFile = path.join(specDir, 'web.test.ts');
+            fs.writeFileSync(specFile, 'LoginPage.submit();');
+            const result = await RefactorEngine.renameFromPaths({
+                workspaceRoot: tmpDir,
+                fromPath: 'page-objects/LoginPage',
+                toPath: 'page-objects/AuthPage',
+            });
+            expect(result.status).toBe('success');
+            expect(result.entityType).toBe('page-object');
+            expect(fs.existsSync(path.join(tmpDir, 'page-objects', 'LoginPage'))).toBe(false);
+            expect(fs.existsSync(path.join(tmpDir, 'page-objects', 'AuthPage'))).toBe(true);
+            expect(fs.readFileSync(specFile, 'utf-8')).toContain('AuthPage.submit();');
+        });
+        it('successfully previews changes with dry-run mode using paths', async () => {
+            const poDir = path.join(tmpDir, 'page-objects', 'LoginPage');
+            fs.mkdirSync(poDir, { recursive: true });
+            fs.writeFileSync(path.join(poDir, 'web.ts'), 'export default class LoginPage {}');
+            const result = await RefactorEngine.renameFromPaths({
+                workspaceRoot: tmpDir,
+                fromPath: 'page-objects/LoginPage',
+                toPath: 'page-objects/AuthPage',
+                dryRun: true,
+            });
+            expect(result.status).toBe('success');
+            // Disk state must NOT be modified in dry-run
+            expect(fs.existsSync(path.join(tmpDir, 'page-objects', 'LoginPage'))).toBe(true);
+            expect(fs.existsSync(path.join(tmpDir, 'page-objects', 'AuthPage'))).toBe(false);
+        });
+        it('rejects cross-entity refactoring with type mismatch error', async () => {
+            const result = await RefactorEngine.renameFromPaths({
+                workspaceRoot: tmpDir,
+                fromPath: 'page-objects/LoginPage',
+                toPath: 'support/steps/loginUser',
+            });
+            expect(result.status).toBe('failed');
+            expect(result.error).toContain('Entity type mismatch');
+        });
+        it('rejects unparseable source or target paths', async () => {
+            const res1 = await RefactorEngine.renameFromPaths({
+                workspaceRoot: tmpDir,
+                fromPath: 'src/unknown/something',
+                toPath: 'page-objects/AuthPage',
+            });
+            expect(res1.status).toBe('failed');
+            expect(res1.error).toContain('Unable to determine entity type from source path');
+            const res2 = await RefactorEngine.renameFromPaths({
+                workspaceRoot: tmpDir,
+                fromPath: 'page-objects/LoginPage',
+                toPath: 'src/unknown/something',
+            });
+            expect(res2.status).toBe('failed');
+            expect(res2.error).toContain('Unable to determine entity type from target path');
+        });
+    });
+    describe('Edge-Cases & Robustness Guards (Step 2.4)', () => {
+        it('rejects refactoring if target step directory already exists in support/steps or steps', async () => {
+            const stepDir1 = path.join(tmpDir, 'support', 'steps', 'loginUser');
+            const stepDir2 = path.join(tmpDir, 'support', 'steps', 'loginAdmin');
+            fs.mkdirSync(stepDir1, { recursive: true });
+            fs.mkdirSync(stepDir2, { recursive: true });
+            const res = await RefactorEngine.renameSymbol({
+                workspaceRoot: tmpDir,
+                type: 'step',
+                oldName: 'loginUser',
+                newName: 'loginAdmin',
+            });
+            expect(res.status).toBe('failed');
+            expect(res.error).toContain('already exists');
+            // Also test root steps directory collision
+            const rootStep1 = path.join(tmpDir, 'steps', 'swipeLeft');
+            const rootStep2 = path.join(tmpDir, 'steps', 'swipeRight');
+            fs.mkdirSync(rootStep1, { recursive: true });
+            fs.mkdirSync(rootStep2, { recursive: true });
+            const res2 = await RefactorEngine.renameSymbol({
+                workspaceRoot: tmpDir,
+                type: 'step',
+                oldName: 'swipeLeft',
+                newName: 'swipeRight',
+            });
+            expect(res2.status).toBe('failed');
+            expect(res2.error).toContain('already exists');
+        });
+        it('rejects refactoring if target action directory already exists in support/actions or actions', async () => {
+            const actionDir1 = path.join(tmpDir, 'support', 'actions', 'customClick');
+            const actionDir2 = path.join(tmpDir, 'support', 'actions', 'tapElement');
+            fs.mkdirSync(actionDir1, { recursive: true });
+            fs.mkdirSync(actionDir2, { recursive: true });
+            const res = await RefactorEngine.renameSymbol({
+                workspaceRoot: tmpDir,
+                type: 'action',
+                oldName: 'customClick',
+                newName: 'tapElement',
+            });
+            expect(res.status).toBe('failed');
+            expect(res.error).toContain('already exists');
+            // Also test root actions directory collision
+            const rootAction1 = path.join(tmpDir, 'actions', 'pressKey');
+            const rootAction2 = path.join(tmpDir, 'actions', 'releaseKey');
+            fs.mkdirSync(rootAction1, { recursive: true });
+            fs.mkdirSync(rootAction2, { recursive: true });
+            const res2 = await RefactorEngine.renameSymbol({
+                workspaceRoot: tmpDir,
+                type: 'action',
+                oldName: 'pressKey',
+                newName: 'releaseKey',
+            });
+            expect(res2.status).toBe('failed');
+            expect(res2.error).toContain('already exists');
+        });
+        it('rejects refactoring if target fixture exists with a different extension (cross-format collision)', async () => {
+            const fixturesDir = path.join(tmpDir, 'fixtures');
+            fs.mkdirSync(fixturesDir, { recursive: true });
+            fs.writeFileSync(path.join(fixturesDir, 'users.json'), '{}');
+            // Target accounts already exists as accounts.csv!
+            fs.writeFileSync(path.join(fixturesDir, 'accounts.csv'), 'id,name');
+            const res = await RefactorEngine.renameSymbol({
+                workspaceRoot: tmpDir,
+                type: 'fixture',
+                oldName: 'users',
+                newName: 'accounts',
+            });
+            expect(res.status).toBe('failed');
+            expect(res.error).toContain('already exists');
+        });
+        it('rejects invalid identifier formats across all entity types', async () => {
+            // 1. Page Object: Must be PascalCase
+            const invalidPoNames = ['loginPage', 'login-page', '1LoginPage', 'Login Page', 'Login@Page', '_LoginPage'];
+            for (const name of invalidPoNames) {
+                const res = await RefactorEngine.renameSymbol({
+                    workspaceRoot: tmpDir,
+                    type: 'page-object',
+                    oldName: 'LoginPage',
+                    newName: name,
+                });
+                expect(res.status).toBe('failed');
+                expect(res.error).toContain('PascalCase');
+            }
+            // 2. Step: Must be camelCase
+            const invalidStepNames = ['LoginUser', 'login_user', 'login-user', '1login', 'login User', 'login$user'];
+            for (const name of invalidStepNames) {
+                const res = await RefactorEngine.renameSymbol({
+                    workspaceRoot: tmpDir,
+                    type: 'step',
+                    oldName: 'loginUser',
+                    newName: name,
+                });
+                expect(res.status).toBe('failed');
+                expect(res.error).toContain('camelCase');
+            }
+            // 3. Action: Must be camelCase
+            const invalidActionNames = ['SwipeUp', 'swipe_up', 'swipe-up', '1swipe', 'swipe!'];
+            for (const name of invalidActionNames) {
+                const res = await RefactorEngine.renameSymbol({
+                    workspaceRoot: tmpDir,
+                    type: 'action',
+                    oldName: 'swipeUp',
+                    newName: name,
+                });
+                expect(res.status).toBe('failed');
+                expect(res.error).toContain('camelCase');
+            }
+            // 4. Fixture: Must be camelCase or snake_case starting with lowercase
+            const invalidFixtureNames = ['Users', 'UserAccounts', 'user-data', '1users', 'users.data', 'users data'];
+            for (const name of invalidFixtureNames) {
+                const res = await RefactorEngine.renameSymbol({
+                    workspaceRoot: tmpDir,
+                    type: 'fixture',
+                    oldName: 'users',
+                    newName: name,
+                });
+                expect(res.status).toBe('failed');
+                expect(res.error).toContain('camelCase or snake_case');
+            }
+        });
+        it('rejects identical oldName and newName or empty names', async () => {
+            const resIdentical = await RefactorEngine.renameSymbol({
+                workspaceRoot: tmpDir,
+                type: 'page-object',
+                oldName: 'LoginPage',
+                newName: 'LoginPage',
+            });
+            expect(resIdentical.status).toBe('failed');
+            expect(resIdentical.error).toContain('Invalid or identical');
+            const resEmpty = await RefactorEngine.renameSymbol({
+                workspaceRoot: tmpDir,
+                type: 'page-object',
+                oldName: '',
+                newName: 'AuthPage',
+            });
+            expect(resEmpty.status).toBe('failed');
+            expect(resEmpty.error).toContain('Invalid or identical');
+        });
+        it('supports fixtures located in support/fixtures directory and preserves nested subdirectories', async () => {
+            const supportFixDir = path.join(tmpDir, 'support', 'fixtures', 'billing');
+            fs.mkdirSync(supportFixDir, { recursive: true });
+            fs.writeFileSync(path.join(supportFixDir, 'invoices.json'), '{"id": 1}');
+            const specDir = path.join(tmpDir, 'specs', 'Billing');
+            fs.mkdirSync(specDir, { recursive: true });
+            const specFile = path.join(specDir, 'web.test.ts');
+            fs.writeFileSync(specFile, 'const inv = Fixture.invoices;\nconst file = "support/fixtures/billing/invoices.json";');
+            const res = await RefactorEngine.renameSymbol({
+                workspaceRoot: tmpDir,
+                type: 'fixture',
+                oldName: 'invoices',
+                newName: 'receipts',
+            });
+            expect(res.status).toBe('success');
+            expect(fs.existsSync(path.join(supportFixDir, 'invoices.json'))).toBe(false);
+            expect(fs.existsSync(path.join(supportFixDir, 'receipts.json'))).toBe(true);
+            const updatedSpec = fs.readFileSync(specFile, 'utf-8');
+            expect(updatedSpec).toContain('Fixture.receipts');
+            expect(updatedSpec).toContain('"support/fixtures/billing/receipts.json"');
+            expect(updatedSpec).not.toContain('Fixture.invoices');
+        });
+        it('handles refactoring when old entity directory does not exist on disk gracefully', async () => {
+            // If the old page-object directory does not exist on disk,
+            // it should still update references in spec files if any exist, without crashing
+            const specDir = path.join(tmpDir, 'specs', 'Orphan');
+            fs.mkdirSync(specDir, { recursive: true });
+            const specFile = path.join(specDir, 'web.test.ts');
+            fs.writeFileSync(specFile, 'await GhostPage.click();');
+            const res = await RefactorEngine.renameSymbol({
+                workspaceRoot: tmpDir,
+                type: 'page-object',
+                oldName: 'GhostPage',
+                newName: 'ActivePage',
+            });
+            expect(res.status).toBe('success');
+            expect(fs.readFileSync(specFile, 'utf-8')).toContain('await ActivePage.click();');
+        });
+        it('propagates refactoring across multi-package Nx monorepo structure (packages/**/specs/**)', async () => {
+            // 1. Setup Nx monorepo indicator and root shared assets
+            fs.writeFileSync(path.join(tmpDir, 'nx.json'), JSON.stringify({}));
+            fs.writeFileSync(path.join(tmpDir, 'pnpm-workspace.yaml'), 'packages:\n  - "packages/*"\n');
+            const rootPoDir = path.join(tmpDir, 'page-objects', 'AuthPage');
+            fs.mkdirSync(rootPoDir, { recursive: true });
+            fs.writeFileSync(path.join(rootPoDir, 'web.ts'), 'export default class AuthPage {}');
+            const rootFixDir = path.join(tmpDir, 'fixtures');
+            fs.mkdirSync(rootFixDir, { recursive: true });
+            fs.writeFileSync(path.join(rootFixDir, 'users.json'), '{"role": "admin"}');
+            // 2. Setup Sub-package 1: packages/portal-e2e
+            const portalSpecDir = path.join(tmpDir, 'packages', 'portal-e2e', 'specs');
+            fs.mkdirSync(portalSpecDir, { recursive: true });
+            const portalSpecFile = path.join(portalSpecDir, 'login.web.test.ts');
+            fs.writeFileSync(portalSpecFile, 'it("logs into portal", async () => {\n  await AuthPage.login();\n  const u = Fixture.users;\n});');
+            // 3. Setup Sub-package 2: packages/admin-e2e
+            const adminSpecDir = path.join(tmpDir, 'packages', 'admin-e2e', 'specs');
+            fs.mkdirSync(adminSpecDir, { recursive: true });
+            const adminSpecFile = path.join(adminSpecDir, 'dashboard.web.test.ts');
+            fs.writeFileSync(adminSpecFile, 'it("verifies admin dashboard", async () => {\n  await AuthPage.login();\n  const u = Fixture.users;\n});');
+            // 4. Refactor root Page Object: AuthPage -> IdentityPage
+            const poRes = await RefactorEngine.renameSymbol({
+                workspaceRoot: tmpDir,
+                type: 'page-object',
+                oldName: 'AuthPage',
+                newName: 'IdentityPage',
+            });
+            expect(poRes.status).toBe('success');
+            expect(fs.existsSync(path.join(tmpDir, 'page-objects', 'AuthPage'))).toBe(false);
+            expect(fs.existsSync(path.join(tmpDir, 'page-objects', 'IdentityPage'))).toBe(true);
+            // Verify propagation into both sub-packages in packages/**
+            expect(fs.readFileSync(portalSpecFile, 'utf-8')).toContain('IdentityPage.login()');
+            expect(fs.readFileSync(portalSpecFile, 'utf-8')).not.toContain('AuthPage.login()');
+            expect(fs.readFileSync(adminSpecFile, 'utf-8')).toContain('IdentityPage.login()');
+            expect(fs.readFileSync(adminSpecFile, 'utf-8')).not.toContain('AuthPage.login()');
+            // 5. Refactor root Fixture: users -> user_accounts
+            const fixRes = await RefactorEngine.renameSymbol({
+                workspaceRoot: tmpDir,
+                type: 'fixture',
+                oldName: 'users',
+                newName: 'user_accounts',
+            });
+            expect(fixRes.status).toBe('success');
+            expect(fs.existsSync(path.join(rootFixDir, 'users.json'))).toBe(false);
+            expect(fs.existsSync(path.join(rootFixDir, 'user_accounts.json'))).toBe(true);
+            expect(fs.readFileSync(portalSpecFile, 'utf-8')).toContain('Fixture.user_accounts');
+            expect(fs.readFileSync(portalSpecFile, 'utf-8')).not.toContain('Fixture.users');
+            expect(fs.readFileSync(adminSpecFile, 'utf-8')).toContain('Fixture.user_accounts');
+            expect(fs.readFileSync(adminSpecFile, 'utf-8')).not.toContain('Fixture.users');
+        });
+        it('supports scoped refactoring within a specific Nx sub-package via workspaceRoot / cwd', async () => {
+            const mobilePkgDir = path.join(tmpDir, 'packages', 'mobile-e2e');
+            const mobilePoDir = path.join(mobilePkgDir, 'page-objects', 'WelcomePage');
+            fs.mkdirSync(mobilePoDir, { recursive: true });
+            fs.writeFileSync(path.join(mobilePoDir, 'mobile.ts'), 'export default class WelcomePage {}');
+            const mobileSpecDir = path.join(mobilePkgDir, 'specs');
+            fs.mkdirSync(mobileSpecDir, { recursive: true });
+            const mobileSpecFile = path.join(mobileSpecDir, 'welcome.mobile.test.ts');
+            fs.writeFileSync(mobileSpecFile, 'await WelcomePage.start();');
+            const webPkgDir = path.join(tmpDir, 'packages', 'web-e2e', 'specs');
+            fs.mkdirSync(webPkgDir, { recursive: true });
+            const webSpecFile = path.join(webPkgDir, 'other.web.test.ts');
+            fs.writeFileSync(webSpecFile, 'console.log("unrelated");');
+            // Execute refactoring scoped strictly to packages/mobile-e2e
+            const res = await RefactorEngine.renameSymbol({
+                workspaceRoot: mobilePkgDir,
+                type: 'page-object',
+                oldName: 'WelcomePage',
+                newName: 'OnboardingPage',
+            });
+            expect(res.status).toBe('success');
+            expect(fs.existsSync(path.join(mobilePkgDir, 'page-objects', 'WelcomePage'))).toBe(false);
+            expect(fs.existsSync(path.join(mobilePkgDir, 'page-objects', 'OnboardingPage'))).toBe(true);
+            expect(fs.readFileSync(mobileSpecFile, 'utf-8')).toContain('OnboardingPage.start();');
+            expect(fs.readFileSync(webSpecFile, 'utf-8')).toBe('console.log("unrelated");');
+        });
+        it('supports skipPathRename when directory or file was already renamed on disk by external watcher / IDE explorer', async () => {
+            const poDir = path.join(tmpDir, 'page-objects', 'LoginPage');
+            fs.mkdirSync(poDir, { recursive: true });
+            fs.writeFileSync(path.join(poDir, 'web.ts'), 'export default class LoginPage {}');
+            const specDir = path.join(tmpDir, 'specs', 'Auth');
+            fs.mkdirSync(specDir, { recursive: true });
+            const specFile = path.join(specDir, 'web.test.ts');
+            fs.writeFileSync(specFile, 'LoginPage.submit();');
+            // Simulate VS Code Explorer already renaming the folder on disk
+            const targetPoDir = path.join(tmpDir, 'page-objects', 'AuthPage');
+            fs.renameSync(poDir, targetPoDir);
+            // Dry-run check with skipPathRename: true
+            const dryResult = await RefactorEngine.renameFromPaths({
+                workspaceRoot: tmpDir,
+                fromPath: 'page-objects/LoginPage',
+                toPath: 'page-objects/AuthPage',
+                dryRun: true,
+                skipPathRename: true,
+            });
+            expect(dryResult.status).toBe('success');
+            expect(dryResult.occurrencesReplaced).toBe(2);
+            expect(dryResult.modifiedFiles.length).toBe(2);
+            // Execution with skipPathRename: true
+            const realResult = await RefactorEngine.renameFromPaths({
+                workspaceRoot: tmpDir,
+                fromPath: 'page-objects/LoginPage',
+                toPath: 'page-objects/AuthPage',
+                dryRun: false,
+                skipPathRename: true,
+            });
+            expect(realResult.status).toBe('success');
+            expect(realResult.occurrencesReplaced).toBe(2);
+            expect(fs.readFileSync(path.join(targetPoDir, 'web.ts'), 'utf-8')).toContain('class AuthPage');
+            expect(fs.readFileSync(specFile, 'utf-8')).toContain('AuthPage.submit();');
+        });
+    });
 });