@flink-app/test-utils 0.12.1-alpha.4 → 0.12.1-alpha.40

package/dist/http.js

@@ -59,6 +59,7 @@ var gotOpts = {
     throwHttpErrors: false,
     json: true,
     retry: 0,
+    followRedirect: false,
 };
 /**
  * Initializes test flink app.
@@ -92,7 +93,7 @@ function get(path_1) {
 exports.get = get;
 function post(path_1, body_1) {
     return __awaiter(this, arguments, void 0, function (path, body, opts) {
-        var headers, res, err_1;
+        var headers, isRawString, res, res, err_1;
         if (opts === void 0) { opts = {}; }
         return __generator(this, function (_a) {
             switch (_a.label) {
@@ -103,16 +104,29 @@ function post(path_1, body_1) {
                     headers = _a.sent();
                     _a.label = 2;
                 case 2:
-                    _a.trys.push([2, 4, , 5]);
-                    return [4 /*yield*/, got_1.default.post(getUrl(path, opts.qs), __assign(__assign({}, gotOpts), { body: body, headers: headers }))];
+                    _a.trys.push([2, 7, , 8]);
+                    isRawString = typeof body === "string";
+                    if (!isRawString) return [3 /*break*/, 4];
+                    return [4 /*yield*/, got_1.default.post(getUrl(path, opts.qs), {
+                            throwHttpErrors: false,
+                            retry: 0,
+                            followRedirect: false,
+                            body: body,
+                            headers: __assign(__assign({}, headers), { "Content-Type": "application/json" }),
+                        })];
                 case 3:
+                    res = _a.sent();
+                    return [2 /*return*/, __assign({ status: res.statusCode }, JSON.parse(res.body || "{}"))];
+                case 4: return [4 /*yield*/, got_1.default.post(getUrl(path, opts.qs), __assign(__assign({}, gotOpts), { body: body, headers: headers }))];
+                case 5:
                     res = _a.sent();
                     return [2 /*return*/, __assign({ status: res.statusCode }, res.body)];
-                case 4:
+                case 6: return [3 /*break*/, 8];
+                case 7:
                     err_1 = _a.sent();
                     console.error(err_1);
                     throw err_1;
-                case 5: return [2 /*return*/];
+                case 8: return [2 /*return*/];
             }
         });
     });

package/package.json

@@ -1,10 +1,10 @@
 {
     "name": "@flink-app/test-utils",
-    "version": "0.12.1-alpha.4",
+    "version": "0.12.1-alpha.40",
     "description": "Test utils for Flink",
     "scripts": {
         "test": "echo \"Error: no test specified\"",
-        "prepublish": "tsc",
+        "prepare": "tsc",
         "build": "tsc",
         "watch": "tsc-watch"
     },
@@ -20,7 +20,7 @@
         "qs": "^6.7.0"
     },
     "devDependencies": {
-        "@flink-app/flink": "^0.12.1-alpha.4",
+        "@flink-app/flink": "^0.12.1-alpha.40",
         "@types/express": "^4.17.12",
         "@types/got": "^9.6.12",
         "@types/node": "22.13.10",
@@ -30,5 +30,5 @@
         "tsc-watch": "^4.2.9",
         "typescript": "5.4.5"
     },
-    "gitHead": "8f06a4ab98e7179322d36546756d4305fd196f5a"
+    "gitHead": "456502f273fe9473df05b71a803f3eda1a2f8931"
 }

package/readme.md

@@ -1,13 +1,562 @@
-# Flink test utils
+# @flink-app/test-utils
 
-A helper library to simplify writing tests for a Flink app.
+A comprehensive testing utility library for Flink applications. This package provides helper functions and mocks to simplify writing tests for your Flink handlers, repositories, and plugins.
+
+## Features
+
+- HTTP testing utilities with automatic JSON handling
+- Mock request objects for unit testing handlers
+- No-op authentication plugin for testing
+- Type-safe test helpers
+- Support for query strings, headers, and authentication
+- Integration testing support
+- Works with Jasmine, Jest, and other testing frameworks
 
 ## Installation
 
-Install plugin to your flink app project:
+```bash
+npm install --save-dev @flink-app/test-utils
+```
+
+## HTTP Testing Utilities
+
+The HTTP utilities allow you to make test requests to your running Flink app without needing external HTTP clients in most cases.
+
+### Setup
+
+Initialize the test utilities with your Flink app instance:
+
+```typescript
+import { FlinkApp } from "@flink-app/flink";
+import * as http from "@flink-app/test-utils";
+
+describe("My API", () => {
+  let app: FlinkApp<AppContext>;
+
+  beforeAll(async () => {
+    app = new FlinkApp<AppContext>({
+      name: "Test App",
+      port: 3001,
+      // ... your configuration
+    });
+    await app.start();
 
+    // Initialize test utilities
+    http.init(app);
+  });
+
+  afterAll(async () => {
+    await app.stop();
+  });
+
+  // Your tests here
+});
 ```
