npm package: @pfacheris/implementation-utils-test-utils
Description: Provides utilities for testing Flatfile Implementations
Author: Flatfile
Latest version: 0.0.3

# @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.

```typescript
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`**:
```markdown
# Test Case: Basic User Data

## Input

### `contacts`

| firstName | lastName | email                |
| --------- | -------- | -------------------- |
| John      | Doe      | john.doe@example.com |
| Jane      | Doe      | jane.doe@example.com |

## Output

### `users`

| fullName | emailAddress         |
| -------- | -------------------- |
| John Doe | john.doe@example.com |
| Jane Doe | jane.doe@example.com |
```

**Your test file**:
```typescript
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.