add advanced mocking example

Author: iddan

.github/workflows/ci.yml

@@ -16,6 +16,7 @@ jobs:
       fail-fast: false
       matrix:
         example:
+          - advanced-mock-config
           - inversify-jest
           - inversify-sinon
           - inversify-vitest

README.md

@@ -4,41 +4,47 @@ Real-world examples demonstrating [Suites](https://suites.dev) integration with
 
 ## Examples
 
-| Example                                | DI Framework | Test Runner | Use When                                    |
-|----------------------------------------|--------------|-------------|---------------------------------------------|
-| [nestjs-jest](./nestjs-jest)           | NestJS       | Jest        | NestJS with Jest                            |
-| [nestjs-vitest](./nestjs-vitest)       | NestJS       | Vitest      | NestJS with Vitest                          |
-| [nestjs-sinon](./nestjs-sinon)         | NestJS       | Sinon       | NestJS with Sinon/Mocha                     |
-| [inversify-jest](./inversify-jest)     | InversifyJS  | Jest        | InversifyJS with Jest                       |
-| [inversify-vitest](./inversify-vitest) | InversifyJS  | Vitest      | InversifyJS with Vitest                     |
-| [inversify-sinon](./inversify-sinon)   | InversifyJS  | Sinon       | InversifyJS with Sinon/Mocha                |
+| Example                                        | DI Framework | Test Runner | Use When                                          |
+| ---------------------------------------------- | ------------ | ----------- | ------------------------------------------------- |
+| [nestjs-jest](./nestjs-jest)                   | NestJS       | Jest        | NestJS with Jest                                  |
+| [nestjs-vitest](./nestjs-vitest)               | NestJS       | Vitest      | NestJS with Vitest                                |
+| [nestjs-sinon](./nestjs-sinon)                 | NestJS       | Sinon       | NestJS with Sinon/Mocha                           |
+| [inversify-jest](./inversify-jest)             | InversifyJS  | Jest        | InversifyJS with Jest                             |
+| [inversify-vitest](./inversify-vitest)         | InversifyJS  | Vitest      | InversifyJS with Vitest                           |
+| [inversify-sinon](./inversify-sinon)           | InversifyJS  | Sinon       | InversifyJS with Sinon/Mocha                      |
+| [advanced-mock-config](./advanced-mock-config) | NestJS       | Jest        | Advanced `.mock().final()` and `.impl()` patterns |
 
 ## Choosing an Example
 
 ### By DI Framework
 
 **NestJS**
+
 - Full-featured framework with built-in modules
 - Includes HTTP, validation, configuration
 - Use for: Applications requiring framework features
 
 **InversifyJS**
+
 - Lightweight IoC container
 - Minimal abstractions
 - Use for: Applications requiring less framework overhead
 
 ### By Test Runner
 
 **Jest**
+
 - Includes built-in assertions and mocking
 - Use for: Standard Jest-based projects
 
 **Vitest**
+
 - Faster test execution
 - Native ESM support
 - Use for: Projects requiring faster feedback
 
 **Sinon**
+
 - Works with any assertion library (Chai, Node assert, etc.)
 - Used with Mocha test runner
 - Use for: Projects with specific assertion library requirements
@@ -67,6 +73,7 @@ const { unit, unitRef } = await TestBed.solitary(UserService).compile();
 Test one class in complete isolation. All dependencies are replaced with test doubles.
 
 **When to use:**
+
 - Testing component logic in isolation
 - Controlling all inputs for predictable results
 
@@ -76,14 +83,15 @@ Test one class in complete isolation. All dependencies are replaced with test do
 
 ```typescript
 const { unit, unitRef } = await TestBed.sociable(UserService)
-  .expose(UserValidator)  // Use real validator
+  .expose(UserValidator) // Use real validator
   .expose(UserRepository) // Use real repository
   .compile();
 ```
 
 Test multiple classes together with their real collaborators. External I/O (databases, APIs, file systems) is replaced with test doubles to keep tests fast.
 
 **When to use:**
+
 - Verifying components work together correctly
 - Testing interactions between business logic components
 
@@ -124,10 +132,12 @@ examples/
 ├── nestjs-sinon/         # NestJS with Sinon
 ├── inversify-jest/       # InversifyJS with Jest
 ├── inversify-vitest/     # InversifyJS with Vitest
-└── inversify-sinon/      # InversifyJS with Sinon
+├── inversify-sinon/      # InversifyJS with Sinon
+└── advanced-mock-config/ # Advanced .mock().final() and .impl() patterns
 ```
 
 Each example contains:
+
 - `src/types.ts` - Domain types
 - `src/user.service.ts` - Business logic
 - `src/user.validator.ts` - Validation logic
@@ -153,6 +163,7 @@ Each example contains:
 ### "reflect-metadata" errors (InversifyJS examples)
 
 InversifyJS requires decorator metadata. Configuration is already set in `tsconfig.json` and imports. If errors occur, verify:
+
 - `experimentalDecorators: true` in tsconfig.json
 - `emitDecoratorMetadata: true` in tsconfig.json
 - `import 'reflect-metadata'` at top of test files

advanced-mock-config/README.md

@@ -0,0 +1,121 @@
+# Suites + NestJS + Jest (Advanced Mock Configuration)
+
+Simple user management example demonstrating [Suites](https://suites.dev) with NestJS and Jest, showcasing advanced mock configuration patterns using `.mock().final()` and `.mock().impl()`.
+
+## Prerequisites
+
+- Node.js 18 or higher
+- pnpm installed globally
+
+## What This Demonstrates
+
+- ✅ **Solitary unit tests** - Test UserService in complete isolation
+- ✅ **Sociable unit tests** - Test components together with real validation, mocked I/O
+- ✅ **`.mock().final()`** - Immutable mock configuration with plain functions
+- ✅ **`.mock().impl()`** - Flexible mock configuration with stub functions
+- ✅ **Token injection** - DATABASE_TOKEN as external boundary
+- ✅ **Class injection** - UserValidator and UserRepository
+
+## Running the Example
+
+```bash
+pnpm install
+pnpm test
+```
+
+All tests should pass, demonstrating both testing strategies with advanced mock configuration.
+
+## Project Structure
+
+```
+src/
+├── types.ts                    # User types and interfaces
+├── user.validator.ts           # Validation logic (no dependencies)
+├── user.repository.ts          # Data access (token injection)
+├── user.service.ts             # Business logic (class injections)
+├── user.solitary.spec.ts       # Solitary unit tests with mock config
+└── user.sociable.spec.ts       # Sociable unit tests with mock config
+```
+
+## Mock Configuration Patterns
+
+### `.mock().final()` - Immutable Configuration
+
+Use when you want to **lock down** mock behavior that should never change:
+
+```typescript
+const { unit, unitRef } = await TestBed.solitary(UserService)
+  .mock(UserValidator)
+  .final({
+    // Plain functions - cannot be reconfigured in tests
+    validate: () => ({ isValid: true, errors: [] })
+  })
+  .compile();
+```
+
+**Key characteristics:**
+
+- Functions provided to `.final()` are plain functions, not Jest mocks
+- Behavior is locked - tests cannot use `mockReturnValue()` or similar
+- Call inspection (`toHaveBeenCalled()`) is not available
+- Best for: external services, logging, fixed configuration values
+
+### `.mock().impl()` - Flexible Configuration
+
+Use when you want **sensible defaults** that tests can override:
+
+```typescript
+const { unit, unitRef } = await TestBed.solitary(UserService)
+  .mock(UserValidator)
+  .impl((stubFn) => ({
+    // Stubs - can be reconfigured and inspected in tests
+    validate: stubFn().mockReturnValue({ isValid: true, errors: [] })
+  }))
+  .compile();
+
+// Later in tests, you can override:
+validator.validate.mockReturnValue({ isValid: false, errors: ['Error'] });
+```
+
+**Key characteristics:**
+
+- Uses `stubFn()` factory to create Jest mock functions
+- Behavior is flexible - tests can reconfigure using `mockReturnValue()`, etc.
+- Call inspection (`toHaveBeenCalled()`, `toHaveBeenCalledWith()`) is available
+- Best for: most mocks where different tests need different behaviors
+
+## Comparing Testing Strategies
+
+**When to use `.final()`:**
+
+- External APIs (email, SMS, payments) - prevent accidental real calls
+- Configuration/settings - fixed test environment values
+- Logging/telemetry - consistent, predictable output
+
+**When to use `.impl()`:**
+
+- Database operations - need to simulate different query results
+- Collaborator services - need flexibility for different test scenarios
+- Any mock where behavior needs to vary per-test
+
+## Comparison Table
+
+| Feature                | `.final()`       | `.impl()`         |
+| ---------------------- | ---------------- | ----------------- |
+| Reconfigurable         | ❌ No            | ✅ Yes            |
+| Call inspection        | ❌ No            | ✅ Yes            |
+| Function type          | Plain functions  | Jest stubs        |
+| `mockReturnValue()`    | ❌ Cannot use    | ✅ Can use        |
+| `toHaveBeenCalled()`   | ❌ Cannot use    | ✅ Can use        |
+
+## Related Examples
+
+- [nestjs-jest](../nestjs-jest) - Basic NestJS + Jest example
+- [nestjs-vitest](../nestjs-vitest) - NestJS with Vitest
+- [inversify-jest](../inversify-jest) - InversifyJS with Jest
+
+## Learn More
+
+- [Suites Documentation](https://suites.dev)
+- [Mock Configuration API](https://suites.dev/docs/api-reference/mock-configuration)
+- [Test Doubles Guide](https://suites.dev/docs/guides/test-doubles)

advanced-mock-config/global.d.ts

@@ -0,0 +1,2 @@
+/// <reference types="@suites/doubles.jest/unit" />
+

advanced-mock-config/jest.config.js

@@ -0,0 +1,13 @@
+module.exports = {
+  testEnvironment: 'node',
+  testRegex: '.spec.ts$',
+  transform: {
+    '^.+\\.ts$': ['ts-jest', { isolatedModules: true }]
+  },
+  collectCoverageFrom: [
+    'src/**/*.ts',
+    '!src/**/*.spec.ts',
+    '!src/types.ts'
+  ]
+};
+

advanced-mock-config/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "advanced-mock-config-example",
+  "version": "0.0.0",
+  "private": true,
+  "description": "Suites Advanced Mock Configuration Example - .mock().final() and .mock().impl()",
+  "scripts": {
+    "test": "tsc --noEmit && jest"
+  },
+  "dependencies": {
+    "@nestjs/common": "^10.4.15",
+    "@nestjs/core": "^10.4.15",
+    "reflect-metadata": "^0.2.2"
+  },
+  "devDependencies": {
+    "@suites/di.nestjs": "^3.0.1",
+    "@suites/doubles.jest": "^3.0.1",
+    "@suites/unit": "^3.0.1",
+    "@types/jest": "^29.5.13",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.2.5",
+    "typescript": "^5.7.2"
+  },
+  "packageManager": "pnpm@9.15.4+sha512.b2dc20e2fc72b3e18848459b37359a32064663e5627a51e4c74b2c29dd8e8e0491483c3abb40789cfd578bf362fb6ba8261b05f0387d76792ed6e23ea3b1b6a0"
+}
+