@digitaldefiance/express-suite-test-utils 1.0.10 → 1.0.12

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Digital Defiance
+
+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

@@ -157,12 +157,194 @@ describe('User model', () => {
 
 **Note:** Requires `mongoose` as a peer dependency and `mongodb-memory-server` as a dependency (already included).
 
+## Testing Approach
+
+This package provides comprehensive testing utilities for Express Suite projects, including custom Jest matchers, console mocks, database helpers, and more.
+
+### Test Utilities Overview
+
+**Custom Matchers**: `toThrowType` for type-safe error testing  
+**Console Mocks**: Mock and spy on console methods  
+**Direct Log Mocks**: Mock `fs.writeSync` for stdout/stderr testing  
+**Database Helpers**: MongoDB Memory Server integration  
+**React Mocks**: Mock React components and hooks
+
+### Usage Patterns
+
+#### Using toThrowType Matcher
+
+```typescript
+import '@digitaldefiance/express-suite-test-utils';
+
+class CustomError extends Error {
+  constructor(public code: number) {
+    super('Custom error');
+  }
+}
+
+describe('Error Testing', () => {
+  it('should throw specific error type', () => {
+    expect(() => {
+      throw new CustomError(404);
+    }).toThrowType(CustomError);
+  });
+
+  it('should validate error properties', () => {
+    expect(() => {
+      throw new CustomError(404);
+    }).toThrowType(CustomError, (error) => {
+      expect(error.code).toBe(404);
+    });
+  });
+});
+```
+
+#### Using Console Mocks
+
+```typescript
+import { withConsoleMocks, spyContains } from '@digitaldefiance/express-suite-test-utils';
+
+describe('Console Output', () => {
+  it('should capture console.log', async () => {
+    await withConsoleMocks({ mute: true }, async (spies) => {
+      console.log('test message');
+      
+      expect(spies.log).toHaveBeenCalledWith('test message');
+      expect(spyContains(spies.log, 'test', 'message')).toBe(true);
+    });
+  });
+
+  it('should capture console.error', async () => {
+    await withConsoleMocks({ mute: true }, async (spies) => {
+      console.error('error message');
+      
+      expect(spies.error).toHaveBeenCalledWith('error message');
+    });
+  });
+});
+```
+
+#### Using Direct Log Mocks
+
+```typescript
+import { withDirectLogMocks, directLogContains, getDirectLogMessages } from '@digitaldefiance/express-suite-test-utils';
+import * as fs from 'fs';
+
+// Mock fs at module level
+jest.mock('fs', () => ({
+  ...jest.requireActual('fs'),
+  writeSync: jest.fn(),
+}));
+
+describe('Direct Logging', () => {
+  it('should capture stdout writes', async () => {
+    await withDirectLogMocks({ mute: true }, async (spies) => {
+      const buffer = Buffer.from('hello world\n', 'utf8');
+      fs.writeSync(1, buffer); // stdout
+      
+      expect(directLogContains(spies.writeSync, 1, 'hello', 'world')).toBe(true);
+      expect(getDirectLogMessages(spies.writeSync, 1)).toEqual(['hello world\n']);
+    });
+  });
+});
+```
+
+#### Using MongoDB Memory Server
+
+```typescript
+import { connectMemoryDB, disconnectMemoryDB, clearMemoryDB } from '@digitaldefiance/express-suite-test-utils';
+import { User } from './models/user';
+
+describe('Database Tests', () => {
+  beforeAll(async () => {
+    await connectMemoryDB();
+  });
+
+  afterAll(async () => {
+    await disconnectMemoryDB();
+  });
+
+  afterEach(async () => {
+    await clearMemoryDB();
+  });
+
+  it('should validate user schema', async () => {
+    const user = new User({ 
+      username: 'test', 
+      email: 'test@example.com' 
+    });
+    
+    await user.validate(); // Real Mongoose validation!
+    await user.save();
+    
+    const found = await User.findOne({ username: 'test' });
+    expect(found).toBeDefined();
+  });
+
+  it('should reject invalid data', async () => {
+    const invalid = new User({ username: 'ab' }); // too short
+    
+    await expect(invalid.validate()).rejects.toThrow();
+  });
+});
+```
+
+### Testing Best Practices
+
+1. **Always clean up** after tests (disconnect DB, restore mocks)
+2. **Use memory database** for fast, isolated tests
+3. **Mock external dependencies** to avoid side effects
+4. **Test error conditions** with `toThrowType` matcher
+5. **Capture console output** when testing logging behavior
+
+### Cross-Package Testing
+
+These utilities are designed to work seamlessly with all Express Suite packages:
+
+```typescript
+import { connectMemoryDB, disconnectMemoryDB } from '@digitaldefiance/express-suite-test-utils';
+import { Application } from '@digitaldefiance/node-express-suite';
+import { UserService } from '@digitaldefiance/node-express-suite';
+
+describe('Integration Tests', () => {
+  let app: Application;
+
+  beforeAll(async () => {
+    await connectMemoryDB();
+    app = new Application({
+      mongoUri: global.__MONGO_URI__,
+      jwtSecret: 'test-secret'
+    });
+  });
+
+  afterAll(async () => {
+    await app.stop();
+    await disconnectMemoryDB();
+  });
+
+  it('should create and find user', async () => {
+    const userService = new UserService(app);
+    const user = await userService.create({
+      username: 'alice',
+      email: 'alice@example.com'
+    });
+    
+    const found = await userService.findByUsername('alice');
+    expect(found).toBeDefined();
+  });
+});
+```
+
 ## License
 
 MIT
 
 ## ChangeLog
 
+### v1.0.11
+
+- Fix mongoose to use @digitaldefiance/mongoose-types
+
 ### v1.0.10
 
 - Fix direct-log mocks to work with non-configurable fs.writeSync in newer Node.js versions

package/package.json

@@ -1,6 +1,11 @@
 {
   "name": "@digitaldefiance/express-suite-test-utils",
-  "version": "1.0.10",
+  "version": "1.0.12",
+  "homepage": "https://github.com/Digital-Defiance/test-utils",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Digital-Defiance/test-utils.git"
+  },
   "description": "Test utilities for Digital Defiance Express Suite",
   "main": "src/index.js",
   "types": "src/index.d.ts",
@@ -46,6 +51,5 @@
   "devDependencies": {
     "@types/node": "^22.0.0",
     "mongoose": "^8.9.3"
-  },
-  "type": "commonjs"
-}
+  }
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from './lib/to-throw-type';
+export * from './lib/console';
+export * from './lib/direct-log';
+export * from './lib/localStorage-mock';
+export * from './lib/bson-mock';
+export * from './lib/react-mocks';
+export * from './lib/mongoose-memory';

