Code transformation toolkit for the Suites testing framework
Automated code transformations for Suites projects. Built on jscodeshift with intelligent AST-based transformations, built-in validation, and TypeScript-first support.
npx @suites/codemod <codemod> <source> [options]Example:
npx @suites/codemod automock/2/to-suites-v3 src/**/*.spec.tsRun with --dry or -d to preview changes without modifying files.
suites/3/to-suites-v4- Add explicit Suites v4 type references and clean up legacy helper importsautomock/2/to-suites-v3- Migrate test files from Automock v2 to Suites v3 testing framework
import { TestBed } from '@automock/jest';
describe('UserService', () => {
let service: UserService;
beforeAll(() => {
const { unit } = TestBed.create(UserService)
.mock(UserRepository)
.using({ findById: jest.fn() })
.compile();
service = unit;
});
});import { TestBed } from '@suites/unit';
describe('UserService', () => {
let service: UserService;
beforeAll(async () => {
const { unit } = await TestBed.solitary(UserService)
.mock(UserRepository)
.final({ findById: jest.fn() })
.compile();
service = unit;
});
});| Argument | Description | Default |
|---|---|---|
codemod |
Codemod slug to run. See available transforms below. | - |
source |
Path to source files or directory to transform including glob patterns. | . |
| Option | Description | Default |
|---|---|---|
-v, --version |
Output the current version | - |
-d, --dry |
Dry run (no changes are made to files) | false |
-f, --force |
Bypass Git safety checks and forcibly run codemods | false |
-p, --print |
Print transformed files to stdout, useful for development | false |
--verbose |
Show more information about the transform process | false |
--doubles <adapter> |
Suites v4 doubles adapter: jest or vitest |
inferred |
--di <adapter> |
Suites v4 DI adapter: nestjs or inversify |
inferred |
--parser <parser> |
Parser to use: tsx, ts, babel |
tsx |
-h, --help |
Display help message | - |
Examples:
# Preview changes (dry run)
npx @suites/codemod automock/2/to-suites-v3 src --dry
# Print output to stdout
npx @suites/codemod automock/2/to-suites-v3 src/file.ts -p
# Verbose output
npx @suites/codemod automock/2/to-suites-v3 src --verbose
# Use different parser
npx @suites/codemod automock/2/to-suites-v3 src --parser babelSuites 4 stops patching declaration files during installation. This transform makes adapter augmentation explicit in your selected TypeScript source and declaration files:
# Run separately for each test TypeScript project.
npx @suites/codemod suites/3/to-suites-v4 ./src --dry --print
# Select adapters explicitly when they cannot be inferred.
npx @suites/codemod suites/3/to-suites-v4 'tests/**/*.ts' --doubles jest --di nestjs --dry
# Apply after reviewing the preview.
npx @suites/codemod suites/3/to-suites-v4 ./srcRelease availability: This transform requires a codemod release containing it. It is not included in @suites/codemod@0.1.0. To try this checkout before release, run pnpm install --frozen-lockfile, pnpm build, then replace npx @suites/codemod with node /path/to/codemod/bin/suites-codemod.js.
Automatic changes:
- Adds a
/// <reference types="@suites/doubles.jest/unit" />or Vitest equivalent to files using Suites types/API. Files using TestBed also receive their DI adapter's/metadatareference. Standalonemock,stub,Mocked, andStubconsumers do not need a DI adapter. - Includes
.d.tsfiles, preserving existing references and adding missing DI metadata when a DI adapter is installed. Unrelated declarations are unchanged. - Moves named
mockandstubimports from@suites/unitto the selected doubles adapter, preserving aliases and type-only imports. This repairs older examples and Automock codemod output; these helpers were not public exports of@suites/unitin v3.1.1 either. - Rewrites obsolete adapter
/typesreferences to/unitor/metadata./typeswas not a canonical v3 export. Side-effect imports of declaration-only entry points become triple-slash references, never runtime imports of those paths. - Preserves
TestBed.solitary(),TestBed.sociable(),.compile(), mock configuration, and dependency retrieval calls.
The transform selects one doubles adapter (--doubles jest|vitest) and, where needed, one DI adapter (--di nestjs|inversify). It reads only the nearest package.json, considering dependencies, devDependencies, and peerDependencies. Existing references and adapter imports also identify an adapter when the manifest does not. Multiple installed adapters require explicit selection even when a file has a reference. Conflicting references/imports must be fixed manually. Run separately for test projects with different adapters.
References are added per file so this transform does not guess your tsconfig inheritance or include patterns. You may consolidate them into a shared suites.d.ts afterward, provided your test tsconfig includes it. Already migrated files are unchanged on repeated runs. Both --dry and --print prevent writes.
Manual work and limitations:
- Upgrade Suites packages together to v4 and check runtime/framework peer requirements using the v4 migration guide. Package manifests, lockfiles, tsconfigs, test-runner settings, and installed packages are not changed.
- Migrate Sinon calls/assertions manually and remove its unsupported adapter. The codemod reports Sinon rather than selecting a replacement. An explicit doubles choice does not convert Sinon APIs.
- Review NestJS metadata arguments and Inversify decorators/injection changes manually. The transform does not remove arguments or infer DI tokens.
- Namespace/default imports, CommonJS/dynamic/import-equals imports, inline import types, star re-exports, and helper re-exports from
@suites/unitreceive actionable errors. Convert these to named imports/exports before retrying. - Only
.tsand.tsxsource files are processed, including.d.tsfor this transform. Use a directory or a quoted glob. Include your declaration setup files in the selected target, and update any obsolete references intsconfig.compilerOptions.typesmanually.
An error leaves the affected file unchanged and makes the CLI exit nonzero. Other files may have completed, so use a clean Git tree and preview first. --allow-critical-errors does not bypass v4 safety errors. After applying, review the diff, run your TypeScript check, and run your test suite.
Intelligently migrates Automock v2 test files to Suites v3 framework.
What it transforms:
- Import statements:
@automock/jest->@suites/unit - TestBed API:
TestBed.create()->TestBed.solitary().compile() - Mock configuration:
.using()->.impl()or.final() - Type annotations:
jest.Mocked<T>->Mocked<T>from@suites/unit - Async/await: Adds
async/awaitto test hooks as needed - Mock retrieval: Intelligently selects
.impl()vs.final()strategy - Jest globals: Preserves
jestimports where needed - Type casts: Removes obsolete type assertions
Mock Strategy Selection:
The codemod automatically chooses between .impl() and .final():
.impl()- Used when mocks are retrieved viaunitRef.get()and need runtime manipulation (spy assertions, dynamic mock configuration).final()- Used when mocks are provided as final implementations without retrieval
Validation:
Built-in validation ensures:
- No
@automockimports remain TestBed.create()is converted toTestBed.solitary().compile()is called with properawait- Mock strategies are correctly applied
- Retrieved mocks use
.impl()strategy
See RELEASING.md for suites-release-bot, npm Trusted Publishing setup, and the manual release workflows.
- Node.js:
^16.10.0 || ^18.12.0 || >=20.0.0 - Project Type: TypeScript or JavaScript
- Git: Clean working directory recommended (bypass with
--force)
"Working directory is not clean"
- Commit your changes or use
--forceto bypass
"No files found"
- Check your source path and ensure it contains
.tsor.tsxfiles
Parser errors
- Try the babel parser:
--parser babel
Validation failed
- Run with
--verbosefor detailed logs - Review validation errors in the output
- Fix the issues reported by validators
For more help, see troubleshooting guide or open an issue.
The codemod uses jscodeshift to:
- Parse TypeScript/JavaScript into an Abstract Syntax Tree (AST)
- Apply intelligent transformations (imports, TestBed API, mocks, types)
- Validate the transformed code
- Output the result
TypeScript Support: First-class support with fallback parser for complex syntax (generics, type guards, decorators, JSX/TSX).
This codemod follows the Codemod Registry pattern used by React, Next.js, and other major frameworks:
Transform Naming: <framework>/<version>/<transform>
automock/2/to-suites-v3- Current migrationautomock/3/to-suites-v4- Future migrations- Supports multiple transforms per version
- Extensible to other frameworks (e.g.,
jest/28/to-v29)
Directory Structure:
src/transforms/
automock/ # Framework namespace
2/ # Source version
to-suites-v3.ts # Migration transform
3/ # Future: next version
to-suites-v4.ts
Design Benefits:
- No default transform - explicit selection prevents mistakes
- Version-based organization supports migration chains
- Framework namespacing allows multi-framework support
- Clear source → target versioning
Contributions welcome! To contribute:
- Fork the repository
- Create a feature branch:
git checkout -b feature/my-feature - Make your changes and add tests
- Run tests:
npm testand linter:npm run lint - Commit:
git commit -m "feat: add feature" - Push and open a Pull Request
-
Create transform directory:
src/transforms/<framework>/<version>/<transform-name>.ts -
Export a default function that follows jscodeshift's transform signature:
import type { FileInfo, API, Options } from 'jscodeshift'; import { transform } from '../../../transform'; export default transform;
Or implement your own transform function:
import type { FileInfo, API, Options } from 'jscodeshift'; export default function transform( fileInfo: FileInfo, api: API, options: Options ): string | null | undefined { // Your transform logic here return transformedCode; }
-
Register in
src/transforms/index.ts:{ name: 'framework/version/transform-name', description: 'Description of what it does', path: './transforms/framework/version/transform-name', }
-
Add test fixtures in
fixtures/ -
Add integration tests in
test/integration/ -
Update this README
Example:
// src/transforms/automock/3/to-suites-v4.ts
import { transform } from '../../../transform';
export default transform;src/
analyzers/ # Code analysis utilities
transforms/ # Transform implementations
automock/ # Framework namespace
2/ # Version-specific transforms
to-suites-v3.ts
index.ts # Transform registry
validators/ # Post-transform validation
utils/ # Shared utilities
cli.ts # CLI interface
runner.ts # Transform runner
transform.ts # Main transform logic
test/
integration/ # Integration tests
transforms/ # Transform unit tests
fixtures/ # Test fixtures (before/after)
MIT (c) Omer Morad
- @suites/unit - The Suites testing framework
- jscodeshift - JavaScript codemod toolkit
- @automock/jest - Automock testing framework
Need help? Open an issue on GitHub or check the Suites documentation.