@testspectra/cli 1.0.70 → 1.1.1

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

@@ -0,0 +1,175 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { RefactorEngine } from '../refactor-engine.js';
+describe('CLI Workspace-Wide Symbol Refactoring Engine (docs/v2/cli/synchronized-symbol-refactoring.md)', () => {
+    let tmpDir;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'testspectra-refactor-test-'));
+    });
+    afterEach(() => {
+        try {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+        catch { }
+    });
+    it('renames page-object class declaration, directory, and test call sites', async () => {
+        // 1. Setup LoginPage directory and files
+        const poDir = path.join(tmpDir, 'page-objects', 'LoginPage');
+        fs.mkdirSync(poDir, { recursive: true });
+        fs.writeFileSync(path.join(poDir, 'web.ts'), 'export default class LoginPage {\n  static username = "#user";\n}');
+        // 2. Setup spec referencing LoginPage
+        const specDir = path.join(tmpDir, 'specs', 'Auth');
+        fs.mkdirSync(specDir, { recursive: true });
+        const specFile = path.join(specDir, 'web.test.ts');
+        fs.writeFileSync(specFile, 'it("logs in", async () => {\n  await LoginPage.username;\n});');
+        const result = await RefactorEngine.renameSymbol({
+            workspaceRoot: tmpDir,
+            type: 'page-object',
+            oldName: 'LoginPage',
+            newName: 'AuthPage',
+        });
+        expect(result.status).toBe('success');
+        expect(result.oldSymbol).toBe('LoginPage');
+        expect(result.newSymbol).toBe('AuthPage');
+        // Verify folder was renamed
+        expect(fs.existsSync(path.join(tmpDir, 'page-objects', 'LoginPage'))).toBe(false);
+        expect(fs.existsSync(path.join(tmpDir, 'page-objects', 'AuthPage', 'web.ts'))).toBe(true);
+        // Verify class renamed inside page-object
+        const updatedPo = fs.readFileSync(path.join(tmpDir, 'page-objects', 'AuthPage', 'web.ts'), 'utf-8');
+        expect(updatedPo).toContain('class AuthPage');
+        expect(updatedPo).not.toContain('class LoginPage');
+        // Verify spec updated
+        const updatedSpec = fs.readFileSync(specFile, 'utf-8');
+        expect(updatedSpec).toContain('AuthPage.username');
+        expect(updatedSpec).not.toContain('LoginPage.username');
+    });
+    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 });
+        fs.writeFileSync(path.join(stepDir, 'web.step.ts'), 'export default async function loginUser() {}');
+        fs.writeFileSync(path.join(stepDir, 'step.md'), '# Step loginUser');
+        const specDir = path.join(tmpDir, 'specs', 'Auth');
+        fs.mkdirSync(specDir, { recursive: true });
+        const specFile = path.join(specDir, 'web.test.ts');
+        fs.writeFileSync(specFile, 'await Step.loginUser();');
+        const specDoc = path.join(specDir, 'spec.md');
+        fs.writeFileSync(specDoc, 'Execute @step:loginUser before test.');
+        const result = await RefactorEngine.renameSymbol({
+            workspaceRoot: tmpDir,
+            type: 'step',
+            oldName: 'loginUser',
+            newName: 'loginAsAdmin',
+        });
+        expect(result.status).toBe('success');
+        expect(fs.existsSync(path.join(tmpDir, 'support', 'steps', 'loginUser'))).toBe(false);
+        expect(fs.existsSync(path.join(tmpDir, 'support', 'steps', 'loginAsAdmin'))).toBe(true);
+        const updatedSpec = fs.readFileSync(specFile, 'utf-8');
+        expect(updatedSpec).toContain('Step.loginAsAdmin()');
+        expect(updatedSpec).not.toContain('Step.loginUser()');
+        const updatedDoc = fs.readFileSync(specDoc, 'utf-8');
+        expect(updatedDoc).toContain('@step:loginAsAdmin');
+        expect(updatedDoc).not.toContain('@step:loginUser');
+    });
+    it('renames custom action and updates Spectra.<name>() calls', async () => {
+        const actionDir = path.join(tmpDir, 'support', 'actions', 'customSwipe');
+        fs.mkdirSync(actionDir, { recursive: true });
+        fs.writeFileSync(path.join(actionDir, 'mobile.action.ts'), 'export default async function customSwipe() {}');
+        const specDir = path.join(tmpDir, 'specs', 'Feed');
+        fs.mkdirSync(specDir, { recursive: true });
+        const specFile = path.join(specDir, 'mobile.test.ts');
+        fs.writeFileSync(specFile, 'await Spectra.customSwipe();');
+        const result = await RefactorEngine.renameSymbol({
+            workspaceRoot: tmpDir,
+            type: 'action',
+            oldName: 'customSwipe',
+            newName: 'swipeTop',
+        });
+        expect(result.status).toBe('success');
+        expect(fs.existsSync(path.join(tmpDir, 'support', 'actions', 'customSwipe'))).toBe(false);
+        expect(fs.existsSync(path.join(tmpDir, 'support', 'actions', 'swipeTop'))).toBe(true);
+        const updatedSpec = fs.readFileSync(specFile, 'utf-8');
+        expect(updatedSpec).toContain('Spectra.swipeTop()');
+        expect(updatedSpec).not.toContain('Spectra.customSwipe()');
+    });
+    it('renames fixture file and propagates Fixture.<name> across call sites', async () => {
+        const fixturesDir = path.join(tmpDir, 'fixtures');
+        fs.mkdirSync(fixturesDir, { recursive: true });
+        fs.writeFileSync(path.join(fixturesDir, 'users.json'), JSON.stringify({ admin: true }));
+        const specDir = path.join(tmpDir, 'specs', 'Auth');
+        fs.mkdirSync(specDir, { recursive: true });
+        const specFile = path.join(specDir, 'web.test.ts');
+        fs.writeFileSync(specFile, 'const u = Fixture.users.admin;');
+        const result = await RefactorEngine.renameSymbol({
+            workspaceRoot: tmpDir,
+            type: 'fixture',
+            oldName: 'users',
+            newName: 'accounts',
+        });
+        expect(result.status).toBe('success');
+        expect(fs.existsSync(path.join(fixturesDir, 'users.json'))).toBe(false);
+        expect(fs.existsSync(path.join(fixturesDir, 'accounts.json'))).toBe(true);
+        const updatedSpec = fs.readFileSync(specFile, 'utf-8');
+        expect(updatedSpec).toContain('Fixture.accounts.admin');
+        expect(updatedSpec).not.toContain('Fixture.users.admin');
+    });
+    it('dry-run mode previews changes without modifying files or directory structures', async () => {
+        const poDir = path.join(tmpDir, 'page-objects', 'LoginPage');
+        fs.mkdirSync(poDir, { recursive: true });
+        fs.writeFileSync(path.join(poDir, 'web.ts'), '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.click();');
+        const result = await RefactorEngine.renameSymbol({
+            workspaceRoot: tmpDir,
+            type: 'page-object',
+            oldName: 'LoginPage',
+            newName: 'AuthPage',
+            dryRun: true,
+        });
+        expect(result.status).toBe('success');
+        expect(result.occurrencesReplaced).toBeGreaterThan(0);
+        // Ensure disk was NOT modified
+        expect(fs.existsSync(path.join(tmpDir, 'page-objects', 'LoginPage'))).toBe(true);
+        expect(fs.existsSync(path.join(tmpDir, 'page-objects', 'AuthPage'))).toBe(false);
+        expect(fs.readFileSync(specFile, 'utf-8')).toBe('LoginPage.click();');
+    });
+    it('atomic rollback guard restores original files if an error occurs midway', async () => {
+        const specDir = path.join(tmpDir, 'specs', 'Auth');
+        fs.mkdirSync(specDir, { recursive: true });
+        // File 1
+        const file1 = path.join(specDir, 'test1.ts');
+        fs.writeFileSync(file1, 'LoginPage.step1();');
+        // File 2
+        const file2 = path.join(specDir, 'test2.ts');
+        fs.writeFileSync(file2, 'LoginPage.step2();');
+        // Simulate an I/O write failure on file2 by spying on writeFileSync
+        let _writeCallCount = 0;
+        const realWriteFileSync = fs.writeFileSync;
+        const writeSpy = vi.spyOn(fs, 'writeFileSync').mockImplementation((filePath, data, opts) => {
+            _writeCallCount++;
+            if (typeof filePath === 'string' && filePath.endsWith('test2.ts')) {
+                throw new Error('Disk write simulated failure');
+            }
+            return realWriteFileSync(filePath, data, opts);
+        });
+        try {
+            const result = await RefactorEngine.renameSymbol({
+                workspaceRoot: tmpDir,
+                type: 'page-object',
+                oldName: 'LoginPage',
+                newName: 'AuthPage',
+            });
+            expect(result.status).toBe('failed');
+            expect(result.error).toContain('Atomic rollback executed');
+            // Verify file1 was restored to original content
+            const f1Content = fs.readFileSync(file1, 'utf-8');
+            expect(f1Content).toBe('LoginPage.step1();');
+        }
+        finally {
+            writeSpy.mockRestore();
+        }
+    });
+});

