Jest Testing Extensions

Custom Jest matchers specifically designed for comparing generated code output with intelligent whitespace handling and detailed diff reporting.

Automatic Setup: These Jest extensions are automatically registered when you import @graphql-codegen/testing. No additional setup is required - the matchers become globally available in all test files.

Capabilities

toBeSimilarStringTo Matcher

Custom Jest matcher that normalizes whitespace and performs string comparisons while ignoring formatting differences. Essential for testing generated code where formatting may vary but content should match.

declare global {
  namespace jest {
    interface Matchers<R> {
      /**
       * Normalizes whitespace and performs string comparisons
       * Ignores formatting differences while comparing content
       * @param expected - The expected string to compare against
       * @returns Jest matcher result
       */
      toBeSimilarStringTo(expected: string): R;
    }
  }
}

Functionality:

• Automatically normalizes whitespace using oneLine template tag from common-tags
• Replaces multiple consecutive spaces with single spaces
• Uses stripIndent for better diff display
• Provides detailed diff output when comparisons fail
• Uses jest-diff for enhanced difference visualization

Usage Examples:

import { expect } from '@jest/globals';

// Basic usage - whitespace differences are ignored
expect(`
  export interface User {
    id: string;
    name: string;
  }
`).toBeSimilarStringTo(`export interface User { id: string; name: string; }`);

// Generated code comparison
const generatedCode = await plugin(schema, [], config);
expect(generatedCode.content).toBeSimilarStringTo(`
  export type QueryResolvers = {
    users?: Resolver<User[], {}, Context>;
  };
`);

// Complex code structure comparison
expect(actualResolvers).toBeSimilarStringTo(`
  export type Resolvers<ContextType = any> = {
    Query?: QueryResolvers<ContextType>;
    User?: UserResolvers<ContextType>;
  };
`);

Matcher Implementation Details:

The matcher extends Jest's expect functionality globally and is automatically available once the package is imported. It performs the following steps:

1. Normalization: Both received and expected strings are processed with oneLine to flatten whitespace
2. Space Reduction: Multiple consecutive spaces are replaced with single spaces using regex /\s\s+/g
3. Comparison: Uses a custom comparison function that checks if the normalized received string includes the normalized expected string
4. Diff Generation: On failure, generates detailed diff using jest-diff with stripIndent for cleaner display
5. Error Reporting: Provides clear messages distinguishing between expectation failures and diff availability

Global Registration: The matcher is registered via expect.extend() when the module is imported, making it available in all Jest test files without additional imports.

Error Handling:

When comparisons fail, the matcher provides:

• Clear indication of what was expected vs received
• Detailed diff output when jest-diff can generate meaningful comparisons
• Fallback error messages when diff generation is not available
• Proper Jest test failure integration with descriptive error messages