@haykal/test-utils

Shared test utilities for Haykal packages — mock factories, fixtures, database helpers, and API test clients.

Installation

pnpm add -D @haykal/test-utils

Peer dependency: jest >= 29.0.0

Key Exports

Mock Factories

| Export | Description | | ---------------------------- | ------------------------------------------- | | createMockRepository() | Mock TypeORM repository with common methods | | createMockCacheService() | Mock CacheService (always cache miss) | | createMockDomainEventBus() | Mock DomainEventBus | | createMockLogger() | Mock LoggerService (no-op) | | createMockRedisClient() | Mock ioredis client | | createMockRequestContext() | Mock RequestContext with test defaults |

Entity Factories

| Export | Description | | ------------------------------ | ----------------------------------------------- | | createMockUserEntity() | Create a UserEntity with test defaults | | createMockRoleEntity() | Create a RoleEntity with test defaults | | createMockPermissionEntity() | Create a PermissionEntity with test defaults | | createMockProfileEntity() | Create a UserProfileEntity with test defaults |

Fixtures

| Export | Description | | ----------------------- | ------------------------------------- | | createMockUser() | Simple user fixture (id, email, name) | | generateTestId() | Generate deterministic test UUID | | createTestTimestamp() | Generate deterministic test timestamp | | resetFixtureCounter() | Reset sequential ID counters |

Database & API Testing

| Export | Description | | --------------- | -------------------------------------------------------- | | TestDatabase | Manages test database lifecycle (setup, teardown, clean) | | TestApiClient | HTTP client for integration/e2e tests |

Usage Examples

Unit Test with Mocks

import {
  createMockRepository,
  createMockLogger,
  createMockDomainEventBus,
  createMockUserEntity,
} from '@haykal/test-utils';

describe('UsersService', () => {
  let service: UsersService;
  const repository = createMockRepository();
  const logger = createMockLogger();
  const eventBus = createMockDomainEventBus();

  beforeEach(() => {
    service = new UsersService(repository, logger, eventBus);
  });

  it('should find user by id', async () => {
    const mockUser = createMockUserEntity({ email: '[email protected]' });
    repository.findById.mockResolvedValue(mockUser);

    const result = await service.findById(mockUser.id);
    expect(result.email).toBe('[email protected]');
  });
});

Integration Test with TestDatabase

import { TestDatabase } from '@haykal/test-utils';

describe('UsersRepository (integration)', () => {
  const db = new TestDatabase({
    entities: [UserEntity],
  });

  beforeAll(() => db.setup());
  afterAll(() => db.teardown());
  afterEach(() => db.clean());

  it('should persist and retrieve a user', async () => {
    const repo = db.getRepository(UserEntity);
    const user = repo.create({ email: '[email protected]' });
    await repo.save(user);

    const found = await repo.findOneBy({ email: '[email protected]' });
    expect(found).toBeDefined();
  });
});

Related Packages

• @haykal/core-backend — Production services that these utils mock
• @haykal/tooling — ESLint and TypeScript configuration