Tiny Fixtures

Common errors

• TypeError: tinyFixtures is not a function

  cause Attempting to use `require()` for an ESM module or incorrect named import syntax in a CommonJS context.
  fix Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`) and use `import { tinyFixtures } from 'tiny-fixtures';`.

• TypeError: Cannot read properties of undefined (reading 'getRefByKey')

  cause This error typically occurs when `getRefByKey` is called on an object that is not a valid fixture reference or if the third return value from `createFixtures` was not correctly destructured or used out of scope.
  fix Verify that you are correctly destructuring the third array element, e.g., `const [setup, teardown, users] = createFixtures('users', [...]);`, and then using `users[index].getRefByKey('id')` to get the reference.

• Error: connect ECONNREFUSED

  cause The `node-postgres` connection pool provided to `tinyFixtures` is unable to establish a connection to the PostgreSQL database, often due to incorrect connection parameters, the database server not running, or firewall issues.
  fix Double-check your `pg.Pool` configuration (host, port, user, password, database) and ensure the PostgreSQL database server is running and accessible from where your tests are executed.

Warnings

• gotcha Tiny Fixtures is currently only tested and compatible with PostgreSQL databases. It specifically expects a `node-postgres` connection pool for database interactions. Using it with other SQL dialects (e.g., MySQL, SQLite) or alternative ORMs/database drivers may lead to unexpected behavior or errors.
  Fix: Ensure your database is PostgreSQL and you are passing a correctly configured `node-postgres` connection pool (from the `pg` package) to `tinyFixtures`.
• gotcha When defining fixtures across multiple tables with foreign key relationships, the order in which `setup` and `teardown` functions are called is crucial for maintaining referential integrity. Parent table setups must always precede child table setups, and conversely, child table teardowns must precede parent table teardowns.
  Fix: Strictly follow the dependency order: `await setupParentFixtures(); await setupChildFixtures();` in `beforeEach` hooks, and `await teardownChildFixtures(); await teardownParentFixtures();` in `afterEach` hooks.

Install

• npm install tiny-fixtures npm
• yarn add tiny-fixtures yarn
• pnpm add tiny-fixtures pnpm

Imports

• tinyFixtures
  wrong:

  const { tinyFixtures } = require('tiny-fixtures');

  correct:

  import { tinyFixtures } from 'tiny-fixtures';

  The library is written in TypeScript and primarily consumed as an ESM module. While CommonJS might technically work, ESM imports are the recommended and most compatible approach in modern Node.js projects.
• FixtureManager

  import type { FixtureManager } from 'tiny-fixtures';

  Type import for the object returned when initializing tinyFixtures with a pool.
• Ref

  import type { Ref } from 'tiny-fixtures';

  Type import for the foreign key reference object returned by `getRefByKey`.

Quickstart

This quickstart demonstrates how to use `tiny-fixtures` to create related data across two tables (`users` and `user_messages`) using foreign key references in a test suite, ensuring clean data for each test run.

import { tinyFixtures } from 'tiny-fixtures';
import { Pool } from 'pg'; // Assuming 'pg' is installed and configured
import { expect } from 'chai'; // Assuming a testing framework like Mocha/Chai

// Dummy connection pool (replace with your actual database pool)
const pool = new Pool({
  user: process.env.DB_USER ?? 'testuser',
  host: process.env.DB_HOST ?? 'localhost',
  database: process.env.DB_NAME ?? 'testdb',
  password: process.env.DB_PASSWORD ?? 'testpassword',
  port: parseInt(process.env.DB_PORT ?? '5432', 10),
});

// Dummy function to fetch users (replace with actual DB query)
const getUsers = async () => {
  const client = await pool.connect();
  try {
    const res = await client.query('SELECT id, email, username FROM users;');
    return res.rows;
  } finally {
    client.release();
  }
};

const getUserMessages = async (userId: number) => {
  const client = await pool.connect();
  try {
    const res = await client.query('SELECT message FROM user_messages WHERE user_id = $1;', [userId]);
    return res.rows;
  } finally {
    client.release();
  }
}

const { createFixtures } = tinyFixtures(pool);

describe('my test cases with foreign keys', () => {
  const [setupUserFixtures, teardownUserFixtures, users] = createFixtures('users', [
    {
      email: 'foo@bar.co',
      username: 'tinyAnt'
    }, {
      email: 'bar@foo.co',
      username: 'antTiny',
    }
  ]);

  const [setupUserMessageFixtures, teardownUserMessageFixtures] = createFixtures(
    'user_messages',
    [{
        user_id: users[0].getRefByKey('id'),
        message: 'Foobar did the bar foo good',
      },
      {
        user_id: users[0].getRefByKey('id'),
        message: 'I am a meat popsicle', 
    }]
  );

  beforeEach(async () => {
    await setupUserFixtures();
    await setupUserMessageFixtures();
  });

  afterEach(async () => {
    await teardownUserMessageFixtures();
    await teardownUserFixtures();
  });

  it('should have a user with two messages, and one with none', async () => {
    const dbUsers = await getUsers();
    expect(dbUsers).to.have.length(2);

    const messagesForUser1 = await getUserMessages(dbUsers[0].id);
    const messagesForUser2 = await getUserMessages(dbUsers[1].id);

    expect(messagesForUser1).to.have.length(2);
    expect(messagesForUser2).to.have.length(0);
  });
});