package/src/lib/bson-mock.ts

@@ -0,0 +1,36 @@
+/**
+ * Mock bson and crypto modules for Jest tests
+ */
+
+export class ObjectId {
+  constructor(public id: string = '000000000000000000000000') {}
+  toString(): string {
+    return this.id;
+  }
+  toHexString(): string {
+    return this.id;
+  }
+}
+
+export class Binary {}
+export class Code {}
+export class DBRef {}
+export class Decimal128 {}
+export class Double {}
+export class Int32 {}
+export class Long {}
+export class MaxKey {}
+export class MinKey {}
+export class Timestamp {}
+export class UUID {}
+
+// Mock secp256k1 for ethereum crypto
+export const secp256k1 = {
+  CURVE: {
+    p: BigInt(0),
+    n: BigInt(0),
+  },
+};
+
+// Default export for ethereum-cryptography
+export default { secp256k1 };

package/src/lib/console.ts

@@ -0,0 +1,69 @@
+/* Reusable console mock helpers for e2e tests */
+
+export type ConsoleSpies = {
+  log: jest.SpyInstance;
+  info: jest.SpyInstance;
+  warn: jest.SpyInstance;
+  error: jest.SpyInstance;
+  debug: jest.SpyInstance;
+};
+
+export interface WithConsoleOptions {
+  mute?: boolean;
+}
+
+/**
+ * Wrap a test body with console spies that are always restored.
+ * By default mutes console output to keep test logs clean.
+ */
+export async function withConsoleMocks<T = unknown>(
+  options: WithConsoleOptions,
+  fn: (spies: ConsoleSpies) => Promise<T> | T,
+): Promise<T> {
+  const mute = options?.mute !== false; // default true
+  const noop = () => undefined;
+  const spies: ConsoleSpies = {
+    log: jest
+      .spyOn(console, 'log')
+      .mockImplementation(mute ? noop : console.log),
+    info: jest
+      .spyOn(console, 'info')
+      .mockImplementation(mute ? noop : console.info),
+    warn: jest
+      .spyOn(console, 'warn')
+      .mockImplementation(mute ? noop : console.warn),
+    error: jest
+      .spyOn(console, 'error')
+      .mockImplementation(mute ? noop : console.error),
+    debug: jest
+      .spyOn(console, 'debug')
+      .mockImplementation(
+        mute
+          ? noop
+          : (console.debug as ((...args: unknown[]) => void) | undefined) ??
+              noop,
+      ),
+  };
+  try {
+    return await fn(spies);
+  } finally {
+    spies.log.mockRestore();
+    spies.info.mockRestore();
+    spies.warn.mockRestore();
+    spies.error.mockRestore();
+    spies.debug.mockRestore();
+  }
+}
+
+/**
+ * True if any call to the spy contains all provided substrings, in order-agnostic check.
+ */
+export function spyContains(
+  spy: jest.SpyInstance,
+  ...needles: string[]
+): boolean {
+  return spy.mock.calls.some((args: unknown[]) => {
+    const text = args.map((a) => (typeof a === 'string' ? a : '')).join(' ');
+    return needles.every((n) => text.includes(n));
+  });
+}

