@skuba-lib/vitest-koa-mocks 0.0.0 → 1.0.0-node-24-20251210005321

package/LICENSE

@@ -0,0 +1,22 @@
+### MIT License
+
+Copyright (c) 2018-present Shopify
+Copyright (c) 2020 SEEK
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,97 @@
+# @skuba-lib/vitest-koa-mocks
+
+[![npm package](https://img.shields.io/npm/v/@skuba-lib/vitest-koa-mocks?labelColor=cb0000&color=5b5b5b)](https://www.npmjs.com/package/@skuba-lib/vitest-koa-mocks)
+[![Node.js version](https://img.shields.io/node/v/@skuba-lib/vitest-koa-mocks?labelColor=5fa04e&color=5b5b5b)](https://www.npmjs.com/package/@skuba-lib/vitest-koa-mocks)
+
+Vitest-compatible Koa mocks for testing Koa middleware and applications.
+
+Inspired by [Shopify's jest-koa-mocks](https://github.com/Shopify/quilt/tree/main/packages/jest-koa-mocks), this package provides utilities that do not rely on Jest globals and are suitable for ESM-based Vitest setups.
+
+## API reference
+
+### `createMockContext`
+
+Create a fully-typed mock [`Koa` `Context`](https://koajs.com) for testing middleware and request handlers.
+
+```typescript
+describe('createServiceAuthClient', () => {
+  const serviceAuthClient = createServiceAuthClient({
+    audience: 'upstream-service',
+    baseUrl,
+  });
+
+  it('attaches expected headers', async () => {
+    nock(baseUrl)
+      .get('/mocked')
+      // ensures authorization is passed through
+      .matchHeader('authorization', MOCK_SERVICE_AUTH_HEADER)
+      // ensures data tags are passed through
+      .matchHeader('seek-tag-record-expiry', '0000-01-01T00:00:00.000Z')
+      .matchHeader('seek-tag-test-record', 'true')
+      // ensures tracing headers are passed through
+      .matchHeader('x-request-id', 'abc')
+      .matchHeader('x-session-id', 'cba')
+      .reply(200);
+
+    const ctx = createMockContext({
+      headers: {
+        'seek-tag-record-expiry': '0000-01-01T00:00:00.000Z',
+        'seek-tag-test-record': 'true',
+        'x-request-id': 'abc',
+        'x-seek-jwt-issuer': 'requesting-service',
+        'x-session-id': 'cba',
+      },
+    });
+
+    contextStorage.enterWith(ctx);
+
+    await Middleware.seekTagMiddleware(
+      { ...ctx, headers: { ...ctx.headers } },
+      () =>
+        serviceAuthClient.request({
+          url: '/mocked',
+        }),
+    );
+  });
+});
+```
+
+`createMockContext` accepts an options object that lets you control:
+
+- HTTP details such as **`method`**, **`url`**, **`statusCode`**, **`headers`**, **`host`**, and whether the request is **`encrypted`**
+- Koa-specific behaviour such as **`state`**, **`session`**, **`cookies`**, and **`throw`** / **`redirect`** handlers
+- arbitrary **`customProperties`** that are merged onto the returned context
+
+The returned context type is `MockContext`, which extends Koa's `Context` with:
+
+- a `cookies` implementation compatible with `MockCookies`
+- a `request` that can include `body`, `rawBody`, and `session` metadata
+
+### `createMockCookies`
+
+Create a standalone mock cookies implementation for Koa-style code.
+
+```typescript
+import { createMockCookies } from '@skuba-lib/vitest-koa-mocks';
+import { expect, it } from 'vitest';
+
+it('tracks request and response cookies', () => {
+  const cookies = createMockCookies({ session: 'abc' });
+
+  expect(cookies.get('session')).toBe('abc');
+
+  cookies.set('session', 'def');
+
+  // requestStore reflects initial inbound cookies
+  expect(cookies.requestStore.get('session')).toBe('abc');
+
+  // responseStore reflects cookies set during the test
+  expect(cookies.responseStore.get('session')).toBe('def');
+});
+```
+
+`createMockCookies` returns a `MockCookies` instance that:
+
+- exposes `get` and `set` methods implemented with Vitest spies (`vi.fn`)
+- maintains separate `requestStore` and `responseStore` `Map` instances for assertions
+- supports a `secure` flag to simulate HTTPS behaviour

package/lib/createMockContext/createMockContext.d.ts

@@ -0,0 +1,29 @@
+import { type Context } from 'koa';
+import { type RequestMethod } from 'node-mocks-http';
+import { vi } from 'vitest';
+import { type MockCookies } from '../createMockCookies/createMockCookies.js';
+export interface MockContext extends Context {
+    cookies: MockCookies;
+    request: Context['request'] & {
+        body?: unknown;
+        rawBody?: string;
+        session?: Record<string, unknown>;
+    };
+}
+export interface Options<CustomProperties extends object, RequestBody = undefined> {
+    url?: string;
+    method?: RequestMethod;
+    statusCode?: number;
+    session?: Record<string, unknown>;
+    headers?: Record<string, string>;
+    cookies?: Record<string, string>;
+    state?: Record<string, unknown>;
+    encrypted?: boolean;
+    host?: string;
+    requestBody?: RequestBody;
+    rawBody?: string;
+    throw?: ((status: number, message?: string) => never) | ReturnType<typeof vi.fn>;
+    redirect?: ((url: string) => void) | ReturnType<typeof vi.fn>;
+    customProperties?: CustomProperties;
+}
+export declare const createMockContext: <CustomProperties extends object, RequestBody = undefined>(options?: Options<CustomProperties, RequestBody>) => MockContext;

package/lib/createMockContext/createMockContext.js

@@ -0,0 +1,47 @@
+import stream from 'stream';
+import Koa from 'koa';
+import httpMocks from 'node-mocks-http';
+import { vi } from 'vitest';
+import { createMockCookies, } from '../createMockCookies/createMockCookies.js';
+export const createMockContext = (options = {}) => {
+    const app = new Koa();
+    const { cookies, method, statusCode, session, requestBody, rawBody = '', url = '/', host = 'test.com', encrypted = false, throw: throwFn = vi.fn(), redirect = vi.fn(), headers = {}, state = {}, customProperties = {}, } = options;
+    const extensions = {
+        ...customProperties,
+        throw: throwFn,
+        session,
+        redirect,
+        state,
+    };
+    const protocol = encrypted ? 'https' : 'http';
+    const requestHeaders = {
+        Host: host,
+        ...headers,
+    };
+    const hasOriginHeader = 'Origin' in requestHeaders || 'origin' in requestHeaders;
+    if (!hasOriginHeader) {
+        requestHeaders.Origin = `${protocol}://${host}`;
+    }
+    const req = httpMocks.createRequest({
+        url,
+        method,
+        statusCode,
+        session,
+        headers: requestHeaders,
+    });
+    req.socket = new stream.Duplex();
+    Object.defineProperty(req.socket, 'encrypted', {
+        writable: false,
+        value: encrypted,
+    });
+    const res = httpMocks.createResponse();
+    res.statusCode = 404;
+    res.set = undefined;
+    const context = app.createContext(req, res);
+    Object.assign(context, extensions);
+    context.cookies = createMockCookies(cookies);
+    context.request.body = requestBody;
+    context.request.rawBody = rawBody;
+    return context;
+};
+//# sourceMappingURL=createMockContext.js.map

package/lib/createMockContext/createMockContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createMockContext.js","sourceRoot":"","sources":["../../src/createMockContext/createMockContext.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAC;AAE5B,OAAO,GAAqB,MAAM,KAAK,CAAC;AACxC,OAAO,SAAiC,MAAM,iBAAiB,CAAC;AAChE,OAAO,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAE5B,OAAO,EAEL,iBAAiB,GAClB,MAAM,2CAA2C,CAAC;AAiCnD,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAI/B,UAAkD,EAAE,EACpD,EAAE;IACF,MAAM,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC;IAEtB,MAAM,EACJ,OAAO,EACP,MAAM,EACN,UAAU,EACV,OAAO,EACP,WAAW,EACX,OAAO,GAAG,EAAE,EACZ,GAAG,GAAG,GAAG,EACT,IAAI,GAAG,UAAU,EACjB,SAAS,GAAG,KAAK,EACjB,KAAK,EAAE,OAAO,GAAG,EAAE,CAAC,EAAE,EAAE,EACxB,QAAQ,GAAG,EAAE,CAAC,EAAE,EAAE,EAClB,OAAO,GAAG,EAAE,EACZ,KAAK,GAAG,EAAE,EACV,gBAAgB,GAAG,EAAE,GACtB,GAAG,OAAO,CAAC;IAEZ,MAAM,UAAU,GAAG;QACjB,GAAG,gBAAgB;QACnB,KAAK,EAAE,OAAO;QACd,OAAO;QACP,QAAQ;QACR,KAAK;KACN,CAAC;IAIF,MAAM,QAAQ,GAAG,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC;IAC9C,MAAM,cAAc,GAA2B;QAE7C,IAAI,EAAE,IAAI;QACV,GAAG,OAAO;KACX,CAAC;IAGF,MAAM,eAAe,GACnB,QAAQ,IAAI,cAAc,IAAI,QAAQ,IAAI,cAAc,CAAC;IAC3D,IAAI,CAAC,eAAe,EAAE,CAAC;QACrB,cAAc,CAAC,MAAM,GAAG,GAAG,QAAQ,MAAM,IAAI,EAAE,CAAC;IAClD,CAAC;IAED,MAAM,GAAG,GAAG,SAAS,CAAC,aAAa,CAAC;QAClC,GAAG;QACH,MAAM;QACN,UAAU;QACV,OAAO;QACP,OAAO,EAAE,cAAc;KACxB,CAAC,CAAC;IAKH,GAAG,CAAC,MAAM,GAAG,IAAI,MAAM,CAAC,MAAM,EAAS,CAAC;IACxC,MAAM,CAAC,cAAc,CAAC,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE;QAC7C,QAAQ,EAAE,KAAK;QACf,KAAK,EAAE,SAAS;KACjB,CAAC,CAAC;IAEH,MAAM,GAAG,GAAG,SAAS,CAAC,cAAc,EAAE,CAAC;IAIvC,GAAG,CAAC,UAAU,GAAG,GAAG,CAAC;IAKrB,GAAG,CAAC,GAAG,GAAG,SAAgB,CAAC;IAG3B,MAAM,OAAO,GAAG,GAAG,CAAC,aAAa,CAAC,GAAG,EAAE,GAAU,CAC/B,CAAC;IACnB,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IACnC,OAAO,CAAC,OAAO,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAC;IAG7C,OAAO,CAAC,OAAO,CAAC,IAAI,GAAG,WAAW,CAAC;IACnC,OAAO,CAAC,OAAO,CAAC,OAAO,GAAG,OAAO,CAAC;IAElC,OAAO,OAAsB,CAAC;AAChC,CAAC,CAAC"}

package/lib/createMockCookies/createMockCookies.d.ts

@@ -0,0 +1,7 @@
+import type { Context } from 'koa';
+export type Cookies = Context['cookies'];
+export interface MockCookies extends Cookies {
+    requestStore: Map<string, string>;
+    responseStore: Map<string, string>;
+}
+export declare const createMockCookies: (cookies?: Record<string, string>, secure?: boolean) => MockCookies;

package/lib/createMockCookies/createMockCookies.js

@@ -0,0 +1,14 @@
+import { vi } from 'vitest';
+export const createMockCookies = (cookies = {}, secure = true) => {
+    const cookieEntries = Object.keys(cookies).map((key) => [key, cookies[key]]);
+    const requestStore = new Map(cookieEntries);
+    const responseStore = new Map(cookieEntries);
+    return {
+        set: vi.fn((key, value) => responseStore.set(key, value)),
+        get: vi.fn((key) => requestStore.get(key)),
+        requestStore,
+        responseStore,
+        secure,
+    };
+};
+//# sourceMappingURL=createMockCookies.js.map

package/lib/createMockCookies/createMockCookies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createMockCookies.js","sourceRoot":"","sources":["../../src/createMockCookies/createMockCookies.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAS5B,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAC/B,UAAkC,EAAE,EACpC,MAAM,GAAG,IAAI,EACA,EAAE;IACf,MAAM,aAAa,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,GAAG,CAC5C,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,CAAqB,CACjD,CAAC;IAEF,MAAM,YAAY,GAAG,IAAI,GAAG,CAAiB,aAAa,CAAC,CAAC;IAC5D,MAAM,aAAa,GAAG,IAAI,GAAG,CAAiB,aAAa,CAAC,CAAC;IAE7D,OAAO;QACL,GAAG,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,GAAW,EAAE,KAAa,EAAE,EAAE,CAAC,aAAa,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACzE,GAAG,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,GAAW,EAAE,EAAE,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAClD,YAAY;QACZ,aAAa;QACb,MAAM;KACmB,CAAC;AAC9B,CAAC,CAAC"}

package/lib/index.d.ts

@@ -0,0 +1,2 @@
+export * from './createMockContext/createMockContext.js';
+export * from './createMockCookies/createMockCookies.js';

package/lib/index.js

@@ -0,0 +1,3 @@
+export * from './createMockContext/createMockContext.js';
+export * from './createMockCookies/createMockCookies.js';
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,0CAA0C,CAAC;AACzD,cAAc,0CAA0C,CAAC"}

package/package.json

@@ -1,11 +1,51 @@
 {
   "name": "@skuba-lib/vitest-koa-mocks",
-  "version": "0.0.0",
-  "description": "",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+  "version": "1.0.0-node-24-20251210005321",
+  "private": false,
+  "description": "Vitest mocks for Koa",
+  "homepage": "https://github.com/seek-oss/skuba/tree/main/packages/vitest-koa-mocks#readme",
+  "bugs": {
+    "url": "https://github.com/seek-oss/skuba/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/seek-oss/skuba.git",
+    "directory": "packages/vitest-koa-mocks"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "./lib/index.js",
+  "module": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "files": [
+    "lib/**/*.d.ts",
+    "lib/**/*.js",
+    "lib/**/*.js.map"
+  ],
+  "dependencies": {
+    "node-mocks-http": "^1.17.2"
+  },
+  "peerDependencies": {
+    "@types/koa": "^3.0.1",
+    "koa": "^3.1.1",
+    "vitest": "^4.0.14"
   },
-  "author": "",
-  "license": "ISC"
-}
+  "engines": {
+    "node": ">=20.9.0"
+  },
+  "skuba": {
+    "entryPoint": "src/index.ts",
+    "template": "oss-npm-package",
+    "type": "package",
+    "version": "13.0.0"
+  },
+  "scripts": {
+    "build": "pnpm skuba build",
+    "format": "pnpm skuba format",
+    "lint": "pnpm skuba lint",
+    "skuba": "node ../../lib/skuba",
+    "test": "vitest run",
+    "test:ci": "vitest run --coverage",
+    "test:watch": "vitest"
+  }
+}