Enhancement: Standardize On Vitest Testing Framework Across The Project

by ADMIN 72 views

Overview

In recent test compilation fixes in PR #205, we converted all test files from mixed Vitest/Jest imports to Jest for consistency. However, Vitest is the more modern choice and we should consider standardizing on Vitest instead of Jest throughout the project. This change will bring numerous benefits, including improved performance, better error messages, and alignment with modern build tooling.

Current State

  • ✅ All test files now use Jest imports consistently (PR #205)
  • ✅ Jest configurations are working properly
  • ✅ Codex setup scripts are configured for Jest
  • ❌ Using older testing framework when modern alternative exists

Rationale for Vitest

Technical Advantages

Vitest offers several technical advantages over Jest, including:

  • Performance: Significantly faster test execution
  • ESM Support: Native ESM support, better for modern TypeScript
  • Developer Experience: Better error messages, HMR for tests
  • Vite Ecosystem: Aligns with modern build tooling
  • TypeScript: Superior TypeScript integration

Ecosystem Benefits

Vitest also provides several ecosystem benefits, including:

  • Modern Tooling: Integrates better with modern dev tools
  • Smaller Bundle: Lighter dependency footprint
  • Active Development: More actively maintained and updated
  • Future-Proof: Better alignment with JavaScript ecosystem direction

Proposed Changes

Phase 1: Framework Migration

To migrate to Vitest, we will follow these steps:

  • [ ] Convert Jest configs to Vitest configs

    • Update jest.config.js → vitest.config.ts
    • Update jest.config.offline.js → vitest.config.offline.ts
    • Update package.json test scripts

  • [ ] Update test imports across all files

    • Convert import { describe, it, expect, jest } from '@jest/globals';
    • To import { describe, it, expect, vi } from 'vitest';
    • Update mock syntax from jest. to vi.

  • [ ] Update TypeScript configurations

    • Add Vitest types to tsconfig.json
    • Remove Jest type dependencies

Phase 2: Codex Integration Updates

Next, we will update Codex setup scripts and documentation:

  • [ ] Update Codex setup scripts

    • Modify scripts/codex-env-setup.sh for Vitest
    • Update offline configurations in setup scripts
    • Update verification scripts

  • [ ] Update documentation

    • Update CODEX-SETUP.md references
    • Update docs/codex-mcp-setup.md
    • Update troubleshooting guides

Phase 3: CI/CD and Dependencies

Finally, we will update GitHub Actions workflows and dependencies:

  • [ ] Update GitHub Actions workflows

    • Modify test commands in CI pipelines
    • Update coverage reporting if applicable

  • [ ] Update dependencies

    • Remove Jest dependencies
    • Add Vitest dependencies
    • Update any Jest-specific plugins

Files to Update

Configuration Files

  • jest.config.js → vitest.config.ts
  • jest.config.offline.js → vitest.config.offline.ts
  • package.json (test scripts and dependencies)
  • tsconfig.json (types)

Test Files (All need import updates)

  • test/objects/batch-companies.test.ts
  • test/objects/lists.test.ts
  • test/utils/relationship-utils.test.ts
  • test/utils/attribute-null-value.test.ts
  • test/integration/company-write-operations.test.ts
  • test/integration/industry-mapping.test.ts
  • test/integration/concurrent-operations.test.ts
  • test/api/industry-categories-mapping.test.ts
  • All other *.test.ts files

Codex Setup Files

  • scripts/codex-env-setup.sh
  • scripts/verify-codex-env.sh
  • CODEX-SETUP.md
  • docs/codex-mcp-setup.md

Benefits

Developer Experience

The benefits of using Vitest include:

  • Faster Tests: Significantly improved test execution speed
  • Better DX: Superior error messages and debugging
  • Modern Tooling: Alignment with current JavaScript ecosystem
  • ESM Native: Better compatibility with modern imports

Maintenance

Vitest also provides several maintenance benefits, including:

  • Future-Proof: More actively developed framework
  • Smaller Dependencies: Lighter dependency footprint
  • Better TypeScript: Superior TypeScript integration
  • Ecosystem: Better integration with modern build tools

Implementation Strategy

Approach 1: Big Bang Migration

  • Convert everything at once in a single PR
  • Pros: Clean, complete migration
  • Cons: Large PR, higher risk of issues

Approach 2: Gradual Migration

  • Convert configurations first
  • Migrate test files in batches
  • Update Codex setup last
  • Pros: Smaller PRs, easier review
  • Cons: Temporary inconsistency

Recommendation: Approach 1 (Big Bang)

Since we already have framework consistency from PR #205, a complete migration in one PR would be cleanest and avoid any temporary mixed states.

Acceptance Criteria

  • [ ] All test files use Vitest imports consistently
  • [ ] All Jest configurations converted to Vitest equivalents
  • [ ] Codex setup scripts work with Vitest
  • [ ] Documentation updated to reflect Vitest usage
  • [ ] All tests pass with new framework
  • [ ] TypeScript compilation works correctly
  • [ ] CI/CD pipelines updated and working

Risk Assessment

Low Risk

  • ✅ Test logic remains unchanged
  • ✅ Framework migration is well-documented
  • ✅ Vitest has Jest compatibility mode

Mitigation

  • ✅ Comprehensive testing after migration
  • ✅ Update Codex setup scripts to match
  • ✅ Document any breaking changes

Timeline

Estimated Effort: 4-6 hours

  • Configuration updates: 1-2 hours
  • Test file migrations: 2-3 hours
  • Codex integration updates: 1 hour
  • Testing and validation: 1 hour

Related Issues/PRs

  • PR #205: Fixed test compilation issues (established Jest consistency)
  • This issue: Upgrade to modern Vitest framework

Next Steps

  1. Get approval for the framework change
  2. Create feature branch for Vitest migration
  3. Implement changes following the proposed plan
  4. Test thoroughly with both unit and integration tests
  5. Update Codex setup to work with new framework
  6. Create PR with comprehensive testing

Priority: Medium Effort: Medium Impact: High (Developer Experience) Type: Enhancement

Frequently Asked Questions

As we move forward with the Vitest migration, we want to ensure that everyone has a clear understanding of the process and any potential questions or concerns. Below, we've compiled a list of frequently asked questions to help address any doubts.

Q: What is Vitest, and why are we migrating to it?

A: Vitest is a modern testing framework that offers several advantages over Jest, including faster test execution, better error messages, and alignment with modern build tooling. We're migrating to Vitest to take advantage of these benefits and improve our overall developer experience.

Q: What are the technical advantages of using Vitest?

A: Vitest offers several technical advantages, including:

  • Performance: Significantly faster test execution
  • ESM Support: Native ESM support, better for modern TypeScript
  • Developer Experience: Better error messages, HMR for tests
  • Vite Ecosystem: Aligns with modern build tooling
  • TypeScript: Superior TypeScript integration

Q: What are the ecosystem benefits of using Vitest?

A: Vitest also provides several ecosystem benefits, including:

  • Modern Tooling: Integrates better with modern dev tools
  • Smaller Bundle: Lighter dependency footprint
  • Active Development: More actively maintained and updated
  • Future-Proof: Better alignment with JavaScript ecosystem direction

Q: What is the proposed implementation strategy?

A: We're considering two approaches: Big Bang Migration and Gradual Migration. The Big Bang approach involves converting everything at once in a single PR, while the Gradual Migration approach involves converting configurations first, then migrating test files in batches, and finally updating Codex setup.

Q: What are the acceptance criteria for the migration?

A: The acceptance criteria include:

  • All test files use Vitest imports consistently
  • All Jest configurations converted to Vitest equivalents
  • Codex setup scripts work with Vitest
  • Documentation updated to reflect Vitest usage
  • All tests pass with new framework
  • TypeScript compilation works correctly
  • CI/CD pipelines updated and working

Q: What are the potential risks and mitigations?

A: The potential risks include:

  • Test logic remains unchanged
  • Framework migration is well-documented
  • Vitest has Jest compatibility mode

Mitigations include:

  • Comprehensive testing after migration
  • Update Codex setup scripts to match
  • Document any breaking changes

Q: What is the estimated effort required for the migration?

A: The estimated effort is 4-6 hours, broken down into:

  • Configuration updates: 1-2 hours
  • Test file migrations: 2-3 hours
  • Codex integration updates: 1 hour
  • Testing and validation: 1 hour

Q: What are the next steps?

A: The next steps include:

  1. Get approval for the framework change
  2. Create a feature branch for Vitest migration
  3. Implement changes following the proposed plan
  4. Test thoroughly with both unit and integration tests
  5. Update Codex setup to work with new framework
  6. Create a PR with comprehensive testing

Priority: Medium Effort: Medium Impact: High (Developer Experience) Type: Enhancement