@flink-app/test-utils 0.12.1-alpha.7 → 0.13.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @flink-app/test-utils
+
+## 0.13.0
+
+### Minor Changes
+
+-   Migrate to pnpm and streamlines build process.

package/dist/http.js

@@ -20,8 +20,8 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 var __generator = (this && this.__generator) || function (thisArg, body) {
-    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
-    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
     function verb(n) { return function (v) { return step([n, v]); }; }
     function step(op) {
         if (f) throw new TypeError("Generator is already executing.");
@@ -50,7 +50,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.del = exports.put = exports.post = exports.get = exports.init = void 0;
+exports.init = init;
+exports.get = get;
+exports.post = post;
+exports.put = put;
+exports.del = del;
 var got_1 = __importDefault(require("got"));
 var qs_1 = __importDefault(require("qs"));
 var app;
@@ -59,6 +63,7 @@ var gotOpts = {
     throwHttpErrors: false,
     json: true,
     retry: 0,
+    followRedirect: false,
 };
 /**
  * Initializes test flink app.
@@ -69,7 +74,6 @@ function init(_app, host) {
     app = _app;
     baseUrl = "http://".concat(host, ":").concat(app.port);
 }
-exports.init = init;
 function get(path_1) {
     return __awaiter(this, arguments, void 0, function (path, opts) {
         var headers, res;
@@ -89,10 +93,9 @@ 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,21 +106,33 @@ 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*/];
             }
         });
     });
 }
-exports.post = post;
 function put(path_1, body_1) {
     return __awaiter(this, arguments, void 0, function (path, body, opts) {
         var headers, res;
@@ -137,7 +152,6 @@ function put(path_1, body_1) {
         });
     });
 }
-exports.put = put;
 function del(path_1) {
     return __awaiter(this, arguments, void 0, function (path, opts) {
         var headers, res;
@@ -157,7 +171,6 @@ function del(path_1) {
         });
     });
 }
-exports.del = del;
 function validateApp() {
     if (!app) {
         throw new Error("App not initialized, run `init(app)` prior to invoking get/post/put/del");

package/dist/mocks.js

@@ -20,8 +20,8 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 var __generator = (this && this.__generator) || function (thisArg, body) {
-    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
-    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
     function verb(n) { return function (v) { return step([n, v]); }; }
     function step(op) {
         if (f) throw new TypeError("Generator is already executing.");
@@ -47,7 +47,8 @@ var __generator = (this && this.__generator) || function (thisArg, body) {
     }
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.noOpAuthPlugin = exports.mockReq = void 0;
+exports.mockReq = mockReq;
+exports.noOpAuthPlugin = noOpAuthPlugin;
 /**
  * Creates a mocked FlinkRequest object where only essential properties are required.
  * Will convert req body to JSON to ensure the body is a plain object.
@@ -64,7 +65,6 @@ function mockReq(req) {
     req.params = req.params ? JSON.parse(JSON.stringify(req.params)) : {};
     return aMockReq;
 }
-exports.mockReq = mockReq;
 /**
  * Auth plugin used for testing handlers.
  * Will allow all requests.
@@ -81,4 +81,3 @@ function noOpAuthPlugin() {
         }); }); },
     };
 }
-exports.noOpAuthPlugin = noOpAuthPlugin;

package/package.json

@@ -1,34 +1,31 @@
 {
-    "name": "@flink-app/test-utils",
-    "version": "0.12.1-alpha.7",
-    "description": "Test utils for Flink",
-    "scripts": {
-        "test": "echo \"Error: no test specified\"",
-        "prepublish": "tsc",
-        "build": "tsc",
-        "watch": "tsc-watch"
-    },
-    "author": "joel@frost.se",
-    "license": "MIT",
-    "types": "dist/index.d.ts",
-    "main": "dist/index.js",
-    "publishConfig": {
-        "access": "public"
-    },
-    "dependencies": {
-        "got": "^9.6.0",
-        "qs": "^6.7.0"
-    },
-    "devDependencies": {
-        "@flink-app/flink": "^0.12.1-alpha.7",
-        "@types/express": "^4.17.12",
-        "@types/got": "^9.6.12",
-        "@types/node": "22.13.10",
-        "jasmine-spec-reporter": "^7.0.0",
-        "nodemon": "^2.0.7",
-        "ts-node": "^9.1.1",
-        "tsc-watch": "^4.2.9",
-        "typescript": "5.4.5"
-    },
-    "gitHead": "cd86dec5f9b3bf23c01374a729bb02d8a48c2869"
-}
+  "name": "@flink-app/test-utils",
+  "version": "0.13.0",
+  "description": "Test utils for Flink",
+  "author": "joel@frost.se",
+  "license": "MIT",
+  "types": "dist/index.d.ts",
+  "main": "dist/index.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "got": "^9.6.0",
+    "qs": "^6.7.0"
+  },
+  "devDependencies": {
+    "@types/got": "^9.6.12",
+    "@types/node": "22.13.10",
+    "@types/qs": "^6.9.7",
+    "ts-node": "^10.9.2",
+    "tsc-watch": "^4.2.9",
+    "@flink-app/flink": "0.13.0"
+  },
+  "gitHead": "4243e3b3cd6d4e1ca001a61baa8436bf2bbe4113",
+  "scripts": {
+    "test": "echo \"Error: no test specified\"",
+    "build": "tsc",
+    "watch": "tsc-watch",
+    "clean": "rimraf dist .flink"
+  }
+}

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;

package/tsconfig.json

@@ -15,7 +15,7 @@
     "noEmit": false,
     "declaration": true,
     "experimentalDecorators": true,
-    "checkJs": true,
+    "checkJs": false,
     "outDir": "dist"
   },
   "include": ["./src/**/*.ts", "./.flink/**/*.ts"],