babel-plugin-react-data-testid-generator
v0.3.2TypeScript
Enhanced babel plugin for automatic React data-testid generation with unique IDs and class component support
0/weekUpdated 8 months agoMITUnpacked: 22.0 KB
Published by Or Kazaz
npm install babel-plugin-react-data-testid-generatorbabel-plugin-react-data-testid-generator
> 🧪 Enhanced Babel plugin for automatic React data-testid generation with unique IDs and comprehensive component support
Automatically adds data-testid attributes to your React components during the build process, making it easier to write reliable end-to-end tests. Features component-scoped unique counters for predictable, collision-free test IDs.
✨ Features
- 🎯 Automatic data-testid generation for functional and class components
- 🔢 Component-scoped unique counters to prevent ID conflicts
- 📊 Predictable naming like ComponentName.element, ComponentName.element2
- 🎭 Full React support: Functional components, arrow functions, class components
- 🔧 Customizable attributes (data-testid, data-cy, data-test-id, etc.)
- 🚀 Zero configuration - works out of the box
- 📦 TypeScript support with full type definitions
- 🌐 Framework agnostic - works with Next.js, Vite, CRA, and more
- 🔄 JSX member expressions support (Modal.Header → ComponentName.Header)
- 🛡️ Never overrides existing attributes
🚀 Installation
``bash`
npm install --save-dev babel-plugin-react-data-testid-generatoror
yarn add --dev babel-plugin-react-data-testid-generator
📖 Usage
$3
Add the plugin to your .babelrc.json or babel.config.js:
`json`
{
"plugins": ["babel-plugin-react-data-testid-generator"]
}
$3
🚀 Next.js
Create .babelrc.json in your project root:
`json`
{
"presets": ["next/babel"],
"plugins": [
[
"babel-plugin-react-data-testid-generator",
{
"attributes": ["data-testid"]
}
]
]
}
⚡ Vite
Configure in vite.config.js:
`javascript
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
export default defineConfig({
plugins: [
react({
babel: {
plugins: [
[
"babel-plugin-react-data-testid-generator",
{
attributes: ["data-testid"],
},
],
],
},
}),
],
});
`
📦 Create React App
Note: CRA v5+ ignores custom babel configs. Use Next.js or Vite instead, or eject from CRA.
For ejected CRA, add to babel.config.js:
`javascript`
module.exports = {
presets: ["react-app"],
plugins: [
[
"babel-plugin-react-data-testid-generator",
{
attributes: ["data-testid"],
},
],
],
};
$3
`json`
{
"plugins": [
[
"babel-plugin-react-data-testid-generator",
{
"attributes": ["data-testid", "data-cy"]
}
]
]
}
🔄 Transformations
$3
Before:
`jsx`
function UserCard({ name }) {
return (
{name}
);
}
After:
`jsx`
function UserCard({ name }) {
return (
{name}
);
}
$3
The plugin uses component-scoped counters to ensure uniqueness:
`jsx`
function FormComponent() {
return (
{" "}
{/ FormComponent.div /}
First {/ FormComponent.div2 /}
Second {/ FormComponent.div3 /}
{/ FormComponent.button /}
{/ FormComponent.button2 /}
);
}
$3
`jsx`
function ModalComponent() {
return (
{" "}
{/ ModalComponent.Container /}
);
}
$3
`jsx`
class TodoList extends React.Component {
render() {
return (
{" "}
{/ TodoList.div /}
My Todos
{/ TodoList.h2 /}
{" "}
{/ TodoList.ul /}
{/ TodoList.button /}
);
}
}
$3
`jsx`
function ConditionalComponent({ isLoggedIn }) {
if (isLoggedIn) {
return Welcome; // ConditionalComponent.div
}
return Please login; // ConditionalComponent.div2
}
⚙️ Configuration Options
| Option | Type | Default | Description |
| ------------ | ---------- | ----------------- | ------------------------------------------- |
| attributes | string[] | ["data-testid"] | Array of attribute names to add to elements |
$3
Multiple testing frameworks:
`json`
{
"plugins": [
[
"babel-plugin-react-data-testid-generator",
{
"attributes": ["data-testid", "data-cy", "data-test-id"]
}
]
]
}
Cypress only:
`json`
{
"plugins": [
[
"babel-plugin-react-data-testid-generator",
{
"attributes": ["data-cy"]
}
]
]
}
Disable plugin:
`json`
{
"plugins": [
[
"babel-plugin-react-data-testid-generator",
{
"attributes": []
}
]
]
}
🧪 Testing Integration
$3
`javascript
import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import UserCard from "./UserCard";
test("should interact with generated test ids", async () => {
render(
// Predictable test IDs
const followButton = screen.getByTestId("UserCard.button");
const messageButton = screen.getByTestId("UserCard.button2");
await userEvent.click(followButton);
expect(screen.getByTestId("UserCard.div")).toBeInTheDocument();
});
`
$3
`javascript
describe("UserCard Component", () => {
it("should interact with elements", () => {
cy.mount(
// Use generated data-cy attributes
cy.get('[data-cy="UserCard.button"]').click();
cy.get('[data-cy="UserCard.button2"]').should("be.visible");
});
});
`
$3
`javascript
import { test, expect } from "@playwright/test";
test("user card interactions", async ({ page }) => {
await page.goto("/user-profile");
// Reliable selectors with generated IDs
await page.locator('[data-testid="UserCard.button"]').click();
await expect(page.locator('[data-testid="UserCard.div"]')).toBeVisible();
});
`
📁 Example Applications
We provide two complete example applications demonstrating the plugin:
$3
`bash`
cd example/babelrc
npm install
npm run dev
Features:
- Next.js 13+ with App Router
- Beautiful modern UI with animations
- Interactive components demonstrating test ID generation
- Open http://localhost:3000
$3
`bash`
cd example/vite
npm install
npm run dev
Features:
- Vite with React 18
- Lightning-fast HMR
- Same UI as Next.js example
- Open http://localhost:3001
Both examples include:
- ✅ Interactive forms and buttons
- ✅ Modal components
- ✅ Card layouts
- ✅ Class and functional components
- ✅ Conditional rendering
- ✅ JSX member expressions
Inspect the DOM to see the automatically generated data-testid attributes!
🛠️ Supported React Patterns
| Pattern | Supported | Example |
| ---------------------- | --------- | ---------------------------------------------- |
| Function Components | ✅ | function MyComponent() {} |const MyComponent = () => {}
| Arrow Functions | ✅ | |class MyComponent extends React.Component {}
| Class Components | ✅ | |export default () => {}
| Anonymous Exports | ⚠️ | (skipped) |
| JSX Member Expressions | ✅ | → ComponentName.Header |<>
| Fragments | ✅ | and |data-testid
| Conditional Rendering | ✅ | Multiple return statements |
| Existing Attributes | ✅ | Never overrides existing |
| Self-Closing Elements | ✅ | , |
| Nested Components | ✅ | Deep nesting with unique counters |
🎯 Best Practices
1. 🏷️ Use PascalCase for component names to get predictable test IDs
2. 🔍 Inspect Generated IDs in development to understand the structure
3. 🌍 Environment-Specific - consider disabling in production:
`javascript
const isProd = process.env.NODE_ENV === "production";
module.exports = {
plugins: [...(!isProd ? [["babel-plugin-react-data-testid-generator"]] : [])],
};
`
4. 🧪 Test ID Patterns - use consistent patterns in tests:
- ComponentName.elementType for first occurrenceComponentName.elementType2
- for second occurrenceComponentName.MemberExpression
- for JSX member expressions
🔧 Development
$3
`bash`
git clone https://github.com/Kazaz-Or/babel-plugin-react-data-testid-generator.git
cd babel-plugin-react-data-testid-generator
yarn install
$3
`bash`
yarn test # Run tests
yarn test:watch # Run tests in watch mode
yarn test:coverage # Run tests with coverage
yarn build # Build the plugin
yarn lint # Lint code
yarn fmt # Format code
$3
The plugin has comprehensive test coverage (96%+) including:
- ✅ 62 test cases covering all React patterns
- ✅ Snapshot testing for consistent output
- ✅ Edge case handling
- ✅ CI/CD with coverage thresholds
🤝 Contributors
Thanks to these wonderful people who have contributed to this project:
 Or Kazaz 🚧 💻 🎨 📖 🤔 |
$3
We welcome contributions! Here are some ways you can help:
- 🐛 Report bugs by opening an issue
- 💡 Suggest features or improvements
- 📖 Improve documentation
- 🧪 Add test cases
- 🔧 Submit pull requests
📋 Contribution Process
1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)yarn test
3. Make your changes and add tests
4. Ensure all tests pass ()git commit -m 'Add amazing feature'
5. Commit your changes ()git push origin feature/amazing-feature
6. Push to the branch ()
7. Open a Pull Request
🤝 Adding Yourself as a Contributor
If you contribute to this project, you can add yourself to the contributors list:
1. Install the all-contributors CLI: npm install -g all-contributors-cli
2. Add yourself:
3. Update the README:
🏷️ Contribution Types
- 💻 code - Code contributionsdoc
- 📖 - Documentationbug
- 🐛 - Bug reportsideas
- 💡 - Ideas and suggestionstest
- 🧪 - Testsdesign
- 🎨 - Designmaintenance
- 🚧 - Maintenanceplatform` - Packaging/platform support
- 📦
📄 License
MIT © Or Kazaz
---
🙏 Acknowledgments
- Inspired by babel-plugin-react-data-testid
Made with 💙 for better testing