DEV Community

Rahul Giri
Rahul Giri

Posted on

Test ID Best Practices Guide: React + TypeScript + Next.js

#programming #react #testing #nextjs

A comprehensive approach to implementing maintainable test identifiers in modern web applications.

🎯 Core Objectives

  • ✅ Minimize test ID usage – prefer semantic selectors first
  • ✅ Implement conflict-free naming patterns
  • ✅ Co-locate test IDs for optimal maintainability
  • ✅ Guarantee uniqueness across large codebases
  • ✅ Eliminate test bloat in production builds

1. When to Use data-testid vs Semantic Selectors

✅ Use data-testid when: 

// Dynamic content without semantic meaning
<div data-testid="order-status-badge">Pending</div>

// Complex component interaction
<div data-testid="drag-drop-source" draggable />
<div data-testid="drag-drop-target" />

// Third-party library components
<DatePicker data-testid="checkout-date-picker" />

// Identical elements
<button data-testid="faq-question-1">+</button>
<button data-testid="faq-question-2">+</button>

// Loading & skeleton states
<div data-testid="product-card-skeleton" />
Enter fullscreen mode Exit fullscreen mode

❌ Avoid data-testid when: 

// Prefer semantic selectors
<button>Login</button>              // getByRole("button", { name: /login/i })
<a href="/checkout">Checkout</a>   // getByRole("link", { name: /checkout/i })
<input placeholder="Email" />      // getByPlaceholderText("Email")

// ARIA labels are enough
<input aria-label="Search" />      // getByRole("textbox", { name: /search/i })
Enter fullscreen mode Exit fullscreen mode

2. Naming Patterns & Recommendations

🔹 Pattern 1: Component-Scoped Kebab-Case (✅ Recommended) 

Format: {component}-{element}-{type}
Enter fullscreen mode Exit fullscreen mode 
data-testid="user-profile-edit-btn"
data-testid="product-card-price-text"
data-testid="checkout-form-submit-btn"
data-testid="navigation-menu-toggle-btn"
data-testid="search-results-filter-dropdown"
Enter fullscreen mode Exit fullscreen mode

Pros: lowest collision rate, refactoring-friendly, grep-able, TypeScript-friendly.
Cons: longer IDs, needs consistent discipline.
👉 Teams report 85% fewer test ID conflicts and 40% faster debugging.

🔹 Pattern 2: Hierarchical Dot Notation 

Format: {domain}.{component}.{element}
Enter fullscreen mode Exit fullscreen mode 
data-testid="auth.login-form.submit-btn"
data-testid="ecommerce.product-grid.filter-btn"
data-testid="admin.user-table.delete-btn"
Enter fullscreen mode Exit fullscreen mode

Pros: clear domain separation, good for micro-frontends.
Cons: tooling issues with dots, harder refactors.

🔹 Pattern 3: BEM-Style 

Format: {block}__{element}--{modifier}
Enter fullscreen mode Exit fullscreen mode 
data-testid="product-card__image--loading"
data-testid="nav-menu__item--active"
data-testid="form-input__field--error"
Enter fullscreen mode Exit fullscreen mode

Pros: captures state variations, matches BEM CSS.
Cons: steep learning curve, verbose, more maintenance.

3. Advanced Co-Location Strategies

Standard Component Layout 

/components
  /UserProfile
    UserProfile.tsx
    UserProfile.test.tsx
    userProfile.testIds.ts   <-- co-located test IDs
Enter fullscreen mode Exit fullscreen mode

Example: Co-located Test IDs 

// userProfile.testIds.ts
export const USER_PROFILE_TEST_IDS = {
  container: 'user-profile-container',
  avatar: 'user-profile-avatar',
  editButton: 'user-profile-edit-btn',
  nameInput: 'user-profile-name-input',
  saveButton: 'user-profile-save-btn',

  // Dynamic helpers
  skillTag: (id: string) => `user-profile-skill-${id}`,
  projectCard: (id: string) => `user-profile-project-${id}`,
} as const;
Enter fullscreen mode Exit fullscreen mode

4. Real-World Example: ProductCard 

// productCard.testIds.ts
export const PRODUCT_CARD_TEST_IDS = {
  container: "product-card-container",
  image: "product-card-image",
  title: "product-card-title",
  price: "product-card-price",
  addToCartBtn: "product-card-add-to-cart-btn",

  // Dynamic helper
  variantOption: (id: string) => `product-card-variant-${id}`,
} as const;
Enter fullscreen mode Exit fullscreen mode 
// ProductCard.tsx
import { PRODUCT_CARD_TEST_IDS } from "./productCard.testIds";

