eslint-plugin-ng-testid 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mihai Ro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,271 @@
+# eslint-plugin-ng-testid
+
+> ESLint plugin that enforces test attributes on interactive elements in Angular templates.
+>
+> Defaults to `data-testid` — configurable to `data-cy`, `data-test`, or any custom attribute.
+
+Stop hunting for why your Playwright / Cypress selectors stopped working. This rule flags every interactive Angular element that is missing a `data-testid` **at lint time**, before the code ever reaches CI.
+
+---
+
+## Features
+
+- ✅ Detects interactive elements by tag, `role`, `tabindex`, event bindings, and `[routerLink]`
+- ✅ Accepts both static (`data-testid="foo"`) and bound (`[attr.data-testid]="expr"`) attributes
+- ✅ Configurable attribute name — use `data-cy`, `data-test`, or any custom attribute
+- ✅ Optional **regex pattern** validation on static values
+- ✅ Optional **strict mode** — rejects opaque dynamic expressions, validates string literals
+- ✅ `allowList` to opt out specific tags project-wide
+- ✅ Ships two ready-made **flat config presets** (`recommended` / `strict`)
+- ✅ Angular 19+ / ESLint 9+ / Flat config only
+
+---
+
+## Requirements
+
+| Peer dependency            | Version   |
+| -------------------------- | --------- |
+| `eslint`                   | `^9.0.0`  |
+| `@angular-eslint/utils`    | `^19.0.0` |
+| `@typescript-eslint/utils` | `^8.0.0`  |
+
+---
+
+## Installation
+
+```bash
+npm install --save-dev eslint-plugin-ng-testid
+```
+
+---
+
+## Usage
+
+### Quickstart — recommended preset
+
+```js
+// eslint.config.js
+import ngTestId from "eslint-plugin-ng-testid";
+
+export default [
+  // ... your other configs
+  ngTestId.configs.recommended, // adds the plugin + turns on the rule as 'error'
+];
+```
+
+### Manual setup
+
+```js
+// eslint.config.js
+import ngTestId from "eslint-plugin-ng-testid";
+
+export default [
+  {
+    plugins: { "ng-testid": ngTestId },
+    rules: {
+      "ng-testid/require-data-testid": "error",
+    },
+  },
+];
+```
+
+---
+
+## Rule: `require-data-testid`
+
+Requires a **non-empty** `data-testid` on every interactive Angular template element that has no interactive descendants.
+
+### What counts as interactive?
+
+| Signal                       | Example                                                |
+| ---------------------------- | ------------------------------------------------------ |
+| Interactive HTML tag         | `<button>`, `<a>`, `<input>`, `<select>`, `<textarea>` |
+| `role` attribute             | `role="button"`, `role="menuitem"`, `role="tab"`, …    |
+| `tabindex` ≠ `-1` and ≠ `""` | `tabindex="0"`                                         |
+| Output / event binding       | `(click)`, `(keydown)`, `(focus)`, …                   |
+| `[routerLink]` input         | `[routerLink]="['/home']"`                             |
+
+### What suppresses the rule?
+
+| Condition                              | Example                                          |
+| -------------------------------------- | ------------------------------------------------ |
+| `disabled` attribute (static or bound) | `<button disabled>` or `<button [disabled]="x">` |
+| `aria-hidden="true"`                   | `<button aria-hidden="true">`                    |
+| `input type="hidden"`                  | `<input type="hidden">`                          |
+| Tag in `allowList`                     | configured per project                           |
+
+Elements wrapped around another interactive element are **exempt** (e.g. a `<label>` containing an `<input>` does not also need a testid).
+
+---
+
+## Options
+
+```ts
+{
+  attribute?:    string;   // default: "data-testid". Use "data-cy", "data-test", etc.
+  pattern?:      string;   // RegExp source — validates static attribute values
+  allowDynamic?: boolean;  // default: true
+  allowList?:    string[]; // tag names to skip entirely
+}
+```
+
+### `attribute` — custom attribute name
+
+Not everyone uses `data-testid`. If your project uses `data-cy`, `data-test`, or any custom attribute, configure it here. The rule name stays `require-data-testid` regardless — it's just a name.
+
+```js
+rules: {
+  'ng-testid/require-data-testid': ['error', {
+    attribute: 'data-cy',
+  }],
+}
+```
+
+```html
+<!-- ✅ passes — data-cy is present -->
+<button data-cy="save-btn">Save</button>
+
+<!-- ❌ fails — data-cy is missing; data-testid is irrelevant when attribute is overridden -->
+<button data-testid="save-btn">Save</button>
+```
+
+### `pattern` — enforce a naming convention
+
+```js
+// eslint.config.js
+rules: {
+  'ng-testid/require-data-testid': ['error', {
+    pattern: '^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$', // kebab-case
+  }],
+}
+```
+
+```html
+<!-- ✅ passes -->
+<button data-testid="save-btn">Save</button>
+
+<!-- ❌ fails: "SaveBtn" does not match pattern -->
+<button data-testid="SaveBtn">Save</button>
+```
+
+### `allowDynamic` — control bound expressions
+
+When `true` (default), any non-empty `[attr.data-testid]` binding is accepted without pattern validation.
+
+When `false`, dynamic expressions that are **string literals** are validated against `pattern`. Non-literal expressions (variables, ternaries, calls) are still accepted.
+
+```js
+rules: {
+  'ng-testid/require-data-testid': ['error', {
+    pattern:      '^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$',
+    allowDynamic: false,
+  }],
+}
+```
+
+```html
+<!-- ✅ literal matches pattern -->
+<button [attr.data-testid]="'save-btn'">Save</button>
+
+<!-- ❌ literal violates pattern -->
+<button [attr.data-testid]="'SaveBtn'">Save</button>
+
+<!-- ✅ non-literal accepted (can't statically validate) -->
+<button [attr.data-testid]="buttonId">Save</button>
+```
+
+### `allowList` — opt out specific tags
+
+Useful for custom component libraries whose button wrapper already enforces testids internally.
+
+```js
+rules: {
+  'ng-testid/require-data-testid': ['error', {
+    allowList: ['my-button', 'app-icon-btn'],
+  }],
+}
+```
+
+```html
+<!-- ✅ tag is on the allowList -->
+<my-button>Save</my-button>
+```
+
+---
+
+## Preset configs
+
+### `recommended`
+
+Turns the rule on as `'error'` with all defaults (`allowDynamic: true`, no pattern, no allowList).
+
+```js
+import ngTestId from "eslint-plugin-ng-testid";
+export default [ngTestId.configs.recommended];
+```
+
+### `strict`
+
+Applies a **kebab-case** pattern and disables opaque dynamic bindings.
+
+Pattern: `^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$`
+
+```js
+import ngTestId from "eslint-plugin-ng-testid";
+export default [ngTestId.configs.strict];
+```
+
+---
+
+## Full example — `eslint.config.js`
+
+```js
+import angular from "angular-eslint";
+import tseslint from "typescript-eslint";
+import ngTestId from "eslint-plugin-ng-testid";
+
+export default tseslint.config(
+  {
+    files: ["**/*.ts"],
+    extends: [...angular.configs.tsRecommended],
+  },
+  {
+    files: ["**/*.html"],
+    extends: [...angular.configs.templateRecommended],
+    plugins: { "ng-testid": ngTestId },
+    rules: {
+      "ng-testid/require-data-testid": [
+        "error",
+        {
+          pattern: "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$",
+          allowDynamic: true,
+          allowList: ["app-submit-button"],
+        },
+      ],
+    },
+  },
+);
+```
+
+---
+
+## Error messages
+
+| Message ID            | When                                                            |
+| --------------------- | --------------------------------------------------------------- |
+| `missingTestId`       | No `data-testid` found, or the value is empty / whitespace-only |
+| `invalidTestIdFormat` | `data-testid` present but fails the `pattern` check             |
+
+---
+
+## Changelog
+
+### 1.0.0
+
+- Initial release
+
+---
+
+## License
+
+MIT © Mihai Ro

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+import type { FlatConfig } from "@typescript-eslint/utils/ts-eslint";
+import { rule, RULE_NAME } from "./rule.js";
+type Plugin = FlatConfig.Plugin & {
+    configs: Record<string, FlatConfig.Config>;
+};
+declare const plugin: Plugin;
+export { rule, RULE_NAME };
+export default plugin;

