0
# ng-mocks
1

2
ng-mocks is a comprehensive Angular testing library that simplifies unit testing by enabling developers to create mock implementations of components, services, directives, pipes, and modules. It offers shallow rendering capabilities, precise stubbing mechanisms to eliminate child dependencies, and supports both Jasmine and Jest testing frameworks across Angular versions 5-20.
3

4
## Package Information
5

6
- **Package Name**: ng-mocks
7
- **Package Type**: npm  
8
- **Language**: TypeScript
9
- **Installation**: `npm install ng-mocks --save-dev`
10

11
## Core Imports
12

13
```typescript
14
import { 
15
  MockBuilder, 
16
  MockRender, 
17
  MockComponent, 
18
  MockService, 
19
  MockModule,
20
  ngMocks 
21
} from "ng-mocks";
22
```
23

24
For CommonJS:
25

26
```javascript
27
const { 
28
  MockBuilder, 
29
  MockRender, 
30
  MockComponent, 
31
  MockService, 
32
  MockModule,
33
  ngMocks 
34
} = require("ng-mocks");
35
```
36

37
## Basic Usage
38

39
```typescript
40
import { MockBuilder, MockRender, MockComponent, ngMocks } from "ng-mocks";
41

42
// Mock a component for testing
43
@Component({
44
  selector: 'app-test',
45
  template: '<child-component [data]="inputData"></child-component>'
46
})
47
class TestComponent {
48
  inputData = 'test data';
49
}
50

51
// Create mocks and render
52
beforeEach(() => {
53
  return MockBuilder(TestComponent)
54
    .mock(ChildComponent)
55
    .build();
56
});
57

58
it('should render with mocked child', () => {
59
  const fixture = MockRender(TestComponent);
60
  const childEl = ngMocks.find(ChildComponent);
61
  
62
  expect(childEl).toBeDefined();
63
  expect(ngMocks.input(childEl, 'data')).toBe('test data');
64
});
65
```
66

67
## Architecture
68

69
ng-mocks is built around several key architectural patterns:
70

71
- **MockBuilder**: Advanced test environment configuration with fine-grained control over what to keep, mock, or exclude
72
- **Mock Creation Functions**: Individual functions for creating mocks of specific Angular constructs (components, services, etc.)
73
- **MockRender**: Component rendering system that supports both real and string templates with fixture management
74
- **ngMocks Helper**: Comprehensive utility object with 50+ methods for DOM interaction, element queries, and instance access
75
- **MockInstance**: Runtime customization system for modifying mock behavior during test execution
76
- **Type Safety**: Full TypeScript integration with accurate type inference and generic preservation
77

78
## Capabilities
79

80
### Test Environment Configuration
81

82
Advanced test setup and configuration using MockBuilder for precise control over testing environment. Supports dependency management, provider configuration, and module customization.
83

84
```typescript { .api }
85
function MockBuilder(
86
  keepDeclaration?: MockBuilderParam | MockBuilderParam[] | null | undefined,
87
  itsModuleAndDependenciesToMock?: MockBuilderParam | MockBuilderParam[] | null | undefined
88
): IMockBuilderExtended;
89

90
interface IMockBuilder extends Promise<IMockBuilderResult> {
91
  keep(def: any, config?: IMockBuilderConfigAll & IMockBuilderConfigModule): this;
92
  mock(def: any, config?: IMockBuilderConfig): this;
93
  exclude(def: any): this;
94
  provide(def: IMockBuilderProvider): this;
95
  replace(source: AnyType<any>, destination: AnyType<any>, config?: IMockBuilderConfigAll & IMockBuilderConfigModule): this;
96
  build(): TestModuleMetadata;
97
}
98
```
99

100
[Test Environment Configuration](./mock-builder.md)
101

102
### Component Rendering and Testing
103

104
Component rendering system with MockRender for creating test fixtures, accessing component instances, and managing lifecycle. Provides powerful fixture management with type-safe access.
105

106
```typescript { .api }
107
function MockRender<MComponent, TComponent extends object = Record<keyof any, any>>(
108
  template: AnyType<MComponent> | string,
109
  params?: TComponent,
110
  detectChangesOrOptions?: boolean | IMockRenderOptions
111
): MockedComponentFixture<MComponent, TComponent>;
112

113
interface MockedComponentFixture<C = any, F = DefaultRenderComponent<C>> extends ComponentFixture<F> {
114
  point: MockedDebugElement<C>;
115
}
116
```
117

118
[Component Rendering](./mock-render.md)
119

120
### Mock Creation and Management
121

122
Individual mock creation functions for all Angular constructs. Provides precise control over mock behavior and supports both automatic and manual mock configuration.
123

124
```typescript { .api }
125
function MockComponent<T>(component: AnyType<T>): AnyType<T>;
126
function MockService<T>(service: AnyType<T>, overrides?: Partial<T>): T;
127
function MockModule<T>(module: AnyType<T>): AnyType<T>;
128
function MockDirective<T>(directive: AnyType<T>): AnyType<T>;
129
function MockPipe<T>(pipe: AnyType<T>, transform?: any): AnyType<T>;
130
```
131

132
[Mock Creation](./mock-creation.md)
133

134
### Testing Utilities and Helpers
135

136
Comprehensive testing utilities through the ngMocks object. Provides DOM interaction, element queries, instance access, event handling, and validation helpers.
137

