@jaypie/testkit 1.0.19 → 1.0.21

package/README.md

@@ -12,21 +12,33 @@ npm install --save-dev @jaypie/testkit
 
 ### Example
 
+#### Mocking Jaypie
+
+The testkit provides a complete mock for Jaypie including:
+
+* Log spying (`expect(log.warn).toHaveBeenCalled()`)
+* Default responses for runtime-only functions (`connect`, `sendMessage`, `submitMetric`)
+* No automatic error handling for handlers (which is good in production but obfuscates tests)
+* Most non-utility functions are mocked to allow simple testing
+
+```javascript
+vi.mock("jaypie", vi.importActual("@jaypie/testkit"));
+```
+
 #### Log Spying
 
 ```javascript
-import { restoreLog, spyLog } from "@jaypie/testkit";
-import { log } from "@jaypie/core";
+import { log } from "jaypie";
+
+vi.mock("jaypie", vi.importActual("@jaypie/testkit"));
 
-beforeEach(() => {
-  spyLog(log);
-});
 afterEach(() => {
-  restoreLog(log);
   vi.clearAllMocks();
 });
 
 test("log", () => {
+  expect(vi.isMockFunction(log.warn)).toBe(true);
+  expect(log.warn).not.toHaveBeenCalled();
   log.warn("Danger");
   expect(log.warn).toHaveBeenCalled();
   expect(log.error).not.toHaveBeenCalled();
@@ -117,6 +129,30 @@ A [JSON Schema](https://json-schema.org/) validator for the [JSON:API](https://j
 
 ### `matchers`
 
+```javascript
+export default {
+  toBeCalledWithInitialParams,
+  toBeClass,
+  toBeJaypieError,
+  toBeValidSchema: jsonSchemaMatchers.toBeValidSchema,
+  toMatchBase64,
+  toMatchJwt,
+  toMatchMongoId,
+  toMatchSchema: jsonSchemaMatchers.toMatchSchema,
+  toMatchSignedCookie,
+  toMatchUuid4,
+  toMatchUuid5,
+  toMatchUuid,
+  toThrowBadRequestError,
+  toThrowConfigurationError,
+  toThrowForbiddenError,
+  toThrowInternalError,
+  toThrowJaypieError,
+  toThrowNotFoundError,
+  toThrowUnauthorizedError,
+};
+```
+
 testSetup.js
 
 ```javascript
