{"id":13148,"library":"eslint-plugin-test-selectors","title":"ESLint Plugin for Test Selectors","description":"eslint-plugin-test-selectors is an ESLint plugin designed to enforce the presence of specific DOM attributes, such as `data-test-id`, on interactive elements within your application's UI. This is crucial for robust UI testing, allowing test automation tools to reliably select and interact with elements. The plugin is currently on stable version `2.2.0`, with recent updates indicating active maintenance and minor feature development. It supports highly configurable test attributes, allowing users to specify single or multiple attribute names (e.g., `data-testid`, `testId`) for improved flexibility. Key differentiators include its ability to ignore disabled or readonly elements by default, and auto-fix capabilities for certain rules, like `onClick`. It integrates seamlessly with ESLint configurations, offering recommended rule sets (`recommended` and `recommendedWithErrors`) and granular control over individual rules, making it a flexible tool for improving the testability of frontend applications.","status":"active","version":"2.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/davidcalhoun/eslint-plugin-test-selectors#readme","tags":["javascript","eslint","eslintplugin","eslint-plugin","jsx","testing"],"install":[{"cmd":"npm install eslint-plugin-test-selectors","lang":"bash","label":"npm"},{"cmd":"yarn add eslint-plugin-test-selectors","lang":"bash","label":"yarn"},{"cmd":"pnpm add eslint-plugin-test-selectors","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This is an ESLint plugin and requires ESLint to function as a peer dependency.","package":"eslint","optional":false}],"imports":[{"note":"ESLint plugins are enabled in the configuration file's `plugins` array, not via JavaScript `import` statements.","wrong":"import testSelectors from 'eslint-plugin-test-selectors'","symbol":"Plugin enablement","correct":"{ \"plugins\": [\"test-selectors\"] }"},{"note":"Use this `extends` configuration to enable all default recommended rules, which emit warnings. Use `recommendedWithErrors` for errors.","symbol":"Recommended rules","correct":"{ \"extends\": [\"plugin:test-selectors/recommended\"] }"},{"note":"Rules are configured by their full ID (e.g., `test-selectors/button`), combining the plugin name and the specific rule. The plugin name alone is not a valid rule ID.","wrong":"{ \"rules\": { \"test-selectors\": \"error\" } }","symbol":"Individual rule configuration","correct":"{ \"rules\": { \"test-selectors/button\": [\"warn\", \"always\"] } }"},{"note":"Since v2.1.0, the `testAttribute` option can accept an array of strings to match multiple valid test attributes for a given rule.","symbol":"Custom `testAttribute` option","correct":"{ \"rules\": { \"test-selectors/onClick\": [\"warn\", \"always\", { \"testAttribute\": [\"data-testid\", \"testId\"] }] } }"}],"quickstart":{"code":"/* .eslintrc.json */\n{\n  \"env\": {\n    \"browser\": true,\n    \"es2021\": true\n  },\n  \"extends\": [\n    \"eslint:recommended\",\n    \"plugin:react/recommended\",\n    \"plugin:test-selectors/recommendedWithErrors\"\n  ],\n  \"parserOptions\": {\n    \"ecmaFeatures\": {\n      \"jsx\": true\n    },\n    \"ecmaVersion\": 12,\n    \"sourceType\": \"module\"\n  },\n  \"plugins\": [\n    \"react\",\n    \"test-selectors\"\n  ],\n  \"settings\": {\n    \"react\": {\n      \"version\": \"detect\"\n    }\n  },\n  \"rules\": {\n    \"test-selectors/button\": [\"error\", \"always\", { \"testAttribute\": [\"data-test-id\", \"data-automation-id\"] }]\n  }\n}\n\n/* src/App.jsx */\nimport React from 'react';\n\nfunction App() {\n  return (\n    <div>\n      {/* This button is missing data-test-id or data-automation-id and will cause an ESLint error */}\n      <button onClick={() => console.log('Submit action')}>Submit</button>\n      \n      {/* This anchor is correctly configured */}\n      <a href=\"#\" data-test-id=\"my-link\">Click Me</a>\n      \n      {/* This button is correctly configured */}\n      <button data-automation-id=\"my-button\">Another Button</button>\n      \n      {/* This input type=text is not usually considered interactive by default rules, so no error */}\n      <input type=\"text\" placeholder=\"Enter text\" /> \n      \n      {/* This input type=submit is interactive and needs a test ID */}\n      <input type=\"submit\" onClick={() => alert('submitted')} />\n    </div>\n  );\n}\n\nexport default App;\n\n// To run this example:\n// 1. Install dependencies: npm install eslint @eslint/js eslint-plugin-react eslint-plugin-test-selectors --save-dev\n// 2. Save the .eslintrc.json and App.jsx files.\n// 3. Run ESLint: npx eslint src/App.jsx","lang":"javascript","description":"This quickstart demonstrates how to configure `eslint-plugin-test-selectors` in a `.eslintrc.json` file, extending recommended rules to emit errors, and explicitly enabling the `button` rule with custom `testAttribute` options. The accompanying `App.jsx` shows examples of interactive elements that will trigger linting errors (a button and a submit input without one of the specified `data-test-id` or `data-automation-id` attributes) and correctly configured elements."},"warnings":[{"fix":"Upgrade ESLint to `8.5.0` or later (e.g., `npm install eslint@^8 --save-dev`). Review your `package.json` and ensure all related testing dependencies like Mocha are also updated if applicable.","message":"Version 2.0.0 introduced significant breaking changes, primarily requiring an upgrade to ESLint v8.5.0 or higher and Mocha v9.1.3 or higher. Projects on older ESLint versions must update their ESLint installation to use `eslint-plugin-test-selectors@2.0.0` or newer.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure your project's Node.js runtime environment is version 10.x or higher. It is recommended to use a Node Version Manager (NVM) to easily manage and switch between Node.js versions.","message":"This plugin requires Node.js v10 or newer. Even if your installed ESLint version might nominally support older Node.js environments, `eslint-plugin-test-selectors` has a stricter requirement. Using an unsupported Node.js version may lead to installation or runtime errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade to `eslint-plugin-test-selectors@2.0.0` or later: `npm install eslint-plugin-test-selectors@latest --save-dev`.","message":"Version 2.0.0 fixed a moderate security advisory in a transitive dependency, `chalk/ansi-regex`. Projects using versions prior to 2.0.0 are vulnerable to this issue and are strongly advised to upgrade.","severity":"security","affected_versions":"<2.0.0"},{"fix":"Upgrade to `eslint-plugin-test-selectors@2.1.0` or later: `npm install eslint-plugin-test-selectors@latest --save-dev`.","message":"Version 2.1.0 addressed a vulnerability in the `word-wrap` dependency. Users on versions prior to 2.1.0 should upgrade to ensure they receive this security patch.","severity":"security","affected_versions":"<2.1.0"},{"fix":"To utilize multiple test attributes, update your rule configuration from `\"testAttribute\": \"data-test-id\"` to `\"testAttribute\": [\"data-test-id\", \"data-automation-id\"]`.","message":"Since version 2.1.0, the `testAttribute` option in rule configurations now supports an array of strings, allowing you to specify multiple valid test attributes for a single rule. While single string configurations remain backwards compatible, leverage the array option for enhanced flexibility in identifying test selectors.","severity":"gotcha","affected_versions":">=2.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `eslint-plugin-test-selectors` is installed as a dev dependency (`npm install eslint-plugin-test-selectors --save-dev`) in your project. If ESLint is installed globally, the plugin must also be installed globally (`npm install -g eslint-plugin-test-selectors`).","cause":"The `eslint-plugin-test-selectors` package was not installed, or ESLint cannot locate it due to a mismatch between global and local installations.","error":"Error: Failed to load plugin 'test-selectors' declared in '.eslintrc.json': Cannot find module 'eslint-plugin-test-selectors'"},{"fix":"Add `\"test-selectors\"` to the `plugins` array in your `.eslintrc` file and verify the rule name (e.g., `\"test-selectors/button\"`) is exactly correct.","cause":"The plugin is not correctly listed in the `plugins` array of your `.eslintrc` configuration, or the rule ID is misspelled, or the plugin's rules are not correctly loaded.","error":"Definition for rule 'test-selectors/button' was not found."},{"fix":"Change `\"eslint-plugin-test-selectors\"` to `\"test-selectors\"` in the `plugins` array of your `.eslintrc` file.","cause":"You have added the full npm package name (`eslint-plugin-test-selectors`) instead of the required shorthand (`test-selectors`) to the `plugins` array in your `.eslintrc` configuration.","error":"The 'plugins' array in a config file is not allowed to contain 'eslint-plugin-test-selectors'. Please remove it."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}