eslint-plugin-test-complexity

An ESLint plugin that enforces test file existence for complex TypeScript code. Target your business logic directories and ensure files exceeding complexity thresholds have corresponding tests.

Why?

Not all code needs tests. Config files, entry points, and simple utilities often don't warrant dedicated test files. But your business logic - the complex code that handles validation, calculations, and core domain rules - absolutely does.

This plugin lets you target specific directories (like src/domain/ or lib/services/) and enforce that any file exceeding a complexity threshold has a corresponding test file.

Features

• Targeted enforcement - Only check directories you specify (no defaults that lint everything)
• Cyclomatic complexity analysis - Calculates complexity based on decision points (if/else, loops, ternary, logical operators, try/catch, optional chaining)
• Dual thresholds - Configure both per-function and total file complexity limits
• Flexible test file detection - Supports co-located tests and custom directory mappings
• Interface file detection - Optionally skip files following the IFoo.ts naming convention

Installation

npm install eslint-plugin-test-complexity --save-dev

Usage

This plugin requires ESLint 9+ and uses the flat config format.

Important: You must configure includePatterns to specify which directories to check. The rule does nothing until configured.

// eslint.config.js
import testComplexity from 'eslint-plugin-test-complexity';

export default [
  {
    plugins: {
      'test-complexity': testComplexity,
    },
    rules: {
      'test-complexity/require-tests-for-complexity': ['error', {
        // Required: specify which directories contain business logic
        includePatterns: [
          'src/domain/**/*.ts',
          'src/services/**/*.ts',
          'lib/**/*.ts',
        ],
      }],
    },
  },
];

Full Configuration Example

// eslint.config.js
import testComplexity from 'eslint-plugin-test-complexity';

export default [
  {
    plugins: {
      'test-complexity': testComplexity,
    },
    rules: {
      'test-complexity/require-tests-for-complexity': ['error', {
        includePatterns: ['src/domain/**/*.ts', 'src/services/**/*.ts'],
        excludePatterns: ['**/*.test.ts', '**/*.spec.ts', '**/*.d.ts'],
        maxFunctionComplexity: 5,
        maxTotalComplexity: 10,
        testDirectoryMapping: {
          'src': 'tests',
        },
      }],
    },
  },
];

Rule Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | includePatterns | string[] | [] | (Required) Glob patterns for directories to check. The rule does nothing until this is configured. | | excludePatterns | string[] | ['**/*.test.ts', '**/*.spec.ts', '**/*.d.ts', '**/*.test.tsx', '**/*.spec.tsx'] | Glob patterns for files to skip. | | maxFunctionComplexity | number | 5 | Complexity threshold for individual functions. If any function exceeds this, a test file is required. | | maxTotalComplexity | number | 10 | Total complexity threshold for the entire file. If the sum of all function complexities exceeds this, a test file is required. | | excludeInterfaces | boolean | true | Skip interface files matching I[A-Z]*.ts pattern. | | testFileSuffixes | string[] | ['.test.ts', '.spec.ts', '.test.tsx', '.spec.tsx'] | Suffixes to check when looking for test files. | | testDirectoryMapping | object | {} | Maps source directories to test directories (see below). |

Test Directory Mapping

By default, the plugin looks for co-located test files (e.g., Button.test.ts next to Button.ts). Use testDirectoryMapping for separated test directories:

{
  testDirectoryMapping: {
    'src': 'tests',                      // src/utils/foo.ts -> tests/utils/foo.test.ts
    'src/domain/entities': 'tests/unit', // More specific paths take precedence
  }
}

Examples

Fails (no test file)

// src/domain/validator.ts - complexity: 6
function validateUser(user) {
  if (!user) return false;           // +1
  if (!user.name) return false;      // +1
  if (!user.email) return false;     // +1
  if (user.age && user.age < 0) {    // +1, +1
    return false;
  }
  return true;
}

error: File exceeds complexity threshold (max function: 6, total: 6)
       but has no test file. Expected: validator.test.ts

Passes

// src/domain/validator.ts
function validateUser(user) {
  // Same complex code...
}

// src/domain/validator.test.ts (or tests/domain/validator.test.ts with mapping)
describe('validateUser', () => {
  // Tests exist, rule passes
});

Complexity Calculation

The plugin uses cyclomatic complexity, counting these decision points:

| Construct | Complexity | |-----------|------------| | if / else if | +1 each | | case (not default) | +1 each | | for / for...in / for...of | +1 each | | while / do...while | +1 each | | && / \|\| / ?? | +1 each | | Ternary ? : | +1 | | catch | +1 | | Optional chaining ?. | +1 each |

Base complexity for any function is 1.

Development

# Install dependencies
npm install

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Build
npm run build

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests (npm test)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

License

MIT