@suites/codemod

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.

Usage

npx @suites/codemod <transform> <path> [options]

Example:

npx @suites/codemod automock/2/to-suites-v3 src/**/*.spec.ts

Run with --dry-run to preview changes without modifying files.

Available Transforms

• automock/2/to-suites-v3 - Migrate test files from Automock v2 to Suites v3 testing framework

Example

Before (Automock)

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;
  });
});

After (Suites)

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;
  });
});

CLI Options

Option	Description	Default
-d, --dry-run	Preview changes without writing files	false
-f, --force	Bypass git safety checks	false
-p, --parser <parser>	Parser: tsx, ts, babel	tsx
-e, --extensions <exts>	File extensions to transform	.ts,.tsx
-i, --ignore <patterns>	Ignore file patterns (comma-separated)	-
--print	Print output to stdout	false
-v, --verbose	Show detailed logs	false
--skip-validation	Skip validation checks	false
--list-transforms	List all available transforms	-

More examples:

# Preview changes
npx @suites/codemod automock/2/to-suites-v3 src --dry-run

# Ignore certain files
npx @suites/codemod automock/2/to-suites-v3 src --ignore "**/*.integration.ts"

# List all transforms
npx @suites/codemod --list-transforms

Transform Details

automock/2/to-suites-v3

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/await to test hooks as needed
• Mock retrieval: Intelligently selects .impl() vs .final() strategy
• Jest globals: Preserves jest imports 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 via unitRef.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 @automock imports remain
• TestBed.create() is converted to TestBed.solitary()
• .compile() is called with proper await
• Mock strategies are correctly applied
• Retrieved mocks use .impl() strategy

Requirements

• Node.js: ^16.10.0 || ^18.12.0 || >=20.0.0
• Project Type: TypeScript or JavaScript
• Git: Clean working directory recommended (bypass with --force)

Troubleshooting

"Working directory is not clean"

• Commit your changes or use --force to bypass

"No files found"

• Check your path and file extensions: --extensions .spec.ts,.test.ts

Parser errors

• Try the babel parser: --parser babel

Validation failed

• Run with --verbose for detailed logs
• Review validation errors in the output
• Use --skip-validation to bypass (not recommended)

For more help, see troubleshooting guide or open an issue.

How It Works

The codemod uses jscodeshift to:

1. Parse TypeScript/JavaScript into an Abstract Syntax Tree (AST)
2. Apply intelligent transformations (imports, TestBed API, mocks, types)
3. Validate the transformed code
4. Output the result

TypeScript Support: First-class support with fallback parser for complex syntax (generics, type guards, decorators, JSX/TSX).

Architecture

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 migration
• automock/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

Contributing

Contributions welcome! To contribute:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make your changes and add tests
4. Run tests: npm test and linter: npm run lint
5. Commit: git commit -m "feat: add feature"
6. Push and open a Pull Request

Adding New Transforms

1. Create transform directory: src/transforms/<framework>/<version>/<transform-name>.ts
2. Export applyTransform function from your transform
3. Register in src/transforms/index.ts:

   {
     name: 'framework/version/transform-name',
     description: 'Description of what it does',
     path: './transforms/framework/version/transform-name',
   }

4. Add test fixtures in fixtures/
5. Add integration tests in test/integration/
6. Update this README

Example:

// src/transforms/automock/3/to-suites-v4.ts
export { applyTransform } from '../../../transform';

Project Structure

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)

Local Development

Running Locally

From within the codemod repository:

# Build first
pnpm build

# Run on a target repository
node dist/cli.js automock/2/to-suites-v3 /path/to/repo --dry-run

# Run on test fixtures
node dist/cli.js automock/2/to-suites-v3 fixtures/simple-final --dry-run

# Verbose output for debugging
node dist/cli.js automock/2/to-suites-v3 /path/to/repo --dry-run --verbose

Using npm link for Testing

# In the codemod repo
npm link

# Now use it anywhere like npx
codemod automock/2/to-suites-v3 /path/to/repo --dry-run

# Unlink when done
npm unlink -g @suites/codemod

Running Tests

# All tests
pnpm test

# Specific test file
pnpm test path/to/test.spec.ts

# With coverage
pnpm test --coverage

License

MIT (c) Omer Morad

Links

• Suites Documentation
• GitHub Repository
• Issue Tracker
• NPM Package

Related Projects

• @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.