Hamlet

Migrate your test suites between frameworks with confidence.

25 conversion directions across 16 frameworks in 3 languages (JavaScript, Java, Python).

Node Support

Hamlet supports active and maintenance LTS versions of Node.js. Currently: Node 22 and Node 24.

CI tests run on both. When a Node major reaches end-of-life, it is dropped in the next minor release.

Quick Start

npm install -g hamlet-converter

# Convert a single file
hamlet jest2vt auth.test.js -o converted/

# Preview a migration
hamlet estimate tests/ --from jest --to vitest

# Migrate your project
hamlet migrate tests/ --from jest --to vitest -o converted/

Supported Conversions

JavaScript Unit Testing

| Direction | Shorthand | |-----------|-----------| | Jest → Vitest | hamlet jest2vt | | Mocha → Jest | hamlet mocha2jest | | Jasmine → Jest | hamlet jas2jest | | Jest → Mocha | hamlet jest2mocha | | Jest → Jasmine | hamlet jest2jas |

JavaScript E2E / Browser

| Direction | Shorthand | |-----------|-----------| | Cypress ↔ Playwright | hamlet cy2pw / hamlet pw2cy | | Cypress ↔ Selenium | hamlet cy2sel / hamlet sel2cy | | Playwright ↔ Selenium | hamlet pw2sel / hamlet sel2pw | | Cypress ↔ WebdriverIO | hamlet cy2wdio / hamlet wdio2cy | | Playwright ↔ WebdriverIO | hamlet pw2wdio / hamlet wdio2pw | | Puppeteer ↔ Playwright | hamlet pptr2pw / hamlet pw2pptr | | TestCafe → Playwright | hamlet tcafe2pw | | TestCafe → Cypress | hamlet tcafe2cy |

Java

| Direction | Shorthand | |-----------|-----------| | JUnit 4 → JUnit 5 | hamlet ju42ju5 | | JUnit 5 ↔ TestNG | hamlet ju52tng / hamlet tng2ju5 |

Python

| Direction | Shorthand | |-----------|-----------| | pytest ↔ unittest | hamlet pyt2ut / hamlet ut2pyt | | nose2 → pytest | hamlet nose22pyt |

Run hamlet list to see all directions with their shorthand aliases.

Commands

Convert

Convert a single file, directory, or glob pattern:

# Single file
hamlet convert auth.test.js --from jest --to vitest -o converted/

# Directory (requires --output)
hamlet convert tests/ --from jest --to vitest -o converted/

# Glob pattern
hamlet convert "tests/**/*.test.js" --from jest --to vitest -o converted/

# Shorthand (equivalent to convert --from jest --to vitest)
hamlet jest2vt auth.test.js -o converted/

Migrate

Full project migration with state tracking, dependency ordering, and config conversion:

hamlet migrate tests/ --from jest --to vitest -o converted/

# Resume an interrupted migration
hamlet migrate tests/ --from jest --to vitest -o converted/ --continue

# Retry only previously failed files
hamlet migrate tests/ --from jest --to vitest -o converted/ --retry-failed

Estimate

Preview migration complexity without converting:

hamlet estimate tests/ --from jest --to vitest

Dry Run

Preview what would happen without writing files:

hamlet convert tests/ --from jest --to vitest -o converted/ --dry-run
hamlet migrate tests/ --from jest --to vitest --dry-run

Other Commands

hamlet list              # Show all conversion directions with shorthands
hamlet shorthands        # List all shorthand command aliases
hamlet detect file.js    # Auto-detect testing framework from a file
hamlet doctor            # Run diagnostics
hamlet status -d .       # Show current migration progress
hamlet checklist -d .    # Generate migration checklist
hamlet reset -d . --yes  # Clear migration state
hamlet serve             # Start the API server
hamlet ui                # Open the browser UI for interactive conversion

Options

