upskill-event-manager/wordpress-dev/SELECTORS.md

# UI Selector Management System

This document provides a centralized database of UI selectors used in the HVAC Community Events plugin tests. Use this as a reference when updating selectors or debugging UI interactions.

## Selector Principles

1. **Prefer attribute selectors** over ID selectors:
   - Better: `input[name="log"]`
   - Avoid: `#user_login`

2. **Use multiple selector strategies** with fallbacks:
   - Better: `input[name="log"], input[type="text"][id="user_login"], input.username`
   - Avoid: `#user_login`

3. **Keep selectors as specific as possible** but not too brittle:
   - Better: `form#hvac_community_loginform input[name="log"]`
   - Avoid: `form > div > input:first-child`

4. **Update this document** when changing selectors in code

## Critical Page Selectors

### Login Page

| Element | Current Selector | Alternative Selectors | Notes |
|---------|-----------------|----------------------|-------|
| Username field | `input[name="log"]` | `#user_login`, `.input[autocomplete="username"]` | Primary login input field |
| Password field | `input[name="pwd"]` | `#user_pass`, `input[type="password"]` | Password input field |
| Submit button | `input[type="submit"]` | `#wp-submit`, `.button.button-primary` | Login form submission button |
| Remember me | `input[name="rememberme"]` | `#rememberme` | Remember login checkbox |
| Error message | `.login-error, .login_error, #login_error` | `div:contains("Invalid username")` | Login error container |
| Login form | `form#hvac_community_loginform` | `form[name="hvac_community_loginform"]` | Main login form |

Last verified: 2025-05-21

### Dashboard Page

| Element | Current Selector | Alternative Selectors | Notes |
|---------|-----------------|----------------------|-------|
| Events table | `.hvac-events-table` | `table.events-table` | Table containing event listings |
| Event row | `.event-row` | `tr.event` | Individual event row |
| Event name | `.event-name a` | `.event-title a` | Event title with link |
| Event date | `.event-date` | `.event-time` | Date/time of event |
| Event status | `.event-status` | `.status-badge` | Event status indicator |
| Filter tabs | `.filter-tabs a` | `.nav-tab` | Filter tabs for event status |
| Create button | `.create-event-button` | `a:contains("Create Event")` | Button to create new event |
| Stats section | `.dashboard-stats` | `.statistics` | Statistics summary section |

Last verified: 2025-05-21

### Certificate Page

| Element | Current Selector | Alternative Selectors | Notes |
|---------|-----------------|----------------------|-------|
| Certificate table | `.certificate-table` | `table.certificates` | Table of certificates |
| Certificate row | `.certificate-row` | `tr.certificate` | Individual certificate row |
| Event filter | `select[name="event_filter"]` | `#event-filter` | Event dropdown filter |
| Attendee filter | `input[name="attendee_search"]` | `#attendee-search` | Attendee search input |
| Generate button | `.generate-certificates` | `button:contains("Generate")` | Certificate generation button |
| Email button | `.email-certificate` | `button:contains("Email")` | Email certificate button |
| Download button | `.download-certificate` | `a:contains("Download")` | Download certificate link |
| Revoke button | `.revoke-certificate` | `button:contains("Revoke")` | Revoke certificate button |

Last verified: 2025-05-21

### Event Creation Page

| Element | Current Selector | Alternative Selectors | Notes |
|---------|-----------------|----------------------|-------|
| Title field | `input[name="post_title"]` | `#post_title` | Event title input |
| Description | `.wp-editor-area` | `textarea[name="post_content"]` | Event description editor |
| Event date | `input[name="event_date"]` | `.event-date-field` | Event date picker |
| Event time | `input[name="event_time"]` | `.event-time-field` | Event time picker |
| Venue field | `select[name="venue_id"]` | `#venue_id` | Venue selection dropdown |
| Organizer | `select[name="organizer_id"]` | `#organizer_id` | Organizer selection dropdown |
| Submit button | `input[name="community-event"]` | `button[type="submit"]` | Submit event button |

Last verified: 2025-05-21

## Selector Versioning

Each time selectors are updated, add a new entry to track changes:

### Version History

#### 2025-05-21: Login Page Selector Update
- Updated username field selector from `#user_login` to `input[name="log"]`
- Updated password field selector from `#user_pass` to `input[name="pwd"]`
- Added multiple error message selectors for better error detection
- Added form ID selector for more reliable form detection

#### 2025-05-01: Initial Selector Documentation
- Created initial documentation of selectors
- Centralized selector references for easier maintenance

## Selector Verification Process

1. Run the selector verification script regularly:
   ```bash
   ./bin/verify-selectors.sh
   ```

2. Update selectors in this document and code when changes are detected

3. Create debug scripts for new pages or critical components:
   ```bash
   # Create a debug script for a new page
   ./bin/create-debug-script.sh --page="profile"
   ```

4. Document selector changes in version history above

## Best Practices for Selector Maintenance

1. **Test selector changes** thoroughly before committing
2. **Update this document** when changing selectors in code
3. **Use descriptive selector names** in page objects
4. **Add comments** explaining complex selectors
5. **Consider theme changes** that might affect selectors
6. **Prefer attribute selectors** that are less likely to change
7. **Use data attributes** for critical test elements when possible