Registry / testing / eslint-plugin-test-selectors

eslint-plugin-test-selectors

library2.2.0jsnpmunverified

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.

testing

npm install eslint-plugin-test-selectors

package ↗

INSTALL

IMPORT

SIG · ESLINT-PLUGIN-TEST

eslint-plugin-test-selectors

testingjavascriptv2.2.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Plugin enablement

✓ { "plugins": ["test-selectors"] }

✗ import testSelectors from 'eslint-plugin-test-selectors'

ESLint plugins are enabled in the configuration file's `plugins` array, not via JavaScript `import` statements.

Recommended rules

✓ { "extends": ["plugin:test-selectors/recommended"] }

Use this `extends` configuration to enable all default recommended rules, which emit warnings. Use `recommendedWithErrors` for errors.

Individual rule configuration

✓ { "rules": { "test-selectors/button": ["warn", "always"] } }

✗ { "rules": { "test-selectors": "error" } }

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.

Custom `testAttribute` option

✓ { "rules": { "test-selectors/onClick": ["warn", "always", { "testAttribute": ["data-testid", "testId"] }] } }

Since v2.1.0, the `testAttribute` option can accept an array of strings to match multiple valid test attributes for a given rule.

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.

/* .eslintrc.json */ { "env": { "browser": true, "es2021": true }, "extends": [ "eslint:recommended", "plugin:react/recommended", "plugin:test-selectors/recommendedWithErrors" ], "parserOptions": { "ecmaFeatures": { "jsx": true }, "ecmaVersion": 12, "sourceType": "module" }, "plugins": [ "react", "test-selectors" ], "settings": { "react": { "version": "detect" } }, "rules": { "test-selectors/button": ["error", "always", { "testAttribute": ["data-test-id", "data-automation-id"] }] } } /* src/App.jsx */ import React from 'react'; function App() { return ( <div> {/* This button is missing data-test-id or data-automation-id and will cause an ESLint error */} <button onClick={() => console.log('Submit action')}>Submit</button> {/* This anchor is correctly configured */} <a href="#" data-test-id="my-link">Click Me</a> {/* This button is correctly configured */} <button data-automation-id="my-button">Another Button</button> {/* This input type=text is not usually considered interactive by default rules, so no error */} <input type="text" placeholder="Enter text" /> {/* This input type=submit is interactive and needs a test ID */} <input type="submit" onClick={() => alert('submitted')} /> </div> ); } export default App; // To run this example: // 1. Install dependencies: npm install eslint @eslint/js eslint-plugin-react eslint-plugin-test-selectors --save-dev // 2. Save the .eslintrc.json and App.jsx files. // 3. Run ESLint: npx eslint src/App.jsx

Debug

Known issues

breakingVersion 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.

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.

affects: >=2.0.0

gotchaThis 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.

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.

affects: >=1.0.0

securityVersion 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.

fix

Upgrade to `eslint-plugin-test-selectors@2.0.0` or later: `npm install eslint-plugin-test-selectors@latest --save-dev`.

affects: <2.0.0

securityVersion 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.

fix

Upgrade to `eslint-plugin-test-selectors@2.1.0` or later: `npm install eslint-plugin-test-selectors@latest --save-dev`.

affects: <2.1.0

gotchaSince 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.

fix

To utilize multiple test attributes, update your rule configuration from `"testAttribute": "data-test-id"` to `"testAttribute": ["data-test-id", "data-automation-id"]`.

affects: >=2.1.0

Errors

Common errors & fixes

Error: Failed to load plugin 'test-selectors' declared in '.eslintrc.json': Cannot find module 'eslint-plugin-test-selectors'

The `eslint-plugin-test-selectors` package was not installed, or ESLint cannot locate it due to a mismatch between global and local installations.

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`).

Definition for rule 'test-selectors/button' was not found.

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.

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.

The 'plugins' array in a config file is not allowed to contain 'eslint-plugin-test-selectors'. Please remove it.

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.

fix

Change `"eslint-plugin-test-selectors"` to `"test-selectors"` in the `plugins` array of your `.eslintrc` file.

Upgrade

Version history

2.2.0latest on npm

Audit

Dependencies

eslintrequiredThis is an ESLint plugin and requires ESLint to function as a peer dependency.

Agent activity

2 hits · last 30 days

node

Resources

packagehttps://www.npmjs.com/package/eslint-plugin-test-selectors ↗