@bitovi/eslint-plugin - An ESLint-specific plugin that contains our custom rules which are specific to Angular projects. It can be combined with any other ESLint plugins in the normal way.
You can learn about how to create your eslint rules by following this walkthrough
When creating eslint rules, you should use AST Explorer.
It's an interactive tool that allows you to view AST as you write your rules. To start creating your rules, you should update your parser and transform configuration options:
Parser: @typescript-eslint/parser
(default is acorn)
Transform: eslint: ESLint v8
(off)
You can view your current parser and transform configuration by looking at the upper right hand corner of the tool.
It is recommended to turn on Prettier (a toggle found at the upper right corner of the bottom left panel once you've turned on your configuration options)
Be sure to restart eslint server whenever you are adding / removing eslint rules from .eslintrc.json
or updating their fix conditions.
While debugging eslint rules, one way to isolate a bug is to create a unit test for that use case. Then you can debug using jest debug to inspect state. It is recommended you install firsttris/vscode-jest-runner so you can quickly run tests for an individual rule and toggle debug mode.
nx test eslint-rules
nx build eslint-rules
nx lint eslint-rules
This allows for visualizing the red squiggly lines involved for eslint errors. We do this by taking advantage of convertAnnotatedSourceToFailureCase()
exported by @angular-eslint/utils
.
The convertAnnotatedSourceToFailureCase()
function from @angular-eslint/utils
provides a way to test ESLint rule failure cases while improving readability and granting additional capabilities not included in the base RuleTester
class.
Calls to convertAnnotatedSourceToFailureCase()
are made within the invalid
array passed to RuleTester.run
, in place of the usual failure objects.
const ruleTester = new ESLintUtils.RuleTester({
parser: '@typescript-eslint/parser',
});
ruleTester.run<MessageIds, unknown[]>(RULE_NAME, rule, {
valid: [],
invalid: [
convertAnnotatedSourceToFailureCase({
/* ... */
}),
],
});
Description
A description
string is a required parameter. This is analogous to the optional name
parameter available in normal invalid
and valid
case objects, and should be written in the same manner as you'd write a unit test description.
Testing Annotations
Passing a string to the annotatedSource
parameter of the function can assert the expected location of the warning underline. This behaves the same way as the code
parameter of valid
and invalid
examples, with the expected annotation location expressed using tildes (~
):
convertAnnotatedSourceToFailureCase({
annotatedSource: `
let myVariable: any;
~~~~~~~~~~~~~~~
`,
});
Note that if your rule provides suggestions or fixes, you must also provide strings showing the result of applying these fixes that have the same indentation and extra line, but with the tildes removed.
Testing Fix Results
If the invalid test case you are authoring is expected to provide a fix, the expected results of that fix should be passed to the annotatedOutput
property. The test case will fail if this is excluded.
You can find examples of this in the tests for angular/event-emitter-has-output
.
Testing Suggestion Results
If the invalid test case you are authoring offers suggestions, you must document the expected message and output of each of these suggestions or the test will fail.
Available suggestions can be tested by populating the suggestions
array with objects providing values for the expected suggestion description (messageId
) and output (output
).
You can find examples of this in the tests for angular/event-emitter-has-output
.