package/src/lib/direct-log.ts

@@ -0,0 +1,105 @@
+import * as fs from 'fs';
+
+/**
+ * Spies returned from withDirectLogMocks
+ */
+export interface DirectLogSpies {
+  writeSync: jest.Mock;
+}
+
+/**
+ * Options for withDirectLogMocks
+ */
+export interface WithDirectLogOptions {
+  /**
+   * If false, do not mute the output (let it pass through).
+   * By default (true), mutes output.
+   */
+  mute?: boolean;
+}
+
+/**
+ * Wrap a test body with fs.writeSync spy for directLog testing.
+ * By default mutes output (does nothing on write).
+ * The spy will capture calls with file descriptor and buffer.
+ * 
+ * Note: Requires fs module to be mocked at module level with jest.mock('fs')
+ */
+export async function withDirectLogMocks<T = unknown>(
+  options: WithDirectLogOptions,
+  fn: (spies: DirectLogSpies) => Promise<T> | T,
+): Promise<T> {
+  const mute = options?.mute !== false; // default true
+  
+  // Get the mocked writeSync function
+  const writeSync = fs.writeSync as unknown as jest.Mock;
+  
+  // Store previous mock implementation if any
+  const previousImpl = writeSync.getMockImplementation();
+  
+  // Set implementation based on mute option
+  if (mute) {
+    writeSync.mockImplementation(() => undefined);
+  } else {
+    // Pass through - requires original implementation to be available
+    writeSync.mockImplementation((...args: any[]) => {
+      // In test environment, we can't easily call the real fs.writeSync
+      // so we just no-op but track the calls
+      return args[1]?.length || 0;
+    });
+  }
+  
+  const spies: DirectLogSpies = { writeSync };
+  
+  try {
+    return await fn(spies);
+  } finally {
+    // Clear calls and restore previous implementation
+    writeSync.mockClear();
+    if (previousImpl) {
+      writeSync.mockImplementation(previousImpl);
+    }
+  }
+}
+
+/**
+ * Helper to check if writeSync was called with a specific file descriptor and message.
+ * @param spy The writeSync mock
+ * @param fd The file descriptor (1 for stdout, 2 for stderr)
+ * @param needles Substrings to search for in the buffer content
+ */
+export function directLogContains(
+  spy: jest.Mock,
+  fd: number,
+  ...needles: string[]
+): boolean {
+  return spy.mock.calls.some((args: unknown[]) => {
+    const [calledFd, buffer] = args;
+    if (calledFd !== fd) return false;
+    
+    const text = buffer instanceof Buffer 
+      ? buffer.toString('utf8') 
+      : String(buffer);
+    
+    return needles.every((n) => text.includes(n));
+  });
+}
+
+/**
+ * Get all messages written to a specific file descriptor.
+ * @param spy The writeSync mock
+ * @param fd The file descriptor (1 for stdout, 2 for stderr)
+ */
+export function getDirectLogMessages(
+  spy: jest.Mock,
+  fd: number,
+): string[] {
+  return spy.mock.calls
+    .filter((args: unknown[]) => args[0] === fd)
+    .map((args: unknown[]) => {
+      const buffer = args[1];
+      return buffer instanceof Buffer 
+        ? buffer.toString('utf8') 
+        : String(buffer);
+    });
+}

package/src/lib/localStorage-mock.ts

