0
# Test Environment Configuration
1

2
Advanced test setup and configuration using MockBuilder for precise control over testing environment. MockBuilder provides a fluent interface for configuring complex test scenarios with fine-grained control over dependencies.
3

4
## Capabilities
5

6
### MockBuilder Function
7

8
Creates a MockBuilder instance with initial keep and mock declarations.
9

10
```typescript { .api }
11
/**
12
 * Creates a MockBuilder instance for configuring test environment
13
 * @param keepDeclaration - Declarations to keep as-is (optional)
14
 * @param itsModuleAndDependenciesToMock - Declarations to mock (optional)
15
 * @returns MockBuilder instance for method chaining
16
 */
17
function MockBuilder(
18
  keepDeclaration?: MockBuilderParam | MockBuilderParam[] | null | undefined,
19
  itsModuleAndDependenciesToMock?: MockBuilderParam | MockBuilderParam[] | null | undefined
20
): IMockBuilderExtended;
21

22
type MockBuilderParam = string | AnyDeclaration<any> | NgModuleWithProviders;
23
```
24

25
**Usage Examples:**
26

27
```typescript
28
import { MockBuilder } from "ng-mocks";
29

30
// Keep component, mock its module
31
const builder = MockBuilder(MyComponent, MyModule);
32

33
// Mock everything in module
34
const builder = MockBuilder(null, MyModule);
35

36
// Keep multiple declarations
37
const builder = MockBuilder([ComponentA, ComponentB], MyModule);
38
```
39

40
### Builder Chain Methods
41

42
The MockBuilder provides a fluent interface with chainable methods for configuration.
43

44
#### Keep Method
45

46
Keeps declarations as they are without mocking them.
47

48
```typescript { .api }
49
/**
50
 * Keeps declarations as they are without mocking
51
 * @param def - Declaration to keep
52
 * @param config - Configuration flags for the kept declaration
53
 * @returns Builder instance for chaining
54
 */
55
keep(def: any, config?: IMockBuilderConfigAll & IMockBuilderConfigModule): this;
56
```
57

58
#### Mock Method
59

60
Mocks declarations with optional customization.
61

62
```typescript { .api }
63
/**
64
 * Mocks a pipe with custom transform function
65
 */
66
mock<T extends PipeTransform>(
67
  pipe: AnyType<T>, 
68
  mock: T['transform'], 
69
  config?: IMockBuilderConfig
70
): this;
71

72
/**
73
 * Mocks a string provider
74
 */
75
mock<T = any>(provider: string, mock: T, config?: IMockBuilderConfig): this;
76

77
/**
78
 * Mocks an injection token
79
 */
80
mock<T>(
81
  token: InjectionToken<T>, 
82
  mock: InjectionToken<T> | T | undefined, 
83
  config?: IMockBuilderConfig
84
): this;
85

86
/**
87
 * Mocks a declaration with partial implementation
88
 */
89
mock<T>(
90
  provider: AnyType<T>, 
91
  mock: AnyType<T> | Partial<T>, 
92
  config?: IMockBuilderConfig & IMockBuilderConfigMock
93
): this;
94

95
/**
96
 * Auto-mocks a declaration
97
 */
98
mock(def: any, config?: IMockBuilderConfig): this;
99
```
100

101
#### Exclude Method
102

103
Excludes declarations from the testing environment.
104

105
```typescript { .api }
106
/**
107
 * Excludes declarations from the testing environment
108
 * @param def - Declaration to exclude
109
 * @returns Builder instance for chaining
110
 */
111
exclude(def: any): this;
112
```
113

114
#### Provide Method
115

116
Adds additional providers to the TestBed.
117

118
```typescript { .api }
119
/**
120
 * Adds additional providers to TestBed
121
 * @param def - Provider to add
122
 * @returns Builder instance for chaining
123
 */
124
provide(def: IMockBuilderProvider): this;
125

126
type IMockBuilderProvider = Provider | { ɵbrand: 'EnvironmentProviders'; };
127
```
128

129
#### Replace Method
130

131
Substitutes one declaration with another.
132

