Testing Kit & Assertions

EntityTS provides a comprehensive test toolkit designed to make unit and integration testing lightning fast, isolated, and deterministic.

---

⚡ Zero-Database Unit Testing (InMemoryContext)

Spin up a fully functional DbContext backed entirely by memory in under 1 millisecond. No Docker, SQLite files, or external databases required:

import { InMemoryContext } from 'entityts';
import { User } from './entities/User';

describe('UserService', () => {
  let context: InMemoryContext;

  beforeEach(() => {
    context = new InMemoryContext({
      entities: [User],
      seedData: {
        users: [
          { id: 1, name: 'Alice', email: 'alice@example.com', isActive: true },
          { id: 2, name: 'Bob', email: 'bob@example.com', isActive: false },
        ],
      },
    });
  });

  it('filters active users correctly', async () => {
    const active = await context.set(User).where('isActive', '=', true).toList();
    expect(active).toHaveLength(1);
    expect(active[0].name).toBe('Alice');
  });

  it('supports inserting and inspecting in-memory rows', async () => {
    await context.set(User).add({ name: 'Charlie', email: 'charlie@example.com', isActive: true });

    // Inspect underlying mock table rows
    const rows = context.getTableRows('users');
    expect(rows).toHaveLength(3);
  });
});

---

🏭 Test Fixture Factories (FixtureFactory)

Quickly generate randomized or sequentially numbered mock entities for your tests:

import { FixtureFactory } from 'entityts';
import { User } from './entities/User';

const UserFactory = FixtureFactory.define(User, seq => ({
  name: `User ${seq}`,
  email: `user${seq}@company.org`,
  isActive: true,
  createdAt: new Date(),
}));

// Build an in-memory instance
const mockUser = UserFactory.build({ name: 'Custom Name' });

// Build a list of 5 mock instances
const mockUsers = UserFactory.buildList(5);

// Build and persist directly to your test DbContext
const savedUser = await UserFactory.create(context, { isActive: false });
const savedUsers = await UserFactory.createList(context, 10);

---

🔍 SQL Statement Assertions (SqlAssertions)

Verify the exact SQL output and parameter bindings generated by your queries:

import { SqlAssertions } from 'entityts';

const query = db.users
  .where('status', '=', 'active')
  .where('age', '>=', 21)
  .orderBy(u => u.name, 'asc');

// Assert SQL structure (whitespace-normalized)
SqlAssertions.assert(query).toSQL(
  'SELECT * FROM "users" WHERE "status" = $1 AND "age" >= $2 ORDER BY "name" ASC',
);

// Assert SQL contains specific fragments
SqlAssertions.assert(query).toContainSQL('WHERE "status" = $1');

// Assert parameter bindings
SqlAssertions.assert(query).withParams('active', 21).havingParamCount(2);