tessl/npm-jest-preset-angular

Jest preset configuration for Angular projects

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Setup Environment

Name: tessl/npm-jest-preset-angular
Author: tessl

Functions for setting up Angular testing environments with proper TestBed configuration and zone handling for different Angular testing scenarios.

Capabilities

setupZoneTestEnv Function

Sets up Angular testing environment with Zone.js support for traditional Angular applications.

/**
 * Sets up Angular testing environment with Zone.js support
 * @param options - Optional TestBed environment configuration options
 */
function setupZoneTestEnv(options?: TestEnvironmentOptions): void;

interface TestEnvironmentOptions {
  [key: string]: any;
}

Path: 'jest-preset-angular/setup-env/zone'

Usage Examples:

// setup-jest.ts
import 'jest-preset-angular/setup-env/zone';

// Or with custom options
import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone';

// Basic setup (called automatically when importing)
// No manual call needed when using import statement

// Manual setup with options
setupZoneTestEnv({
  // Custom TestBed configuration options
});

Configuration:

// jest.config.js
module.exports = {
  preset: 'jest-preset-angular',
  setupFilesAfterEnv: ['<rootDir>/setup-jest.ts']
};

Features:

Automatically imports and configures Zone.js and Zone.js testing utilities
Initializes Angular TestBed with BrowserDynamicTestingModule
Sets up platformBrowserDynamicTesting platform
Applies text encoding polyfills for Node.js environment
Configures proper test environment options

setupZonelessTestEnv Function

Sets up Angular testing environment for zoneless Angular applications (Angular 18+ experimental feature).

/**
 * Sets up Angular testing environment without Zone.js for zoneless applications
 * @param options - Optional TestBed environment configuration options
 */
function setupZonelessTestEnv(options?: TestEnvironmentOptions): void;

Path: 'jest-preset-angular/setup-env/zoneless'

Usage Examples:

// setup-jest.ts for zoneless Angular app
import 'jest-preset-angular/setup-env/zoneless';

// Or with custom options
import { setupZonelessTestEnv } from 'jest-preset-angular/setup-env/zoneless';

// Manual setup with options
setupZonelessTestEnv({
  // Custom TestBed configuration options for zoneless environment
});

Configuration:

// jest.config.js for zoneless Angular app
module.exports = {
  preset: 'jest-preset-angular',
  setupFilesAfterEnv: ['<rootDir>/setup-jest.ts']
};

Features:

Skips Zone.js import and configuration
Initializes Angular TestBed for zoneless operation
Sets up platformBrowserDynamicTesting without zone patches
Applies text encoding polyfills for Node.js environment
Optimized for Angular applications using zoneless change detection

Environment Setup Utilities

Shared utilities used by both zone and zoneless setup functions.

/**
 * Applies text encoding polyfills for Node.js environment compatibility
 */
function polyfillEncoder(): void;

/**
 * Resolves and validates test environment options
 * @param options - Raw test environment options
 * @returns Processed test environment options
 */
function resolveTestEnvOptions(options?: TestEnvironmentOptions): TestEnvironmentOptions;

Internal Usage: These utilities are automatically called by the setup functions and typically don't need direct usage:

// Used internally by setup functions
polyfillEncoder(); // Ensures TextEncoder/TextDecoder are available
const processedOptions = resolveTestEnvOptions(userOptions);

Global Configuration

The setup environment functions support global configuration through the ngJest global variable.

declare global {
  var ngJest: {
    skipNgcc?: boolean;
    tsconfig?: string;
    testEnvironmentOptions?: TestEnvironmentOptions;
  } | undefined;
}

Usage Examples:

// In test setup or jest configuration
globalThis.ngJest = {
  skipNgcc: true, // Skip Angular Ivy compilation cache
  tsconfig: '<rootDir>/tsconfig.spec.json',
  testEnvironmentOptions: {
    // Custom Angular TestBed options
  }
};

Setup File Configuration

Zone-based Applications (Default):

// setup-jest.ts
import 'jest-preset-angular/setup-env/zone';

// Jest will automatically call setupZoneTestEnv()

Zoneless Applications:

// setup-jest.ts
import 'jest-preset-angular/setup-env/zoneless';

// Jest will automatically call setupZonelessTestEnv()

Manual Setup with Options:

// setup-jest.ts
import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone';

setupZoneTestEnv({
  // Custom TestBed configuration
});

TestBed Integration

Both setup functions configure Angular's TestBed with appropriate modules and platforms:

Zone Setup:

Imports zone.js and zone.js/testing
Uses BrowserDynamicTestingModule
Configures platformBrowserDynamicTesting() with zone support

Zoneless Setup:

Skips zone.js imports
Uses BrowserDynamicTestingModule without zone patches
Configures platformBrowserDynamicTesting() for zoneless operation

Environment Detection

The setup functions automatically handle Node.js environment compatibility:

// Automatic polyfills applied:
// - TextEncoder/TextDecoder for Angular's text processing
// - Proper module resolution for Angular testing utilities
// - Browser API simulation through JSDOM integration

Compatibility

Supported Angular Versions:

Zone-based: Angular 18+, 19+, 20+
Zoneless: Angular 18+ (experimental feature)

Supported Node.js Versions:

Node.js 18.19.1+
Node.js 20.11.1+
Node.js 22.0.0+

Common Setup Patterns

Basic Zone-based Setup:

// jest.config.js
module.exports = {
  preset: 'jest-preset-angular',
  setupFilesAfterEnv: ['<rootDir>/setup-jest.ts']
};

// setup-jest.ts
import 'jest-preset-angular/setup-env/zone';

Advanced Configuration:

// setup-jest.ts
import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone';

// Configure global settings
globalThis.ngJest = {
  testEnvironmentOptions: {
    // Custom TestBed options
  }
};

// Setup with custom options
setupZoneTestEnv({
  // Environment-specific options
});

Error Handling

The setup functions include proper error handling and logging:

// Setup functions will log warnings for:
// - Missing Angular dependencies
// - Incompatible zone configurations
// - Invalid test environment options

All setup is handled automatically when importing the respective modules, making it easy to configure Angular testing environments with minimal boilerplate code.