@kitiumai/vitest-helpers

Vitest testing helpers with framework-specific utilities for modern JavaScript/TypeScript testing.

What is this package?

@kitiumai/vitest-helpers is a comprehensive testing utility library built specifically for Vitest, the next-generation testing framework for JavaScript and TypeScript. It provides a rich set of utilities, presets, and enterprise-grade features to enhance your testing workflow, making it easier to write, run, and maintain tests across different frameworks and environments.

Why do we need this package?

Modern JavaScript/TypeScript applications require robust testing strategies that go beyond basic unit tests. This package addresses several key challenges:

• Framework Integration: Seamless integration with popular frameworks (React, Vue, Angular, Svelte, etc.) through pre-configured presets
• Enterprise Testing Needs: Advanced features like visual testing, accessibility testing, security auditing, and performance monitoring
• Team Collaboration: Shared configurations and test reports for better team coordination
• CI/CD Integration: Automated testing pipelines with support for multiple CI platforms
• Performance Optimization: Parallel execution, caching, and memory management for faster test runs
• Developer Experience: Interactive CLI tools and comprehensive utilities that reduce boilerplate and improve productivity

Competitor Comparison

| Feature | @kitiumai/vitest-helpers | Vitest Plugins | Jest Helpers | Testing Library Utils | |---------|-------------------------|---------------|--------------|----------------------| | Framework Presets | ✅ 15+ frameworks | ❌ Limited | ❌ Manual | ❌ N/A | | Visual Testing | ✅ Built-in | ❌ External plugins | ❌ External | ❌ N/A | | Accessibility Testing | ✅ WCAG compliance | ❌ External | ❌ External | ❌ N/A | | Security Auditing | ✅ Secret detection | ❌ External | ❌ External | ❌ N/A | | Performance Monitoring | ✅ Parallel execution | ❌ Basic | ❌ Basic | ❌ N/A | | CI/CD Integration | ✅ 4+ platforms | ❌ Manual | ❌ Manual | ❌ N/A | | Team Collaboration | ✅ Shared configs | ❌ N/A | ❌ N/A | ❌ N/A | | Interactive CLI | ✅ Full-featured | ❌ N/A | ❌ N/A | ❌ N/A | | Enterprise Features | ✅ Monitoring, compliance | ❌ Limited | ❌ Limited | ❌ N/A | | Tree-shaking | ✅ Modular imports | ✅ Varies | ✅ Varies | ✅ Varies |

Unique Selling Proposition (USP)

"Enterprise-Ready Testing Ecosystem for Modern JavaScript"

• Framework-Agnostic Core: Built on @kitiumai/test-core for consistent testing patterns across projects
• Zero-Config Presets: One-line setup for complex testing scenarios
• Enterprise Features: Visual testing, accessibility, security, and compliance reporting out-of-the-box
• Performance First: Optimized for speed with parallel execution and intelligent caching
• Team-Centric: Collaboration tools and shared configurations for large teams
• Extensible Architecture: Plugin system for custom testing needs
• Production Proven: Used in production environments with comprehensive monitoring

Installation

npm install @kitiumai/vitest-helpers vitest

Peer Dependencies:

• vitest ^1.0.0 || ^2.0.0
• typescript ^5.0.0

Optional:

• @vitest/ui - For UI mode
• @vitest/browser - For browser testing

Features

• 🎯 Config Presets - Pre-configured setups for React, Vue, Angular, Svelte, Solid, Next.js, Nuxt, Astro and more
• 🔧 Workspace Support - Multi-project testing made easy
• 🧪 Vitest-first Helpers - Consistent wrappers for mocks, fixtures, and async utils
• 🌐 Browser Mode - Browser testing helpers
• ⚡ Benchmarks - Performance testing utilities
• 📊 Custom Reporters - Enhanced test output
• 🔌 Plugin System - Extensible architecture for custom utilities
• 🚀 CI/CD Integration - Automated testing pipelines for GitHub, GitLab, CircleCI, and more
• 📈 Monitoring - Test performance metrics and analytics
• 👥 Team Collaboration - Shared configurations and test reports
• ⚡ Performance Optimization - Parallel execution, caching, and memory management
• 💻 Interactive CLI - Command-line tools for test management
• 👁️ Visual Testing - Screenshot comparison and UI regression testing
• ♿ Accessibility Testing - WCAG compliance and a11y checks
• 🔒 Security & Compliance - Audit logging, secret detection, and compliance reporting
• 🧰 Framework-Agnostic - Built on @kitiumai/test-core