@@ -0,0 +1,40 @@
+/**
+ * Simple localStorage mock for Node.js test environment
+ */
+export class LocalStorageMock implements Storage {
+  private store: Map<string, string> = new Map();
+
+  get length(): number {
+    return this.store.size;
+  }
+
+  clear(): void {
+    this.store.clear();
+  }
+
+  getItem(key: string): string | null {
+    return this.store.get(key) ?? null;
+  }
+
+  key(index: number): string | null {
+    const keys = Array.from(this.store.keys());
+    return keys[index] ?? null;
+  }
+
+  removeItem(key: string): void {
+    this.store.delete(key);
+  }
+
+  setItem(key: string, value: string): void {
+    this.store.set(key, value);
+  }
+}
+
+// Set up global localStorage mock
+if (typeof globalThis.localStorage === 'undefined') {
+  Object.defineProperty(globalThis, 'localStorage', {
+    value: new LocalStorageMock(),
+    writable: true,
+    configurable: true,
+  });
+}

package/src/lib/mongoose-memory.d.ts

@@ -1,4 +1,4 @@
-import { Connection } from 'mongoose';
+import { Connection } from '@digitaldefiance/mongoose-types';
 /**
  * Connect to in-memory MongoDB for testing
  * @returns Object with both the connection and URI

package/src/lib/mongoose-memory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mongoose-memory.d.ts","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-express-suite-test-utils/src/lib/mongoose-memory.ts"],"names":[],"mappings":"AACA,OAAiB,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAKhD;;;GAGG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC;IAAE,UAAU,EAAE,UAAU,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAsBxF;AAED;;GAEG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC,CAWxD;AAED;;GAEG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAOnD"}
+{"version":3,"file":"mongoose-memory.d.ts","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-express-suite-test-utils/src/lib/mongoose-memory.ts"],"names":[],"mappings":"AAAA,OAAiB,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAMvE;;;GAGG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC;IAC/C,UAAU,EAAE,UAAU,CAAC;IACvB,GAAG,EAAE,MAAM,CAAC;CACb,CAAC,CAsBD;AAED;;GAEG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC,CAWxD;AAED;;GAEG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAOnD"}

package/src/lib/mongoose-memory.js

@@ -4,8 +4,8 @@ exports.connectMemoryDB = connectMemoryDB;
 exports.disconnectMemoryDB = disconnectMemoryDB;
 exports.clearMemoryDB = clearMemoryDB;
 const tslib_1 = require("tslib");
+const mongoose_types_1 = tslib_1.__importDefault(require("@digitaldefiance/mongoose-types"));
 const mongodb_memory_server_1 = require("mongodb-memory-server");
-const mongoose_1 = tslib_1.__importDefault(require("mongoose"));
 let mongoServer;
 let connection;
 /**
@@ -14,8 +14,8 @@ let connection;
  */
 async function connectMemoryDB() {
     // If mongoose is connected but we don't have our server, disconnect first
-    if (mongoose_1.default.connection.readyState !== 0 && !mongoServer) {
-        await mongoose_1.default.disconnect();
+    if (mongoose_types_1.default.connection.readyState !== 0 && !mongoServer) {
+        await mongoose_types_1.default.disconnect();
         connection = undefined;
     }
     // Create new server if needed
@@ -24,10 +24,10 @@ async function connectMemoryDB() {
     }
     const uri = mongoServer.getUri();
     // Connect if not already connected
-    if (mongoose_1.default.connection.readyState === 0) {
-        await mongoose_1.default.connect(uri);
+    if (mongoose_types_1.default.connection.readyState === 0) {
+        await mongoose_types_1.default.connect(uri);
     }
-    connection = mongoose_1.default.connection;
+    connection = mongoose_types_1.default.connection;
     return { connection, uri };
 }
 /**
@@ -36,7 +36,7 @@ async function connectMemoryDB() {
 async function disconnectMemoryDB() {
     if (connection) {
         await connection.dropDatabase();
-        await mongoose_1.default.disconnect();
+        await mongoose_types_1.default.disconnect();
         connection = undefined;
     }
     if (mongoServer) {

package/src/lib/mongoose-memory.ts

@@ -0,0 +1,64 @@
+import mongoose, { Connection } from '@digitaldefiance/mongoose-types';
+import { MongoMemoryServer } from 'mongodb-memory-server';
+
+let mongoServer: MongoMemoryServer | undefined;
+let connection: Connection | undefined;
+
+/**
+ * Connect to in-memory MongoDB for testing
+ * @returns Object with both the connection and URI
+ */
+export async function connectMemoryDB(): Promise<{
+  connection: Connection;
+  uri: string;
+}> {
+  // If mongoose is connected but we don't have our server, disconnect first
+  if (mongoose.connection.readyState !== 0 && !mongoServer) {
+    await mongoose.disconnect();
+    connection = undefined;
+  }
+
+  // Create new server if needed
+  if (!mongoServer) {
+    mongoServer = await MongoMemoryServer.create();
+  }
+
+  const uri = mongoServer.getUri();
+
+  // Connect if not already connected
+  if (mongoose.connection.readyState === 0) {
+    await mongoose.connect(uri);
+  }
+
+  connection = mongoose.connection;
+
+  return { connection, uri };
+}
+
+/**
+ * Drop all collections and disconnect
+ */
+export async function disconnectMemoryDB(): Promise<void> {
+  if (connection) {
+    await connection.dropDatabase();
+    await mongoose.disconnect();
+    connection = undefined;
+  }
+
+  if (mongoServer) {
+    await mongoServer.stop();
+    mongoServer = undefined;
+  }
+}
+
+/**
+ * Clear all collections without disconnecting
+ */
+export async function clearMemoryDB(): Promise<void> {
+  if (connection) {
+    const collections = connection.collections;
+    for (const key in collections) {
+      await collections[key].deleteMany({});
+    }
+  }
+}

package/src/lib/react-mocks.ts

@@ -0,0 +1,29 @@
+/**
+ * Mock utilities for React component testing
+ */
+
+/**
+ * Mock timezones for testing
+ */
+export const mockTimezones = [
+  'America/New_York',
+  'America/Los_Angeles',
+  'Europe/London',
+  'Europe/Paris',
+  'Asia/Tokyo',
+  'UTC',
+];
+
+/**
+ * Get initial timezone mock
+ */
+export const mockGetInitialTimezone = (): string => 'UTC';
+
+/**
+ * Mock RegisterForm props
+ */
+export const mockRegisterFormProps = {
+  timezones: mockTimezones,
+  getInitialTimezone: mockGetInitialTimezone,
+  onSubmit: jest.fn().mockResolvedValue({ success: true, message: 'Success' }),
+};

package/src/lib/to-throw-type.ts

@@ -0,0 +1,200 @@
+import { expect } from '@jest/globals';
+import type { MatcherContext } from 'expect';
+import { readFileSync } from 'fs';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type ErrorClass<E extends Error> = new (...args: any[]) => E;
+
+declare global {
+  namespace jest {
+    interface Matchers<R> {
+      toThrowType<E extends Error>(
+        errorType: ErrorClass<E>,
+        validator?: (error: E) => void,
+      ): R;
+    }
+  }
+}
+
+interface MatcherError extends Error {
+  matcherResult?: {
+    expected: unknown;
+    received: unknown;
+  };
+}
+
+function isMatcherError(error: unknown): error is MatcherError {
+  return error instanceof Error && 'matcherResult' in error;
+}
+
+function extractTestInfo(stackTrace: string) {
+  const stackLines = stackTrace.split('\n');
+  const anonymousLine = stackLines.find((line) =>
+    line.includes('Object.<anonymous>'),
+  );
+  const match = anonymousLine?.match(/\((.+?\.spec\.ts):(\d+):(\d+)\)/);
+
+  if (!match) {
+    return { testHierarchy: ['Unknown Test'], location: '' };
+  }
+
+  const fullTestPath = match[1];
+  const lineNumber = parseInt(match[2]);
+  const testFile = fullTestPath.split('/').pop() || '';
+
+  try {
+    const fileContent = readFileSync(fullTestPath, 'utf8');
+    const lines = fileContent.split('\n');
+    const testLineContent = lines[lineNumber - 1];
+    const testNameMatch = testLineContent.match(/it\(['"](.+?)['"]/);
+    const testName = testNameMatch?.[1];
+
+    const testHierarchy = ['Test'];
+    if (testName) {
+      testHierarchy.push(testName);
+    }
+
+    return {
+      testHierarchy,
+      location: ` (${testFile}:${lineNumber})`,
+    };
+  } catch {
+    return {
+      testHierarchy: ['Test'],
+      location: ` (${testFile}:${lineNumber})`,
+    };
+  }
+}
+
+export const toThrowType = async function <E extends Error>(
+  this: MatcherContext,
+  received: (() => unknown | Promise<unknown>) | Promise<unknown>,
+  errorType: ErrorClass<E>,
+  validator?: (error: E) => void,
+): Promise<{ pass: boolean; message: () => string }> {
+  const matcherName = 'toThrowType';
+  const options = {
+    isNot: this.isNot,
+    promise: this.promise,
+  };
+
+  let error: unknown;
+  let pass = false;
+
+  try {
+    if (this.promise) {
+      try {
+        await received;
+        pass = false;
+      } catch (e) {
+        error = e;
+        if (
+          error instanceof Error &&
+          (error instanceof errorType || error.constructor === errorType)
+        ) {
+          pass = true;
+          if (validator) {
+            await validator(error as E);
+          }
+        }
+      }
+    } else {
+      if (typeof received !== 'function') {
+        throw new Error(
+          this.utils.matcherHint(matcherName, undefined, undefined, options) +
+            '\n\n' +
+            'Received value must be a function',
+        );
+      }
+      try {
+        await (received as () => unknown | Promise<unknown>)();
+        pass = false;
+      } catch (e) {
+        error = e;
+        if (
+          error instanceof Error &&
+          (error instanceof errorType || error.constructor === errorType)
+        ) {
+          pass = true;
+          if (validator) {
+            await validator(error as E);
+          }
+        }
+      }
+    }
+  } catch (validatorError) {
+    const error =
+      validatorError instanceof Error
+        ? validatorError
+        : new Error(String(validatorError));
+    const message = error.message;
+    const stack = error.stack || '';
+
+    let diffString: string;
+    if (isMatcherError(error) && error.matcherResult) {
+      diffString =
+        this.utils.diff(
+          error.matcherResult.expected,
+          error.matcherResult.received,
+        ) || '';
+    } else {
+      diffString = this.utils.diff('Error to match assertions', message) || '';
+    }
+
+    const { testHierarchy, location } = extractTestInfo(stack);
+
+    return {
+      pass: false,
+      message: () =>
+        `\n\n${this.utils.RECEIVED_COLOR(
+          `● ${testHierarchy.join(' › ')}${location ? ` ${location}` : ''}`,
+        )}\n\n` +
+        this.utils.matcherHint(matcherName, undefined, undefined, options) +
+        '\n\n' +
+        diffString +
+        '\n\n' +
+        (stack
+          ? this.utils.RECEIVED_COLOR(stack.split('\n').slice(1).join('\n'))
+          : ''),
+    };
+  }
+
+  const testHeader =
+    error instanceof Error && error.stack
+      ? (() => {
+          const { testHierarchy, location } = extractTestInfo(error.stack);
+          return `\n\n${this.utils.RECEIVED_COLOR(
+            `● ${testHierarchy.join(' › ')}${location}`,
+          )}\n\n`;
+        })()
+      : '\n';
+
+  return {
+    pass,
+    message: () =>
+      testHeader +
+      this.utils.matcherHint(matcherName, undefined, undefined, options) +
+      '\n\n' +
+      (pass
+        ? `Expected function not to throw ${this.utils.printExpected(
+            errorType.name,
+          )}`
+        : this.promise
+        ? this.utils.matcherErrorMessage(
+            this.utils.matcherHint(matcherName, undefined, undefined, options),
+            'Expected promise to reject',
+            'Promise resolved successfully',
+          )
+        : this.utils.matcherErrorMessage(
+            this.utils.matcherHint(matcherName, undefined, undefined, options),
+            `Expected function to throw ${this.utils.printExpected(
+              errorType.name,
+            )}`,
+            `Received: ${this.utils.printReceived(
+              error instanceof Error ? error.constructor.name : typeof error,
+            )}`,
+          )),
+  };
+};
+
+expect.extend({ toThrowType });

package/src/lib/types.ts

@@ -0,0 +1,31 @@
+/// <reference types="jest" />
+
+export {};
+
+declare global {
+  namespace jest {
+    interface Matchers<R> {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      toThrowType<E extends Error, T extends new (...args: any[]) => E>(
+        errorType: T,
+        validator?: (error: E) => void,
+      ): R;
+    }
+  }
+}
+
+declare module 'expect' {
+  interface ExpectExtendMap {
+    toThrowType: {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      <E extends Error, T extends new (...args: any[]) => E>(
+        this: jest.MatcherContext,
+        received: () => unknown,
+        errorType: T,
+        validator?: (error: E) => void,
+      ): jest.CustomMatcherResult;
+    };
+  }
+}
+
+