Testing Encore.ts Applications Instructions

Encore.ts uses standard TypeScript testing tools. The recommended setup is Vitest.

Setup Vitest npm install -D vitest

Add to package.json:

{ "scripts": { "test": "vitest" } }

Test an API Endpoint // api.test.ts import { describe, it, expect } from "vitest"; import { hello } from "./api";

describe("hello endpoint", () => { it("returns a greeting", async () => { const response = await hello(); expect(response.message).toBe("Hello, World!"); }); });

Run Tests

Run with Encore (recommended - sets up infrastructure)

encore test

Or run directly with npm

npm test

Using encore test is recommended because it:

Sets up test databases automatically Provides isolated infrastructure per test Handles service dependencies Test with Request Parameters // api.test.ts import { describe, it, expect } from "vitest"; import { getUser } from "./api";

describe("getUser endpoint", () => { it("returns the user by ID", async () => { const user = await getUser({ id: "123" }); expect(user.id).toBe("123"); expect(user.name).toBeDefined(); }); });

Test Database Operations

Encore provides isolated test databases:

// user.test.ts import { describe, it, expect, beforeEach } from "vitest"; import { createUser, getUser, db } from "./user";

describe("user operations", () => { beforeEach(async () => { // Clean up before each test await db.execDELETE FROM users; });

it("creates and retrieves a user", async () => { const created = await createUser({ email: "test@example.com", name: "Test" }); const retrieved = await getUser({ id: created.id });

expect(retrieved.email).toBe("test@example.com");

}); });

Test Service-to-Service Calls // order.test.ts import { describe, it, expect } from "vitest"; import { createOrder } from "./order";

describe("order service", () => { it("creates an order and notifies user service", async () => { // Service calls work normally in tests const order = await createOrder({ userId: "user-123", items: [{ productId: "prod-1", quantity: 2 }], });

expect(order.id).toBeDefined();
expect(order.status).toBe("pending");

}); });

Test Error Cases import { describe, it, expect } from "vitest"; import { getUser } from "./api"; import { APIError } from "encore.dev/api";

describe("error handling", () => { it("throws NotFound for missing user", async () => { await expect(getUser({ id: "nonexistent" })) .rejects .toThrow("user not found"); });

it("throws with correct error code", async () => { try { await getUser({ id: "nonexistent" }); } catch (error) { expect(error).toBeInstanceOf(APIError); expect((error as APIError).code).toBe("not_found"); } }); });

Test Pub/Sub // notifications.test.ts import { describe, it, expect, vi } from "vitest"; import { orderCreated } from "./events";

describe("pub/sub", () => { it("publishes order created event", async () => { const messageId = await orderCreated.publish({ orderId: "order-123", userId: "user-456", total: 9999, });

expect(messageId).toBeDefined();

}); });

Test Cron Jobs

Test the underlying function, not the cron schedule:

// cleanup.test.ts import { describe, it, expect } from "vitest"; import { cleanupExpiredSessions } from "./cleanup";

describe("cleanup job", () => { it("removes expired sessions", async () => { // Create some expired sessions first await createExpiredSession();

// Call the endpoint directly
await cleanupExpiredSessions();

// Verify cleanup happened
const remaining = await countSessions();
expect(remaining).toBe(0);

}); });

Mocking External Services import { describe, it, expect, vi, beforeEach } from "vitest"; import { sendWelcomeEmail } from "./email";

// Mock external API vi.mock("./external-email-client", () => ({ send: vi.fn().mockResolvedValue({ success: true }), }));

describe("email service", () => { it("sends welcome email", async () => { const result = await sendWelcomeEmail({ userId: "123" }); expect(result.sent).toBe(true); }); });

Test Configuration

Create vitest.config.ts:

import { defineConfig } from "vitest/config";

export default defineConfig({ test: { globals: true, environment: "node", include: ["*/.test.ts"], coverage: { reporter: ["text", "json", "html"], }, }, });

Guidelines Use encore test to run tests with infrastructure setup Each test file gets an isolated database transaction (rolled back after) Test API endpoints by calling them directly as functions Service-to-service calls work normally in tests Mock external dependencies (third-party APIs, email services, etc.) Don't mock Encore infrastructure (databases, Pub/Sub) - use the real thing