React Test Attributes

React Test Attributes is a library for React apps that decorates the DOM with custom attributes that can be used to uniquely indentify elements in a page. The main use case is for E2E testing using tools like Cypress or Selenium.

Table Of Contents

• Features
• Installation
• Quick Start
• Usage
  • API
  • Global Configuration
• Contributing
• License

Features

• 🏷 TypeScript support - It is written in TypeScript to make it easier and faster to use the library
• 🍃 Lightweight - Almost zero footprint on your project and no other dependencies required
• 🚀 Production mode - data-* attributes are added to the DOM only when not in production mode
• 🌳 Tree-shakeable - Only the parts you use will be included in your final bundle

Installation

To add this package as a dependency to your app, simply run

npm install react-test-attributes --save

or, if you are using Yarn (as I strongly suggest):

yarn add react-test-attributes

Quick Start

Import React Test Attributes to your React component (note that, since it is the default export of this package, you can name it whatever you want):

import Test from 'react-test-attributes';

Then simply wrap the components you want to decorate:

<Test id="btn-submit">
  <button>Sumbit</button>
</Test>

The resulting DOM will be the following, depending on the value of NODE_ENV environment variable when your project is built:

<!-- NODE_ENV != "production" -->
<button data-testid="btn-submit">Submit</button>

<!-- NODE_ENV == "production" -->
<button>Submit</button>

Usage

API

The Test component accepts the following props:

• id is the value of the added attribute
• suffix is the string to append to "data-" when building the attribute name (default to "testid")
• enableInProductionMode indicates whether or not adding the test attribute in production mode (default to false)

For example, if you want to name the attribute data-tid and give it the value "link-home" you should write:

<Test id="link-home" suffix="tid">
  <a href="/home">Home</a>
</Test>

This produces the following DOM:

<a href="/home" data-tid="link-home">Home</a>

Global Configuration

The context TestAttributesConfig can provide a global configuration to all of its Test descendants.

For example, we can globally override the suffix and enable writing the test attributes also in production mode by doing this:

import Test, { TestAttributesConfig } from 'react-test-attributes';

const App = () => {
  return (
    <TestAttributesConfig
      value={{ suffix: 'tid', enableInProductionMode: true }}
    >
      <Test id="title">
        <h1>I am the title</h1>
      </Test>
      <Test id="link-home">
        <a href="/home">Home</a>
      </Test>
    </TestAttributesConfig>
  );
};

This produces the following DOM:

<h1 data-tid="title">I am the title</h1>
<a href="/home" data-tid="link-home">Home</a>

Contributing

If you find any bug or if you have ideas on how to improve this project, you are more than welcome to open issues and/or making pull requests!

License

Project source code is licensed under the MIT license. You are free to fork this repository, edit the code, share and use it both for non-commercial and commercial purposes.