eslint-plugin-data-test

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

• ❌ <button>Download</button>
• ✅ <button data-test="download-button">Download</button>

Installation

You'll first need to install ESLint, which requires Node.js. Note that eslint-plugin-data-test requires a version of node that supports object spread syntax (>= 5.12.0, but hopefully, no one is using v5 at this point).

$ npm i eslint --save-dev

Next, install eslint-plugin-data-test:

$ npm install eslint-plugin-data-test --save-dev

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

Usage

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

{
  "plugins": ["data-test"]
}

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

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

By default, this will run all Supported Rules and emit eslint errors.

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 data-test/button rule, skip the extends addition above and simply add the following to the rules section of your .eslintrc configuration:

{
  "rules": {
    "data-test/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:

{
  "rules": {
    "data-test/anchor": "off"
  }
}

Note: see Supported Rules below for a full list.

Custom rule options

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

domAttribute

The default test attribute expected is data-test for raw dom nodes, but you can override it with whatever you like. Here is how you would use data-test-id instead:

{
  "rules": {
    "data-test/onChange": [
      "error",
      "always",
      { "domAttribute": "data-test-id" }
    ]
  }
}

componentAttribute

Since data-test is not a valid javascript variable name, handling this value at the component level can be a nuisance, so you can speficy a separate attribute name for components that pass a data-test down to an underlying dom node. Note that this is mutually exclusive with domAttribute since you can't render a node that is both a dom node and a component at the same time, nor would you typically apply both attributes to the same node. The default value for this is dataTest, but as with domAttribute, you can customize it to whatever you want. For example:

{
  "rules": {
    "data-test/onChange": [
      "error",
      "always",
      { "componentAttribute": "dataTestId" }
    ]
  }
}

Note that this property can only be set on the handler rules (onClick, onChange, etc.) and not on the element rules (button, anchor, etc.) since those rules only apply to dom elements already.

readonly

By default all inputs with the readonly attribute are ignored, e.g. <input readonly />. If you don't want to ignore this attribute, set readonly to true:

{
  "rules": {
    "data-test/input": ["error", "always", { "readonly": true }]
  }
}

This property is only valid on inputs (since readonly is only valid on inputs).

Ignore

Sometimes when working with third parties or in cases where you're abstracting the data-test attribute into the component definition entirely, you will want to ignore certain kinds of elements and components. You can do this with the ignore parameter:

{
  "rules": {
    "data-test/onChange": [
      "error",
      "always",
      { "ignore": "MyComponent" }
    ]
  }
}

In thie case, any uses of MyComponent will not be tested for data-test properties.

Ignore Pattern

Similar, if you have a whole set of components that match a pattern that you want to ignore, you can provide one or more string regex patterns:

{
  "rules": {
    "data-test/onChange": [
      "error",
      "always",
      { "ignorePattern": ".*Component" }
    ]
  }
}

Supported Rules

• data-test/anchor
• data-test/button
• data-test/input
• data-test/onChange
• data-test/onClick
• data-test/onKeyDown
• data-test/onKeyUp
• data-test/onSubmit
• data-test/Link

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

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

• Decoupling CSS Selectors From Your Tests
• Test your DOM with Data Attributes
• Something Better than IDs for Identifying Elements in Selenium Tests