All Exported APIs

This package exports a comprehensive set of APIs organized by functionality. All APIs from @kitiumai/test-core are re-exported for convenience.

Core Testing Utilities (from @kitiumai/test-core)

• createMockFunction, createMockObject, restoreSpy, spyOn
• createFixture, FixtureManager, Fixture, FixtureSetup, FixtureTeardown
• createHttpMockManager, HttpMockManager, HttpMockRequest, HttpMockResponse, HttpResponses
• createDeferred, Deferred, parallelLimit, retry, sleep, waitFor, waitForValue
• Builder, BuilderGenerators, createBuilder, createBuilderFactory
• Factory, Sequence, createFactory, createFactoryWithBuilder, DataGenerators, Factories
• createLogger, expectLogs, LogLevel, TestLogger, TestLogEntry, LogExpectation

Compatibility Layer

• createMockFn, mockFunction, delay, createVitestMock

Setup & Configuration

• createVitestSetup, definePreset, createWorkspaceConfig, setupPresets
• developmentPreset, ciPreset, libraryPreset, reactPreset, vuePreset, angularPreset, sveltePreset, solidPreset, nextjsPreset, nuxtPreset, astroPreset, VitestPresets, createCustomPreset

CI/CD Integration

• CIHelper, CIConfig

Monitoring

• TestMonitor, MonitoringTestMetrics, MonitoringConfig, globalMonitor

Collaboration

• CollaborationManager, SharedConfig, TestReport, collaborationManager

Performance

• ParallelExecutor, CacheManager, MemoryOptimizer, ParallelConfig, CacheConfig, MemoryConfig
• parallelExecutor, cacheManager, memoryOptimizer

CLI Tools

• VitestCLI, CLIConfig, createCLI

Visual Testing

• VisualTester, VisualTestReporter, VisualTestConfig, VisualTestResult
• visualTester, visualReporter

Accessibility Testing

• AccessibilityTester, AccessibilityReporter, AccessibilityRule, AccessibilityViolation, AccessibilityResult
• accessibilityTester, accessibilityReporter

Security & Compliance

• AuditLogger, SecretDetector, ComplianceReporter, AuditLogEntry, SecretDetectionResult, ComplianceReport
• auditLogger, secretDetector, complianceReporter

Migration Tools

• convertJestConfigToVitest, JestToVitestMapping, migrationSteps, codeTransformations

Additional Modules

• Benchmarks: defineBenchmark, createBenchmarkSuite, BenchmarkReporters
• Browser: createBrowserConfig, setupBrowserPool, BrowserTypes
• Reporters: createCustomReporter, BuiltInReporters
• Tracing: enableDistributedTracing, createTracingContext, TracingIntegrations
• Examples: getExample, AvailableExamples
• Config: createVitestConfig, mergeVitestConfigs
• Lint: createVitestLintConfig, configureLinting
• Tooling: setupDevelopmentTools, createToolingConfig
• Plugins: pluginManager, monitoringPlugin, performancePlugin (and more)

For detailed API documentation, see the API References section below.

Quick Start

Using a Preset

// vitest.config.ts
import { KitiumVitestPresets } from '@kitiumai/vitest-helpers';

export default KitiumVitestPresets.ci(); // or .local, .library, .browser

Vitest convenience helpers

Use the compatibility helpers to keep mocks, fixtures, and async utilities consistent across projects:

import { createVitestMock, createFixture, waitFor } from '@kitiumai/vitest-helpers';

const fetchMock = createVitestMock(() => Promise.resolve({ ok: true }));

const fixture = createFixture({
  setup: async () => ({ fetchMock }),
  teardown: async () => fetchMock.mockReset(),
});

await waitFor(() => expect(fetchMock).toHaveBeenCalled());

Fixture and data factory workflow

Compose deterministic data and reusable fixtures to keep suites predictable across repos:

import {
  createFixture,
  createFactory,
  Builder,
  createLogger,
  expectLogs,
} from '@kitiumai/vitest-helpers';

const userFactory = createFactory({
  name: () => 'Ada Lovelace',
  email: ({ name }) => `${name.toLowerCase().replace(/\s/g, '.')}@example.com`,
});

const logger = createLogger({ level: 'info' });

const userFixture = createFixture({
  setup: async () => ({ user: userFactory.build() }),
  teardown: async () => logger.flush?.(),
});

const builder = new Builder(userFactory).sequence('id');

it('creates a user deterministically', async () => {
  const { user } = await userFixture.setup();
  expect(user.email).toContain('@example.com');

  await expectLogs(logger, [{ level: 'info' }]);
});

Minimal Vitest config template

Ship a single config file and keep overrides in-code:

// vitest.config.ts
import { createKitiumVitestConfig } from '@kitiumai/vitest-helpers';

export default createKitiumVitestConfig({
  preset: process.env.CI ? 'ci' : 'local',
  projectName: 'web-app',
  setupFiles: ['./test/setup.ts'],
});

Enterprise Features

Plugin System

Extend Vitest with custom plugins for specialized testing needs:

import {
  pluginManager,
  monitoringPlugin,
  performancePlugin,
} from '@kitiumai/vitest-helpers/plugins';

// Register built-in plugins
pluginManager.register(monitoringPlugin);
pluginManager.register(performancePlugin);

// Load all plugins
await pluginManager.load({
  /* config */
});

// Use plugin utilities
const metrics = monitoringPlugin.utilities.getMetrics();
const cache = performancePlugin.utilities.cache;

CI/CD Integration

Generate CI configurations for popular platforms:

import { CIHelper } from '@kitiumai/vitest-helpers/ci';

// Generate GitHub Actions workflow
const githubConfig = CIHelper.generateConfig('github', {
  nodeVersion: '18',
  testCommand: 'pnpm test',
  coverage: true,
  parallel: true,
});

console.log(githubConfig);

Performance Optimization

Parallel test execution and caching:

import {
  parallelExecutor,
  cacheManager,
  memoryOptimizer,
} from '@kitiumai/vitest-helpers/performance';

// Run tests in parallel
const results = await parallelExecutor.executeParallel([
  () => testFunction1(),
  () => testFunction2(),
  () => testFunction3(),
]);

// Cache expensive operations
await cacheManager.set('expensive-result', computedResult);
const cached = await cacheManager.get('expensive-result');

// Monitor memory usage
const stats = memoryOptimizer.getMemoryStats();
if (stats.shouldGC) {
  await memoryOptimizer.optimize();
}

Visual Testing

Screenshot comparison for UI regression testing:

import { visualTester, visualReporter } from '@kitiumai/vitest-helpers/visual';

// Compare screenshots
const result = await visualTester.compareScreenshots(
  'homepage',
  screenshotBuffer,
  'homepage-baseline'
);

visualReporter.addResult(result);
console.log(visualReporter.generateReport());

Accessibility Testing

WCAG compliance checking:

import { accessibilityTester, accessibilityReporter } from '@kitiumai/vitest-helpers/accessibility';

// Test HTML for accessibility
const result = await accessibilityTester.testHTML('<html>...</html>');
console.log(accessibilityReporter.generateReport(result));

Security & Compliance

Audit logging and secret detection:

import { auditLogger, secretDetector, complianceReporter } from '@kitiumai/vitest-helpers/security';