| Option | Description | |--------|-------------| | -o, --output <path> | Output path (required for directories) | | -f, --from <framework> | Source framework | | -t, --to <framework> | Target framework | | --dry-run | Preview without writing files | | --on-error <mode> | Error handling: skip (default), fail, best-effort | | -q, --quiet | Suppress non-error output | | --verbose | Show detailed per-pattern output | | --json | Machine-readable JSON output | | --no-color | Disable color output | | --auto-detect | Auto-detect source framework |

JSON Output

For CI integration, use --json for machine-readable output:

hamlet jest2vt auth.test.js -o converted/ --json

{
  "success": true,
  "files": [{ "source": "auth.test.js", "output": "converted/auth.test.js", "confidence": 95 }],
  "summary": { "converted": 1, "skipped": 0, "failed": 0 }
}

How It Works

1. Detect — determine source framework from content (regex heuristics per framework)
2. Parse — classify source lines into IR nodes (suites, tests, hooks, assertions, raw code)
3. Transform — apply regex-based pattern substitutions to convert API calls and test structure
4. Score — walk the IR tree to calculate confidence (converted vs. unconvertible nodes)
5. Report — generate HAMLET-TODO markers for patterns that need manual review

Architecture note: Conversion is currently regex-based string transformation. The IR (intermediate representation) captures test structure for confidence scoring but emitters operate on the source string, not the IR tree. See DESIGN.md §1 for the hybrid IR + PatternEngine design rationale.

Confidence Scores

Every conversion produces a confidence score (0-100%):

• High (80-100%): Fully automated, ready to use
• Medium (50-79%): Mostly automated, review HAMLET-TODO markers
• Low (0-49%): Significant manual work needed

HAMLET-TODO Markers

When a pattern can't be automatically converted, Hamlet inserts a comment:

// HAMLET-TODO: cy.session() has no direct equivalent in Playwright
// Original: cy.session('admin', () => { ... })

Search for HAMLET-TODO after conversion to find patterns that need manual attention.

Config Conversion

Convert framework configuration files:

hamlet convert-config jest.config.js --to vitest -o vitest.config.js
hamlet convert-config cypress.config.js --to playwright -o playwright.config.ts

Programmatic API

ESM only — This package ships ES modules. Use import, not require(). Node >= 22 required.

import { ConverterFactory, FRAMEWORKS } from 'hamlet-converter/core';

const converter = await ConverterFactory.createConverter('jest', 'vitest');
const output = await converter.convert(jestCode);

// Get conversion report
const report = converter.getLastReport();
console.log(`Confidence: ${report.confidence}%`);

Entry Points

| Import path | Stability | Contents | |-------------|-----------|----------| | hamlet-converter | Stable | convertFile, convertRepository, processTestFiles, validateTests, generateReport, convertConfig, convertCypressToPlaywright, RepositoryConverter, BatchProcessor, ConversionReporter, VERSION, DEFAULT_OPTIONS, SUPPORTED_TEST_TYPES | | hamlet-converter/internals | Internal | DependencyAnalyzer, TestValidator, TypeScriptConverter, PluginConverter, VisualComparison, TestMapper, TestMetadataCollector, utility namespaces. May change between minor versions. | | hamlet-converter/core | Internal | ConverterFactory, BaseConverter, PatternEngine, MigrationEngine, and other core classes. May change between minor versions. | | hamlet-converter/converters | Internal | Legacy E2E converter classes (CypressToPlaywright, etc.). May change between minor versions. |

The hamlet-converter (main) entry point is the stable public API. Exports from /internals, /core, and /converters are available for advanced use but are not covered by semver stability guarantees.

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | Runtime error (conversion failed) | | 2 | Invalid arguments (bad framework, missing file) |

Development

npm install
npm test                    # Run all tests
npm run lint                # Lint source
npm run format              # Format with Prettier

Requirements

• Node.js >= 22.0.0

Contributing

See CONTRIBUTING.md for guidelines on adding new frameworks.

License

MIT License - see LICENSE for details.

Links

• GitHub Repository
• npm Package
• Issue Tracker