138
```typescript { .api }
139
const ngMocks: {
140
  find<T>(component: Type<T>): MockedDebugElement<T>;
141
  findAll<T>(component: Type<T>): Array<MockedDebugElement<T>>;
142
  get<T>(provider: AnyDeclaration<T>): T;
143
  input<T>(elSelector: DebugNodeSelector, input: string): T;
144
  output<T>(elSelector: DebugNodeSelector, output: string): EventEmitter<T>;
145
  click(elSelector: HTMLElement | DebugNodeSelector, payload?: Partial<MouseEvent>): void;
146
  trigger(elSelector: DebugNodeSelector, event: string | Event, payload?: any): void;
147
  stub<T, I>(instance: I, name: keyof I, style?: 'get' | 'set'): T;
148
  // ... 40+ additional utility methods
149
};
150
```
151

152
[Testing Utilities](./testing-utilities.md)
153

154
### Runtime Mock Customization
155

156
Runtime mock instance customization with MockInstance for modifying behavior during test execution. Supports method stubbing, property overrides, and lifecycle management.
157

158
```typescript { .api }
159
function MockInstance<T extends object, K extends keyof T, S extends () => T[K]>(
160
  instance: AnyType<T>,
161
  name: K,
162
  stub: S,
163
  encapsulation: 'get'
164
): S;
165

166
function MockInstance<T extends object, K extends keyof T, S extends T[K]>(
167
  instance: AnyType<T>,
168
  name: K,
169
  stub: S
170
): S;
171

172
function MockReset(...instances: Array<AnyType<any>>): void;
173
```
174

175
[Runtime Customization](./mock-instance.md)
176

177
### Configuration and Global Settings
178

179
Global configuration system for default behaviors, spy integration, and testing framework compatibility. Supports Jasmine, Jest, and custom spy implementations.
180

181
```typescript { .api }
182
const ngMocks: {
183
  autoSpy(type: 'jasmine' | 'jest' | 'default' | 'reset' | CustomMockFunction): void;
184
  defaultConfig<T>(token: string | AnyDeclaration<T>, config?: IMockBuilderConfig): void;
185
  defaultMock<T>(def: AnyType<T>, handler?: (value: T, injector: Injector) => void | Partial<T>, config?: IMockBuilderConfig): void;
186
  globalKeep(source: AnyDeclaration<any>, recursively?: boolean): void;
187
  globalMock(source: AnyDeclaration<any>, recursively?: boolean): void;
188
  globalExclude(source: AnyDeclaration<any>, recursively?: boolean): void;
189
  config(config: { mockRenderCacheSize?: number | null; onMockBuilderMissingDependency?: 'throw' | 'warn' | 'i-know-but-disable' | null; }): void;
190
};
191
```
192

193
[Configuration](./configuration.md)
194

195
### Core Utility Functions
196

197
Essential utility functions for working with Angular declarations and dependency injection.
198

199
```typescript { .api }
200
function getTestBedInjection<T>(token: AnyDeclaration<T>): T;
201
function getInjection<T>(token: AnyDeclaration<T>): T;
202
function getMockedNgDefOf<T>(def: AnyType<T>): T;
203
function getSourceOfMock<T>(def: AnyType<T>): AnyType<T>;
204
function isMockControlValueAccessor(def: any): boolean;
205
function isMockNgDef(def: any): boolean;
206
function isMockOf<T>(mockDef: any, def: AnyType<T>): boolean;
207
function isMockValidator(def: any): boolean;
208
function isMockedNgDefOf<T>(mockDef: any, def: AnyType<T>): boolean;
209
function isNgDef(def: any): boolean;
210
function isNgInjectionToken(def: any): boolean;
211
```
212

213
### Core Classes and Interfaces
214

215
Base classes and interfaces for mock implementations.
216

217
```typescript { .api }
218
class Mock {
219
  // Base mock class with configuration methods
220
}
221

222
class MockControlValueAccessor {
223
  // Mock implementation of ControlValueAccessor
224
}
225

226
class MockValidator {
227
  // Mock implementation of validators
228
}
229

230
class LegacyControlValueAccessor {
231
  // Legacy CVA support
232
}
233
```
234

235
## Types
236

237
```typescript { .api }
238
type AnyType<T> = new (...args: any[]) => T;
239
type AnyDeclaration<T> = AnyType<T> | InjectionToken<T>;
240
type DebugNodeSelector = string | [string] | [string, string | number] | DebugNode | ComponentFixture<any>;
241

242
interface MockedDebugElement<T = any> extends DebugElement {
243
  componentInstance: T;
244
}
245

246
interface MockedDebugNode<T = any> extends DebugNode {
247
  componentInstance: T;
248
}
249

250
interface IMockRenderOptions {
251
  detectChanges?: boolean;
252
  providers?: NgModule['providers'];
253
  reset?: boolean;
254
  viewProviders?: NgModule['providers'];
255
}
256

257
interface IMockBuilderConfig {
258
  dependency?: boolean;
259
  export?: boolean;
260
  shallow?: boolean;
261
  onRoot?: boolean;
262
  exportAll?: boolean;
263
  render?: boolean | { $implicit?: any; variables?: Record<keyof any, any>; };
264
  precise?: boolean;
265
}
266

267
type MockedFunction = (...args: any[]) => any;
268
type CustomMockFunction = (mockName: string) => MockedFunction;
269
```