package/dist/refactor/index.d.ts

@@ -0,0 +1 @@
+export * from './refactor-engine.js';

package/dist/refactor/index.js

@@ -0,0 +1 @@
+export * from './refactor-engine.js';

package/dist/refactor/refactor-engine.d.ts

@@ -0,0 +1,25 @@
+export type RefactorType = 'page-object' | 'step' | 'action' | 'fixture';
+export interface RenameOptions {
+    workspaceRoot: string;
+    type: RefactorType;
+    oldName: string;
+    newName: string;
+    dryRun?: boolean;
+}
+export interface RefactorResult {
+    status: 'success' | 'failed';
+    entityType: RefactorType;
+    oldSymbol: string;
+    newSymbol: string;
+    modifiedFiles: string[];
+    occurrencesReplaced: number;
+    renamedPaths?: Array<{
+        from: string;
+        to: string;
+    }>;
+    error?: string;
+}
+export declare class RefactorEngine {
+    private static findFiles;
+    static renameSymbol(options: RenameOptions): Promise<RefactorResult>;
+}

package/dist/refactor/refactor-engine.js

@@ -0,0 +1,255 @@
+import fs from 'fs';
+import path from 'path';
+import { TypeGenerator } from '../generator/type-generator.js';
+export class RefactorEngine {
+    static findFiles(dir, extensions) {
+        const results = [];
+        if (!fs.existsSync(dir))
+            return results;
+        function walk(currentDir) {
+            const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (entry.name === 'node_modules' ||
+                    entry.name === 'dist' ||
+                    entry.name === '.git' ||
+                    entry.name === '.testspectra') {
+                    continue;
+                }
+                const fullPath = path.join(currentDir, entry.name);
+                if (entry.isDirectory()) {
+                    walk(fullPath);
+                }
+                else if (entry.isFile()) {
+                    if (extensions.some((ext) => entry.name.endsWith(ext))) {
+                        results.push(fullPath);
+                    }
+                }
+            }
+        }
+        walk(dir);
+        return results;
+    }
+    static async renameSymbol(options) {
+        const { workspaceRoot, type, oldName, newName, dryRun = false } = options;
+        if (!oldName || !newName || oldName === newName) {
+            return {
+                status: 'failed',
+                entityType: type,
+                oldSymbol: oldName,
+                newSymbol: newName,
+                modifiedFiles: [],
+                occurrencesReplaced: 0,
+                error: 'Invalid or identical old/new symbol names',
+            };
+        }
+        // Phase 1: Determine file operations and replacement patterns
+        const plannedRenames = [];
+        const plannedEdits = [];
+        let oldSymbol = oldName;
+        let newSymbol = newName;
+        // 1. Target Directory / File Discovery
+        if (type === 'page-object') {
+            oldSymbol = oldName;
+            newSymbol = newName;
+            const poDir = path.join(workspaceRoot, 'page-objects', oldName);
+            if (fs.existsSync(poDir)) {
+                plannedRenames.push({ from: poDir, to: path.join(workspaceRoot, 'page-objects', newName) });
+            }
+        }
+        else if (type === 'step') {
+            oldSymbol = `Step.${oldName}`;
+            newSymbol = `Step.${newName}`;
+            const stepCandidates = [
+                path.join(workspaceRoot, 'support', 'steps', oldName),
+                path.join(workspaceRoot, 'steps', oldName),
+            ];
+            for (const cand of stepCandidates) {
+                if (fs.existsSync(cand)) {
+                    const parent = path.dirname(cand);
+                    plannedRenames.push({ from: cand, to: path.join(parent, newName) });
+                }
+            }
+        }
+        else if (type === 'action') {
+            oldSymbol = `Spectra.${oldName}`;
+            newSymbol = `Spectra.${newName}`;
+            const actionCandidates = [
+                path.join(workspaceRoot, 'support', 'actions', oldName),
+                path.join(workspaceRoot, 'actions', oldName),
+            ];
+            for (const cand of actionCandidates) {
+                if (fs.existsSync(cand)) {
+                    const parent = path.dirname(cand);
+                    plannedRenames.push({ from: cand, to: path.join(parent, newName) });
+                }
+            }
+        }
+        else if (type === 'fixture') {
+            oldSymbol = `Fixture.${oldName}`;
+            newSymbol = `Fixture.${newName}`;
+            const fixturesDir = path.join(workspaceRoot, 'fixtures');
+            if (fs.existsSync(fixturesDir)) {
+                const entries = fs.readdirSync(fixturesDir);
+                for (const entry of entries) {
+                    const parsed = path.parse(entry);
+                    if (parsed.name === oldName) {
+                        plannedRenames.push({
+                            from: path.join(fixturesDir, entry),
+                            to: path.join(fixturesDir, `${newName}${parsed.ext}`),
+                        });
+                    }
+                }
+            }
+        }
+        // 2. Scan Codebases and AST replacements in memory
+        const searchDirs = [
+            path.join(workspaceRoot, 'specs'),
+            path.join(workspaceRoot, 'suites'),
+            path.join(workspaceRoot, 'page-objects'),
+            path.join(workspaceRoot, 'support'),
+            path.join(workspaceRoot, 'steps'),
+            path.join(workspaceRoot, 'actions'),
+            path.join(workspaceRoot, 'global-hooks'),
+        ];
+        const allCodeFiles = searchDirs.flatMap((dir) => this.findFiles(dir, ['.ts', '.js', '.md']));
+        const uniqueFiles = Array.from(new Set(allCodeFiles));
+        let totalOccurrences = 0;
+        for (const filePath of uniqueFiles) {
+            const originalContent = fs.readFileSync(filePath, 'utf-8');
+            let modified = originalContent;
+            let count = 0;
+            if (type === 'page-object') {
+                // Replace `class OldName` -> `class NewName`
+                const classReg = new RegExp(`\\bclass\\s+${oldName}\\b`, 'g');
+                const classMatches = (modified.match(classReg) || []).length;
+                if (classMatches > 0) {
+                    modified = modified.replace(classReg, `class ${newName}`);
+                    count += classMatches;
+                }
+                // Replace `OldName.` -> `NewName.`
+                const refReg = new RegExp(`\\b${oldName}\\.`, 'g');
+                const refMatches = (modified.match(refReg) || []).length;
+                if (refMatches > 0) {
+                    modified = modified.replace(refReg, `${newName}.`);
+                    count += refMatches;
+                }
+            }
+            else if (type === 'step') {
+                // Replace `Step.oldStep(` -> `Step.newStep(`
+                const stepCallReg = new RegExp(`\\bStep\\.${oldName}\\b`, 'g');
+                const stepCallMatches = (modified.match(stepCallReg) || []).length;
+                if (stepCallMatches > 0) {
+                    modified = modified.replace(stepCallReg, `Step.${newName}`);
+                    count += stepCallMatches;
+                }
+                // Replace `@step:oldStep` -> `@step:newStep` in markdown specs
+                const directiveReg = new RegExp(`@step:${oldName}\\b`, 'g');
+                const dirMatches = (modified.match(directiveReg) || []).length;
+                if (dirMatches > 0) {
+                    modified = modified.replace(directiveReg, `@step:${newName}`);
+                    count += dirMatches;
+                }
+            }
+            else if (type === 'action') {
+                // Replace `Spectra.oldAction(` -> `Spectra.newAction(`
+                const actionReg = new RegExp(`\\bSpectra\\.${oldName}\\b`, 'g');
+                const actionMatches = (modified.match(actionReg) || []).length;
+                if (actionMatches > 0) {
+                    modified = modified.replace(actionReg, `Spectra.${newName}`);
+                    count += actionMatches;
+                }
+            }
+            else if (type === 'fixture') {
+                // Replace `Fixture.oldFixture` -> `Fixture.newFixture`
+                const fixReg = new RegExp(`\\bFixture\\.${oldName}\\b`, 'g');
+                const fixMatches = (modified.match(fixReg) || []).length;
+                if (fixMatches > 0) {
+                    modified = modified.replace(fixReg, `Fixture.${newName}`);
+                    count += fixMatches;
+                }
+            }
+            if (count > 0) {
+                totalOccurrences += count;
+                plannedEdits.push({
+                    filePath,
+                    originalContent,
+                    newContent: modified,
+                    count,
+                });
+            }
+        }
+        if (dryRun) {
+            return {
+                status: 'success',
+                entityType: type,
+                oldSymbol,
+                newSymbol,
+                modifiedFiles: plannedEdits.map((e) => path.relative(workspaceRoot, e.filePath)),
+                occurrencesReplaced: totalOccurrences,
+                renamedPaths: plannedRenames,
+            };
+        }
+        // Phase 2: Atomic Flush & Rollback Guard
+        const modifiedFilesWritten = [];
+        const originalSnapshots = new Map();
+        try {
+            // 1. Write file edits
+            for (const edit of plannedEdits) {
+                originalSnapshots.set(edit.filePath, edit.originalContent);
+                fs.writeFileSync(edit.filePath, edit.newContent, 'utf-8');
+                modifiedFilesWritten.push(edit.filePath);
+            }
+            // 2. Perform path renames (directories and files)
+            for (const rn of plannedRenames) {
+                if (fs.existsSync(rn.from)) {
+                    const parent = path.dirname(rn.to);
+                    if (!fs.existsSync(parent))
+                        fs.mkdirSync(parent, { recursive: true });
+                    fs.renameSync(rn.from, rn.to);
+                }
+            }
+            // 3. Automatically regenerate ambient declarations post-refactor
+            TypeGenerator.generateAll(workspaceRoot);
+            const typesDir = path.join(workspaceRoot, '.testspectra', 'types');
+            if (fs.existsSync(typesDir)) {
+                modifiedFilesWritten.push(path.join(typesDir, 'web.d.ts'));
+            }
+            return {
+                status: 'success',
+                entityType: type,
+                oldSymbol,
+                newSymbol,
+                modifiedFiles: Array.from(new Set(modifiedFilesWritten.map((p) => path.relative(workspaceRoot, p)))),
+                occurrencesReplaced: totalOccurrences,
+                renamedPaths: plannedRenames,
+            };
+        }
+        catch (ioErr) {
+            // ROLLBACK GUARD: Restore all modified files from original snapshots
+            for (const [filePath, orig] of originalSnapshots.entries()) {
+                try {
+                    fs.writeFileSync(filePath, orig, 'utf-8');
+                }
+                catch { }
+            }
+            // Reverse path renames
+            for (const rn of plannedRenames) {
+                if (fs.existsSync(rn.to)) {
+                    try {
+                        fs.renameSync(rn.to, rn.from);
+                    }
+                    catch { }
+                }
+            }
+            return {
+                status: 'failed',
+                entityType: type,
+                oldSymbol,
+                newSymbol,
+                modifiedFiles: [],
+                occurrencesReplaced: 0,
+                error: `Atomic rollback executed due to I/O error: ${ioErr.message}`,
+            };
+        }
+    }
+}

