Testing

Fragno provides comprehensive testing utilities to help you test your fragments without running a server. The createFragmentForTest function creates a test instance with type-safe route handling and response parsing.

Creating a Test Fragment

import { createFragmentForTest, withTestUtils } from "@fragno-dev/core/test";
import { routes } from "./fragment-definition";

// Important: Use .extend(withTestUtils()) to expose deps via services.test.deps
const fragment = createFragmentForTest(
  myFragmentDefinition.extend(withTestUtils()).build(),
  routes,
  {
    config: { apiKey: "test-key" },
    // Optional: override service implementations
    serviceImplementations: { emailService: mockEmailService },
  },
);

Testing Route Handlers

The callRoute method executes routes by method and path, returning a typed discriminated union:

const response = await fragment.callRoute("POST", "/users/:id", {
  pathParams: { id: "123" },
  body: { name: "John" },
  query: { filter: "active" },
  headers: { authorization: "Bearer token" },
});

// Response is a discriminated union
assert(response.type === "json");
expect(response.status).toBe(200);
expect(response.data).toEqual({ id: "123", name: "John" });

The method and path parameters are strongly typed based on your fragment's routes, providing autocomplete and type checking.

Response Types

The callRoute method returns a discriminated union with four possible types:

JSON Response

assert(response.type === "json");
expect(response.status).toBe(200);
expect(response.headers).toBeInstanceOf(Headers);
expect(response.data).toEqual({ id: "123", name: "John" });

Streaming Response

assert(response.type === "jsonStream");
const items = [];
for await (const item of response.stream) {
  items.push(item);
}
expect(items).toEqual([...expected]);

Empty Response

assert(response.type === "empty");
expect(response.status).toBe(204);

Error Response

assert(response.type === "error");
expect(response.status).toBe(404);
expect(response.error).toEqual({
  message: "Not found",
  code: "NOT_FOUND",
});

Database Testing

For database-backed fragments, see the Database Integration docs for database test helpers and the in-memory adapter: Database Testing.

Testing

On this page