@@ -174,6 +210,45 @@ expect(json).not.toMatchSchema(jsonApiSchema);
 
 From `jest-json-schema`; see [README](https://github.com/americanexpress/jest-json-schema?tab=readme-ov-file#tomatchschemaschema)
 
+
+#### `expect(subject).toMatch*()` Regular Expression Matchers
+
+Note: these regular expressions matchers so not verify the value is value, only that it matches the pattern (it "looks like" something). For example, `expect("123e4567-e89b-12d3-a456-426614174000").toMatchUuid()` will pass because the string matches a UUID pattern, even though it is not a valid UUID. 
+
+* `toMatchBase64`
+* `toMatchJwt`
+* `toMatchMongoId`
+* `toMatchSignedCookie`
+* `toMatchUuid4`
+* `toMatchUuid5`
+* `toMatchUuid`
+
+#### `expect(subject).toThrowJaypieError()`
+
+```javascript
+import { ConfigurationError } from "@jaypie/core";
+
+const error = new ConfigurationError();
+expect(() => {
+  throw error;
+}).toThrowJaypieError();
+```
+
+Do not forget to `await expect` when passing `async` functions:
+
+```javascript
+import { ConfigurationError } from "@jaypie/core";
+
+const error = new ConfigurationError();
+await expect(async () => {
+  throw error;
+}).toThrowJaypieError();
+
+// Breaks and causes a false-positive because `expect` did not `await`
+// expect(async () => {}).toThrowJaypieError();
+// > Error: Expected function to throw a JaypieError, but it did not throw.
+```
+
 ### `mockLogFactory()`
 
 Creates a mock of the `log` provided by `@jaypie/core`.
@@ -193,7 +268,7 @@ Restores the `log` provided by `@jaypie/core`, commonly performed `afterEach` wi
 
 ### `spyLog(log)`
 
-Spies on the `log` provided by `@jaypie/core`, commonly performed `beforeEach` with `restoreLog` in `afterEach`.
+Spies on the `log` provided by `@jaypie/core`, commonly performed `beforeEach` with `restoreLog` in `afterEach`. Not necessary when mocking the entire Jaypie module.
 
 ```javascript
 import { restoreLog, spyLog } from "@jaypie/testkit";
@@ -234,13 +309,13 @@ const event = sqsTestRecords(
 * matcher toBeJaypieData
 * matcher toBeJaypieDataObject
 * matcher toBeJaypieDataArray
-* matcher toThrowJaypieError
 * ...@knowdev/jest
 
 ## 📝 Changelog
 
 | Date       | Version | Summary        |
 | ---------- | ------- | -------------- |
+|  7/16/2024 |  1.0.21 | Export Jaypie mock as default |
 |  3/20/2024 |   1.0.2 | Export `LOG`   |
 |  3/16/2024 |   1.0.0 | Artists ship   |
 |  3/15/2024 |   0.1.0 | Initial deploy |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaypie/testkit",
-  "version": "1.0.19",
+  "version": "1.0.21",
   "author": "Finlayson Studio",
   "type": "module",
   "main": "src/index.js",
@@ -8,11 +8,20 @@
     "format": "npm run format:package && npm run format:lint",
     "format:lint": "eslint --fix .",
     "format:package": "sort-package-json ./package.json",
+    "init:commander": "hygen jaypie commander-init",
     "init:deploy": "hygen jaypie workflow-npm",
     "lint": "eslint .",
     "new": "hygen jaypie vite",
+    "new:command": "hygen jaypie command",
+    "new:constants": "hygen jaypie constants",
+    "new:hygen": "hygen jaypie hygen",
+    "new:index": "hygen jaypie index",
+    "new:model": "hygen jaypie model",
+    "new:test": "hygen jaypie vitest",
     "test": "vitest",
+    "test:spec:constants": "vitest run ./src/__tests__/constants.spec.js",
     "test:spec:index": "vitest run ./src/__tests__/index.spec.js",
+    "test:spec:jaypie.mock": "vitest run ./src/__tests__/jaypie.mock.spec.js",
     "test:spec:jsonApiSchema.module": "vitest run ./src/__tests__/jsonApiSchema.module.spec.js",
     "test:spec:matchers.module": "vitest run ./src/__tests__/matchers.module.spec.js",
     "test:spec:mockLog.module": "vitest run ./src/__tests__/mockLog.module.spec.js",
@@ -20,20 +29,19 @@
     "test:spec:toBeCalledWithInitialParams.matcher": "vitest run ./src/matchers/__tests__/toBeCalledWithInitialParams.matcher.spec.js",
     "test:spec:toBeClass.matcher": "vitest run ./src/matchers/__tests__/toBeClass.matcher.spec.js",
     "test:spec:toBeJaypieError.matcher": "vitest run ./src/matchers/__tests__/toBeJaypieError.matcher.spec.js",
+    "test:spec:toMatch.matcher": "vitest run ./src/matchers/__tests__/toMatch.matcher.spec.js",
     "test:spec:toThrowJaypieError.matcher": "vitest run ./src/matchers/__tests__/toThrowJaypieError.matcher.spec.js"
   },
   "dependencies": {
     "@jaypie/core": "^1.0.33",
+    "jaypie": "^1.0.44",
     "jest-json-schema": "^6.1.0",
     "lodash.isequal": "^4.5.0",
     "uuid": "^9.0.1"
   },
   "devDependencies": {
     "eslint": "^8.57.0",
-    "eslint-config-prettier": "^9.1.0",
-    "eslint-plugin-import": "^2.29.1",
-    "eslint-plugin-prettier": "^5.1.3",
-    "eslint-plugin-vitest": "^0.3.26",
+    "eslint-config-jaypie": "^1.0.7",
     "hygen": "^6.2.11",
     "jest-extended": "^4.0.2",
     "prettier": "^3.2.5",

package/src/constants.js

@@ -0,0 +1,28 @@
+//
+//
+// Constants
+//
+
+export const LOG = {
+  LEVEL: {
+    ALL: "all",
+    DEBUG: "debug",
+    ERROR: "error",
+    FATAL: "fatal",
+    INFO: "info",
+    SILENT: "silent",
+    TRACE: "trace",
+    WARN: "warn",
+  },
+};
+
+export const RE_BASE64_PATTERN = /^[a-zA-Z0-9\\+\\/]+$/;
+export const RE_JWT_PATTERN = /^([^.]+)\.([^.]+)\.([^.]+)$/;
+export const RE_MONGO_ID_PATTERN = /^[a-f0-9]{24}$/i;
+export const RE_SIGNED_COOKIE_PATTERN = /^s:([^.]+)\.([^.]+)$/;
+export const RE_UUID_4_PATTERN =
+  /^[a-f0-9]{8}-?[a-f0-9]{4}-?4[a-f0-9]{3}-?[89ab][a-f0-9]{3}-?[a-f0-9]{12}$/i;
+export const RE_UUID_5_PATTERN =
+  /^[a-f0-9]{8}-?[a-f0-9]{4}-?5[a-f0-9]{3}-?[89ab][a-f0-9]{3}-?[a-f0-9]{12}$/i;
+export const RE_UUID_PATTERN =
+  /^[a-f0-9]{8}-?[a-f0-9]{4}-?[a-f0-9]{4}-?[89ab][a-f0-9]{3}-?[a-f0-9]{12}$/i;

package/src/index.js

@@ -1,20 +1,11 @@
+import * as mockingJay from "./jaypie.mock.js";
+
 //
 //
 // Constants
 //
 
-export const LOG = {
-  LEVEL: {
-    ALL: "all",
-    DEBUG: "debug",
-    ERROR: "error",
-    FATAL: "fatal",
-    INFO: "info",
-    SILENT: "silent",
-    TRACE: "trace",
-    WARN: "warn",
-  },
-};
+export { LOG } from "./constants.js";
 
 //
 //
@@ -25,3 +16,5 @@ export { jsonApiErrorSchema, jsonApiSchema } from "./jsonApiSchema.module.js";
 export { default as matchers } from "./matchers.module.js";
 export { mockLogFactory, restoreLog, spyLog } from "./mockLog.module.js";
 export { default as sqsTestRecords } from "./sqsTestRecords.function.js";
+
+export default mockingJay;

package/src/jaypie.mock.js

@@ -0,0 +1,206 @@
+import { getMessages as originalGetMessages } from "@jaypie/aws";
+import { force, uuid as originalUuid } from "@jaypie/core";
+import { BadRequestError, JAYPIE, log, UnavailableError } from "@jaypie/core";
+import { beforeAll, vi } from "vitest";
+
+import { spyLog } from "./mockLog.module.js";
+
+//
+//
+// Setup
+//
+
+const TAG = JAYPIE.LIB.TESTKIT;
+
+// Export all the modules from Jaypie packages:
+
+export * from "@jaypie/aws";
+export * from "@jaypie/core";
+export * from "@jaypie/express";
+export * from "@jaypie/datadog";
+export * from "@jaypie/lambda";
+export * from "@jaypie/mongoose";
+
+// Spy on log:
+
+beforeAll(() => {
+  spyLog(log);
+});
+
+// afterEach(() => {
+// This is not necessary because the log isn't being used outside tests:
+// restoreLog(log);
+// The is the client's responsibility:
+// vi.clearAllMocks();
+// });
+
+//
+//
+// Mock Functions
+//
+
+// @jaypie/aws
+
+export const getMessages = vi.fn((...params) => originalGetMessages(...params));
+
+export const getSecret = vi.fn(() => {
+  return `_MOCK_SECRET_[${TAG}]`;
+});
+
+export const sendBatchMessages = vi.fn(() => {
+  // TODO: better default value
+  return { value: `_MOCK_BATCH_MESSAGES_[${TAG}]` };
+});
+
+export const sendMessage = vi.fn(() => {
+  // TODO: better default value
+  return { value: `_MOCK_MESSAGE_[${TAG}]` };
+});
+
+// @jaypie/core Functions
+
+export const envBoolean = vi.fn(() => {
+  return true;
+});
+
+export const jaypieHandler = vi.fn(
+  (
+    handler,
+    {
+      setup = [],
+      teardown = [],
+      unavailable = force.boolean(process.env.PROJECT_UNAVAILABLE),
+      validate = [],
+    } = {},
+  ) => {
+    return async (...args) => {
+      let result;
+      let thrownError;
+      if (unavailable) throw new UnavailableError();
+      for (const validator of validate) {
+        if (typeof validator === "function") {
+          const valid = await validator(...args);
+          if (valid === false) {
+            throw new BadRequestError();
+          }
+        }
+      }
+      try {
+        for (const setupFunction of setup) {
+          if (typeof setupFunction === "function") {
+            await setupFunction(...args);
+          }
+        }
+        result = handler(...args);
+      } catch (error) {
+        thrownError = error;
+      }
+      for (const teardownFunction of teardown) {
+        if (typeof teardownFunction === "function") {
+          try {
+            await teardownFunction(...args);
+          } catch (error) {
+            // eslint-disable-next-line no-console
+            console.error(error);
+          }
+        }
+      }
+      if (thrownError) {
+        throw thrownError;
+      }
+      return result;
+    };
+  },
+);
+
+export const sleep = vi.fn(() => {
+  return true;
+});
+
+export const uuid = vi.fn(originalUuid);
+
+// @jaypie/datadog
+
+export const submitMetric = vi.fn(() => {
+  return true;
+});
+
+export const submitMetricSet = vi.fn(() => {
+  return true;
+});
+
+// @jaypie/express
+
+export const expressHandler = vi.fn((handler, props = {}) => {
+  if (typeof handler !== "function") {
+    throw new BadRequestError("handler must be a function");
+  }
+  if (!props) {
+    props = {};
+  }
+  props.setup = force.array(props.setup); // allows a single item
+  props.teardown = force.array(props.teardown); // allows a single item
+  if (!Array.isArray(props.setup)) {
+    props.setup = [];
+  }
+  if (props.locals === null) {
+    throw new BadRequestError("locals cannot be null");
+  }
+  if (props.locals) {
+    if (typeof props.locals !== "object" || Array.isArray(props.locals)) {
+      throw new BadRequestError("locals must be an object");
+    }
+    // Locals
+    const keys = Object.keys(props.locals);
+    if (keys.length > 0) {
+      props.setup.push((req = {}) => {
+        if (typeof req !== "object") {
+          throw new BadRequestError("req must be an object");
+        }
+        // Set req.locals if it doesn't exist
+        if (!req.locals) req.locals = {};
+        if (typeof req.locals !== "object" || Array.isArray(req.locals)) {
+          throw new BadRequestError("req.locals must be an object");
+        }
+        if (!req.locals._jaypie) req.locals._jaypie = {};
+      });
+      const localsSetup = async (localsReq, localsRes) => {
+        for (let i = 0; i < keys.length; i += 1) {
+          const key = keys[i];
+          if (typeof props.locals[key] === "function") {
+            // eslint-disable-next-line no-await-in-loop
+            localsReq.locals[key] = await props.locals[key](
+              localsReq,
+              localsRes,
+            );
+          } else {
+            localsReq.locals[key] = props.locals[key];
+          }
+        }
+      };
+      props.setup.push(localsSetup);
+    }
+  }
+  return jaypieHandler(handler, props);
+});
+
+// @jaypie/lambda
+
+// For testing, this is the same as the jaypieHandler
+export const lambdaHandler = vi.fn((handler, props = {}) => {
+  return jaypieHandler(handler, props);
+});
+
+// @jaypie/mongoose
+
+export const connect = vi.fn(() => {
+  return true;
+});
+
+export const connectFromSecretEnv = vi.fn(() => {
+  return true;
+});
+
+export const disconnect = vi.fn(() => {
+  return true;
+});

package/src/matchers/toMatch.matcher.js

@@ -0,0 +1,76 @@
+import {
+  RE_BASE64_PATTERN,
+  RE_JWT_PATTERN,
+  RE_MONGO_ID_PATTERN,
+  RE_SIGNED_COOKIE_PATTERN,
+  RE_UUID_4_PATTERN,
+  RE_UUID_5_PATTERN,
+  RE_UUID_PATTERN,
+} from "../constants.js";
+
+//
+//
+// Helper
+//
+
+function forSubjectToMatchPattern(
+  subject,
+  pattern,
+  { patternName = "pattern" } = {},
+) {
+  if (pattern.test(subject)) {
+    return {
+      message: () => `expected "${subject}" not to match ${patternName}`,
+      pass: true,
+    };
+  }
+  return {
+    message: () => `expected "${subject}" to match ${patternName}`,
+    pass: false,
+  };
+}
+
+//
+//
+// Main
+//
+
+export const toMatchBase64 = (subject) =>
+  forSubjectToMatchPattern(subject, RE_BASE64_PATTERN, {
+    patternName: "Base64",
+  });
+
+export const toMatchJwt = (subject) =>
+  forSubjectToMatchPattern(subject, RE_JWT_PATTERN, {
+    patternName: "JWT",
+  });
+
+export const toMatchMongoId = (subject) =>
+  forSubjectToMatchPattern(subject, RE_MONGO_ID_PATTERN, {
+    patternName: "MongoDbId",
+  });
+
+export const toMatchSignedCookie = (subject) =>
+  forSubjectToMatchPattern(subject, RE_SIGNED_COOKIE_PATTERN, {
+    patternName: "Signed-Cookie",
+  });
+
+export const toMatchUuid4 = (subject) =>
+  forSubjectToMatchPattern(subject, RE_UUID_4_PATTERN, {
+    patternName: "UUIDv4",
+  });
+
+export const toMatchUuid5 = (subject) =>
+  forSubjectToMatchPattern(subject, RE_UUID_5_PATTERN, {
+    patternName: "UUIDv5",
+  });
+
+/**
+ * Determines if subject matches a UUID pattern.
+ * Does _NOT_ check if the UUID is valid.
+ * @param {String} subject
+ */
+export const toMatchUuid = (subject) =>
+  forSubjectToMatchPattern(subject, RE_UUID_PATTERN, {
+    patternName: "UUID",
+  });

package/src/matchers.module.js

@@ -12,6 +12,16 @@ import toThrowJaypieError, {
   toThrowUnauthorizedError,
 } from "./matchers/toThrowJaypieError.matcher.js";
 
+import {
+  toMatchBase64,
+  toMatchJwt,
+  toMatchMongoId,
+  toMatchSignedCookie,
+  toMatchUuid4,
+  toMatchUuid5,
+  toMatchUuid,
+} from "./matchers/toMatch.matcher.js";
+
 //
 //
 // Export
@@ -22,7 +32,14 @@ export default {
   toBeClass,
   toBeJaypieError,
   toBeValidSchema: jsonSchemaMatchers.toBeValidSchema,
+  toMatchBase64,
+  toMatchJwt,
+  toMatchMongoId,
   toMatchSchema: jsonSchemaMatchers.toMatchSchema,
+  toMatchSignedCookie,
+  toMatchUuid4,
+  toMatchUuid5,
+  toMatchUuid,
   toThrowBadRequestError,
   toThrowConfigurationError,
   toThrowForbiddenError,

package/src/mockLog.module.js

@@ -7,6 +7,7 @@ export function mockLogFactory() {
     error: vi.fn(),
     fatal: vi.fn(),
     info: vi.fn(),
+    init: vi.fn(),
     lib: vi.fn(),
     tag: vi.fn(),
     trace: vi.fn(),
@@ -23,6 +24,7 @@ export function mockLogFactory() {
   mock.trace.var = mock.var;
   mock.warn.var = mock.var;
   // Have modules return correct objects
+  mock.init.mockReturnValue(null);
   mock.lib.mockReturnValue(mock);
   mock.with.mockReturnValue(mock);
 
@@ -32,6 +34,7 @@ export function mockLogFactory() {
     error: mock.error,
     fatal: mock.fatal,
     info: mock.info,
+    init: mock.init,
     lib: mock.lib,
     tag: mock.tag,
     trace: mock.trace,
@@ -55,6 +58,7 @@ const logMethodNames = [
   "error",
   "fatal",
   "info",
+  "init",
   "lib",
   "tag",
   "trace",