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`:

```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`:

```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`:

```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`:

```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:

```tsx
// 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/`:

```tsx
// 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:

```tsx
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](https://playwright.dev/docs/best-practices)
- [Testing Library data-testid](https://testing-library.com/docs/queries/bytestid/)
- [React Testing Patterns](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library)