133
```typescript { .api }
134
/**
135
 * Substitutes one declaration with another
136
 * @param source - Original declaration to replace
137
 * @param destination - Replacement declaration
138
 * @param config - Configuration for the replacement
139
 * @returns Builder instance for chaining
140
 */
141
replace(
142
  source: AnyType<any>, 
143
  destination: AnyType<any>, 
144
  config?: IMockBuilderConfigAll & IMockBuilderConfigModule
145
): this;
146
```
147

148
#### Build Method
149

150
Returns TestModuleMetadata for use with TestBed.
151

152
```typescript { .api }
153
/**
154
 * Returns TestModuleMetadata for use with TestBed
155
 * @returns TestModuleMetadata that can be used with TestBed.configureTestingModule
156
 */
157
build(): TestModuleMetadata;
158
```
159

160
#### BeforeCompileComponents Method
161

162
Allows extending TestBed before component compilation.
163

164
```typescript { .api }
165
/**
166
 * Allows extending TestBed before component compilation
167
 * @param callback - Function to modify TestBed
168
 * @returns Builder instance for chaining
169
 */
170
beforeCompileComponents(callback: (testBed: TestBedStatic) => void): this;
171
```
172

173
### Configuration Flags
174

175
Configuration flags control how declarations are handled in the test environment.
176

177
```typescript { .api }
178
interface IMockBuilderConfigAll {
179
  /** Whether to treat as dependency */
180
  dependency?: boolean;
181
  /** Whether to export from module */
182
  export?: boolean;
183
  /** Whether to use shallow rendering */
184
  shallow?: boolean;  
185
  /** Whether to provide on root injector */
186
  onRoot?: boolean;
187
}
188

189
interface IMockBuilderConfigModule {
190
  /** Whether to export all module declarations */
191
  exportAll?: boolean;
192
}
193

194
interface IMockBuilderConfigComponent {
195
  /** Render configuration for component templates */
196
  render?: {
197
    [blockName: string]: boolean | {
198
      $implicit?: any;
199
      variables?: Record<keyof any, any>;
200
    };
201
  };
202
}
203

204
interface IMockBuilderConfigDirective {
205
  /** Render configuration for structural directives */
206
  render?: boolean | {
207
    $implicit?: any;
208
    variables?: Record<keyof any, any>;
209
  };
210
}
211

212
interface IMockBuilderConfigMock {
213
  /** Whether to use precise mocking */
214
  precise?: boolean;
215
}
216
```
217

218
### Extension System
219

220
MockBuilder supports custom extensions for reusable configuration patterns.
221

222
```typescript { .api }
223
namespace MockBuilder {
224
  /**
225
   * Adds a custom function to MockBuilder
226
   * @param func - Function name to add
227
   * @param callback - Implementation function
228
   */
229
  function extend<K extends keyof IMockBuilderExtended & string>(
230
    func: K,
231
    callback: (builder: IMockBuilderExtended, parameters: never) => void
232
  ): void;
233

234
  /**
235
   * Removes a custom function from MockBuilder
236
   * @param func - Function name to remove
237
   */
238
  function extend<K extends keyof IMockBuilderExtended & string>(func: K): void;
239
}
240

241
interface IMockBuilderExtended extends IMockBuilder {}
242
```
243

244
**Usage Examples:**
245

246
```typescript
247
import { MockBuilder } from "ng-mocks";
248

249
// Basic usage with keep and mock
250
const setup = MockBuilder(MyComponent, MyModule)
251
  .keep(SharedService)
252
  .mock(HttpClient, { get: () => of({ data: 'test' }) })
253
  .exclude(ProblematicModule);
254

255
// Using with TestBed
256
beforeEach(() => setup);
257

258
// Advanced configuration with flags
259
MockBuilder(MyComponent, MyModule)
260
  .keep(AuthService, { export: true })
261
  .mock(ApiService, { precise: true })
262
  .provide({ provide: API_URL, useValue: 'http://test-api.com' })
263
  .replace(BrowserAnimationsModule, NoopAnimationsModule);
264

265
// Using build() method for manual TestBed setup
266
const moduleMetadata = MockBuilder(MyComponent, MyModule).build();
267
TestBed.configureTestingModule(moduleMetadata);
268
```
269

270
### Result Interface
271

272
The MockBuilder promise resolves to a result containing the configured TestBed.
273

274
```typescript { .api }
275
interface IMockBuilderResult {
276
  /** The configured TestBed instance */
277
  testBed: TestBedStatic;
278
}
279
```