-npm i -D @flink-app/test-utils
+
+### GET Requests
+
+```typescript
+import { get } from "@flink-app/test-utils";
+
+it("should get all items", async () => {
+  const response = await get("/items");
+
+  expect(response.status).toBe(200);
+  expect(response.data).toBeDefined();
+  expect(response.data.items).toBeInstanceOf(Array);
+});
 ```
 
-Read docs for more details.
+### POST Requests
+
+```typescript
+import { post } from "@flink-app/test-utils";
+
+it("should create a new item", async () => {
+  const newItem = {
+    name: "Test Item",
+    description: "A test item",
+  };
+
+  const response = await post("/items", newItem);
+
+  expect(response.status).toBe(200);
+  expect(response.data.item._id).toBeDefined();
+  expect(response.data.item.name).toBe("Test Item");
+});
+```
+
+### PUT Requests
+
+```typescript
+import { put } from "@flink-app/test-utils";
+
+it("should update an item", async () => {
+  const updates = {
+    name: "Updated Name",
+  };
+
+  const response = await put("/items/123", updates);
+
+  expect(response.status).toBe(200);
+  expect(response.data.item.name).toBe("Updated Name");
+});
+```
+
+### DELETE Requests
+
+```typescript
+import { del } from "@flink-app/test-utils";
+
+it("should delete an item", async () => {
+  const response = await del("/items/123");
+
+  expect(response.status).toBe(200);
+  expect(response.success).toBe(true);
+});
+```
+
+## Request Options
+
+All HTTP methods support an optional options object:
+
+### Query String Parameters
+
+```typescript
+const response = await get("/items", {
+  qs: {
+    limit: "10",
+    offset: "0",
+    category: "electronics",
+  },
+});
+// Requests: /items?limit=10&offset=0&category=electronics
+```
+
+### Custom Headers
+
+```typescript
+const response = await post("/items", newItem, {
+  headers: {
+    "X-Custom-Header": "value",
+    "X-Request-ID": "12345",
+  },
+});
+```
+
+### Authentication
+
+The test utilities support automatic authentication using the app's auth plugin:
+
+```typescript
+const user = {
+  _id: "user123",
+  username: "testuser",
+  roles: ["admin"],
+};
+
+const response = await get("/admin/users", {
+  user: user,
+});
+// Automatically adds: Authorization: Bearer <token>
+```
+
+### Combining Options
+
+```typescript
+const response = await post(
+  "/items",
+  { name: "New Item" },
+  {
+    qs: { draft: "true" },
+    headers: { "X-Request-ID": "123" },
+    user: currentUser,
+  }
+);
+```
+
+## Mock Request Objects
+
+For unit testing handlers without a running server:
+
+### mockReq
+
+Create a mock FlinkRequest object:
+
+```typescript
+import { mockReq } from "@flink-app/test-utils";
+
+it("should handle request correctly", async () => {
+  const req = mockReq({
+    body: { name: "Test" },
+    params: { id: "123" },
+    query: { include: "details" },
+    headers: { "content-type": "application/json" },
+  });
+
+  const result = await myHandler(req, ctx);
+
+  expect(result.status).toBe(200);
+});
+```
+
+### Mock Request Properties
+
+```typescript
+const req = mockReq<RequestBody, Params, Query>({
+  body: { name: "Test" },      // Request body
+  params: { id: "123" },        // URL parameters
+  query: { page: "1" },         // Query string
+  headers: {                    // HTTP headers
+    "content-type": "application/json",
+    "authorization": "Bearer token",
+  },
+});
+
+// Mock request automatically provides:
+// - req.get(headerName) method
+// - JSON serialization of body/params
+// - Default empty objects for omitted properties
+```
+
+## Authentication Mocking
+
+### noOpAuthPlugin
+
+A no-op authentication plugin that allows all requests:
+
+```typescript
+import { noOpAuthPlugin } from "@flink-app/test-utils";
+
+const app = new FlinkApp<AppContext>({
+  name: "Test App",
+  port: 3001,
+  plugins: [],
+});
+
+// Set the no-op auth plugin for testing
+app.auth = noOpAuthPlugin();
+
+await app.start();
+```
+
+This plugin:
+- Always authenticates successfully
+- Returns a mock token: `"mock-token"`
+- Useful for testing handlers without setting up real authentication
+
+## Complete Testing Example
+
+```typescript
+import { FlinkApp } from "@flink-app/flink";
+import * as http from "@flink-app/test-utils";
+import { mockReq, noOpAuthPlugin } from "@flink-app/test-utils";
+
+describe("Todo API", () => {
+  let app: FlinkApp<AppContext>;
+
+  beforeAll(async () => {
+    app = new FlinkApp<AppContext>({
+      name: "Test App",
+      port: 3001,
+      mongo: {
+        url: "mongodb://localhost:27017/test",
+      },
+    });
+
+    app.auth = noOpAuthPlugin();
+    await app.start();
+    http.init(app);
+  });
+
+  afterAll(async () => {
+    await app.stop();
+  });
+
+  describe("GET /todos", () => {
+    it("should return all todos", async () => {
+      const response = await http.get("/todos");
+
+      expect(response.status).toBe(200);
+      expect(response.data.todos).toBeInstanceOf(Array);
+    });
+
+    it("should filter todos by status", async () => {
+      const response = await http.get("/todos", {
+        qs: { status: "completed" },
+      });
+
+      expect(response.status).toBe(200);
+      expect(response.data.todos.every((t) => t.status === "completed")).toBe(true);
+    });
+  });
+
+  describe("POST /todos", () => {
+    it("should create a new todo", async () => {
+      const newTodo = {
+        title: "Test Todo",
+        description: "Test Description",
+      };
+
+      const response = await http.post("/todos", newTodo);
+
+      expect(response.status).toBe(200);
+      expect(response.data.todo._id).toBeDefined();
+      expect(response.data.todo.title).toBe("Test Todo");
+    });
+
+    it("should require authentication", async () => {
+      const response = await http.post("/todos", {
+        title: "Test",
+      });
+
+      // With noOpAuthPlugin, this would pass
+      // With real auth, this would return 401
+      expect(response.status).toBe(200);
+    });
+
+    it("should validate required fields", async () => {
+      const response = await http.post("/todos", {});
+
+      expect(response.status).toBe(400);
+      expect(response.error).toBe("validation_error");
+    });
+  });
+
+  describe("PUT /todos/:id", () => {
+    let todoId: string;
+
+    beforeEach(async () => {
+      const created = await http.post("/todos", {
+        title: "Todo to Update",
+      });
+      todoId = created.data.todo._id;
+    });
+
+    it("should update a todo", async () => {
+      const response = await http.put(`/todos/${todoId}`, {
+        title: "Updated Title",
+        status: "completed",
+      });
+
+      expect(response.status).toBe(200);
+      expect(response.data.todo.title).toBe("Updated Title");
+    });
+  });
+
+  describe("DELETE /todos/:id", () => {
+    it("should delete a todo", async () => {
+      const created = await http.post("/todos", {
+        title: "Todo to Delete",
+      });
+
+      const response = await http.del(`/todos/${created.data.todo._id}`);
+
+      expect(response.status).toBe(200);
+      expect(response.success).toBe(true);
+    });
+  });
+});
+```
+
+## Unit Testing Handlers
+
+Test individual handlers without a running server:
+
+```typescript
+import { mockReq } from "@flink-app/test-utils";
+import GetTodoById from "./handlers/GetTodoById";
+
+describe("GetTodoById Handler", () => {
+  let mockContext: AppContext;
+
+  beforeEach(() => {
+    mockContext = {
+      repos: {
+        todoRepo: {
+          findById: jasmine.createSpy("findById"),
+        },
+      },
+    } as any;
+  });
+
+  it("should return todo when found", async () => {
+    const mockTodo = {
+      _id: "123",
+      title: "Test Todo",
+      status: "active",
+    };
+
+    (mockContext.repos.todoRepo.findById as any).and.returnValue(
+      Promise.resolve(mockTodo)
+    );
+
+    const req = mockReq({
+      params: { id: "123" },
+    });
+
+    const result = await GetTodoById(req, mockContext);
+
+    expect(result.status).toBe(200);
+    expect(result.data.todo).toEqual(mockTodo);
+    expect(mockContext.repos.todoRepo.findById).toHaveBeenCalledWith("123");
+  });
+
+  it("should return 404 when not found", async () => {
+    (mockContext.repos.todoRepo.findById as any).and.returnValue(
+      Promise.resolve(null)
+    );
+
+    const req = mockReq({
+      params: { id: "999" },
+    });
+
+    const result = await GetTodoById(req, mockContext);
+
+    expect(result.status).toBe(404);
+    expect(result.error).toBe("not_found");
+  });
+});
+```
+
+## Response Type
+
+All HTTP methods return a `FlinkResponse` object:
+
+```typescript
+interface FlinkResponse<T> {
+  status: number;           // HTTP status code
+  success?: boolean;        // Success flag (if present in response)
+  data?: T;                // Response data (if present)
+  error?: string;          // Error code (if error occurred)
+  message?: string;        // Error message (if error occurred)
+  // ... any other fields from the response
+}
+```
+
+## TypeScript Support
+
+The test utilities are fully typed:
+
+```typescript
+interface CreateTodoRequest {
+  title: string;
+  description?: string;
+}
+
+interface CreateTodoResponse {
+  todo: {
+    _id: string;
+    title: string;
+    description?: string;
+    createdAt: string;
+  };
+}
+
+const response = await post<CreateTodoRequest, CreateTodoResponse>(
+  "/todos",
+  { title: "New Todo" }
+);
+
+// response.data is typed as CreateTodoResponse
+expect(response.data?.todo._id).toBeDefined();
+```
+
+## Best Practices
+
+1. **Initialize once**: Call `http.init(app)` once in `beforeAll`, not before each test
+2. **Clean up**: Always call `app.stop()` in `afterAll`
+3. **Use separate database**: Use a test database, not your production database
+4. **Reset data**: Clear test data between tests if needed
+5. **Mock external services**: Use mocks for external API calls
+6. **Test error cases**: Don't just test happy paths
+7. **Use authentication**: Test both authenticated and unauthenticated scenarios
+
+## Working with Different Test Frameworks
+
+### Jasmine
+
+```typescript
+describe("My tests", () => {
+  let app: FlinkApp<AppContext>;
+
+  beforeAll(async () => {
+    app = createTestApp();
+    await app.start();
+    http.init(app);
+  });
+
+  afterAll(async () => {
+    await app.stop();
+  });
+
+  it("should work", async () => {
+    const response = await http.get("/endpoint");
+    expect(response.status).toBe(200);
+  });
+});
+```
+
+### Jest
+
+```typescript
+describe("My tests", () => {
+  let app: FlinkApp<AppContext>;
+
+  beforeAll(async () => {
+    app = createTestApp();
+    await app.start();
+    http.init(app);
+  });
+
+  afterAll(async () => {
+    await app.stop();
+  });
+
+  test("should work", async () => {
+    const response = await http.get("/endpoint");
+    expect(response.status).toBe(200);
+  });
+});
+```
+
+## Troubleshooting
+
+### Port Already in Use
+
+Use a different port for testing:
+
+```typescript
+const app = new FlinkApp<AppContext>({
+  port: 3001, // Different from dev/prod port
+  // ...
+});
+```
+
+### Tests Hanging
+
+Make sure to call `app.stop()` in `afterAll`:
+
+```typescript
+afterAll(async () => {
+  await app.stop();
+});
+```
+
+### Authentication Errors
+
+Use `noOpAuthPlugin()` for testing or provide valid user objects:
+
+```typescript
+app.auth = noOpAuthPlugin();
+
+// OR
+
+const response = await http.get("/endpoint", {
+  user: { _id: "123", roles: ["admin"] },
+});
+```
+
+## License
+
+MIT