package/dist/index.js

@@ -0,0 +1,28 @@
+import { rule, RULE_NAME } from "./rule.js";
+const plugin = {
+    meta: {
+        name: "eslint-plugin-ng-testid",
+        version: "1.0.0",
+    },
+    rules: {
+        [RULE_NAME]: rule,
+    },
+    configs: {},
+};
+plugin.configs = {
+    recommended: {
+        plugins: { "ng-testid": plugin },
+        rules: { "ng-testid/require-data-testid": "error" },
+    },
+    strict: {
+        plugins: { "ng-testid": plugin },
+        rules: {
+            "ng-testid/require-data-testid": [
+                "error",
+                { pattern: "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$", allowDynamic: false },
+            ],
+        },
+    },
+};
+export { rule, RULE_NAME };
+export default plugin;

package/dist/rule.d.ts

@@ -0,0 +1,17 @@
+import { ESLintUtils } from "@typescript-eslint/utils";
+export declare const RULE_NAME = "require-data-testid";
+export interface RuleOptions {
+    /**
+     * the attribute name to check. Defaults to "data-testid".
+     * use this if your project uses data-cy, data-test, etc.
+     */
+    attribute?: string;
+    pattern?: string;
+    /**
+     * when true (default), a bound [attr.x] with any non-empty expression
+     * is accepted without pattern validation.
+     */
+    allowDynamic?: boolean;
+    allowList?: string[];
+}
+export declare const rule: ESLintUtils.RuleModule<"missingTestId" | "invalidTestIdFormat" | "invalidPattern", [RuleOptions], unknown, ESLintUtils.RuleListener>;

