@studiosonrai/nestjs-testfx 1.0.0

package/README.md

@@ -0,0 +1,666 @@
+# nestjs-testfx
+
+Shared testing utilities for NestJS + TypeORM applications. This package provides a robust foundation for writing API tests with database integration.
+
+## Features
+
+- **DatabaseTestHelper**: Transaction-based test isolation and database cleanup
+- **BaseFactory**: Abstract factory pattern for generating test data with Faker.js
+- **EntityComparator**: Deep entity comparison with custom Jest matchers
+- **Fixtures**: Pre-defined static test data with loader utilities
+- **Jest Setup Template**: Ready-to-use Jest configuration with safety checks
+
+## Installation
+
+```bash
+npm install nestjs-testfx --save-dev
+```
+
+### Peer Dependencies
+
+Ensure you have these peer dependencies installed:
+
+```bash
+npm install --save-dev \
+  @faker-js/faker \
+  @nestjs/common \
+  @nestjs/config \
+  @nestjs/testing \
+  @nestjs/typeorm \
+  jest \
+  typeorm
+```
+
+## Quick Start
+
+### 1. Set Up Jest Configuration
+
+Copy the Jest setup template to your project:
+
+```typescript
+// src/testing/jest.setup.ts
+import { config } from 'dotenv';
+import { createEntityEquivalentMatcher } from 'nestjs-testfx';
+
+config({ path: '.test.env' });
+
+jest.setTimeout(30000);
+
+beforeAll(() => {
+  if (process.env.NODE_ENV !== 'test') {
+    throw new Error('Tests must run with NODE_ENV=test');
+  }
+});
+
+expect.extend({
+  toBeEntityEquivalent: createEntityEquivalentMatcher(),
+});
+```
+
+Update your `jest.config.js`:
+
+```javascript
+module.exports = {
+  setupFilesAfterEnv: ['<rootDir>/src/testing/jest.setup.ts'],
+  // ... other config
+};
+```
+
+### 2. Create Your DataSource
+
+```typescript
+// src/testing/test-data-source.ts
+import { DataSource } from 'typeorm';
+
+export const testDataSource = new DataSource({
+  type: 'postgres', // or 'mssql', 'mysql'
+  host: process.env.DB_HOST,
+  port: parseInt(process.env.DB_PORT || '5432'),
+  username: process.env.DB_USERNAME,
+  password: process.env.DB_PASSWORD,
+  database: process.env.DB_DATABASE,
+  entities: ['src/**/*.entity.ts'],
+  synchronize: false,
+});
+```
+
+### 3. Create Factories for Your Entities
+
+```typescript
+// src/testing/factories/user.factory.ts
+import { DataSource } from 'typeorm';
+import { BaseFactory } from 'nestjs-testfx';
+import { User } from '../../entities/user.entity';
+
+export class UserFactory extends BaseFactory<User> {
+  constructor(dataSource: DataSource) {
+    super(dataSource, User);
+  }
+
+  build(overrides?: Partial<User>): User {
+    const fake = this.generateFakeData();
+
+    return this.createInstance(this.applyOverrides({
+      email: fake.email,
+      firstName: fake.firstName,
+      lastName: fake.lastName,
+      isActive: true,
+      createdAt: new Date(),
+    }, overrides));
+  }
+
+  async createAdmin(overrides?: Partial<User>): Promise<User> {
+    return this.create({
+      role: 'admin',
+      isActive: true,
+      ...overrides,
+    });
+  }
+}
+```
+
+### 4. Write Your First Test
+
+```typescript
+// src/users/users.service.spec.ts
+import { DatabaseTestHelper } from 'nestjs-testfx';
+import { testDataSource } from '../testing/test-data-source';
+import { UserFactory } from '../testing/factories/user.factory';
+import { UsersService } from './users.service';
+
+describe('UsersService', () => {
+  let databaseHelper: DatabaseTestHelper;
+  let userFactory: UserFactory;
+  let service: UsersService;
+
+  beforeAll(async () => {
+    databaseHelper = await DatabaseTestHelper.fromDataSource(testDataSource, {
+      cleanupOrder: ['Order', 'User'],
+      dialect: 'postgres',
+    });
+    userFactory = new UserFactory(databaseHelper.getDataSource());
+    service = new UsersService(databaseHelper.getRepository(User));
+  });
+
+  afterAll(async () => {
+    await databaseHelper.close();
+  });
+
+  beforeEach(async () => {
+    await databaseHelper.cleanDatabase(['User']);
+  });
+
+  it('should find user by email', async () => {
+    const user = await userFactory.create({ email: 'test@example.com' });
+
+    const found = await service.findByEmail('test@example.com');
+
+    expect(found).toBeDefined();
+    expect(found?.id).toBe(user.id);
+  });
+});
+```
+
+## API Reference
+
+### DatabaseTestHelper
+
+Manages database connections and provides test isolation utilities.
+
+```typescript
+import { DatabaseTestHelper } from 'nestjs-testfx';
+
+// Create from existing DataSource
+const helper = await DatabaseTestHelper.fromDataSource(dataSource, {
+  cleanupOrder: ['OrderItem', 'Order', 'User'],
+  dialect: 'postgres', // 'mssql' | 'postgres' | 'mysql'
+});
+
+// Transaction-based isolation
+await helper.startTransaction();
+const manager = helper.getTransactionManager();
+await manager.save(User, userData);
+await helper.rollbackTransaction(); // Undo all changes
+
+// Clean specific tables
+await helper.cleanDatabase(['User', 'Order']);
+
+// Query helpers
+const exists = await helper.entityExists(User, { email: 'test@example.com' });
+const count = await helper.countEntities(User, { isActive: true });
+
+// Execute in separate transaction (auto-commits)
+const user = await helper.inNewTransaction(async (manager) => {
+  return manager.save(User, { email: 'test@example.com' });
+});
+
+// Close connection
+await helper.close();
+```
+
+### BaseFactory
+
+Abstract base class for entity factories.
+
+```typescript
+import { BaseFactory, FactoryOptions } from 'nestjs-testfx';
+
+class ProductFactory extends BaseFactory<Product> {
+  constructor(dataSource: DataSource) {
+    super(dataSource, Product);
+  }
+
+  build(overrides?: Partial<Product>): Product {
+    const fake = this.generateFakeData();
+    return this.createInstance(this.applyOverrides({
+      name: fake.name,
+      price: fake.decimal,
+      inStock: true,
+    }, overrides));
+  }
+
+  // Convenience methods
+  async createOutOfStock(overrides?: Partial<Product>): Promise<Product> {
+    return this.create({ inStock: false, ...overrides });
+  }
+}
+
+// Usage
+const factory = new ProductFactory(dataSource);
+
+// Build without saving
+const product = factory.build({ name: 'Widget' });
+
+// Create and save
+const saved = await factory.create({ name: 'Gadget' });
+
+// Create multiple
+const products = await factory.createMany(10, { inStock: true });
+
+// Create within transaction
+const product = await factory.create(
+  { name: 'Test' },
+  { manager: transactionManager }
+);
+
+// Build without saving
+const instance = await factory.create({}, { save: false });
+```
+
+#### Available Fake Data
+
+`generateFakeData()` provides:
+
+| Property | Description |
+|----------|-------------|
+| `id` | Random integer (1-999999) |
+| `email` | Random email address |
+| `firstName` | Random first name |
+| `lastName` | Random last name |
+| `phone` | Random phone number |
+| `address` | Random street address |
+| `city` | Random city name |
+| `state` | Random state/province |
+| `postalCode` | Random zip/postal code |
+| `country` | Random country name |
+| `name` | Random company name |
+| `description` | Random paragraph |
+| `createdAt` | Random past date |
+| `updatedAt` | Random recent date |
+| `boolean` | Random boolean |
+| `number` | Random integer (1-1000) |
+| `decimal` | Random float (0-100, 2 decimals) |
+| `datetime` | Random future date |
+| `text` | Random sentences |
+| `url` | Random URL |
+| `priority` | 'low' \| 'medium' \| 'high' |
+| `status` | 'active' \| 'inactive' \| 'pending' |
+
+### EntityComparator
+
+Deep entity comparison with custom options.
+
+```typescript
+import { EntityComparator } from 'nestjs-testfx';
+
+// Basic comparison
+const result = EntityComparator.compare(actual, expected);
+console.log(result.areEqual); // true/false
+
+// Ignore auto-generated fields
+const result = EntityComparator.compare(savedUser, {
+  email: 'test@example.com',
+  firstName: 'John',
+}, {
+  ignoreFields: ['id', 'createdAt', 'updatedAt'],
+});
+
+// Custom comparators
+const result = EntityComparator.compare(entity1, entity2, {
+  customComparators: {
+    // Compare dates by day only
+    scheduledDate: (a, b) =>
+      new Date(a).toDateString() === new Date(b).toDateString(),
+    // Compare prices within tolerance
+    price: (a, b) => Math.abs(a - b) < 0.01,
+  },
+});
+
+// Compare subset of fields
+const result = EntityComparator.compareSubset(fullEntity, {
+  email: 'test@example.com',
+  name: 'John',
+});
+
+// Format for error messages
+if (!result.areEqual) {
+  console.log(EntityComparator.formatComparisonResult(result));
+}
+```
+
+### Jest Custom Matcher
+
+```typescript
+// In jest.setup.ts
+import { createEntityEquivalentMatcher } from 'nestjs-testfx';
+
+expect.extend({
+  toBeEntityEquivalent: createEntityEquivalentMatcher(),
+});
+
+// In tests
+expect(actualUser).toBeEntityEquivalent(expectedUser);
+
+expect(savedEntity).toBeEntityEquivalent(expectedData, {
+  ignoreFields: ['id', 'createdAt', 'updatedAt'],
+});
+```
+
+### Fixtures
+
+Pre-defined static test data.
+
+```typescript
+// Define fixtures
+export const ROLE_FIXTURES = {
+  ADMIN: { id: 1, name: 'Admin', description: 'Administrator' },
+  USER: { id: 2, name: 'User', description: 'Standard user' },
+};
+
+export function getAllRoleFixtures() {
+  return Object.values(ROLE_FIXTURES);
+}
+
+export function getRoleById(id: number) {
+  return Object.values(ROLE_FIXTURES).find(r => r.id === id);
+}
+
+// Load fixtures
+class FixtureLoader {
+  constructor(private manager: EntityManager) {}
+
+  async loadRoles() {
+    for (const role of getAllRoleFixtures()) {
+      await this.manager.save(Role, role);
+    }
+  }
+}
+```
+
+## Complete Test Example
+
+```typescript
+import {
+  DatabaseTestHelper,
+  EntityComparator,
+} from 'nestjs-testfx';
+import { testDataSource } from '../testing/test-data-source';
+import { UserFactory } from '../testing/factories/user.factory';
+import { OrderFactory } from '../testing/factories/order.factory';
+import { OrderService } from './order.service';
+
+describe('OrderService', () => {
+  let databaseHelper: DatabaseTestHelper;
+  let userFactory: UserFactory;
+  let orderFactory: OrderFactory;
+  let service: OrderService;
+
+  beforeAll(async () => {
+    databaseHelper = await DatabaseTestHelper.fromDataSource(testDataSource, {
+      cleanupOrder: ['OrderItem', 'Order', 'User'],
+      dialect: 'postgres',
+    });
+
+    userFactory = new UserFactory(databaseHelper.getDataSource());
+    orderFactory = new OrderFactory(databaseHelper.getDataSource());
+
+    service = new OrderService(
+      databaseHelper.getRepository(Order),
+      databaseHelper.getRepository(User),
+    );
+  });
+
+  afterAll(async () => {
+    await databaseHelper.close();
+  });
+
+  beforeEach(async () => {
+    await databaseHelper.cleanDatabase(['OrderItem', 'Order', 'User']);
+  });
+
+  describe('createOrder', () => {
+    it('should create order for user', async () => {
+      // Arrange
+      const user = await userFactory.create({ email: 'buyer@example.com' });
+
+      // Act
+      const order = await service.createOrder(user.id, {
+        items: [{ productId: 1, quantity: 2 }],
+      });
+
+      // Assert
+      expect(order.id).toBeDefined();
+      expect(order.userId).toBe(user.id);
+      expect(order.status).toBe('pending');
+    });
+
+    it('should calculate total correctly', async () => {
+      const user = await userFactory.create();
+      const order = await service.createOrder(user.id, {
+        items: [
+          { productId: 1, quantity: 2, price: 10 },
+          { productId: 2, quantity: 1, price: 25 },
+        ],
+      });
+
+      expect(order.total).toBe(45); // (2 * 10) + (1 * 25)
+    });
+  });
+
+  describe('cancelOrder', () => {
+    it('should cancel pending order', async () => {
+      const user = await userFactory.create();
+      const order = await orderFactory.createPending(user.id);
+
+      const cancelled = await service.cancelOrder(order.id);
+
+      expect(cancelled.status).toBe('cancelled');
+    });
+
+    it('should not cancel completed order', async () => {
+      const user = await userFactory.create();
+      const order = await orderFactory.createCompleted(user.id);
+
+      await expect(service.cancelOrder(order.id)).rejects.toThrow(
+        'Cannot cancel completed order'
+      );
+    });
+  });
+
+  describe('with transactions', () => {
+    it('should rollback on error', async () => {
+      const user = await userFactory.create();
+
+      await expect(
+        service.createOrderWithPayment(user.id, {
+          items: [{ productId: 1, quantity: 1 }],
+          paymentMethod: 'invalid',
+        })
+      ).rejects.toThrow();
+
+      // Verify no order was created
+      const count = await databaseHelper.countEntities(Order, { userId: user.id });
+      expect(count).toBe(0);
+    });
+  });
+});
+```
+
+## Factory Manager Pattern
+
+For larger projects, use a factory manager to centralize factory access:
+
+```typescript
+// src/testing/factories/index.ts
+import { DataSource } from 'typeorm';
+import { UserFactory } from './user.factory';
+import { OrderFactory } from './order.factory';
+import { ProductFactory } from './product.factory';
+
+export class FactoryManager {
+  public readonly user: UserFactory;
+  public readonly order: OrderFactory;
+  public readonly product: ProductFactory;
+
+  constructor(dataSource: DataSource) {
+    this.user = new UserFactory(dataSource);
+    this.order = new OrderFactory(dataSource);
+    this.product = new ProductFactory(dataSource);
+  }
+}
+
+// Usage in tests
+describe('Service', () => {
+  let factories: FactoryManager;
+
+  beforeAll(async () => {
+    factories = new FactoryManager(dataSource);
+  });
+
+  it('test', async () => {
+    const user = await factories.user.create();
+    const order = await factories.order.createForUser(user.id);
+  });
+});
+```
+
+## Test Data Helper Pattern
+
+For complex test scenarios, create a test data helper:
+
+```typescript
+// src/testing/helpers/test-data.helper.ts
+import { DatabaseTestHelper } from 'nestjs-testfx';
+import { FactoryManager } from '../factories';
+import { ROLE_FIXTURES } from '../fixtures';
+
+export class TestDataHelper {
+  constructor(
+    private databaseHelper: DatabaseTestHelper,
+    private factories: FactoryManager,
+  ) {}
+
+  async setupFixtures(manager?: EntityManager) {
+    const em = manager || this.databaseHelper.getDataSource().manager;
+    for (const role of Object.values(ROLE_FIXTURES)) {
+      await em.save(Role, role);
+    }
+  }
+
+  async createTestScenario(name: string) {
+    switch (name) {
+      case 'e-commerce':
+        return this.createEcommerceScenario();
+      case 'multi-tenant':
+        return this.createMultiTenantScenario();
+      default:
+        throw new Error(`Unknown scenario: ${name}`);
+    }
+  }
+
+  private async createEcommerceScenario() {
+    await this.setupFixtures();
+
+    const admin = await this.factories.user.createAdmin();
+    const customers = await this.factories.user.createMany(5);
+    const products = await this.factories.product.createMany(20);
+
+    return { admin, customers, products };
+  }
+}
+```
+
+## Environment Configuration
+
+Create a `.test.env` or `.ci.env` file:
+
+```env
+NODE_ENV=test
+DB_HOST=localhost
+DB_PORT=5432
+DB_DATABASE=myapp_test
+DB_USERNAME=postgres
+DB_PASSWORD=postgres
+
+# Optional: reduce log noise
+LOG_LEVEL=warn
+```
+
+## Best Practices
+
+### 1. Clean Tables in Correct Order
+
+```typescript
+// Define cleanup order respecting foreign keys
+const cleanupOrder = [
+  'OrderItem',    // References Order
+  'Order',        // References User
+  'UserRole',     // References User and Role
+  'User',         // Parent
+  'Role',         // Parent
+];
+
+const helper = await DatabaseTestHelper.fromDataSource(dataSource, {
+  cleanupOrder,
+});
+```
+
+### 2. Use Transaction Isolation for Speed
+
+```typescript
+beforeEach(async () => {
+  await databaseHelper.startTransaction();
+});
+
+afterEach(async () => {
+  await databaseHelper.rollbackTransaction();
+});
+```
+
+### 3. Create Meaningful Factory Methods
+
+```typescript
+class OrderFactory extends BaseFactory<Order> {
+  // Good: Descriptive, purpose-clear methods
+  async createPendingForNewCustomer() { ... }
+  async createCompletedWithItems(itemCount: number) { ... }
+  async createHighValueOrder(minAmount: number) { ... }
+}
+```
+
+### 4. Use Fixtures for Reference Data
+
+```typescript
+// Use fixtures for data with known IDs
+const userRole = ROLE_FIXTURES.USER;
+
+// Use factories for variable test data
+const user = await userFactory.create({ roleId: userRole.id });
+```
+
+## Troubleshooting
+
+### "Tests must use a test database"
+
+Ensure your `.test.env` has a database name containing 'test' or 'ci':
+
+```env
+DB_DATABASE=myapp_test  # ✓
+DB_DATABASE=myapp_ci    # ✓
+DB_DATABASE=myapp       # ✗ Will fail safety check
+```
+
+### Foreign Key Constraint Errors
+
+Update `cleanupOrder` to delete child tables before parents:
+
+```typescript
+const cleanupOrder = [
+  'ChildTable',   // First
+  'ParentTable',  // Last
+];
+```
+
+### Transaction Already Started
+
+Ensure you call `rollbackTransaction()` or `commitTransaction()` before starting a new one:
+
+```typescript
+afterEach(async () => {
+  await databaseHelper.rollbackTransaction();
+});
+```
+
+## License
+
+MIT

