0
# TypeScript ESLint Rule Tester
1

2
The @typescript-eslint/rule-tester package provides comprehensive tooling for testing ESLint rules, specifically designed for TypeScript-ESLint rules. It offers a RuleTester class that extends ESLint's native rule testing capabilities with enhanced TypeScript support, including type-aware rule testing, complex configuration validation, and sophisticated test case management with support for both valid and invalid test scenarios.
3

4
## Package Information
5

6
- **Package Name**: @typescript-eslint/rule-tester
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @typescript-eslint/rule-tester`
10

11
## Core Imports
12

13
```typescript
14
import { RuleTester, noFormat } from "@typescript-eslint/rule-tester";
15
import type { 
16
  RuleTesterConfig, 
17
  ValidTestCase, 
18
  InvalidTestCase,
19
  RunTests 
20
} from "@typescript-eslint/rule-tester";
21
```
22

23
For CommonJS:
24

25
```javascript
26
const { RuleTester, noFormat } = require("@typescript-eslint/rule-tester");
27
```
28

29
## Basic Usage
30

31
```typescript
32
import { RuleTester } from "@typescript-eslint/rule-tester";
33
import { myCustomRule } from "./my-custom-rule";
34

35
// Create a rule tester instance
36
const ruleTester = new RuleTester({
37
  languageOptions: {
38
    parserOptions: {
39
      project: "./tsconfig.json",
40
    },
41
  },
42
});
43

44
// Test your rule
45
ruleTester.run("my-custom-rule", myCustomRule, {
46
  valid: [
47
    // Valid test cases
48
    "const x = 1;",
49
    {
50
      code: "function foo(): number { return 1; }",
51
      languageOptions: {
52
        parserOptions: {
53
          project: "./tsconfig.json",
54
        },
55
      },
56
    },
57
  ],
58
  invalid: [
59
    // Invalid test cases
60
    {
61
      code: "var x = 1;",
62
      errors: [{ messageId: "noVar" }],
63
      output: "const x = 1;",
64
    },
65
  ],
66
});
67
```
68

69
## Architecture
70

71
The Rule Tester is built around several key components:
72

73
- **RuleTester Class**: Central testing engine that manages rule execution and validation
74
- **Test Framework Integration**: Pluggable system supporting Jest, Mocha, and custom test frameworks
75
- **TypeScript Parser Integration**: Built-in @typescript-eslint/parser with type-aware rule testing
76
- **Configuration System**: Extends ESLint's flat config format with TypeScript-specific options
77
- **Validation Engine**: Comprehensive validation using AJV schema validation for test case integrity
78
- **Dependency Constraints**: Conditional test execution based on environment requirements
79

80
## Capabilities
81

82
### Rule Testing Engine
83

84
Core rule testing functionality providing comprehensive test execution, validation, and reporting for ESLint rules.
85

86
```typescript { .api }
87
class RuleTester {
88
  constructor(testerConfig?: RuleTesterConfig);
89
  
90
  run<MessageIds extends string, Options extends readonly unknown[]>(
91
    ruleName: string,
92
    rule: RuleModule<MessageIds, Options>,
93
    test: RunTests<MessageIds, Options>
94
  ): void;
95
  
96
  defineRule(name: string, rule: AnyRuleModule): void;
97
}
98
```
99

100
[Rule Testing Engine](./rule-testing.md)
101

102
### Test Case Configuration
103

104
Comprehensive test case definition system with support for valid and invalid scenarios, autofix testing, and suggestion validation.
105

106
```typescript { .api }
107
interface RunTests<MessageIds extends string, Options extends readonly unknown[]> {
108
  readonly valid: readonly (string | ValidTestCase<Options>)[];
109
  readonly invalid: readonly InvalidTestCase<MessageIds, Options>[];
110
}
111

112
interface ValidTestCase<Options extends readonly unknown[]> {
113
  readonly after?: () => void;
114
  readonly before?: () => void;
115
  readonly code: string;
116
  readonly dependencyConstraints?: DependencyConstraint;
117
  readonly filename?: string;
118
  readonly languageOptions?: TestLanguageOptions;
119
  readonly name?: string;
120
  readonly only?: boolean;
121
  readonly options?: Readonly<Options>;
122
  readonly settings?: Readonly<SharedConfigurationSettings>;
123
  readonly skip?: boolean;
124
}
125

126
interface InvalidTestCase<MessageIds extends string, Options extends readonly unknown[]> 
127
  extends ValidTestCase<Options> {
128
  readonly errors: readonly TestCaseError<MessageIds>[];
129
  readonly output?: string | string[] | null;
130
}
131
```
132

133
[Test Case Configuration](./test-cases.md)
134

135
### Dependency Constraints
136

137
Environment dependency validation system for conditional test execution based on package versions and availability.
138

139
```typescript { .api }
140
type DependencyConstraint = Readonly<Record<string, VersionConstraint>>;
141

142
type VersionConstraint = AtLeastVersionConstraint | SemverVersionConstraint;
143

144
type AtLeastVersionConstraint = 
145
  | `${number}.${number}.${number}-${string}`
146
  | `${number}.${number}.${number}`
147
  | `${number}.${number}`
148
  | `${number}`;
149

150
interface SemverVersionConstraint {
151
  readonly range: string;
152
  readonly options?: boolean | RangeOptions;
153
}
154
```
155

156
[Dependency Constraints](./dependency-constraints.md)
157

158
### Global Configuration
159

160
Static configuration methods for managing default settings across all RuleTester instances.
161

162
```typescript { .api }
163
class RuleTester {
164
  static setDefaultConfig(config: RuleTesterConfig): void;
165
  static getDefaultConfig(): Readonly<RuleTesterConfig>;
166
  static resetDefaultConfig(): void;
167
  static only<Options>(item: string | ValidTestCase<Options>): ValidTestCase<Options>;
168
}
169
```
170

171
[Global Configuration](./global-configuration.md)
172

173
### Utility Functions
174

175
Helper functions for test case formatting and test framework integration.
176

177
```typescript { .api }
178
function noFormat(raw: TemplateStringsArray, ...keys: string[]): string;
179
```
180

181
[Utility Functions](./utilities.md)
182

183
## Core Types
184

185
```typescript { .api }
186
interface RuleTesterConfig extends FlatConfig.Config {
187
  readonly defaultFilenames?: Readonly<{
188
    ts: string;
189
    tsx: string;
190
  }>;
191
  readonly dependencyConstraints?: DependencyConstraint;
192
}
193

194
interface TestLanguageOptions {
195
  readonly parser?: Readonly<Parser.LooseParserModule>;
196
  readonly parserOptions?: Readonly<ParserOptions>;
197
  readonly globals?: Readonly<Linter.GlobalsConfig>;
198
  readonly env?: Readonly<Linter.EnvironmentConfig>;
199
}
200

201
interface TestCaseError<MessageIds extends string> {
202
  readonly messageId: MessageIds;
203
  readonly line?: number;
204
  readonly column?: number;
205
  readonly endLine?: number;
206
  readonly endColumn?: number;
207
  readonly type?: AST_NODE_TYPES | AST_TOKEN_TYPES;
208
  readonly data?: ReportDescriptorMessageData;
209
  readonly suggestions?: readonly SuggestionOutput<MessageIds>[] | null;
210
}
211

212
interface SuggestionOutput<MessageIds extends string> {
213
  readonly messageId: MessageIds;
214
  readonly output: string;
215
  readonly data?: ReportDescriptorMessageData;
216
}
217

218
type SharedConfigurationSettings = Record<string, unknown>;
219
```