npm package: @haykal/test-utils
Description: > Shared test utilities for Haykal packages — mock factories, fixtures, database helpers, and API test clients.
Latest version: 1.0.0

# @haykal/test-utils

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

## Installation

```bash
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

```typescript
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: 'test@example.com' });
    repository.findById.mockResolvedValue(mockUser);

    const result = await service.findById(mockUser.id);
    expect(result.email).toBe('test@example.com');
  });
});
```

### Integration Test with TestDatabase

```typescript
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: 'test@example.com' });
    await repo.save(user);

    const found = await repo.findOneBy({ email: 'test@example.com' });
    expect(found).toBeDefined();
  });
});
```

## Related Packages

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