|
| 1 | +--- |
| 2 | +id: rule-tester |
| 3 | +sidebar_label: rule-tester |
| 4 | +--- |
| 5 | + |
| 6 | +import CodeBlock from '@theme/CodeBlock'; |
| 7 | + |
| 8 | +# `@typescript-eslint/rule-tester` |
| 9 | + |
| 10 | +> A utility for testing ESLint rules |
| 11 | +
|
| 12 | +This is a fork of ESLint's built-in `RuleTester` to provide some better types and additional features for testing TypeScript rules. |
| 13 | + |
| 14 | +## Usage |
| 15 | + |
| 16 | +For non-type-aware rules you can test them as follows: |
| 17 | + |
| 18 | +```ts |
| 19 | +import { RuleTester } from '@typescript-eslint/rule-tester'; |
| 20 | +import rule from '../src/rules/my-rule.ts'; |
| 21 | + |
| 22 | +const ruleTester = new RuleTester({ |
| 23 | + parser: '@typescript-eslint/parser', |
| 24 | +}); |
| 25 | + |
| 26 | +ruleTester.run('my-rule', rule, { |
| 27 | + valid: [ |
| 28 | + // valid tests can be a raw string, |
| 29 | + 'const x = 1;', |
| 30 | + // or they can be an object |
| 31 | + { |
| 32 | + code: 'const y = 2;', |
| 33 | + options: [{ ruleOption: true }], |
| 34 | + }, |
| 35 | + |
| 36 | + // you can enable JSX parsing by passing parserOptions.ecmaFeatures.jsx = true |
| 37 | + { |
| 38 | + code: 'const z = <div />;', |
| 39 | + parserOptions: { |
| 40 | + ecmaFeatures: { |
| 41 | + jsx: true, |
| 42 | + }, |
| 43 | + }, |
| 44 | + }, |
| 45 | + ], |
| 46 | + invalid: [ |
| 47 | + // invalid tests must always be an object |
| 48 | + { |
| 49 | + code: 'const a = 1;', |
| 50 | + // invalid tests must always specify the expected errors |
| 51 | + errors: [ |
| 52 | + { |
| 53 | + messageId: 'ruleMessage', |
| 54 | + // If applicable - it's recommended that you also assert the data in |
| 55 | + // addition to the messageId so that you can ensure the correct message |
| 56 | + // is generated |
| 57 | + data: { |
| 58 | + placeholder1: 'a', |
| 59 | + }, |
| 60 | + }, |
| 61 | + ], |
| 62 | + }, |
| 63 | + |
| 64 | + // fixers can be tested using the output parameter |
| 65 | + { |
| 66 | + code: 'const b = 1;', |
| 67 | + output: 'const c = 1;', |
| 68 | + errors: [ |
| 69 | + /* ... */ |
| 70 | + ], |
| 71 | + }, |
| 72 | + // passing `output = null` will enforce the code is NOT changed |
| 73 | + { |
| 74 | + code: 'const c = 1;', |
| 75 | + output: null, |
| 76 | + errors: [ |
| 77 | + /* ... */ |
| 78 | + ], |
| 79 | + }, |
| 80 | + |
| 81 | + // suggestions can be tested via errors |
| 82 | + { |
| 83 | + code: 'const d = 1;', |
| 84 | + output: null, |
| 85 | + errors: [ |
| 86 | + { |
| 87 | + messageId: 'suggestionError', |
| 88 | + suggestions: [ |
| 89 | + { |
| 90 | + messageId: 'suggestionOne', |
| 91 | + output: 'const e = 1;', |
| 92 | + }, |
| 93 | + ], |
| 94 | + }, |
| 95 | + ], |
| 96 | + }, |
| 97 | + // passing `suggestions = null` will enforce there are NO suggestions |
| 98 | + { |
| 99 | + code: 'const d = 1;', |
| 100 | + output: null, |
| 101 | + errors: [ |
| 102 | + { |
| 103 | + messageId: 'noSuggestionError', |
| 104 | + suggestions: null, |
| 105 | + }, |
| 106 | + ], |
| 107 | + }, |
| 108 | + ], |
| 109 | +}); |
| 110 | +``` |
| 111 | + |
| 112 | +### Type-Aware Testing |
| 113 | + |
| 114 | +Type-aware rules can be tested in almost exactly the same way, except you need to create some files on disk. |
| 115 | +We require files on disk due to a limitation with TypeScript in that it requires physical files on disk to initialize the project. |
| 116 | +We suggest creating a `fixture` folder nearby that contains three files: |
| 117 | + |
| 118 | +1. `file.ts` - this should be an empty file. |
| 119 | +2. `react.tsx` - this should be an empty file. |
| 120 | +3. `tsconfig.json` - this should be the config to use for your test, for example: |
| 121 | + ```json |
| 122 | + { |
| 123 | + "compilerOptions": { |
| 124 | + "strict": true |
| 125 | + }, |
| 126 | + "include": ["file.ts", "react.tsx"] |
| 127 | + } |
| 128 | + ``` |
| 129 | + |
| 130 | +:::caution |
| 131 | +It's important to note that both `file.ts` and `react.tsx` must both be empty files! |
| 132 | +The rule tester will automatically use the string content from your tests - the empty files are just there for initialization. |
| 133 | +::: |
| 134 | + |
| 135 | +You can then test your rule by providing the type-aware config: |
| 136 | + |
| 137 | +```ts |
| 138 | +const ruleTester = new RuleTester({ |
| 139 | + parser: '@typescript-eslint/parser', |
| 140 | + // Added lines start |
| 141 | + parserOptions: { |
| 142 | + tsconfigRootDir: './path/to/your/folder/fixture', |
| 143 | + project: './tsconfig.json', |
| 144 | + }, |
| 145 | + // Added lines end |
| 146 | +}); |
| 147 | +``` |
| 148 | + |
| 149 | +With that config the parser will automatically run in type-aware mode and you can write tests just like before. |
| 150 | + |
| 151 | +### Test Dependency Constraints |
| 152 | + |
| 153 | +Sometimes it's desirable to test your rule against multiple versions of a dependency to ensure backwards and forwards compatibility. |
| 154 | +With backwards-compatibility testing there comes a complication in that some tests may not be compatible with an older version of a dependency. |
| 155 | +For example - if you're testing against an older version of TypeScript, certain features might cause a parser error! |
| 156 | + |
| 157 | +import DependencyConstraint from '!!raw-loader!../../packages/rule-tester/src/types/DependencyConstraint.ts'; |
| 158 | + |
| 159 | +<CodeBlock language="ts">{DependencyConstraint}</CodeBlock> |
| 160 | + |
| 161 | +The `RuleTester` allows you to apply dependency constraints at either an individual test or constructor level. |
| 162 | + |
| 163 | +```ts |
| 164 | +const ruleTester = new RuleTester({ |
| 165 | + parser: '@typescript-eslint/parser', |
| 166 | + // Added lines start |
| 167 | + dependencyConstraints: { |
| 168 | + // none of the tests will run unless `my-dependency` matches the semver range `>=1.2.3` |
| 169 | + 'my-dependency': '1.2.3', |
| 170 | + // you can also provide granular semver ranges |
| 171 | + 'my-granular-dep': { |
| 172 | + // none of the tests will run unless `my-granular-dep` matches the semver range `~3.2.1` |
| 173 | + range: '~3.2.1', |
| 174 | + }, |
| 175 | + }, |
| 176 | + // Added lines end |
| 177 | +}); |
| 178 | + |
| 179 | +ruleTester.run('my-rule', rule, { |
| 180 | + valid: [ |
| 181 | + { |
| 182 | + code: 'const y = 2;', |
| 183 | + // Added lines start |
| 184 | + dependencyConstraints: { |
| 185 | + // this test won't run unless BOTH dependencies match the given ranges |
| 186 | + first: '1.2.3', |
| 187 | + second: '3.2.1', |
| 188 | + }, |
| 189 | + // Added lines end |
| 190 | + }, |
| 191 | + ], |
| 192 | + invalid: [ |
| 193 | + /* ... */ |
| 194 | + ], |
| 195 | +}); |
| 196 | +``` |
| 197 | + |
| 198 | +All dependencies provided in the `dependencyConstraints` object must match their given ranges in order for a test to not be skipped. |
| 199 | + |
| 200 | +## Options |
| 201 | + |
| 202 | +### `RuleTester` constructor options |
| 203 | + |
| 204 | +import RuleTesterConfig from '!!raw-loader!../../packages/rule-tester/src/types/RuleTesterConfig.ts'; |
| 205 | + |
| 206 | +<CodeBlock language="ts">{RuleTesterConfig}</CodeBlock> |
| 207 | + |
| 208 | +### Valid test case options |
| 209 | + |
| 210 | +import ValidTestCase from '!!raw-loader!../../packages/rule-tester/src/types/ValidTestCase.ts'; |
| 211 | + |
| 212 | +<CodeBlock language="ts">{ValidTestCase}</CodeBlock> |
| 213 | + |
| 214 | +### Invalid test case options |
| 215 | + |
| 216 | +import InvalidTestCase from '!!raw-loader!../../packages/rule-tester/src/types/InvalidTestCase.ts'; |
| 217 | + |
| 218 | +<CodeBlock language="ts">{InvalidTestCase}</CodeBlock> |
0 commit comments