Fixtures

To create test data for your app, Joystick includes a function exported as a named export from @joystick.js/node as fixture. The fixture function itself returns another function you can call via the fixtures function assigned to the options you pass to joystick.app() in your index.server.js file.

Example Usage

Defining a fixture

Fixtures should be defined in the /fixtures folder at the root of your app. Inside that folder, a file should be created for each fixture in your app with a name describing the target (e.g., a collection name in a MongoDB database or a table name in a PostgreSQL database like /fixtures/books.js).

import joystick, { fixture } from "@joystick.js/node";
import { faker } from '@faker-js/faker';
import random_book_title from '../lib/random_book.js';

const books = fixture({
  target: "books",
  quantity: 25,
  template: (fixture = {}, index = 0, input = {}) => {
    return {
      _id: joystick.id(),
      title: random_book_title(),
      author: faker.person.fullName(),
    };
  },
  skip: async (fixture = {}, input = {}) => {
    const total = await process.databases.mongodb.collection(fixture?.options?.target).countDocuments({});
    return total >= fixture?.options?.quantity;
  },
  on_create: async (
    fixture = {},
    data_to_create = [],
    on_after_create_each = null,
  ) => {
    await process.databases.mongodb.collection(fixture?.options?.target).bulkWrite(
      data_to_create.map((book) => {
        return {
          insertOne: book,
        };
      })
    );
  },
  on_after_create_all: (fixture = {}, data_to_create = [], input = {}) => {
    console.log(`Fixture created ${data_to_create.length} books.`);
  },
});

export default books;

Calling a fixture

To call a fixture, import it into your index.server.js file and then call the function returned by fixture inside of the function you pass to fixtures in your joystick.app() options:

import joystick from "@joystick.js/node";
import books_fixture from './fixtures/books.js';

joystick.app({
  fixtures: () => {
    books_fixture();
  },
  routes: { ... }
});

When your app starts, after a connection has been established to each of your databases, Joystick will call the fixtures() function passed to joystick.app() above, triggering a run of any fixtures called within it.

API

Definition

fixture(options: object) => function;

Parameters

target string required

A string containing the name of the intended target for the data (e.g., a MongoDB collection name or PostgreSQL table name).

quantity integer required

How many copies of the fixture template to generate.

template function required

A function returning the data to create (e.g., an object of key/value pairs). Receives the fixture instance, the index for the current iteration, and any input provided when the fixture was invoked.

skip function

A function returning a boolean true or false that determines whether or not the fixture should run. Receives the fixture instance and any input provided when the fixture was invoked.

on_create function required

A function called after the template function has been invoked quantity times. Handles inserting the data into the database or performing additional logic.

on_after_create_each function

A function called after each record is created. Useful for triggering additional fixtures or logic dependent on the inserted data.

on_after_create_all function

A function called after all records have been created. Useful for performing cleanup or triggering dependent fixtures.