blackcanyontickets/reactrebuild0825/DATA_TESTID_GUIDE.md

Data Test ID Implementation Guide

Overview

To make our Playwright tests more reliable and maintainable, we should add data-testid attributes to key UI elements. This prevents tests from breaking when CSS classes or text content changes.

Current Test Status

✅ Working Tests (using current selectors):

• smoke.spec.ts - Basic functionality validation
• auth-realistic.spec.ts - Authentication flows using form elements

⚠️ Enhanced Tests (require data-testid attributes):

• auth.spec.ts - Full authentication suite
• navigation.spec.ts - Navigation and routing
• theme.spec.ts - Theme switching
• responsive.spec.ts - Responsive design
• components.spec.ts - UI components

Implementation Plan

Phase 1: Critical Elements (Authentication)

Add these data-testid attributes to /src/pages/LoginPage.tsx:

// Email input
<Input
  id="email"
  name="email"
  data-testid="email-input"
  // ... other props
/>

// Password input  
<Input
  id="password"
  name="password"
  data-testid="password-input"
  // ... other props
/>

// Password toggle button
<button
  type="button"
  data-testid="password-toggle"
  onClick={() => setShowPassword(!showPassword)}
  // ... other props
>

// Remember me checkbox
<input
  id="rememberMe"
  name="rememberMe"
  data-testid="remember-me"
  type="checkbox"
  // ... other props
/>

// Login button
<Button
  type="submit"
  data-testid="login-button"
  // ... other props
>

// Error alert
{error && (
  <Alert variant="error" data-testid="error-message">
    // ... content
  </Alert>
)}

// Form validation errors
<div data-testid="email-error">Email is required</div>
<div data-testid="password-error">Password is required</div>

Phase 2: Navigation Elements

Add these data-testid attributes to /src/components/layout/Sidebar.tsx:

// Main sidebar container
<div data-testid="sidebar" className={`h-full bg-white/90...`}>

// Navigation links
<Link
  to={item.path}
  data-testid={`nav-${item.label.toLowerCase()}`}
  // ... other props
>

// User profile section
<div data-testid="user-profile">
  <img data-testid="user-avatar" />
  <p data-testid="user-name">{user.name}</p>
</div>

Add these to /src/components/layout/Header.tsx:

// Header container
<header data-testid="header">

// Mobile menu button
<button data-testid="mobile-menu-button">

// User menu
<div data-testid="user-menu">
  <div data-testid="user-dropdown">
    <Link data-testid="profile-link">Profile</Link>
    <Link data-testid="settings-link">Settings</Link>
    <button data-testid="logout-button">Logout</button>
  </div>
</div>

// Theme toggle
<button data-testid="theme-toggle">
  <MoonIcon data-testid="moon-icon" />
  <SunIcon data-testid="sun-icon" />
</button>

Phase 3: Layout Elements

Add these to /src/components/layout/AppLayout.tsx:

// Skip to content link
<a href="#main-content" data-testid="skip-to-content">

// Main content area
<main id="main-content" data-testid="main-content">

// Mobile overlay
<div data-testid="mobile-overlay" />

// Breadcrumb navigation
<nav data-testid="breadcrumb">

Phase 4: Page Elements

Add these to each page component:

// Dashboard page
<div data-testid="dashboard-page">
  <h1 data-testid="page-title">Dashboard</h1>
</div>

// Events page  
<div data-testid="events-page">
  <h1 data-testid="page-title">Events</h1>
  <div data-testid="event-card-{eventId}">
</div>

Phase 5: Component Elements

Add these to UI components in /src/components/ui/:

// Button component
<button data-testid={props['data-testid']} />

// Card component
<div data-testid={props['data-testid']} />

// Alert component
<div data-testid={props['data-testid']} role="alert" />

// Modal component
<div data-testid="modal-overlay">
  <div data-testid="modal-content">
    <button data-testid="modal-close">
  </div>
</div>

// Loading components
<div data-testid="loading-spinner" />
<div data-testid="skeleton" />

Testing Naming Conventions

Standard Patterns

• Pages: {page-name}-page (e.g., dashboard-page, events-page)
• Navigation: nav-{item} (e.g., nav-dashboard, nav-events)
• Forms: {field}-input, {field}-error (e.g., email-input, email-error)
• Buttons: {action}-button (e.g., login-button, submit-button)
• User Interface: user-{element} (e.g., user-menu, user-avatar)
• Theme: theme-toggle, theme-{variant}
• Modal: modal-{action} (e.g., modal-close, modal-confirm)
• Cards: {type}-card-{id} (e.g., event-card-123)

Component Props Pattern

For reusable components, accept data-testid as a prop:

interface ButtonProps {
  'data-testid'?: string;
  // ... other props
}

export function Button({ 'data-testid': testId, ...props }: ButtonProps) {
  return <button data-testid={testId} {...props} />;
}

Implementation Checklist

Phase 1: Authentication (Critical)

• Login form inputs (email-input, password-input)
• Login form buttons (login-button, password-toggle)
• Form validation (remember-me, error-message)
• Demo account buttons (use existing text selectors)

Phase 2: Navigation (Critical)

• Sidebar container (sidebar)
• Navigation links (nav-dashboard, nav-events)
• User profile (user-menu, user-name, user-avatar)
• Mobile menu (mobile-menu-button, mobile-overlay)

Phase 3: Layout

• Header elements (header, theme-toggle)
• Main content (main-content, skip-to-content)
• Breadcrumbs (breadcrumb)

Phase 4: Pages

• Page containers and titles
• Content sections
• Interactive elements

Phase 5: Components

• Update UI components to accept data-testid props
• Add data-testid to complex components (modals, dropdowns)
• Loading and error states

Test Migration Plan

1. Run Current Tests: Use npm run test:smoke and npm run test:auth-realistic
2. Add Phase 1 Data-TestIDs: Focus on authentication elements
3. Migrate Auth Tests: Switch from form selectors to data-testid
4. Add Phase 2 Data-TestIDs: Navigation elements
5. Enable Navigation Tests: Update selectors in navigation.spec.ts
6. Continue Phases 3-5: Gradually enhance remaining tests

Benefits

✅ Test Reliability: Tests won't break when CSS classes change
✅ Maintainability: Clear intent for test-specific elements
✅ Performance: More efficient element selection
✅ Team Collaboration: Clear contracts between dev and test teams
✅ CI/CD Stability: Reduced flaky test failures

Quick Start

To begin implementation:

1. Add data-testid attributes to login form elements
2. Run: npm run test:auth to verify tests pass
3. Gradually add more data-testid attributes following the patterns above
4. Update test files to use new selectors

Resources

• Playwright Best Practices
• Testing Library data-testid
• React Testing Patterns