@kitiumai/jest-helpers

Enterprise-grade Jest testing utilities that handle all complexity internally - The most comprehensive testing toolkit for modern JavaScript applications.

What is @kitiumai/jest-helpers?

@kitiumai/jest-helpers is a comprehensive testing framework wrapper that transforms Jest from a basic testing library into an enterprise-grade testing platform. Unlike traditional Jest toolkits that just provide utilities, this package handles all Jest complexity internally, providing a simple, consistent API for developers while enabling advanced testing capabilities.

Key Philosophy

"Testing should be simple, but powerful"

• 🎯 Simple API: One function call sets up everything
• 🏢 Enterprise Features: Big tech-grade capabilities (Google, Meta, Netflix level)
• 🔧 Zero Configuration: Auto-setup with sensible defaults
• 🎭 Comprehensive: Covers every testing scenario from unit to E2E

Why Do You Need This Package?

The Problem with Traditional Testing

Traditional Jest testing often involves:

• ❌ Complex setup files with dozens of imports
• ❌ Manual mock management and cleanup
• ❌ Inconsistent testing patterns across teams
• ❌ Missing enterprise features (property testing, fluent assertions, etc.)
• ❌ Poor developer experience with cryptic error messages
• ❌ No built-in support for modern testing patterns

The @kitiumai/jest-helpers Solution

• ✅ One-line setup: setupFilesAfterEnv: ['@kitiumai/jest-helpers/auto-setup']
• ✅ Automatic cleanup: Fixtures, mocks, timers - all cleaned up automatically
• ✅ Enterprise patterns: Property testing, fluent assertions, factories
• ✅ Developer experience: Clear error messages, debugging tools
• ✅ Consistent API: Same patterns across unit, integration, and E2E tests
• ✅ Modern features: Visual testing, accessibility testing, contract testing

Unique Selling Proposition (USP)

🏆 The Only Jest Wrapper That Handles Everything Internally

While other packages provide testing utilities, @kitiumai/jest-helpers is fundamentally different:

| Feature | @kitiumai/jest-helpers | Jest + Toolkits | Testing Library | |---------|----------------------|-----------------|-----------------| | Setup Complexity | 1 line | 50+ lines | 20+ lines | | Internal Complexity | Hidden | Exposed | Exposed | | Enterprise Features | ✅ Built-in | ❌ Manual | ❌ Manual | | Auto-cleanup | ✅ Everything | ❌ Partial | ❌ Partial | | Consistent API | ✅ Same everywhere | ❌ Varies | ❌ Varies | | Property Testing | ✅ Built-in | ❌ Add library | ❌ Add library | | Fluent Assertions | ✅ Built-in | ❌ Add library | ❌ Add library | | Visual Testing | ✅ Built-in | ❌ Add library | ❌ Add library |

🚀 Big Tech Features in a Simple Package

Features you'd find at Google, Meta, or Netflix, but with a simple API:

• Property-based testing (QuickCheck/Hypothesis style)
• Fluent assertions (Google Truth style)
• Advanced mocking (Mockito style)
• Visual regression testing
• Accessibility testing
• Contract testing
• Chaos engineering primitives

Competitor Comparison

vs. Jest Ecosystem

• jest-extended: Basic matchers only
• @testing-library/jest-dom: DOM-specific matchers only
• jest-mock-extended: Mock utilities only
• @kitiumai/jest-helpers: Complete testing platform

vs. Testing Libraries

• Vitest: Great for Vite, but missing enterprise features
• AVA: Minimalist, but lacks Jest's ecosystem
• Mocha: Requires extensive setup and plugins
• @kitiumai/jest-helpers: Jest power with enterprise capabilities

vs. Enterprise Testing Tools

• Testim: Commercial, expensive, complex
• Mabl: AI-focused, limited customization
• Applitools: Visual testing only
• @kitiumai/jest-helpers: Open source, comprehensive, developer-friendly

Installation

npm install @kitiumai/jest-helpers

Peer Dependencies:

• jest ^29.0.0
• typescript ^5.0.0
• @kitiumai/logger ^2.0.0 (for console capture features)

Quick Start

Option 1: Auto-Setup (Simplest - Recommended)

// jest.config.js
module.exports = {
  setupFilesAfterEnv: ['@kitiumai/jest-helpers/auto-setup'],
};

That's it! Everything is configured automatically.

import { setupJest } from '@kitiumai/jest-helpers';