package/src/http.ts

@@ -9,6 +9,7 @@ const gotOpts: GotJSONOptions = {
     throwHttpErrors: false,
     json: true,
     retry: 0,
+    followRedirect: false,
 };
 
 export type HttpOpts = {
@@ -59,16 +60,41 @@ export async function post<Req = any, Res = any>(path: string, body: Req, opts:
     const headers = await setAuthHeader(opts.user, opts.headers);
 
     try {
-        const res = await got.post(getUrl(path, opts.qs), {
-            ...gotOpts,
-            body: body as any,
-            headers,
-        });
-
-        return {
-            status: res.statusCode,
-            ...res.body,
-        };
+        // If body is a string, send it as raw body without JSON encoding
+        // This is needed for webhook signature validation where the signature
+        // is computed on the raw JSON string
+        const isRawString = typeof body === "string";
+
+        if (isRawString) {
+            // Send raw string body
+            const res = await got.post(getUrl(path, opts.qs), {
+                throwHttpErrors: false,
+                retry: 0,
+                followRedirect: false,
+                body: body as any,
+                headers: {
+                    ...headers,
+                    "Content-Type": "application/json",
+                },
+            });
+
+            return {
+                status: res.statusCode,
+                ...JSON.parse((res.body as any) || "{}"),
+            };
+        } else {
+            // Send JSON body
+            const res = await got.post(getUrl(path, opts.qs), {
+                ...gotOpts,
+                body: body as any,
+                headers,
+            });
+
+            return {
+                status: res.statusCode,
+                ...res.body,
+            };
+        }
     } catch (err) {
         console.error(err);
         throw err;