@flatfile/implementations-utils-test-utils

Provides utilities for testing Flatfile Implementations, especially for listeners and job workers. This package is designed to work with testing frameworks like Jest.

Features

• bootstrapWorkbook / bootstrapSheet: Automatically create and tear down Spaces and Workbooks for your tests using beforeAll/afterAll or beforeEach/afterEach.
• Scenario: Load test data from markdown files, define input and expected output, and assert that your code produces the correct results.
• Test Helpers: Utility functions like requireJobToComplete to wait for asynchronous operations to finish in your tests.

Usage

Bootstrapping a Test Environment

Use bootstrapSheet to create a temporary workbook with a single sheet for your test. It will be automatically deleted after the test runs.

import { bootstrapSheet } from "@flatfile/implementations-utils-test-utils";
import { Flatfile } from "@flatfile/api";

describe("My Test Suite", () => {
  // This will create a new space and workbook before all tests in this suite
  // and delete the space after all tests are done.
  const { sheet, space } = bootstrapSheet(
    {
      name: "Contacts",
      slug: "contacts",
      fields: {
        firstName: { type: "string", label: "First Name" },
        lastName: { type: "string", label: "Last Name" },
        email: { type: "string", label: "Email" },
      },
    },
    "once" // or "each"
  );

  it("should do something with the sheet", () => {
    // You can now use `sheet()` and `space()` to access the created resources.
    // Note: these are functions that return the bootstrapped resources.
    expect(sheet().slug).toBe("contacts");
    expect(space().id).toBeDefined();
  });
});

Using Scenarios for Data-Driven Tests

The Scenario class lets you define test cases in simple markdown files.

my-test.scenario.md:

# Test Case: Basic User Data

## Input

### `contacts`

| firstName | lastName | email                |
| --------- | -------- | -------------------- |
| John      | Doe      | [email protected] |
| Jane      | Doe      | [email protected] |

## Output

### `users`

| fullName | emailAddress         |
| -------- | -------------------- |
| John Doe | [email protected] |
| Jane Doe | [email protected] |

Your test file:

import { Scenario } from "@flatfile/implementations-utils-test-utils";
import { Collection, FlatfileRecord } from "@flatfile/safe-api";

it("should transform contacts to users", () => {
  // Load the scenario
  const scenario = new Scenario("path/to/my-test.scenario.md");

  // Get the input data as a collection of records
  const inputData = scenario.getInput();

  // Your transformation logic here...
  const outputData = yourTransformationFunction(inputData); // This should return a Collection

  // Assert that the output matches the expectation in the scenario file
  scenario.assertDataMatchesOutputExpectation(outputData, ["users"]);
});

This approach makes it easy to manage complex test data and keep your tests clean and readable.