package/dist/reporter/__tests__/semantic-formatter.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/reporter/__tests__/semantic-formatter.test.js

@@ -0,0 +1,73 @@
+import { describe, it, expect } from 'vitest';
+import { formatAction, formatAssertion } from '../semantic-formatter.js';
+describe('semantic-formatter', () => {
+    describe('formatAction', () => {
+        it('formats click', () => expect(formatAction('click', 'LoginPage.submitButton')).toBe('Click on element "LoginPage.submitButton"'));
+        it('formats doubleClick', () => expect(formatAction('doubleClick', 'targetBtn')).toBe('Double-click on element "targetBtn"'));
+        it('formats rightClick', () => expect(formatAction('rightClick', 'targetBtn')).toBe('Right-click on element "targetBtn"'));
+        it('formats type', () => expect(formatAction('type', 'LoginPage.emailInput', { text: 'admin@testspectra.dev' })).toBe('Type "admin@testspectra.dev" into element "LoginPage.emailInput"'));
+        it('formats clear', () => expect(formatAction('clear', 'input')).toBe('Clear text in element "input"'));
+        it('formats select', () => expect(formatAction('select', 'dropdown', { option: 'Option A' })).toBe('Select option "Option A" in element "dropdown"'));
+        it('formats hover', () => expect(formatAction('hover', 'menu')).toBe('Hover over element "menu"'));
+        it('formats dragDrop', () => expect(formatAction('dragDrop', 'source', { dest: 'dest' })).toBe('Drag element "source" and drop onto element "dest"'));
+        it('formats scrollIntoView', () => expect(formatAction('scrollIntoView', 'footer')).toBe('Scroll element "footer" into view'));
+        it('formats longPress', () => expect(formatAction('longPress', 'btn', { durationMs: 1500 })).toBe('Long-press on element "btn" for 1500ms'));
+        it('formats waitForElement', () => expect(formatAction('waitForElement', 'modal')).toBe('Wait for element "modal" to be displayed'));
+        it('formats navigate', () => expect(formatAction('navigate', undefined, { url: '/login' })).toBe('Navigate to "/login"'));
+        it('formats back', () => expect(formatAction('back')).toBe('Navigate back in browser'));
+        it('formats forward', () => expect(formatAction('forward')).toBe('Navigate forward in browser'));
+        it('formats refresh', () => expect(formatAction('refresh')).toBe('Refresh current page'));
+        it('formats setViewport', () => expect(formatAction('setViewport', undefined, { width: 1920, height: 1080 })).toBe('Set viewport to 1920x1080'));
+        it('formats wait', () => expect(formatAction('wait', undefined, { ms: 1000 })).toBe('Wait for 1000ms'));
+        it('formats pressKey', () => expect(formatAction('pressKey', undefined, { key: 'Enter' })).toBe('Press keyboard key "Enter"'));
+        it('formats scroll', () => expect(formatAction('scroll', undefined, { direction: 'down', pixels: 400 })).toBe('Scroll down by 400px'));
+        it('formats swipe', () => expect(formatAction('swipe', undefined, { direction: 'left', distance: 300 })).toBe('Swipe left by 300px'));
+        it('formats intercept', () => expect(formatAction('intercept', undefined, { method: 'GET', url: '/api/data' })).toBe('Intercept GET "/api/data" mock rule registered'));
+        it('formats clearCookies', () => expect(formatAction('clearCookies')).toBe('Clear all browser cookies'));
+        it('formats clearLocalStorage', () => expect(formatAction('clearLocalStorage')).toBe('Clear browser localStorage'));
+    });
+    describe('formatAssertion', () => {
+        // 38 assertions
+        it('formats be.visible', () => expect(formatAssertion('be.visible', 'DashboardPage.header')).toBe('Expect element "DashboardPage.header" to be visible'));
+        it('formats not.be.visible', () => expect(formatAssertion('not.be.visible', 'DashboardPage.header')).toBe('Expect element "DashboardPage.header" not to be visible'));
+        it('formats exist', () => expect(formatAssertion('exist', 'DashboardPage.header')).toBe('Expect element "DashboardPage.header" to exist in DOM'));
+        it('formats not.exist', () => expect(formatAssertion('not.exist', 'DashboardPage.header')).toBe('Expect element "DashboardPage.header" not to exist in DOM'));
+        it('formats be.clickable', () => expect(formatAssertion('be.clickable', 'btn')).toBe('Expect element "btn" to be clickable'));
+        it('formats not.be.clickable', () => expect(formatAssertion('not.be.clickable', 'btn')).toBe('Expect element "btn" not to be clickable'));
+        it('formats be.enabled', () => expect(formatAssertion('be.enabled', 'btn')).toBe('Expect element "btn" to be enabled'));
+        it('formats be.disabled', () => expect(formatAssertion('be.disabled', 'btn')).toBe('Expect element "btn" to be disabled'));
+        it('formats be.checked', () => expect(formatAssertion('be.checked', 'checkbox')).toBe('Expect element "checkbox" to be checked'));
+        it('formats not.be.checked', () => expect(formatAssertion('not.be.checked', 'checkbox')).toBe('Expect element "checkbox" not to be checked'));
+        it('formats be.selected', () => expect(formatAssertion('be.selected', 'radio')).toBe('Expect element "radio" to be selected'));
+        it('formats not.be.selected', () => expect(formatAssertion('not.be.selected', 'radio')).toBe('Expect element "radio" not to be selected'));
+        it('formats be.focused', () => expect(formatAssertion('be.focused', 'input')).toBe('Expect element "input" to be focused'));
+        it('formats not.be.focused', () => expect(formatAssertion('not.be.focused', 'input')).toBe('Expect element "input" not to be focused'));
+        it('formats have.text', () => expect(formatAssertion('have.text', 'title', { expected: 'Hello' })).toBe('Expect element "title" to have text "Hello"'));
+        it('formats not.have.text', () => expect(formatAssertion('not.have.text', 'title', { expected: 'Hello' })).toBe('Expect element "title" not to have text "Hello"'));
+        it('formats contain.text', () => expect(formatAssertion('contain.text', 'title', { expected: 'Hello' })).toBe('Expect element "title" to contain text "Hello"'));
+        it('formats not.contain.text', () => expect(formatAssertion('not.contain.text', 'title', { expected: 'Hello' })).toBe('Expect element "title" not to contain text "Hello"'));
+        it('formats have.value', () => expect(formatAssertion('have.value', 'input', { expected: 'admin' })).toBe('Expect element "input" to have value "admin"'));
+        it('formats not.have.value', () => expect(formatAssertion('not.have.value', 'input', { expected: 'admin' })).toBe('Expect element "input" not to have value "admin"'));
+        it('formats contain.value', () => expect(formatAssertion('contain.value', 'input', { expected: 'min' })).toBe('Expect element "input" to contain value "min"'));
+        it('formats not.contain.value', () => expect(formatAssertion('not.contain.value', 'input', { expected: 'min' })).toBe('Expect element "input" not to contain value "min"'));
+        it('formats have.attr', () => expect(formatAssertion('have.attr', 'img', { name: 'alt', value: 'logo' })).toBe('Expect element "img" to have attribute "alt" = "logo"'));
+        it('formats not.have.attr', () => expect(formatAssertion('not.have.attr', 'img', { name: 'alt' })).toBe('Expect element "img" not to have attribute "alt"'));
+        it('formats have.class', () => expect(formatAssertion('have.class', 'div', { expected: 'active' })).toBe('Expect element "div" to have class "active"'));
+        it('formats not.have.class', () => expect(formatAssertion('not.have.class', 'div', { expected: 'active' })).toBe('Expect element "div" not to have class "active"'));
+        it('formats have.css', () => expect(formatAssertion('have.css', 'div', { name: 'color', value: 'red' })).toBe('Expect element "div" to have CSS "color" = "red"'));
+        it('formats not.have.css', () => expect(formatAssertion('not.have.css', 'div', { name: 'color', value: 'red' })).toBe('Expect element "div" not to have CSS "color" = "red"'));
+        it('formats have.length', () => expect(formatAssertion('have.length', 'DashboardPage.statCards', { expected: 4 })).toBe('Expect collection "DashboardPage.statCards" count to equal 4'));
+        it('formats not.have.length', () => expect(formatAssertion('not.have.length', 'cards', { expected: 4 })).toBe('Expect collection "cards" count not to equal 4'));
+        it('formats have.length.greaterThan', () => expect(formatAssertion('have.length.greaterThan', 'cards', { expected: 2 })).toBe('Expect collection "cards" count to be greater than 2'));
+        it('formats have.length.lessThan', () => expect(formatAssertion('have.length.lessThan', 'cards', { expected: 10 })).toBe('Expect collection "cards" count to be less than 10'));
+        it('formats be.empty', () => expect(formatAssertion('be.empty', 'cards')).toBe('Expect collection "cards" to be empty'));
+        it('formats not.be.empty', () => expect(formatAssertion('not.be.empty', 'cards')).toBe('Expect collection "cards" not to be empty'));
+        it('formats shouldHaveUrl', () => expect(formatAssertion('shouldHaveUrl', undefined, { expected: '/home' })).toBe('Expect browser URL to be "/home"'));
+        it('formats shouldContainUrl', () => expect(formatAssertion('shouldContainUrl', undefined, { expected: '/home' })).toBe('Expect browser URL to contain "/home"'));
+        it('formats shouldHaveTitle', () => expect(formatAssertion('shouldHaveTitle', undefined, { expected: 'Home' })).toBe('Expect browser title to be "Home"'));
+        it('formats shouldContainTitle', () => expect(formatAssertion('shouldContainTitle', undefined, { expected: 'Home' })).toBe('Expect browser title to contain "Home"'));
+        it('formats shouldBeLoaded', () => expect(formatAssertion('shouldBeLoaded', undefined)).toBe('Expect page to be fully loaded'));
+        it('formats shouldBePageLoaded', () => expect(formatAssertion('shouldBePageLoaded', undefined)).toBe('Expect page to be fully loaded'));
+        it('formats shouldHaveNoConsoleErrors', () => expect(formatAssertion('shouldHaveNoConsoleErrors', undefined)).toBe('Expect browser console to have no errors'));
+    });
+});

package/dist/reporter/semantic-formatter.d.ts

@@ -0,0 +1,6 @@
+import { ActionKey, AssertionKey } from './types.js';
+/**
+ * Transforms raw matcher assertions and element commands into grammatically correct English sentences.
+ */
+export declare function formatAction(actionKey: ActionKey | string, target?: any, args?: Record<string, any>): string;
+export declare function formatAssertion(assertionKey: AssertionKey | string, target?: any, args?: Record<string, any>): string;