const test = setupJest('unit');
const mockFn = test.utils.mock.createMock({ returnValue: 'test' });

Option 2: Manual Setup (More Control)

import { setupJest } from '@kitiumai/jest-helpers';

const test = setupJest('unit');

// One-time setup (handles all complexity)
beforeAll(test.setup.beforeAll);
beforeEach(test.setup.beforeEach);
afterEach(test.setup.afterEach);
afterAll(test.setup.afterAll);

// Use utilities
const mockFn = test.utils.mock.createMock({ returnValue: 'test' });

Core Features

🎯 Simple API

import { setupJest } from '@kitiumai/jest-helpers';

const test = setupJest('unit'); // Everything configured automatically!

🎭 Advanced Mocking

const mock = test.utils.mock.createAdvancedMock();
mock.whenCalledWith('arg').return('result');
mock.verify().calledWith('arg');

🧩 Automatic Fixtures

const fixtures = defineFixtures({
  database: createFixture(
    async () => setupDatabase(),
    async (db) => db.close()
  ),
});

const test = setupJest('integration', { fixtures });

✅ Custom Matchers

expect(data).toBeValidJson();
expect(mock).toHaveBeenCalledWithValidArguments();
expect(response).toHaveResponseTimeLessThan(100);

🗄️ Database Testing

const db = test.utils.database.createConnection();
await db.seed({ users: [{ id: 1, name: 'John' }] });

🌐 HTTP Mocking

const mockApi = test.utils.http.createMockServer();
mockApi.get('/api/users').respondWith({ users: [] });

⏱️ Timer Management

const timers = test.utils.timers.createManager();
timers.enableFakeTimers();
timers.advanceBy(1000);

📝 Console Capture

const console = test.utils.console.captureWithContext();
console.getLogs().shouldContain('Expected message');

🔄 Async Utilities

await test.utils.async.waitForCondition(() => api.isReady());
await test.utils.async.retry(() => flakyOperation(), { maxAttempts: 3 });

🏗️ Test Data Builders

const user = test.utils.builders.createUser({ name: 'John' });
const company = test.utils.builders.createCompany({ users: [user] });

🔍 Observability Matchers

expect(logs).toHaveLogWithLevel('error');
expect(metrics).toHaveMetric('requests_total', 42);
expect(trace).toHaveSpan('database_query');

Enterprise Features

🎲 Property-Based Testing

propertyTest('addition is commutative', [numberGen, numberGen], (a, b) => {
  expect(a + b).toBe(b + a);
});

🌟 Fluent Assertions

expect(user)
  .toBeDefined()
  .toHaveProperty('name')
  .and(user.name)
  .toBeString()
  .toHaveLengthGreaterThan(0);

🏭 Test Data Factories

const UserFactory = createFactory(User, {
  name: () => faker.name.fullName(),
  email: () => faker.internet.email(),
});

const user = UserFactory.build();
const users = UserFactory.buildList(5);

🎭 Advanced Mock Verification

const mock = createAdvancedMock();
mock.verify().calledOnce();
mock.verify().calledWith(validArgumentMatcher);
mock.verify().calledInOrder([call1, call2, call3]);

👁️ Visual Testing

const visual = test.utils.visual.createTester();
await visual.compareScreenshot('homepage', screenshot);

♿ Accessibility Testing

const a11y = test.utils.accessibility.createTester();
const results = await a11y.testPage(page);
expect(results).toHaveNoViolations();

📊 Parameterized Testing

parameterizedTest('addition', [
  [1, 2, 3],
  [4, 5, 9],
  [-1, 1, 0],
], (a, b, expected) => {
  expect(a + b).toBe(expected);
});

🔄 Multi-Framework Support

// Same API works with Jest and Vitest
import { universalTest } from '@kitiumai/jest-helpers';

universalTest('works everywhere', () => {
  // Test code that works in both frameworks
});

🔒 Strict Mode

import { setupStrictMode } from '@kitiumai/jest-helpers/strict-mode';

setupStrictMode({
  enforceTimeouts: true,
  preventConsoleLogs: true,
  requireTestDescriptions: true,
});

API Reference

Main Exports

Core Functions

• setupJest(preset, options?) - Main setup function
• jestHelpers - Direct access to utilities

Testing Utilities

• propertyTest(name, generators, testFn) - Property-based testing
• parameterizedTest(name, data, testFn) - Data-driven tests
• universalTest(name, testFn) - Cross-framework tests

Namespaced Exports

