@jaypie/testkit 0.1.2 → 1.0.0

package/.vscode/settings.json

@@ -13,6 +13,7 @@
     "oidc",
     "pinia",
     "roboto",
+    "sorpresa",
     "testkit",
     "unplugin",
     "vendia",

package/README.md

@@ -12,16 +12,212 @@ npm install --save-dev @jaypie/testkit
 
 ### Example
 
-TODO: Example should include one trivial and possibly one thorough example of using the library
+#### Log Spying
+
+```javascript
+import { restoreLog, spyLog } from "@jaypie/testkit";
+import { log } from "@jaypie/core";
+
+beforeEach(() => {
+  spyLog(log);
+});
+afterEach(() => {
+  restoreLog(log);
+  vi.clearAllMocks();
+});
+
+test("log", () => {
+  log.warn("Danger");
+  expect(log.warn).toHaveBeenCalled();
+  expect(log.error).not.toHaveBeenCalled();
+});
+```
+
+👺 Logging Conventions:
+
+* Only use `log.trace` or `log.var` during "happy path"
+* Use `log.debug` for edge cases
+* Now you can add an "observability" test that will fail as soon as new code triggers an unexpected edge condition
+
+```javascript
+describe("Observability", () => {
+  it("Does not log above trace", async () => {
+    // Arrange
+    // TODO: "happy path" setup
+    // Act
+    await myNewFunction(); // TODO: add any "happy path" parameters
+    // Assert
+    expect(log.debug).not.toHaveBeenCalled();
+    expect(log.info).not.toHaveBeenCalled();
+    expect(log.warn).not.toHaveBeenCalled();
+    expect(log.error).not.toHaveBeenCalled();
+    expect(log.fatal).not.toHaveBeenCalled();
+  });
+});
+```
+
+> 👺 Follow the "arrange, act, assert" pattern
+
+#### Test Matchers
+
+testSetup.js
+
+```javascript
+import { matchers as jaypieMatchers } from "@jaypie/testkit";
+import * as extendedMatchers from "jest-extended";
+import { expect } from "vitest";
+
+expect.extend(extendedMatchers);
+expect.extend(jaypieMatchers);
+```
+
+test.spec.js
+
+```javascript
+import { ConfigurationError } from "@jaypie/core";
+
+const error = new ConfigurationError();
+const json = error.json();
+expect(error).toBeJaypieError();
+expect(json).toBeJaypieError();
+```
 
 ## 📖 Reference
 