// Log security events
auditLogger.log({
  action: 'test-run',
  user: 'test-user',
  resource: 'test-suite',
  details: { testCount: 100 },
});

// Scan for secrets
const findings = await secretDetector.scanDirectory('./src');
console.log('Security findings:', findings);

// Generate compliance report
const report = await complianceReporter.generateReport(testResults);
console.log(complianceReporter.generateReportMarkdown(report));

Interactive CLI

Command-line tools for test management:

npx @kitiumai/vitest-helpers/cli

Available commands:

• setup-ci - Generate CI/CD configuration
• monitor - Start test monitoring
• collaborate - Team collaboration tools
• performance - Performance optimization tools

Usage & Tree-Shaking

Subpath Imports (Recommended for Bundle Size)

The vitest-helpers package provides modular subpath exports to help bundlers tree-shake unused code. Import only what you need:

// ✅ Minimal — only vitest setup utilities
import { createVitestSetup, setupPresets } from '@kitiumai/vitest-helpers/setup';

// ✅ Specific feature — browser testing only
import { createBrowserConfig } from '@kitiumai/vitest-helpers/browser';

// ✅ Benchmarks only — for performance testing
import { defineBenchmark } from '@kitiumai/vitest-helpers/benchmarks';

// ✅ Migration utilities only — for Jest to Vitest migration
import { migrateJestToVitest } from '@kitiumai/vitest-helpers/migration';

Top-level Barrel (Works, But Larger)

If you import from the top-level barrel, modern bundlers (esbuild, Rollup, webpack with Terser) will still tree-shake unused exports:

// ⚠️ Works but includes all exports; bundler will tree-shake unused ones
import { createVitestSetup, defineBenchmark, migrateJestToVitest } from '@kitiumai/vitest-helpers';

Available Subpaths

• @kitiumai/vitest-helpers/setup — Vitest setup and presets
• @kitiumai/vitest-helpers/setup/presets — Pre-configured presets only
• @kitiumai/vitest-helpers/setup/workspace — Workspace configuration
• @kitiumai/vitest-helpers/compatibility — Jest-to-Vitest mapping and validation
• @kitiumai/vitest-helpers/browser — Browser mode configuration
• @kitiumai/vitest-helpers/benchmarks — Benchmark utilities
• @kitiumai/vitest-helpers/reporters — Custom reporter helpers
• @kitiumai/vitest-helpers/tracing — OpenTelemetry and distributed tracing
• @kitiumai/vitest-helpers/migration — Jest to Vitest migration tools
• @kitiumai/vitest-helpers/config — Vitest configuration helpers
• @kitiumai/vitest-helpers/lint — Linting configuration for tests
• @kitiumai/vitest-helpers/tooling — Development tooling setup
• @kitiumai/vitest-helpers/plugins — Plugin system and built-in plugins
• @kitiumai/vitest-helpers/ci — CI/CD integration templates
• @kitiumai/vitest-helpers/monitoring — Test performance monitoring
• @kitiumai/vitest-helpers/collaboration — Team collaboration tools
• @kitiumai/vitest-helpers/performance — Performance optimization utilities
• @kitiumai/vitest-helpers/cli — Interactive CLI tools
• @kitiumai/vitest-helpers/visual — Visual testing and screenshot comparison
• @kitiumai/vitest-helpers/accessibility — Accessibility testing and WCAG compliance
• @kitiumai/vitest-helpers/security — Security auditing and compliance reporting

Build Optimization Tips

1. Use subpath imports in production to guarantee minimal bundle surface across all bundlers.
2. For setup/config files, import from @kitiumai/vitest-helpers/setup to avoid including browser/migration/benchmark utilities.
3. For migration projects, use @kitiumai/vitest-helpers/migration to ship only migration tools without benchmark/browser code.
4. Verify bundling with esbuild: esbuild --bundle --minify --analyze src/index.ts to see what's included.

The package provides ESM builds with sideEffects: false, so tree-shaking works across all modern toolchains.

License

MIT