import { namespaced } from '@kitiumai/jest-helpers/namespaced';

// Access all utilities through namespaced object
namespaced.mock.createMock();
namespaced.fixtures.createFixture();
namespaced.matchers.toBeValidJson();

Module Exports

Core Modules

• @kitiumai/jest-helpers/mocks - Mocking utilities
• @kitiumai/jest-helpers/fixtures - Fixture management
• @kitiumai/jest-helpers/matchers - Custom matchers
• @kitiumai/jest-helpers/database - Database testing
• @kitiumai/jest-helpers/http - HTTP mocking
• @kitiumai/jest-helpers/timers - Timer management
• @kitiumai/jest-helpers/setup - Setup utilities
• @kitiumai/jest-helpers/integration - Integration testing
• @kitiumai/jest-helpers/console - Console capture
• @kitiumai/jest-helpers/async - Async utilities
• @kitiumai/jest-helpers/builders - Test data builders

Enterprise Modules

• @kitiumai/jest-helpers/strict-mode - Enterprise presets
• @kitiumai/jest-helpers/auto-setup - Auto-setup entry points
• @kitiumai/jest-helpers/auto-setup/unit - Unit test preset
• @kitiumai/jest-helpers/auto-setup/integration - Integration test preset
• @kitiumai/jest-helpers/auto-setup/e2e - E2E test preset
• @kitiumai/jest-helpers/auto-setup/contract - Contract test preset

Examples

Unit Testing

import { setupJest } from '@kitiumai/jest-helpers';

const test = setupJest('unit');

describe('UserService', () => {
  it('should create user', () => {
    const mockRepo = test.utils.mock.createMock();
    const service = new UserService(mockRepo);

    const user = service.createUser({ name: 'John' });

    expect(user).toBeDefined();
    expect(mockRepo.save).toHaveBeenCalledWith(user);
  });
});

Integration Testing

import { setupJest, defineFixtures } from '@kitiumai/jest-helpers';

const fixtures = defineFixtures({
  database: createFixture(
    async () => setupTestDatabase(),
    async (db) => db.close()
  ),
});

const test = setupJest('integration', { fixtures });

describe('UserAPI', () => {
  it('should return users', async () => {
    const response = await fetch('/api/users');
    const users = await response.json();

    expect(response.status).toBe(200);
    expect(users).toHaveLengthGreaterThan(0);
  });
});

Property-Based Testing

import { propertyTest, generators } from '@kitiumai/jest-helpers';

propertyTest(
  'array sort is idempotent',
  [generators.array(generators.number())],
  (arr) => {
    const sorted = [...arr].sort();
    const sortedAgain = [...sorted].sort();
    expect(sorted).toEqual(sortedAgain);
  }
);

Fluent Assertions

import { expect } from '@kitiumai/jest-helpers/matchers/fluent';

expect(user)
  .toBeDefined()
  .toHaveProperty('name')
  .and(user.name)
  .toBeString()
  .toHaveLengthGreaterThan(0)
  .and(user)
  .toHaveProperty('email')
  .and(user.email)
  .toMatch(/@example\.com$/);

Advanced Mocking

import { createAdvancedMock } from '@kitiumai/jest-helpers';

const mockApi = createAdvancedMock();
mockApi.whenCalledWith('GET', '/users').return(Promise.resolve([]));
mockApi.whenCalledWith('POST', '/users').throw(new Error('Unauthorized'));

// Use in tests
const result = await mockApi('GET', '/users');
expect(result).toEqual([]);

await expect(mockApi('POST', '/users')).rejects.toThrow('Unauthorized');

Configuration

Jest Config Examples

Minimal Setup

module.exports = {
  setupFilesAfterEnv: ['@kitiumai/jest-helpers/auto-setup'],
};

With Custom Configuration

module.exports = {
  setupFilesAfterEnv: ['@kitiumai/jest-helpers/auto-setup/integration'],
  testTimeout: 10000,
  testEnvironment: 'jsdom',
};

Advanced Setup

const { createJestConfig } = require('@kitiumai/jest-helpers/setup');

module.exports = createJestConfig({
  preset: 'integration',
  environment: 'jsdom',
  setupFiles: ['./custom-setup.js'],
});

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

git clone https://github.com/kitium-ai/jest-helpers.git
cd jest-helpers
pnpm install
pnpm build
pnpm test

License

MIT © Kitium AI

Support

• 📖 Documentation
• 🐛 Issues
• 💬 Discussions
• 📧 Email Support