package/dist/src/factories/base.factory.d.ts

@@ -0,0 +1,49 @@
+import { Repository, EntityManager, DataSource, ObjectLiteral } from 'typeorm';
+export interface FactoryOptions {
+    save?: boolean;
+    manager?: EntityManager;
+    count?: number;
+}
+export interface EntityFactory<T> {
+    build(overrides?: Partial<T>): T;
+    create(overrides?: Partial<T>, options?: FactoryOptions): Promise<T>;
+    createMany(count: number, overrides?: Partial<T>, options?: FactoryOptions): Promise<T[]>;
+}
+export declare abstract class BaseFactory<T extends ObjectLiteral> implements EntityFactory<T> {
+    protected dataSource: DataSource;
+    protected repository: Repository<T>;
+    protected entityClass: new () => T;
+    constructor(dataSource: DataSource, entityClass: new () => T);
+    abstract build(overrides?: Partial<T>): T;
+    create(overrides?: Partial<T>, options?: FactoryOptions): Promise<T>;
+    createMany(count: number, overrides?: Partial<T>, options?: FactoryOptions): Promise<T[]>;
+    protected generateFakeData(): {
+        id: number;
+        email: string;
+        firstName: string;
+        lastName: string;
+        phone: string;
+        address: string;
+        city: string;
+        state: string;
+        postalCode: string;
+        country: string;
+        name: string;
+        description: string;
+        createdAt: Date;
+        updatedAt: Date;
+        boolean: boolean;
+        number: number;
+        decimal: number;
+        datetime: Date;
+        text: string;
+        url: string;
+        priority: "low" | "medium" | "high";
+        status: "active" | "inactive" | "pending";
+        code: "installation" | "inspection" | "maintenance" | "repair";
+        randomMinutes: number;
+    };
+    protected applyOverrides<K>(baseData: K, overrides?: Partial<K>): K;
+    protected createInstance(data: Partial<T>): T;
+    protected getRepository(): Repository<T>;
+}