Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/davidcalhoun/eslint-plugin-test-selectors

Enforces that data-test-id attributes are added to interactive DOM elements (JSX) to help with UI testing. JSX only.
https://github.com/davidcalhoun/eslint-plugin-test-selectors

eslint eslint-plugin eslintplugin jsx lint plugin testing ui

Last synced: 3 months ago
JSON representation

Enforces that data-test-id attributes are added to interactive DOM elements (JSX) to help with UI testing. JSX only.

Host: GitHub
URL: https://github.com/davidcalhoun/eslint-plugin-test-selectors
Owner: davidcalhoun
Created: 2018-08-31T23:39:18.000Z (about 6 years ago)
Default Branch: main
Last Pushed: 2023-10-18T13:26:29.000Z (about 1 year ago)
Last Synced: 2024-07-11T13:44:46.303Z (4 months ago)
Topics: eslint, eslint-plugin, eslintplugin, jsx, lint, plugin, testing, ui
Language: JavaScript
Homepage:
Size: 455 KB
Stars: 28
Watchers: 3
Forks: 15
Open Issues: 6
Metadata Files:
- Readme: readme.md
- Changelog: changelog.md

Awesome Lists containing this project

README

# eslint-plugin-test-selectors

[![Downloads][downloads-image]][npm-url]

Enforces that a `data-test-id` attribute is present on interactive DOM elements to help with UI testing.

- ❌ `Download`
- ✅ `Download`

### Example of eslint-plugin-test-selectors running in Visual Studio Code:

![Example of eslint-plugin-test-selectors running in Visual Studio Code](vscode-test-selectors-example.png)

## Selected changelog

[See full changelog](https://github.com/davidcalhoun/eslint-plugin-test-selectors/blob/main/changelog.md)

- `2.1.0` - custom `testAttribute` property now accepts arrays. Also fixes vulnerability in word-wrap.
- `2.0.0` - new `onSubmit` rule (thank you @@jzatt), upgrade to ESLint 8 and Mocha 9, fix moderate security advisory for `chalk/ansi-regex`
- `1.3.0` - Add auto-fix capability to `onClick` (thank you @bkonuwa and @pixelbandito). ([#8](https://github.com/davidcalhoun/eslint-plugin-test-selectors/pull/8))

## Installation

You'll first need to install [ESLint](http://eslint.org), which requires [Node.js](https://nodejs.org) (note that `eslint-plugin-test-selectors` requires Node.js 10+):

```
$ npm i eslint --save-dev
```

Next, install `eslint-plugin-test-selectors`:

```
$ npm install eslint-plugin-test-selectors --save-dev
```

**Note:** If you installed ESLint globally (using the `-g` flag) then you must also install `eslint-plugin-test-selectors` globally.

## Usage

Add `test-selectors` to the plugins section of your `.eslintrc` configuration file. You can omit the `eslint-plugin-` prefix:

```json
{
"plugins": ["test-selectors"]
}
```

If you want to use all the recommended default rules, you can simply add this line to the `extends` section of your `.eslintrc` configuration:

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

By default, this will run all [Supported Rules](#supported-rules) and emit eslint warnings. If you want to be more strict, you can emit eslint errors by instead using `plugin:test-selectors/recommendedWithErrors`.

Another option: you can also selectively enable and disable individual rules in the `rules` section of your `.eslintrc` configuration. For instance, if you only want to enable the `test-selectors/button` rule, skip the `extends` addition above and simply add the following to the `rules` section of your `.eslintrc` configuration:

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

If you like most of the recommended rules by adding the `extends` option above, but find one in particular to be bothersome, you can simply disable it:

```json
{
"rules": {
"test-selectors/anchor": "off"
}
}
```

Note: see [Supported Rules](#supported-rules) below for a full list.

## Custom rule options

All tests can be customized individually by passing an object with one or more of the following properties.

### testAttribute

The default test attribute expected is `data-test-id`, but you can override it with whatever you like. Here is how you would use `data-some-custom-attribute` instead:

```json
{
"rules": {
"test-selectors/onChange": ["warn", "always", { "testAttribute": "data-some-custom-attribute" }]
}
}
```

Note: You can also pass multiple attributes

```json
{
"rules": {
"test-selectors/onChange": ["warn", "always", { "testAttribute": ["data-testid", "testId"] }]
}
}
```

### ignoreDisabled

By default all elements with the `disabled` attribute are ignored, e.g. ``. If you don't want to ignore this attribute, set `ignoreDisabled` to `false`:

```json
{
"rules": {
"test-selectors/onChange": ["warn", "always", { "ignoreDisabled": false }]
}
}
```

### ignoreReadonly

By default all elements with the `readonly` attribute are ignored, e.g. ``. If you don't want to ignore this attribute, set `ignoreReadonly` to `false`:

```json
{
"rules": {
"test-selectors/onChange": ["warn", "always", { "ignoreReadonly": false }]
}
}
```

### htmlOnly

Only supported on `button` rule, this option will exempt React components called Button from the rule.

```json
{
"rules": {
"test-selectors/button": ["warn", "always", { "htmlOnly": true }]
}
}
```

## Supported Rules

- `test-selectors/anchor`
- `test-selectors/button`
- `test-selectors/input`
- `test-selectors/onChange`
- `test-selectors/onClick`
- `test-selectors/onKeyDown`
- `test-selectors/onKeyUp`
- `test-selectors/onSubmit`

## Further Reading

If you don't want these test attributes added in production, you can use something like [babel-plugin-jsx-remove-data-test-id](https://github.com/coderas/babel-plugin-jsx-remove-data-test-id)

Why `data` attributes and not `id` or `class`? Check out some of the following:

- [Decoupling CSS Selectors From Your Tests](https://mixandgo.com/learn/decoupling-css-selectors-from-your-tests)
- [Test your DOM with Data Attributes](https://medium.com/@colecodes/test-your-dom-with-data-attributes-44fccc43ed4b)
- [Something Better than IDs for Identifying Elements in Selenium Tests](https://techblog.constantcontact.com/software-development/a-better-way-to-id-elements-in-selenium-tests/)

[downloads-image]: https://img.shields.io/npm/dm/eslint-plugin-test-selectors.svg?style=flat-square
[npm-url]: https://www.npmjs.com/package/eslint-plugin-test-selectors
[npm-image]: https://img.shields.io/npm/dm/eslint-plugin-test-selectors.svg?style=flat
[i1]: https://github.com/davidcalhoun/eslint-plugin-test-selectors/issues/1
[i2]: https://github.com/davidcalhoun/eslint-plugin-test-selectors/issues/2
[i3]: https://github.com/davidcalhoun/eslint-plugin-test-selectors/issues/3
[i4]: https://github.com/davidcalhoun/eslint-plugin-test-selectors/issues/4