package/dist/rule.js

@@ -0,0 +1,237 @@
+import { getTemplateParserServices } from "@angular-eslint/utils";
+import { ESLintUtils } from "@typescript-eslint/utils";
+export const RULE_NAME = "require-data-testid";
+// Static lookup sets (module-level, allocated once)
+const INTERACTIVE_TAGS = new Set([
+    "button",
+    "a",
+    "input",
+    "select",
+    "textarea",
+]);
+// Tags that are structural Angular abstractions — never carry DOM attributes
+const SKIP_TAGS = new Set(["ng-template", "ng-container", "ng-content"]);
+const INTERACTIVE_ROLES = new Set([
+    "button",
+    "link",
+    "menuitem",
+    "menuitemcheckbox",
+    "menuitemradio",
+    "tab",
+    "checkbox",
+    "radio",
+    "switch",
+    "option",
+    "treeitem",
+]);
+const INTERACTIVE_EVENTS = new Set([
+    "click",
+    "keydown",
+    "keyup",
+    "keypress",
+    "focus",
+    "blur",
+]);
+// single pass over node.attributes — extracts everything the rule needs.
+function snapshotAttrs(node, testAttr) {
+    let isHiddenInput = false;
+    let isDisabled = false;
+    let isAriaHidden = false;
+    let role;
+    let tabindex;
+    let testIdValue;
+    for (const attr of node.attributes) {
+        switch (attr.name) {
+            case "type":
+                if (node.name === "input" && attr.value === "hidden")
+                    isHiddenInput = true;
+                break;
+            case "disabled":
+                isDisabled = true;
+                break;
+            case "aria-hidden":
+                isAriaHidden = attr.value === "true";
+                break;
+            case "role":
+                role = attr.value;
+                break;
+            case "tabindex":
+                tabindex = attr.value;
+                break;
+            default:
+                if (attr.name === testAttr)
+                    testIdValue = attr.value;
+                break;
+        }
+    }
+    return {
+        isHiddenInput,
+        isDisabled,
+        isAriaHidden,
+        role,
+        tabindex,
+        testIdValue,
+    };
+}
+// [disabled]="expr" binding — checked separately since inputs !== attributes.
+function isDisabledViaBinding(node) {
+    for (const input of node.inputs) {
+        if (input.name === "disabled")
+            return true;
+    }
+    return false;
+}
+function isInteractiveElement(node, snap) {
+    if (snap.isHiddenInput)
+        return false;
+    if (INTERACTIVE_TAGS.has(node.name))
+        return true;
+    if (snap.role && INTERACTIVE_ROLES.has(snap.role))
+        return true;
+    if (snap.tabindex !== undefined &&
+        snap.tabindex !== "-1" &&
+        snap.tabindex !== "")
+        return true;
+    for (const output of node.outputs) {
+        if (INTERACTIVE_EVENTS.has(output.name))
+            return true;
+    }
+    for (const input of node.inputs) {
+        if (input.name === "routerLink")
+            return true;
+    }
+    return false;
+}
+// rule
+export const rule = ESLintUtils.RuleCreator.withoutDocs({
+    name: RULE_NAME,
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Require a non-empty test attribute on interactive Angular template elements",
+        },
+        schema: [
+            {
+                type: "object",
+                properties: {
+                    attribute: { type: "string" },
+                    pattern: { type: "string" },
+                    allowDynamic: { type: "boolean" },
+                    allowList: {
+                        type: "array",
+                        items: { type: "string" },
+                        uniqueItems: true,
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+        messages: {
+            missingTestId: "Interactive element <{{tag}}> is missing a non-empty {{attribute}} attribute.",
+            invalidTestIdFormat: '{{attribute}} "{{value}}" on <{{tag}}> must match the pattern "{{pattern}}".',
+            invalidPattern: 'Option "pattern" is not a valid regular expression: {{error}}',
+        },
+    },
+    defaultOptions: [{}],
+    create(context) {
+        const parserServices = getTemplateParserServices(context);
+        const opts = context.options[0] ?? {};
+        const attribute = opts.attribute ?? "data-testid";
+        const allowDynamic = opts.allowDynamic ?? true;
+        const allowList = opts.allowList ? new Set(opts.allowList) : null;
+        const boundAttrName = `attr.${attribute}`;
+        // validate pattern at rule-creation time so the error is clear and early.
+        // reported via the Program node to avoid a type cast.
+        let testIdRegex = null;
+        let patternError = null;
+        if (opts.pattern) {
+            try {
+                testIdRegex = new RegExp(opts.pattern);
+            }
+            catch (e) {
+                patternError = e.message;
+            }
+        }
+        function getTestIdResult(node, snap) {
+            // static attribute: data-testid="value" (or custom attribute name)
+            if (snap.testIdValue !== undefined) {
+                const value = snap.testIdValue.trim();
+                if (!value)
+                    return { ok: false, reason: "missing" };
+                if (testIdRegex && !testIdRegex.test(value))
+                    return { ok: false, reason: "pattern", value };
+                return { ok: true };
+            }
+            // bound input: [attr.data-testid]="expr" or [data-testid]="expr"
+            for (const input of node.inputs) {
+                if (input.name !== boundAttrName && input.name !== attribute)
+                    continue;
+                const source = input.value?.source?.trim() ?? "";
+                if (!source)
+                    return { ok: false, reason: "missing" };
+                if (allowDynamic)
+                    return { ok: true };
+                // validate string literals even inside bound expressions
+                const literalMatch = /^['"]([^'"]+)['"]/.exec(source);
+                if (literalMatch) {
+                    const value = literalMatch[1];
+                    if (testIdRegex && !testIdRegex.test(value))
+                        return { ok: false, reason: "pattern", value };
+                }
+                return { ok: true };
+            }
+            return { ok: false, reason: "missing" };
+        }
+        return {
+            // use the Program node to surface invalid-pattern errors cleanly,
+            // with a real node reference rather than a bare loc object.
+            Program(node) {
+                if (patternError) {
+                    context.report({
+                        node,
+                        messageId: "invalidPattern",
+                        data: { error: patternError },
+                    });
+                }
+            },
+            Element(node) {
+                if (SKIP_TAGS.has(node.name))
+                    return;
+                if (allowList?.has(node.name))
+                    return;
+                if (patternError)
+                    return; // already reported, don't pile on
+                const snap = snapshotAttrs(node, attribute);
+                if (!isInteractiveElement(node, snap))
+                    return;
+                if (snap.isDisabled || isDisabledViaBinding(node))
+                    return;
+                if (snap.isAriaHidden)
+                    return;
+                const result = getTestIdResult(node, snap);
+                if (result.ok)
+                    return;
+                const loc = parserServices.convertNodeSourceSpanToLoc(node.sourceSpan);
+                if (result.reason === "missing") {
+                    context.report({
+                        loc,
+                        messageId: "missingTestId",
+                        data: { tag: node.name, attribute },
+                    });
+                }
+                else {
+                    context.report({
+                        loc,
+                        messageId: "invalidTestIdFormat",
+                        data: {
+                            tag: node.name,
+                            attribute,
+                            value: result.value,
+                            pattern: opts.pattern,
+                        },
+                    });
+                }
+            },
+        };
+    },
+});

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "eslint-plugin-ng-testid",
+  "version": "1.0.0",
+  "description": "ESLint plugin that enforces data-testid attributes on interactive Angular template elements",
+  "license": "MIT",
+  "author": "Mihai Ro",
+  "homepage": "https://github.com/mihai-ro/eslint-plugin-ng-testid#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mihai-ro/eslint-plugin-ng-testid.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mihai-ro/eslint-plugin-ng-testid/issues"
+  },
+  "keywords": [
+    "eslint",
+    "eslint-plugin",
+    "angular",
+    "testing",
+    "accessibility",
+    "testid",
+    "data-testid",
+    "angular-eslint"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "node --import tsx/esm --test 'tests/**/*.test.ts'",
+    "prepublishOnly": "npm test && npm run build"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "peerDependencies": {
+    "@angular-eslint/utils": ">=19.0.0",
+    "@typescript-eslint/utils": ">=8.0.0",
+    "eslint": ">=9.0.0"
+  },
+  "devDependencies": {
+    "@angular-eslint/template-parser": "^19.0.0",
+    "@angular-eslint/utils": "^19.0.0",
+    "@angular/compiler": "^19.0.0",
+    "@types/node": "^20.0.0",
+    "@typescript-eslint/rule-tester": "^8.0.0",
+    "@typescript-eslint/utils": "^8.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.5.0"
+  }
+}