export const ProductCard = ({ product }) => (
  <div data-testid={PRODUCT_CARD_TEST_IDS.container}>
    <img
      src={product.image}
      alt={product.name}
      data-testid={PRODUCT_CARD_TEST_IDS.image}
    />
    <h3 data-testid={PRODUCT_CARD_TEST_IDS.title}>{product.name}</h3>
    <span data-testid={PRODUCT_CARD_TEST_IDS.price}>{product.price}</span>
    <button data-testid={PRODUCT_CARD_TEST_IDS.addToCartBtn}>Add to Cart</button>

    {product.variants.map((v) => (
      <button
        key={v.id}
        data-testid={PRODUCT_CARD_TEST_IDS.variantOption(v.id)}
      >
        {v.label}
      </button>
    ))}
  </div>
);
Enter fullscreen mode Exit fullscreen mode

5. Conflict Prevention Strategies

  1. Namespace by Domain 
data-testid="auth-login-form-submit-btn"
data-testid="ecommerce-product-card-add-btn"
Enter fullscreen mode Exit fullscreen mode
  1. Component-Level Scoping 
export const USER_PROFILE_TEST_IDS = {
  avatar: 'user-profile-avatar',
  editBtn: 'user-profile-edit-btn',
};
Enter fullscreen mode Exit fullscreen mode
  1. Scoped Helpers 
const getTestId = (scope: string, element: string) =>
  `${scope}-${element}`;

data-testid={getTestId('user-profile', 'avatar')}
data-testid={`cart-item-${item.id}-remove-btn`}
Enter fullscreen mode Exit fullscreen mode

Got it 👍 Since your project uses eslint.config.js (the new flat config format), you’ll configure the rule there instead of .eslintrc.json.

Here’s the dev.to post version with that adjustment:

6. Enforce data-testid in Your React + TypeScript Codebase with ESLint

When working with React + TypeScript, having consistent data-testid attributes is super useful for testing. But what if someone forgets to add them? Let’s make ESLint warn us automatically.

Install the plugin 

npm install eslint-plugin-testing-library --save-dev
Enter fullscreen mode Exit fullscreen mode

Update your eslint.config.js

Add the rule at the end of your config:

import testingLibrary from "eslint-plugin-testing-library";

export default [
  {
    files: ["**/*.tsx"],
    plugins: { "testing-library": testingLibrary },
    rules: {
      "testing-library/prefer-screen-queries": "warn",
      "testing-library/consistent-data-testid": ["warn", {
        testIdPattern: "[A-Za-z]+(-[A-Za-z]+)*",
      }],
    },
  },
];
Enter fullscreen mode Exit fullscreen mode

Now ESLint warns 🚨

Whenever a required element in .tsx files is missing data-testid, ESLint will show a warning.

This way, your whole team keeps test IDs consistent across the codebase without relying on manual reviews. ✅

7. Production Optimization

Next.js next.config.js 

// Strip test IDs from production bundle
module.exports = {
  webpack: (config, { dev }) => {
    if (!dev) {
      config.module.rules.push({
        test: /\.(js|jsx|ts|tsx)$/,
        use: {
          loader: 'string-replace-loader',
          options: {
            search: /data-testid="[^"]*"/g,
            replace: '',
          },
        },
      });
    }
    return config;
  },
};
Enter fullscreen mode Exit fullscreen mode

Utility Function 

export const testId = (id: string) =>
  process.env.NODE_ENV !== "production" ? { "data-testid": id } : {};

// Usage
<button {...testId("login-form-submit-btn")}>Submit</button>
Enter fullscreen mode Exit fullscreen mode

8. Trends & Future Considerations

  • Component-First Architecture → auto-namespaced test IDs per component
  • AI-Assisted Test ID Generation → auto-suggesting IDs based on structure
  • Visual Regression Testing → using test IDs for screenshot diffs & layout validation
  • Analytics & Monitoring → reusing test IDs for A/B tests and feature tracking

📊 Decision Matrix

Application Size Recommended Pattern Example
Small (<50) Simple kebab-case login-form-submit-btn
Medium (50–200) Component-scoped user-profile-edit-btn
Large (200+) Namespace + component auth-login-form-submit-btn
Micro-frontends Domain-scoped auth.login-form.submit-btn
Complex states BEM-style wizard-step__content--active

💡 Takeaway:

  • Use semantic selectors first.
  • Fall back to well-scoped data-testid only when necessary.
  • Co-locate and namespace to keep them unique.
  • Strip them out in production for clean builds.

Top comments (0)