The Truth About migration Jest checklist Rome: A Step-by-Step Guide

// Sample Rome test run output
$ npx rome test
✓ src/utils/email.test.ts (12 tests)
✓ __tests__/UserCard.test.tsx (8 tests)

Passed: 20 tests
Failed: 0 tests
Time: 0.8s

// pre-migration-audit.js
// Imports
import { readFileSync, readdirSync, statSync } from 'fs';
import { join, resolve } from 'path';
import { createRequire } from 'module';
import chalk from 'chalk'; // npm install chalk@5.3.0
import glob from 'glob'; // npm install glob@10.3.10

const require = createRequire(import.meta.url);
const packageJson = require(join(process.cwd(), 'package.json'));
const jestConfigPath = join(process.cwd(), 'jest.config.js');
const auditResults = {
  jestVersion: null,
  hasCustomMatchers: false,
  hasSnapshotTests: false,
  incompatibleFeatures: [],
  testFileCount: 0,
  totalAssertions: 0,
};

/**
 * Reads Jest version from package.json
 */
function getJestVersion() {
  try {
    const jestDep = packageJson.devDependencies?.jest || packageJson.dependencies?.jest;
    if (!jestDep) throw new Error('Jest not found in dependencies');
    // Strip semver range characters
    auditResults.jestVersion = jestDep.replace(/[^\d.]/g, '');
    console.log(chalk.blue(`Detected Jest version: ${auditResults.jestVersion}`));
  } catch (err) {
    console.error(chalk.red(`Error detecting Jest version: ${err.message}`));
    process.exit(1);
  }
}

/**
 * Checks for Jest custom matchers (incompatible with Rome)
 */
function checkCustomMatchers() {
  try {
    const matcherFiles = glob.sync('**/*matcher*.{js,ts}', { ignore: 'node_modules/**' });
    if (matcherFiles.length > 0) {
      auditResults.hasCustomMatchers = true;
      auditResults.incompatibleFeatures.push('Custom Jest matchers (use Rome\'s expect extensions)');
      console.log(chalk.yellow(`Found ${matcherFiles.length} custom matcher files: ${matcherFiles.join(', ')}`));
    } else {
      console.log(chalk.green('No custom Jest matchers detected'));
    }
  } catch (err) {
    console.error(chalk.red(`Error checking custom matchers: ${err.message}`));
  }
}

/**
 * Counts test files and snapshot usage
 */