-TODO: Reference should be a complete list of everything in the package
+```
+import { 
+  jsonApiErrorSchema,
+  jsonApiSchema,
+  matchers,
+  mockLogFactory,
+  restoreLog,
+  spyLog,
+} from '@jaypie/testkit'
+```
+
+### `jsonApiErrorSchema`
+
+A [JSON Schema](https://json-schema.org/) validator for the [JSON:API](https://jsonapi.org/) error schema. Powers the `toBeJaypieError` matcher (via `toMatchSchema`).
+
+### `jsonApiSchema`
+
+A [JSON Schema](https://json-schema.org/) validator for the [JSON:API](https://jsonapi.org/) data schema.
+
+### `matchers`
+
+testSetup.js
+
+```javascript
+import { matchers as jaypieMatchers } from "@jaypie/testkit";
+import * as extendedMatchers from "jest-extended";
+import { expect } from "vitest";
+
+expect.extend(extendedMatchers);
+expect.extend(jaypieMatchers);
+```
+
+#### `expect(subject).toBeJaypieError()`
+
+Validates instance objects:
+
+```javascript
+try {
+  throw new Error("Sorpresa!");
+} catch (error) {
+  expect(error).not.toBeJaypieError();
+}
+```
+
+Validates plain old JSON:
+
+```javascript
+expect({ errors: [ { status, title, detail } ] }).toBeJaypieError();
+```
+
+Jaypie errors, which are `ProjectErrors`, all have a `.json()` to convert
+
+#### `expect(subject).toBeValidSchema()`
+
+```javascript
+import { jsonApiErrorSchema, jsonApiSchema } from "@jaypie/testkit";
+
+expect(jsonApiErrorSchema).toBeValidSchema();
+expect(jsonApiSchema).toBeValidSchema();
+expect({ project: "mayhem" }).not.toBeValidSchema();
+```
+
+From `jest-json-schema` [toBeValidSchema.js](https://github.com/americanexpress/jest-json-schema/blob/main/matchers/toBeValidSchema.js) (not documented in README)
+
+#### `expect(subject).toMatchSchema(schema)`
+
+```javascript
+import { jsonApiErrorSchema, jsonApiSchema } from "@jaypie/testkit";
+import { ConfigurationError } from "@jaypie/core";
+
+const error = new ConfigurationError();
+const json = error.json();
+expect(json).toMatchSchema(jsonApiErrorSchema);
+expect(json).not.toMatchSchema(jsonApiSchema);
+```
+
+From `jest-json-schema`; see [README](https://github.com/americanexpress/jest-json-schema?tab=readme-ov-file#tomatchschemaschema)
+
+### `mockLogFactory()`
+
+Creates a mock of the `log` provided by `@jaypie/core`.
+
+```javascript
+import { mockLogFactory } from "@jaypie/testkit";
+
+const log = mockLogFactory();
+log.warn("Danger");
+expect(log.warn).toHaveBeenCalled();
+expect(log.error).not.toHaveBeenCalled();
+```
+
+### `restoreLog(log)`
+
+Restores the `log` provided by `@jaypie/core`, commonly performed `afterEach` with `spyLog` in `beforeEach`. See example with `spyLog`.
+
+### `spyLog(log)`
+
+Spies on the `log` provided by `@jaypie/core`, commonly performed `beforeEach` with `restoreLog` in `afterEach`.
+
+```javascript
+import { restoreLog, spyLog } from "@jaypie/testkit";
+import { log } from "@jaypie/core";
+
+beforeEach(() => {
+  spyLog(log);
+});
+afterEach(() => {
+  restoreLog(log);
+  vi.clearAllMocks();
+});
+
+test("log", () => {
+  log.warn("Danger");
+  expect(log.warn).toHaveBeenCalled();
+  expect(log.error).not.toHaveBeenCalled();
+});
+```
+
+## 🌠 Wishlist
+
+* matcher toBeHttpStatus
+* matcher toBeJaypieAny
+* matcher toBeJaypieData
+* matcher toBeJaypieDataObject
+* matcher toBeJaypieDataArray
+* matcher toThrowJaypieError
+* ...@knowdev/jest
 
 ## 📝 Changelog
 
 | Date       | Version | Summary        |
 | ---------- | ------- | -------------- |
+|  3/16/2024 |   1.0.0 | Artists ship   |
+|  3/15/2024 |   0.1.0 | Initial deploy |
 |  3/15/2024 |   0.0.1 | Initial commit |
 
 ## 📜 License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaypie/testkit",
-  "version": "0.1.2",
+  "version": "1.0.0",
   "author": "Finlayson Studio",
   "type": "module",
   "main": "src/index.js",
@@ -15,12 +15,14 @@
     "test:spec:index": "vitest run ./src/__tests__/index.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"
+    "test:spec:mockLog.module": "vitest run ./src/__tests__/mockLog.module.spec.js",
+    "test:spec:toBeJaypieError.matcher": "vitest run ./src/matchers/__tests__/toBeJaypieError.matcher.spec.js"
   },
   "dependencies": {
     "jest-json-schema": "^6.1.0"
   },
   "devDependencies": {
+    "@jaypie/core": "^0.3.7",
     "eslint": "^8.57.0",
     "eslint-config-prettier": "^9.1.0",
     "eslint-plugin-import": "^2.29.1",

package/src/jsonApiSchema.module.js

@@ -12,6 +12,7 @@ export const jsonApiErrorSchema = {
         },
         required: ["status", "title"],
       },
+      minItems: 1,
     },
   },
   required: ["errors"],

package/src/matchers/__tests__/toBeJaypieError.matcher.spec.js

@@ -0,0 +1,100 @@
+// eslint-disable-next-line no-unused-vars
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { ConfigurationError } from "@jaypie/core";
+
+// Subject
+import toBeJaypieError from "../toBeJaypieError.matcher.js";
+
+//
+//
+// Mock constants
+//
+
+//
+//
+// Mock modules
+//
+
+//
+//
+// Mock environment
+//
+
+const DEFAULT_ENV = process.env;
+beforeEach(() => {
+  process.env = { ...process.env };
+});
+afterEach(() => {
+  process.env = DEFAULT_ENV;
+});
+
+//
+//
+// Run tests
+//
+
+describe("To Be Jaypie Error Matcher", () => {
+  it("Is a function", () => {
+    expect(toBeJaypieError).toBeFunction();
+  });
+  describe("Error Conditions", () => {
+    it("Rejects instances of plain error objects", () => {
+      const error = new Error(
+        "If this is your first night at Fight Club, you have to fight",
+      );
+      const result = toBeJaypieError(error);
+      expect(result.message).toBeFunction();
+      expect(result.message()).toBeString();
+      expect(result.pass).toBeFalse();
+    });
+    it("Rejects if nothing passed", () => {
+      const result = toBeJaypieError();
+      expect(result.message).toBeFunction();
+      expect(result.message()).toBeString();
+      expect(result.pass).toBeFalse();
+    });
+    it("Rejects if non-object passed", () => {
+      const result = toBeJaypieError(12);
+      expect(result.message).toBeFunction();
+      expect(result.message()).toBeString();
+      expect(result.pass).toBeFalse();
+    });
+    it("Rejects if no errors array", () => {
+      const result = toBeJaypieError({});
+      expect(result.message).toBeFunction();
+      expect(result.message()).toBeString();
+      expect(result.pass).toBeFalse();
+    });
+    it("Rejects if errors array is empty", () => {
+      const result = toBeJaypieError({ errors: [] });
+      expect(result.message).toBeFunction();
+      expect(result.message()).toBeString();
+      expect(result.pass).toBeFalse();
+    });
+    it("Must match the entire json:api error schema", () => {
+      const result = toBeJaypieError({ errors: ["taco"] });
+      expect(result.message).toBeFunction();
+      expect(result.message()).toBeString();
+      expect(result.pass).toBeFalse();
+    });
+  });
+  describe("Happy Path", () => {
+    it("Matches instances of Jaypie error objects", () => {
+      const error = new ConfigurationError();
+      const result = toBeJaypieError(error);
+      expect(result.message).toBeFunction();
+      expect(result.message()).toBeString();
+      expect(result.pass).toBeTrue();
+    });
+    it("Matches plain old json errors", () => {
+      const error = new ConfigurationError(
+        "If this is your first night at Fight Club, you have to fight",
+      ).json();
+      const result = toBeJaypieError(error);
+      expect(result.message).toBeFunction();
+      expect(result.message()).toBeString();
+      expect(result.pass).toBeTrue();
+    });
+  });
+});

package/src/matchers/toBeJaypieError.matcher.js

@@ -0,0 +1,57 @@
+import { matchers as jsonSchemaMatchers } from "jest-json-schema";
+import { jsonApiErrorSchema } from "../jsonApiSchema.module.js";
+
+//
+//
+// Constants
+//
+
+//
+//
+// Helper Functions
+//
+
+function isErrorObjectJaypieError(error) {
+  if (error.isProjectError) {
+    return {
+      message: () => `expected "${error}" not to be a Jaypie error`,
+      pass: true,
+    };
+  }
+  return {
+    message: () => `expected "${error}" to be a Jaypie error`,
+    pass: false,
+  };
+}
+
+//
+//
+// Main
+//
+
+const toBeJaypieError = (received) => {
+  // See if it is an instance of error:
+  if (received instanceof Error) {
+    return isErrorObjectJaypieError(received);
+  }
+
+  const result = jsonSchemaMatchers.toMatchSchema(received, jsonApiErrorSchema);
+  if (result.pass) {
+    return {
+      message: () => `expected ${received} not to be a Jaypie error`,
+      pass: true,
+    };
+  } else {
+    return {
+      message: () => `expected ${received} to be a Jaypie error`,
+      pass: false,
+    };
+  }
+};
+
+//
+//
+// Export
+//
+
+export default toBeJaypieError;

package/src/matchers.module.js

@@ -1,11 +1,14 @@
 import { matchers as jsonSchemaMatchers } from "jest-json-schema";
 
+import toBeJaypieError from "./matchers/toBeJaypieError.matcher.js";
+
 //
 //
 // Export
 //
 
 export default {
+  toBeJaypieError,
   toBeValidSchema: jsonSchemaMatchers.toBeValidSchema,
   toMatchSchema: jsonSchemaMatchers.toMatchSchema,
 };