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:

   ./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:

   # 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