function auditTestFiles() {
  try {
    const testFiles = glob.sync('**/*.{test,spec}.{js,ts,jsx,tsx}', { ignore: 'node_modules/**' });
    auditResults.testFileCount = testFiles.length;
    console.log(chalk.blue(`Found ${testFiles.length} test files`));

    let snapshotCount = 0;
    testFiles.forEach((file) => {
      const content = readFileSync(file, 'utf-8');
      // Count assertions (expect statements)
      const assertionMatches = content.match(/expect\(/g);
      if (assertionMatches) auditResults.totalAssertions += assertionMatches.length;
      // Check for snapshots
      if (content.includes('toMatchSnapshot')) {
        snapshotCount++;
        auditResults.hasSnapshotTests = true;
      }
    });

    if (snapshotCount > 0) {
      auditResults.incompatibleFeatures.push(`Snapshot tests (${snapshotCount} files, use Rome\'s snapshot API)`);
      console.log(chalk.yellow(`Found ${snapshotCount} snapshot test files`));
    } else {
      console.log(chalk.green('No snapshot tests detected'));
    }
  } catch (err) {
    console.error(chalk.red(`Error auditing test files: ${err.message}`));
  }
}

/**
 * Main execution
 */
async function main() {
  console.log(chalk.bold('Starting Jest to Rome pre-migration audit...'));
  getJestVersion();
  checkCustomMatchers();
  auditTestFiles();

  // Output final report
  console.log(chalk.bold('\n=== Audit Report ==='));
  console.log(`Jest Version: ${auditResults.jestVersion}`);
  console.log(`Test File Count: ${auditResults.testFileCount}`);
  console.log(`Total Assertions: ${auditResults.totalAssertions}`);
  console.log(`Custom Matchers: ${auditResults.hasCustomMatchers ? 'Yes' : 'No'}`);
  console.log(`Snapshot Tests: ${auditResults.hasSnapshotTests ? 'Yes' : 'No'}`);
  console.log(`Incompatible Features: ${auditResults.incompatibleFeatures.length > 0 ? auditResults.incompatibleFeatures.join(', ') : 'None'}`);

  if (auditResults.incompatibleFeatures.length > 0) {
    console.log(chalk.yellow('\n⚠️  Incompatible features detected. Review Rome migration docs before proceeding.'));
  } else {
    console.log(chalk.green('\n✅ No incompatible features detected. Safe to proceed with migration.'));
  }
}

main();

// migrate-tests.js
// Imports
import { readFileSync, writeFileSync, readdirSync } from 'fs';
import { join, resolve } from 'path';
import glob from 'glob';
import chalk from 'chalk';
import { parse } from '@babel/parser'; // npm install @babel/parser@7.23.0
import traverse from '@babel/traverse'; // npm install @babel/traverse@7.23.0
import generate from '@babel/generator'; // npm install @babel/generator@7.23.0

const ROME_EXPECT_EXTENSIONS = 'https://github.com/rome/tools/issues/4123'; // Link to Rome expect extension docs
const MIGRATION_LOG = join(process.cwd(), 'rome-migration-log.json');

/**
 * Transforms Jest test syntax to Rome syntax
 * @param {string} fileContent - Original test file content
 * @param {string} filePath - Path to test file
 * @returns {string} Transformed content
 */
function transformTestSyntax(fileContent, filePath) {
  try {
    // Parse with Babel to handle TS/JSX
    const ast = parse(fileContent, {
      sourceType: 'module',
      plugins: ['typescript', 'jsx', 'asyncGenerators', 'bigInt', 'classProperties', 'decorators-legacy'],
    });

    let transformedContent = fileContent;

    // Replace Jest globals with Rome equivalents
    traverse(ast, {
      // Replace describe/it/test blocks
      CallExpression(path) {
        const callee = path.node.callee;
        // Replace jest.fn() with Rome's mock function
        if (callee.type === 'MemberExpression' && callee.object.name === 'jest' && callee.property.name === 'fn') {
          path.node.callee = { type: 'Identifier', name: 'mockFn' };
          console.log(chalk.gray(`  Replaced jest.fn() in ${filePath}`));
        }
        // Replace describe with Rome's describe (same name, but add import)
        if (callee.name === 'describe') {
          // No rename needed, Rome uses same describe syntax
        }
        // Replace it/test with Rome's it/test (same syntax)
      },
      // Replace expect matchers
      MemberExpression(path) {
        const { object, property } = path.node;
        if (object.name === 'expect') {
          // Replace .toBe with Rome's .toBe (same, but check for custom matchers)
          if (property.name === 'toMatchSnapshot') {
            console.log(chalk.yellow(`  Warning: toMatchSnapshot in ${filePath} needs manual migration. See ${ROME_EXPECT_EXTENSIONS}`));
          }
        }
      },
    });

    // Generate transformed code
    const output = generate(ast, { retainLines: true }, fileContent);
    transformedContent = output.code;

    // Add Rome test imports (Rome auto-imports globals, but explicit for clarity)
    if (!transformedContent.includes('import { describe, it, expect } from \'rome\'')) {
      transformedContent = `import { describe, it, expect, mockFn } from 'rome';\n${transformedContent}`;
    }

    return transformedContent;
  } catch (err) {
    console.error(chalk.red(`Error transforming ${filePath}: ${err.message}`));
    return null;
  }
}

/**
 * Migrates all test files in the project
 */
async function migrateAllTests() {
  try {
    const testFiles = glob.sync('**/*.{test,spec}.{js,ts,jsx,tsx}', { ignore: 'node_modules/**' });
    console.log(chalk.bold(`Migrating ${testFiles.length} test files...`));
    const migrationLog = [];

    for (const file of testFiles) {
      console.log(chalk.blue(`Processing ${file}...`));
      const content = readFileSync(file, 'utf-8');
      const transformed = transformTestSyntax(content, file);
      if (transformed) {
        writeFileSync(file, transformed, 'utf-8');
        migrationLog.push({ file, status: 'success' });
        console.log(chalk.green(`  Successfully migrated ${file}`));
      } else {
        migrationLog.push({ file, status: 'failed', error: 'Transformation failed' });
      }
    }

    // Write migration log
    writeFileSync(MIGRATION_LOG, JSON.stringify(migrationLog, null, 2), 'utf-8');
    console.log(chalk.bold(`\nMigration log written to ${MIGRATION_LOG}`));
  } catch (err) {
    console.error(chalk.red(`Fatal error during migration: ${err.message}`));
    process.exit(1);
  }
}

/**
 * Creates Rome configuration file
 */
function createRomeConfig() {
  try {
    const romeConfig = {
      $schema: 'https://docs.rome.tools/schemas/12.1.3/rome.json',
      formatter: { enabled: true, indentStyle: 'space', indentSize: 2 },
      linter: { enabled: true, rules: { recommended: true } },
      tester: {
        enabled: true,
        include: ['**/*.{test,spec}.{js,ts,jsx,tsx}'],
        exclude: ['node_modules/**'],
        timeout: 5000,
      },
    };
    writeFileSync(join(process.cwd(), 'rome.json'), JSON.stringify(romeConfig, null, 2), 'utf-8');
    console.log(chalk.green('Created rome.json configuration file'));
  } catch (err) {
    console.error(chalk.red(`Error creating Rome config: ${err.message}`));
    process.exit(1);
  }
}

// Main execution
async function main() {
  console.log(chalk.bold('Starting Jest to Rome migration...'));
  createRomeConfig();
  await migrateAllTests();
  console.log(chalk.bold('\n=== Migration Complete ==='));
  console.log('Next steps: 1. Run npx rome test to verify tests. 2. Uninstall Jest dependencies.');
}

main();

// post-migration-verify.js
// Imports
import { readFileSync, unlinkSync, readdirSync } from 'fs';
import { join, resolve } from 'path';
import { execSync } from 'child_process';
import chalk from 'chalk';
import glob from 'glob';

const JEST_DEPS = ['jest', 'ts-jest', '@types/jest', 'jest-environment-jsdom', 'jest-transform-stub'];
const SNAPSHOT_DIR = '**/__snapshots__/**';

/**
 * Runs Rome test suite and validates output
 */
function runRomeTests() {
  try {
    console.log(chalk.bold('Running Rome test suite...'));
    const output = execSync('npx rome test --reporter=json', { encoding: 'utf-8', stdio: 'pipe' });
    const testResults = JSON.parse(output);

    const totalTests = testResults.testResults.reduce((acc, curr) => acc + curr.assertionResults.length, 0);
    const passedTests = testResults.testResults.reduce((acc, curr) => {
      return acc + curr.assertionResults.filter((r) => r.status === 'passed').length;
    }, 0);
    const failedTests = totalTests - passedTests;

    console.log(chalk.blue(`Total tests: ${totalTests}`));
    console.log(chalk.green(`Passed: ${passedTests}`));
    console.log(failedTests > 0 ? chalk.red(`Failed: ${failedTests}`) : chalk.green('Failed: 0'));

    if (failedTests > 0) {
      console.log(chalk.yellow('\nFailed tests:'));
      testResults.testResults.forEach((suite) => {
        suite.assertionResults.filter((r) => r.status === 'failed').forEach((test) => {
          console.log(chalk.red(`  ${suite.name}: ${test.title}`));
          console.log(chalk.gray(`    Error: ${test.failureMessages.join('\n')}`));
        });
      });
      return false;
    }
    return true;
  } catch (err) {
    console.error(chalk.red(`Error running Rome tests: ${err.message}`));
    console.error(chalk.gray(`Output: ${err.stdout}`));
    return false;
  }
}

/**
 * Removes Jest dependencies from package.json and node_modules
 */
function removeJestDependencies() {
  try {
    console.log(chalk.bold('\nRemoving Jest dependencies...'));
    // Uninstall Jest packages
    const uninstallCmd = `npm uninstall ${JEST_DEPS.join(' ')}`;
    execSync(uninstallCmd, { stdio: 'inherit' });
    console.log(chalk.green('Uninstalled Jest dependencies'));

    // Remove Jest config files
    const jestConfigFiles = ['jest.config.js', 'jest.config.ts', 'jest.setup.js', 'jest.teardown.js'];
    jestConfigFiles.forEach((file) => {
      try {
        unlinkSync(join(process.cwd(), file));
        console.log(chalk.green(`Removed ${file}`));
      } catch (err) {
        // File doesn't exist, ignore
      }
    });

    // Remove snapshot files
    const snapshotFiles = glob.sync(SNAPSHOT_DIR, { ignore: 'node_modules/**' });
    if (snapshotFiles.length > 0) {
      console.log(chalk.yellow(`Found ${snapshotFiles.length} snapshot files. Remove manually if using Rome's snapshot API.`));
    }
  } catch (err) {
    console.error(chalk.red(`Error removing Jest dependencies: ${err.message}`));
    process.exit(1);
  }
}

/**
 * Validates no Jest imports remain in codebase
 */
function validateNoJestImports() {
  try {
    console.log(chalk.bold('\nValidating no Jest imports remain...'));
    const allFiles = glob.sync('**/*.{js,ts,jsx,tsx}', { ignore: 'node_modules/**' });
    let jestImportCount = 0;

    allFiles.forEach((file) => {
      const content = readFileSync(file, 'utf-8');
      if (content.includes('from \'jest\'') || content.includes('require(\'jest\')') || content.includes('jest.fn()')) {
        console.log(chalk.red(`  Jest reference found in ${file}`));
        jestImportCount++;
      }
    });

    if (jestImportCount > 0) {
      console.log(chalk.red(`Found ${jestImportCount} files with Jest references. Fix before proceeding.`));
      return false;
    } else {
      console.log(chalk.green('No Jest references found in codebase.'));
      return true;
    }
  } catch (err) {
    console.error(chalk.red(`Error validating Jest imports: ${err.message}`));
    return false;
  }
}

/**
 * Generates migration benchmark report
 */
function generateBenchmarkReport() {
  try {
    console.log(chalk.bold('\nGenerating benchmark report...'));
    // Run Jest tests (if still installed) and Rome tests, compare times
    const jestTime = 'N/A (Jest uninstalled)';
    const romeStart = Date.now();
    execSync('npx rome test', { stdio: 'pipe' });
    const romeTime = (Date.now() - romeStart) / 1000;

    const report = {
      migrationDate: new Date().toISOString(),
      romeVersion: execSync('npx rome --version', { encoding: 'utf-8' }).trim(),
      testRunTimeSeconds: romeTime,
      jestRunTimeSeconds: jestTime,
      speedImprovement: 'N/A',
    };

    console.log(chalk.blue(`Rome test run time: ${romeTime}s`));
    writeFileSync(join(process.cwd(), 'migration-benchmark.json'), JSON.stringify(report, null, 2), 'utf-8');
    console.log(chalk.green('Benchmark report written to migration-benchmark.json'));
  } catch (err) {
    console.error(chalk.red(`Error generating benchmark: ${err.message}`));
  }
}

// Main execution
async function main() {
  console.log(chalk.bold('Starting post-migration verification...'));
  const testsPass = runRomeTests();
  if (!testsPass) {
    console.log(chalk.red('Tests failed. Fix errors before proceeding.'));
    process.exit(1);
  }

  const noJestImports = validateNoJestImports();
  if (!noJestImports) process.exit(1);

  removeJestDependencies();
  generateBenchmarkReport();

  console.log(chalk.bold('\n=== ✅ Migration 100% Complete ==='));
  console.log('Your project is now fully migrated to Rome. Enjoy faster tests!');
}

main();

# Run Rome watch mode scoped to migrated tests
npx rome test --watch --include='src/**/*.test.ts' --reporter=verbose

// Rome expect extension example (valid email matcher)
// extensions/valid-email.ts
import { defineExpectExtension } from 'rome';

export default defineExpectExtension({
  name: 'toBeValidEmail',
  validate(value: unknown) {
    if (typeof value !== 'string') {
      return { pass: false, message: `Expected string, got ${typeof value}` };
    }
    const emailRegex = /^[\^\s@]+@[\^\s@]+\.[\^\s@]+$/;
    return { pass: emailRegex.test(value), message: `${value} is not a valid email` };
  },
});

// Rome inline snapshot example
import { describe, it, expect } from 'rome';

describe('User component', () => {
  it('renders valid user card', () => {
    const user = { name: 'Alice', email: 'alice@example.com' };
    const output = renderUserCard(user); // Your component render function
    expect(output).toMatchSnapshot(`

        Alice
        alice@example.com

    `);
  });
});

example-jest-to-rome/
├── src/
│   ├── components/
│   │   └── UserCard.tsx
│   └── utils/
│       └── email.ts
├── __tests__/
│   ├── UserCard.test.tsx
│   └── email.test.ts
├── extensions/
│   └── valid-email.ts  # Rome expect extension
├── scripts/
│   ├── pre-migration-audit.js
│   ├── migrate-tests.js
│   └── post-migration-verify.js
├── rome.json  # Rome configuration
├── package.json
├── tsconfig.json
├── migration-benchmark.json
└── README.md  # Migration checklist