ESLint Plugin for Angular Test ID Enforcement

1.0.6 verified Thu Apr 23 auth: no javascript

eslint-plugin-angular-test-ids is an ESLint plugin designed to enforce the presence of specific attributes, typically `data-test`, on HTML elements within Angular templates. Currently at version `1.0.6`, this plugin offers a practical solution for development teams where end-to-end testing strategies rely on stable identifiers. While the plugin's author expresses a preference for user-visible labels, it acknowledges the widespread industry need for test IDs often mandated by QA processes. Key differentiators include its deep integration with `@angular-eslint/template-parser` for accurate Angular template analysis and highly flexible configuration options. Users can customize the required attribute name (e.g., `data-test`, `test-id`) and precisely define the list of elements that must include this attribute, supporting both native HTML elements and Angular Material components. This allows teams to tailor enforcement rules to their project's specific requirements, making it a robust tool for maintaining testability in Angular applications.

Common errors

error ESLint: Definition for rule 'angular-test-ids/require-test-id' was not found ↓

cause The 'angular-test-ids' plugin has not been correctly registered in the ESLint configuration's `plugins` array.

fix

Add "angular-test-ids" to the plugins array in your .eslintrc file.

error Parsing error: You have to provide an explicit 'parser' option. ↓

cause ESLint does not know how to parse Angular HTML template files without a specified parser, typically `@angular-eslint/template-parser`.

fix

Ensure that the parser option in your .eslintrc (specifically for HTML files) is set to "@angular-eslint/template-parser".

error Property 'attribute' is not known. ↓

cause Incorrect option name or invalid JSON syntax (e.g., unquoted keys) within the rule options object.

fix

Verify that option names like attribute, overrideElements, and addElements are spelled correctly and enclosed in double quotes as JSON object keys.

Warnings

gotcha This plugin critically relies on `@angular-eslint/template-parser` to correctly process Angular template files. Incorrect parser configuration will prevent rules from running or lead to parsing errors. ↓

fix Ensure your `.eslintrc` file explicitly defines `"parser": "@angular-eslint/template-parser"` for HTML files, or extends a configuration that does, such as `"extends": ["plugin:@angular-eslint/template/recommended"]`.

gotcha The default elements that require a test ID include common native HTML and Angular Material components. If your project uses custom components or other UI libraries, you will need to extend or override this list. ↓

fix Use the `addElements` option to append custom selectors to the default list, or `overrideElements` to replace it entirely, within the `angular-test-ids/require-test-id` rule configuration.

Install

npm install eslint-plugin-angular-test-ids

yarn add eslint-plugin-angular-test-ids

pnpm add eslint-plugin-angular-test-ids

Imports

plugin:angular-test-ids
wrong
```
"plugins": ["@undsoft/eslint-plugin-angular-test-ids"]
```
correct
```
"plugins": ["angular-test-ids"]
```
Registers the plugin within your ESLint configuration, making its rules available for use.
rule:require-test-id
wrong
```
"rules": {"require-test-id": ["error"]}
```
correct
```
"rules": {"angular-test-ids/require-test-id": ["error"]}
```
Enables the primary rule of the plugin to enforce `data-test` attributes on specified elements. The rule must be prefixed with `angular-test-ids/`.

rule:options

wrong

"angular-test-ids/require-test-id": ["error", {attribute: "data-e2e"}]

correct

"angular-test-ids/require-test-id": ["error", {"attribute": "data-e2e", "addElements": ["app-my-component"]}]

Rule options are provided as a JSON object in the second element of the rule's configuration array. Keys must be quoted as per JSON specification.

Quickstart

Configures ESLint in an Angular project to use the `angular-test-ids` plugin, enforcing a custom `data-test-id` attribute on buttons, inputs, and custom `div[role='button']` elements.

{
  "files": ["*.html"],
  "parser": "@angular-eslint/template-parser",
  "plugins": ["angular-test-ids"],
  "rules": {
    "angular-test-ids/require-test-id": [
      "error",
      {
        "attribute": "data-test-id",
        "addElements": ["div[role='button']"]
      }
    ]
  },
  "parserOptions": {
    "ecmaVersion": 2020,
    "sourceType": "module"
  }
}