Test Environment Configuration

/**
 * Creates a MockBuilder instance for configuring test environment
 * @param keepDeclaration - Declarations to keep as-is (optional)
 * @param itsModuleAndDependenciesToMock - Declarations to mock (optional)
 * @returns MockBuilder instance for method chaining
 */
function MockBuilder(
  keepDeclaration?: MockBuilderParam | MockBuilderParam[] | null | undefined,
  itsModuleAndDependenciesToMock?: MockBuilderParam | MockBuilderParam[] | null | undefined
): IMockBuilderExtended;

type MockBuilderParam = string | AnyDeclaration<any> | NgModuleWithProviders;

import { MockBuilder } from "ng-mocks";

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

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

// Keep multiple declarations
const builder = MockBuilder([ComponentA, ComponentB], MyModule);

/**
 * Keeps declarations as they are without mocking
 * @param def - Declaration to keep
 * @param config - Configuration flags for the kept declaration
 * @returns Builder instance for chaining
 */
keep(def: any, config?: IMockBuilderConfigAll & IMockBuilderConfigModule): this;

/**
 * Mocks a pipe with custom transform function
 */
mock<T extends PipeTransform>(
  pipe: AnyType<T>, 
  mock: T['transform'], 
  config?: IMockBuilderConfig
): this;

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

/**
 * Mocks an injection token
 */
mock<T>(
  token: InjectionToken<T>, 
  mock: InjectionToken<T> | T | undefined, 
  config?: IMockBuilderConfig
): this;

/**
 * Mocks a declaration with partial implementation
 */
mock<T>(
  provider: AnyType<T>, 
  mock: AnyType<T> | Partial<T>, 
  config?: IMockBuilderConfig & IMockBuilderConfigMock
): this;

/**
 * Auto-mocks a declaration
 */
mock(def: any, config?: IMockBuilderConfig): this;

/**
 * Excludes declarations from the testing environment
 * @param def - Declaration to exclude
 * @returns Builder instance for chaining
 */
exclude(def: any): this;

/**
 * Adds additional providers to TestBed
 * @param def - Provider to add
 * @returns Builder instance for chaining
 */
provide(def: IMockBuilderProvider): this;

type IMockBuilderProvider = Provider | { ɵbrand: 'EnvironmentProviders'; };

/**
 * Substitutes one declaration with another
 * @param source - Original declaration to replace
 * @param destination - Replacement declaration
 * @param config - Configuration for the replacement
 * @returns Builder instance for chaining
 */
replace(
  source: AnyType<any>, 
  destination: AnyType<any>, 
  config?: IMockBuilderConfigAll & IMockBuilderConfigModule
): this;

/**
 * Returns TestModuleMetadata for use with TestBed
 * @returns TestModuleMetadata that can be used with TestBed.configureTestingModule
 */
build(): TestModuleMetadata;

/**
 * Allows extending TestBed before component compilation
 * @param callback - Function to modify TestBed
 * @returns Builder instance for chaining
 */
beforeCompileComponents(callback: (testBed: TestBedStatic) => void): this;

interface IMockBuilderConfigAll {
  /** Whether to treat as dependency */
  dependency?: boolean;
  /** Whether to export from module */
  export?: boolean;
  /** Whether to use shallow rendering */
  shallow?: boolean;  
  /** Whether to provide on root injector */
  onRoot?: boolean;
}

interface IMockBuilderConfigModule {
  /** Whether to export all module declarations */
  exportAll?: boolean;
}

interface IMockBuilderConfigComponent {
  /** Render configuration for component templates */
  render?: {
    [blockName: string]: boolean | {
      $implicit?: any;
      variables?: Record<keyof any, any>;
    };
  };
}

interface IMockBuilderConfigDirective {
  /** Render configuration for structural directives */
  render?: boolean | {
    $implicit?: any;
    variables?: Record<keyof any, any>;
  };
}

interface IMockBuilderConfigMock {
  /** Whether to use precise mocking */
  precise?: boolean;
}

namespace MockBuilder {
  /**
   * Adds a custom function to MockBuilder
   * @param func - Function name to add
   * @param callback - Implementation function
   */
  function extend<K extends keyof IMockBuilderExtended & string>(
    func: K,
    callback: (builder: IMockBuilderExtended, parameters: never) => void
  ): void;

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

interface IMockBuilderExtended extends IMockBuilder {}

import { MockBuilder } from "ng-mocks";

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

// Using with TestBed
beforeEach(() => setup);

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

// Using build() method for manual TestBed setup
const moduleMetadata = MockBuilder(MyComponent, MyModule).build();
TestBed.configureTestingModule(moduleMetadata);

interface IMockBuilderResult {
  /** The configured TestBed instance */
  testBed: TestBedStatic;
}